Política HTTPModifier

Política padrão

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

A política HTTPModifier muda uma mensagem de solicitação ou resposta existente.

A política permite realizar as seguintes ações nessas mensagens:

Adicionar novos parâmetros de formulário, cabeçalhos ou parâmetros de consulta para uma mensagem
Remover cabeçalhos, parâmetros de consulta e parâmetros de formulário de uma mensagem
Definir o valor das propriedades atuais de uma mensagem

Com HTTPModifier, é possível adicionar, alterar ou remover propriedades da solicitação ou da resposta. Também é possível usar HTTPModifier para criar uma mensagem de resposta ou de solicitação personalizada e transmiti-la a um destino alternativo, conforme descrito em Criar mensagens de solicitação personalizadas.

A política HTTPModifier pode criar variáveis de fluxo com os seguintes elementos filhos:

A ordem em que você organiza os elementos <Add>, <Set> e <Remove> é importante. A política executa essas ações na ordem em que aparecem na configuração da política. Se você precisar remover todos os cabeçalhos e definir um cabeçalho específico, inclua o elemento <Remove> antes do elemento <Set>.

Esta é uma política padrão e pode ser implantada em qualquer tipo de ambiente. Para informações sobre os tipos de políticas e a disponibilidade de cada tipo de ambiente, consulte Tipos de políticas.

Casos de uso

Há muitas situações em que você quer modificar uma mensagem de solicitação ou resposta durante o processamento do Apigee. Por exemplo:

Definir um valor padrão para um parâmetro de string de consulta ou outro tipo de entrada.
Eliminar cabeçalhos HTTP de uma mensagem de solicitação antes que a mensagem seja encaminhada para o serviço de back-end.
Adicionar cabeçalhos HTTP antes de uma resposta ser enviada ao app do cliente.
Gerar mensagens personalizadas de solicitação ou resposta. Por exemplo, é possível usar uma chamada externa para invocar uma API remota por meio de um proxy de API. É possível usar a política HTTPModifier para criar uma mensagem de solicitação personalizada e atribuí-la a uma variável. Em seguida, use uma chamada externa para enviar essa mensagem à API remota.
Adicionar cabeçalhos a solicitações e respostas para depuração e solução de problemas.

Elemento `<HTTPModifier>`

Define uma política HTTPModifier.

Valor padrão	Consulte a guia Política padrão a seguir
Obrigatório?	Obrigatório
Tipo	Objeto complexo
Elemento pai	N/A
Elemento filho	`<Add>` `<AssignTo>` `<DisplayName>` `<IgnoreUnresolvedVariables>` `<Remove>` `<Set>`

O elemento <HTTPModifier> usa a seguinte sintaxe:

Sintaxe

O elemento <HTTPModifier> usa a seguinte sintaxe:

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
   > na<me="POLICY_NAME" 
  !-- All HTTPModifier >chi<ld >eleme<nts are op>tional <--
  Add
    FormParams
      F>ormParam name=&<quot;FORMP>ARAM_NAME"<FORMPARAM_V>ALUE/<FormPar>am
    <  ...
    /FormParams
   > Headers
   <   Head>er name="H<EADER_NA>ME&qu<ot;HEADER_V>ALUE/He<ader
      ...
    /Headers
    Q>ueryParams
     < QueryParam> name="QUE<RYPARAM_NAME>&qu<ot;Q>UERY<PARAM_VALUE/QueryParam
      ...
    /QueryParams
  /Add

  AssignTo createNew=&>quot;[true|false]" t<ransport=>&quo<t;http">;
    type="[r<equest|respo>nse]<"DESTINATION_VARIABL>E_NAME/Assig<nTo

  DisplayNamePOLICY_D>ISPL<AY_NAME/DisplayName

  IgnoreUnresolvedVariables[true|false]/<IgnoreU>nresolve<dVaria>bles
<
  !-- Can also be empty to remove everything from the me<ssage (Remo>ve/) --><;
  Remove>
    !-<- Can also be an empty array to> remove all For<mParams (F>ormParams/) --&<gt;
    For>mPara<ms
      FormParam name="FORMPARAM_NAME"FORM<PARAM_VA>LUE/FormPa<ram
   >   ...
<    /FormParams
    !-- C>an also be a<n empty> array to remov<e all He>aders< (Headers/) -->
    Headers
      Header name="HEA<DER_NAME&quo>t;HEADER_V<ALUE/Header>
      <...
    /Headers
    !-- Can also> be an empty arr<ay to remov>e all QueryPara<ms (QueryPar>ams</) --&g>t;
 <   >Query<Params
   >   Quer<yParam name=&quot;QUERYPARAM_NA>ME"QUERYPA<RAM_VALUE/>QueryParam
    <  ...
    />Query<Params<>/span>
  /Remo<ve

  Set
    FormParams
>      FormPa<ram nam>e="FORMPAR<AM_NAME&>quot;<FORM>PARA<M_VAL>UE/Fo<rmParam
   >   ...
<    /FormParams
    Headers
     > Header name=&qu<ot;HEADER_N>AME"HEADER<_VALUE/Heade>r
   <   ...
   > /Headers
    PathPATH/Path
  <  QueryPara>ms
  <    >QueryParam name="QUERYPARAM_NAME&<quot;>QUERY<PARAM_V>ALUE/QueryParam
    <  ...>
  <  /Q>ue<ryParams
    >StatusCodeHTTP_STATUS_CODE or {variable}/StatusCode
    Verb[GET|POST|PUT|PATCH|DELETE|{variable}]/Verb
    Version[1.0|1.1|{variable}]/Verb
  /Set

/HTTPModifier

Política padrão

O exemplo a seguir mostra as configurações padrão quando você adiciona uma política HTTPModifier ao fluxo na interface da Apigee:

<HTTPModifier continueOnError="false" enabled="true" name=&qu>ot;<http-modifi>er-default"<;
  DisplayN>ame<HTTP Modifi>er-<1/Disp>layNa<me
  Pr>opertie<s/
  Remove
    H>eader<s
      >Heade<r name=&quo>t;h1&qu<ot;/
    /Headers
   > Quer<yParams
    >  Que<ryParam na>me=&quo<t;q1"/
    /Que>ryPar<ams
    For>mPa<rams
  >   < Fo>rmPar<am name=>"<;f1"/
 >   /F<ormParams
 > /R<emov>e
 < Ad>d
   < Headers>/
   < QueryParams>/
   < FormParams>/
  /<Add
<  Se>t
 <   He>ade>rs/
 <   Qu>ery<Para>ms/<
    FormParams/
    !-- >Verb<GET/Verb --
    Path/
  /S>et
<  IgnoreUnresolvedVariablestrue/IgnoreUnresolvedVariables
 > <AssignTo crea>teNew="false" transport="http" type="request"/
/HTTPModifier

Quando você insere uma nova política HTTPModifier na interface da Apigee, o modelo contém stubs para todas as operações possíveis. Normalmente, você seleciona quais operações quer executar com essa política e remove o restante dos elementos filhos. Por exemplo, para executar uma operação de adição, use o elemento <Add> e remova <Remove> e outros elementos filhos da política a fim de torná-la mais legível.

Este elemento tem os seguintes atributos comuns a todas as políticas:

Atributo	Padrão	Obrigatório?	Descrição
`name`	N/A	Valor	O nome interno da política. O valor do atributo `name` pode conter letras, números, espaços, hifens, sublinhados e pontos. Esse valor não pode exceder 255 caracteres. Opcionalmente, use o elemento `<DisplayName>` para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.
`continueOnError`	falso	Opcional	Defina como `false` para retornar um erro quando uma política falhar. Esse é o comportamento esperado para a maioria das políticas. Defina como `true` para que a execução do fluxo continue, mesmo depois que uma política falhar. Consulte também: As regras de falha são acionadas SOMENTE em um estado de erro (sobre continueOnError) Como corrigir falhas no fluxo atual
`enabled`	true	Opcional	Defina como `true` para aplicar a política. Defina como `false` para desativar a política. A política não será aplicada mesmo que permaneça vinculada a um fluxo.
`async`	falso	Obsoleto	Esse atributo está obsoleto.

A tabela a seguir fornece uma descrição de alto nível dos elementos filhos de <HTTPModifier>:

Elemento filho	Obrigatório?	Descrição
Operações comuns
`<Add>`	Opcional	Adiciona informações ao objeto de mensagem especificado pelo elemento `<AssignTo>`. `<Add>` adiciona cabeçalhos ou parâmetros à mensagem que não existem na mensagem original. O `<Set>` também oferece essa funcionalidade. Para substituir cabeçalhos ou parâmetros atuais, use o elemento `<Set>`.
`<Remove>`	Opcional	Exclui os elementos especificados da variável de mensagem definida no elemento `<AssignTo>`.
`<Set>`	Opcional	Substitui os valores das propriedades atuais na solicitação ou resposta, que é especificada pelo elemento `<AssignTo>`. `<Set>` substitui os cabeçalhos ou parâmetros que já existem na mensagem original ou adiciona novos quando eles não existem.
Outros elementos filhos
`<AssignTo>`	Opcional	Especifica em que mensagem a política HTTPModifier funciona. Pode ser a solicitação ou a resposta padrão ou uma nova mensagem personalizada.
`<IgnoreUnresolvedVariables>`	Opcional	Determina se o processamento é interrompido quando uma variável não resolvida é encontrada.

Cada um desses elementos filhos é descrito nas seções a seguir.

Exemplos

Os seguintes exemplos mostram algumas maneiras de usar a política HTTPModifier:

1: Adicionar cabeçalho

O exemplo a seguir adiciona um cabeçalho à solicitação com o elemento <Add>. A variável VerifyAPIKey neste exemplo é gerada pela política VerifyAPIKey:

<HTTPModifier name="HM-add-heade>rs-<1&q>uot;
<  Add
 >   Head<ers
      Header name=&q>uot;partner-id"{verifyapikey.VAK-1.devel<oper.ap>p.par<tner-id}>/He<ader>
  <  /Heade>rs
  /A<dd
  Assi>g<nTorequest/As>signTo
/HTTPModifier

2: Modificar resposta

O exemplo a seguir modifica um objeto de resposta atual adicionando um cabeçalho:

<HTTPModifier name="HM-modify-resp>ons<e&q>uot;
<  Set
 >   Head<ers
      Header name=&>quot;Cache-Hit"{lookupcache.Loo<kupCach>e-1.c<achehit}>/He<ader>
  <  /Headers
  /Set
  Ignor>eUnre<solvedVariablesfalse/Ignor>eUn<resolved>Variable<s
  Assig>n<Toresponse/As>signTo
/HTTPModifier

Este exemplo não cria uma nova mensagem. Ele modifica uma mensagem de resposta atual adicionando um cabeçalho HTTP.

Porque este exemplo especificaresponse como o nome da variável na <AssignTo>, essa política modifica o objeto de resposta definido originalmente com os dados retornados pelo servidor de destino.

O cabeçalho HTTP adicionado pela política à mensagem de resposta é derivado de uma variável preenchida pela política LookupCache. Portanto, a mensagem de resposta modificada por essa política HTTPModifier contém um cabeçalho HTTP que indica se os resultados foram extraídos do cache ou não. Definir cabeçalhos na resposta pode ser útil para depuração e solução de problemas.

3: Remover o parâmetro de consulta

O exemplo a seguir remove o parâmetro de consulta apikey da solicitação:

<HTTPModifier name="HM-remove-query-p>ara<m">;
  R<emove
    Q>ueryPar<ams
      QueryParam name>=&quo<t;apikey&quo>t;/<
    /Q>uer<yParams
>  /Remo<ve
  Assi>g<nTorequest/As>signTo
/HTTPModifier

É recomendável remover o parâmetro de consulta apikey da mensagem de solicitação quando você usar a política VerifyAPIKey para autenticar o usuário. Faça isso para evitar que informações confidenciais da chave sejam transmitidas ao destino do back-end.

Referência a elementos filhos

Esta seção descreve os elementos filhos de <HTTPModifier>.

`<Add>`

Adiciona informações à solicitação ou à resposta, que é especificada pelo elemento <AssignTo>.

O elemento <Add> adiciona novas propriedades à mensagem que não existem na mensagem original. O <Set> também oferece essa funcionalidade. Para alterar os valores das propriedades atuais, use o elemento <Set>.

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	Tipo complexo
Elemento pai	`<HTTPModifier>`
Elemento filho	`<FormParams>` `<Headers>` `<QueryParams>`

O elemento <Add> usa a seguinte sintaxe:

Sintaxe

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
   > na<me=>"<;POLICY_NA>ME"<; 
  Add
    FormParams
      F>ormParam name=&<quot;FORMP>ARAM_NAME"<FORMPARAM_V>ALUE/<FormPar>am
    <  ...
    /FormParams
   > Headers
   <   Head>er name="H<EADER_NA>ME&qu<ot;HEADER_V>ALUE/He<ader
      ...
    /Headers
    Q>ueryParams
     < QueryParam> name="QUE<RYPARAM_NAME>&qu<ot;Q>U<ERYPARAM_VALU>E/QueryParam
      ...
    /QueryParams
  /Add
/HTTPModifier

Exemplo 1

O exemplo a seguir usa o elemento <FormParams> para encontrar os valores de três parâmetros de string de consulta da solicitação inicial e defini-los como parâmetros de formulário na solicitação de endpoint de destino:

<HTTPModifier name="HM-add-formpara>ms-<3&q>uot;
<  Add
    >FormPar<ams
      FormParam name=>"username"{requ<est.queryp>aram.na<me}/FormParam
      FormP>aram name="zip_code&quo<t;{request>.queryp<aram.zipCode}/FormParam
      For>mParam name="default<_language&>quot;<{request.qu>ery<para>m.l<ang}/F>ormPa<ram
    /For>mPa<rams
  >/Ad<d
  Remo>ve
    <QueryPara>m<s/
  /Remove
>  AssignTorequest/AssignTo
/HTTPModifier

Exemplo 2

O exemplo a seguir usa o elemento <Headers> para adicionar um cabeçalho partner-id à solicitação que será enviada ao endpoint de destino:

<HTTPModifier name="HM-add-heade>rs-<1&q>uot;
<  Add
 >   Head<ers
      Header name=&q>uot;partner-id"{verifyapikey.VAK-1.devel<oper.ap>p.par<tner-id}>/He<ader>
  <  /Heade>rs
  /A<dd
  Assi>g<nTorequest/As>signTo
/HTTPModifier

Exemplo 3

O exemplo a seguir usa o elemento <QueryParams> para adicionar um único parâmetro de consulta com um valor estático à solicitação:

<HTTPModifier name="HM-add-querypara>ms-<1&q>uot;
<  Add
    Q>ueryPar<ams
      QueryParam name>=&<quot;myPara>m&quo<t;42/QueryPa>ram<
   > /Q<ueryPara>ms
  /A<dd
  Assi>g<nTorequest/As>signTo
/HTTPModifier

Este exemplo usa <Add> no pré-fluxo de solicitação. Se você examinar os resultados em uma ferramenta como a ferramenta de depuração, a solicitação para https://example-target.com/get se tornará https://example-target.com/get?myParam=42.

Os elementos filhos de <Add> são compatíveis com a substituição dinâmica de strings, conhecida como modelos de mensagens.

`<FormParams>` (filho de `<Add>`)

Adiciona novos parâmetros de formulário à mensagem de solicitação. Esse elemento não afeta mensagens de resposta.

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	Matriz de elementos `<FormParam>`
Elemento pai	`<Add>`
Elemento filho	`<FormParam>`

O elemento <FormParams> usa a seguinte sintaxe:

Sintaxe

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
   > na<me=>&quot<;POLICY_NA>ME"<; 
  Add
    FormParams
      F>ormParam name=&<quot;FORMP>ARAM_NAME"<FORMPARAM_V>ALU<E/FormParam
      ...
    /FormParams
  AssignTo createNew="[true|false]&qu>ot; transport="http&<quot;
   > ty<pe=&>q<uot;[request|>response]"DESTINATION_VARIABLE_NAME/AssignTo
  /Add
/HTTPModifier

Exemplo 1

O exemplo a seguir adiciona um único parâmetro de formulário (answer) e um valor estático (42) à solicitação:

<HTTPModifier name="HM-add-formpara>ms-<1&q>uot;
<  Add
    >FormPar<ams
      FormParam nam>e=<"answ>er&qu<ot;42/FormP>ara<m
  >  /<FormPara>ms
  /A<dd
  Assi>g<nTorequest/As>signTo
/HTTPModifier

Exemplo 2

O exemplo a seguir acessa o valor do parâmetro de consulta name e o adiciona à solicitação como um parâmetro de formulário, depois remove o parâmetro de consulta:

<HTTPModifier name="HM-Swap-QueryParam-to-FormPa>ram<s&q>uot;
<  Add
    FormParam n>ame="name"{request<.que>ryp<aram.n>ame}
<  /Add
  Remove
    Que>ryP<aram na>m<e="name&>quot;/
  /Remove
/HTTPModifier

Este exemplo não especifica um destino com <AssignTo>. Essa política adiciona o parâmetro somente à solicitação.

Exemplo 3

O exemplo a seguir adiciona vários parâmetros de formulário à solicitação:

<HTTPModifier name="HM-add-formpara>ms-<3&q>uot;
<  Add
    >FormPar<ams
      FormParam name=>"username"{requ<est.queryp>aram.na<me}/FormParam
      FormP>aram name="zip_code&quo<t;{request>.queryp<aram.zipCode}/FormParam
      For>mParam name="default<_language&>quot;<{request.qu>ery<para>m.l<ang}/F>ormPa<ram
    /For>mPa<rams
  >/Ad<d
  Remo>ve
    <QueryPara>m<s/
  /Remove
>  AssignTorequest/AssignTo
/HTTPModifier

Este exemplo recebe os parâmetros de string de consulta da solicitação de origem e os adiciona como parâmetros de formulário com nomes diferentes. Em seguida, ele remove os parâmetros de consulta originais. A Apigee enviará a solicitação modificada ao endpoint de destino.

É possível usar a ferramenta de depuração para examinar o fluxo. Você verá que o corpo da solicitação contém os dados do formulário codificado por URL, que foram originalmente transmitidos como parâmetros de string de consulta:

username=nick&zip_code=90210&default_language=en

Use <FormParams> somente quando os seguintes critérios forem atendidos:

Verbos HTTP: GET e POST
Tipo de mensagem: solicitação
Um ou ambos os itens a seguir:
- Dados do formulário: defina como um valor ou como "" (string vazia). Por exemplo, com curl, adicione -d "" à solicitação.
- Cabeçalho Content-Length: defina como 0 (isso se nenhum dado estiver na solicitação original. Caso contrário, o tamanho atual, em bytes). Por exemplo, com curl adicione -H "Content-Length: 0" à solicitação.

Por exemplo:

curl -vL -X POST -d "" -H "Content-Type: application/x-www-form-urlencoded"
  https://ahamilton-eval-test.apigee.net/am-test

Quando você adiciona <FormParams>, a Apigee define o cabeçalho Content-Type da solicitação como application/x-www-form-urlencoded antes de enviar a mensagem para o serviço de destino.

`<Headers>` (filho de `<Add>`)

Adiciona novos cabeçalhos à solicitação ou resposta especificada, definida pelo elemento <AssignTo>.

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	Matriz de elementos `<Header>`
Elemento pai	`<Add>`
Elemento filho	`<Header>`

O elemento <Headers> usa a seguinte sintaxe:

Sintaxe

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
   > na<me=>&quot<;POLICY>_NAME&q<uot; 
  Add
    Headers
 >     Header <name=&q>uot;HEADER_NAME<"HE>ADE<R_VA>L<UE/Header
   >   ...
    /Headers
  /Add
/HTTPModifier

Exemplo 1

O exemplo a seguir adiciona o cabeçalho partner-id à mensagem de solicitação e atribui o valor da variável de fluxo verifyapikey.VAK-1.developer.app.partner-id a esse cabeçalho.

<HTTPModifier name="HM-add-heade>rs-<1&q>uot;
<  Add
 >   Head<ers
      Header name=&q>uot;partner-id"{verifyapikey.VAK-1.devel<oper.ap>p.par<tner-id}>/He<ader>
  <  /Heade>rs
  /A<dd
  Assi>g<nTorequest/As>signTo
/HTTPModifier

`<QueryParams>` (filho de `<Add>`)

Adiciona novos parâmetros de consulta à solicitação. Esse elemento não afeta respostas.

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	Matriz de elementos `<QueryParam>`
Elemento pai	`<Add>`
Elemento filho	`<QueryParam>`

O elemento <QueryParams> usa a seguinte sintaxe:

Sintaxe

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
   > na<me=>&quot<;POLICY_NAM>E"< 
  Add
    QueryParams
      Que>ryParam name=&qu<ot;QUERYPAR>AM_NAME"QU<ERYPARAM_VAL>UE/<Quer>y<Param
      .>..
    /QueryParams
  /Add
/HTTPModifier

Exemplo 1

O exemplo a seguir adiciona o parâmetro de consulta myParam à solicitação e atribui o valor 42 a ele:

<HTTPModifier name="HM-add-querypara>ms-<1&q>uot;
<  Add
    Q>ueryPar<ams
      QueryParam name>=&<quot;myPara>m&quo<t;42/QueryPa>ram<
   > /Q<ueryPara>ms
  /A<dd
  Assi>g<nTorequest/As>signTo
/HTTPModifier

Use <QueryParams> somente quando os seguintes critérios forem atendidos:

Verbos HTTP: GET e POST
Tipo de mensagem: solicitação

Além disso, só é possível definir parâmetros de consulta quando o atributo type do elemento <AssignTo> for uma mensagem de solicitação. A definição delas na resposta não tem efeito.

Se você definir uma matriz vazia de parâmetros de consulta na política (<Add><QueryParams/></Add>), a política não adicionará parâmetros de consulta. Isso é o mesmo que omitir <QueryParams>.

`<AssignTo>`

Determina em que objeto a política HTTPModifier opera. As opções são:

Mensagem de solicitação: o request recebido pelo proxy da API
Mensagem de resposta: o response retornado do servidor de destino
Mensagem personalizada: uma solicitação personalizada ou um objeto de resposta

Em alguns casos, não é possível alterar o objeto em que a política HTTPModifier atua. Por exemplo, não é possível usar <Add> ou <Set> para adicionar ou alterar parâmetros de consulta (<QueryParams>) ou parâmetros de formulário (<FormParams>) na resposta. Só é possível manipular parâmetros de consulta e de formulário na solicitação.

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	String
Elemento pai	`<HTTPModifier>`
Elemento filho	Nenhum

Se você não especificar <AssignTo> ou especificar o elemento <AssignTo>, mas não especificar um valor de texto para ele, a política atuará na solicitação ou resposta padrão, que é baseada no local em que a política é executada. Se a política for executada no fluxo da solicitação, ela afetará a mensagem de solicitação. Se for executada no fluxo de resposta, a política afetará a resposta por padrão.

O elemento <AssignTo> usa a seguinte sintaxe:

Sintaxe

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
   > na<me="POLICY_NAME" 
  AssignTo createNew="[true|false]" transp>ort="http"
    <type=&quo>t<;[request|res>ponse]"DESTINATION_VARIABLE_NAME/AssignTo
/HTTPModifier

Exemplo 1

O exemplo a seguir não especifica nenhuma mensagem no texto de <AssignTo>. Isso significa que a política atuará na mensagem request ou response, dependendo de onde a política for executada.

<HTTPModifier name="assign>to-<1"
  AssignTo createNew="false" transport=&q>uot;http" type=&<quot;request&>quot;/<!-- no-op -->
  ...
/HTTPModifier

Se você especificar createNew="false" e não fornecer explicitamente um nome de mensagem, os outros atributos de <AssignTo> serão irrelevantes. Nesse caso, talvez seja bom omitir o elemento <AssignTo> completamente.

Exemplo 2

O exemplo a seguir cria um novo objeto de solicitação, substituindo o objeto existente:

<HTTPModifier name="assign>to-<2"
  AssignTo createNew="true" transport=&q>uot;htt<p" type=>"request"/
  ...
/HTTPModifier

Ao criar um novo objeto de solicitação ou resposta, os outros elementos da política HTTPModifier (como <Add> e <Set>) atuarão nesse novo objeto de solicitação.

É possível acessar o novo objeto de solicitação em outras políticas do fluxo posteriormente ou enviar o novo objeto de solicitação para um serviço externo com uma política ServiceCallout.

Exemplo 3

O exemplo a seguir cria um novo objeto de solicitação chamado MyRequestObject:

<HTTPModifier name="assign>to-<3"
  AssignTo createNew="true" transport=&>quot;http"< type=&qu>ot;requ<est"MyRe>questObject/AssignTo
  ...
/HTTPModifier

Ao criar um novo objeto de solicitação ou resposta, os outros elementos da política HTTPModifier (como <Add> e <Set>) atuarão nesse novo objeto de solicitação.

É possível acessar o novo objeto de solicitação em outras políticas do fluxo posteriormente ou enviar o novo objeto de solicitação para um serviço externo com uma política ServiceCallout.

A tabela a seguir descreve os atributos de <AssignTo>:

Atributo Descrição Obrigatório? Tipo

Atributo	Descrição	Obrigatório?	Tipo
`createNew`	Determina se essa política cria uma nova mensagem ao atribuir valores. Se for `true`, a política criará uma nova variável do tipo especificado por `type` (`request` ou `response`). Se você não especificar o nome da nova variável, a política criará uma nova solicitação ou um objeto de resposta com base no valor de `type`. Cuidado: ao criar um novo objeto de solicitação ou resposta, o objeto de resposta ou solicitação atual será excluído e substituído pelo novo. Isso significa que todas as informações no objeto são perdidas. Se `false`, a política responderá de uma destas duas maneiras: Se `<AssignTo>` puder resolver o nome da variável para uma solicitação ou resposta, ele continuará em processamento. Por exemplo, se a política estiver em um fluxo de solicitação, a variável será o objeto de solicitação. Se a política estiver em uma resposta, a variável será o objeto de resposta. Se `<AssignTo>` não puder ser resolvido ou se for resolvido para um tipo de mensagem, a política emitirá um erro. Se `createNew` não for especificado, a política responderá de duas maneiras: Se `<AssignTo>` for resolvido para uma mensagem, o processamento avançará para a próxima etapa. Se `<AssignTo>` não puder ser resolvido ou se for resolvido para um tipo que não seja de mensagem, será criada uma nova variável de tipo especificada em `type`.	Opcional	Booleano
`transport`	Especifica o tipo de transporte para o tipo de mensagem de solicitação ou resposta. O valor padrão é `http` (o único valor compatível).	Opcional	String
`type`	Especifica o tipo da nova mensagem, quando `createNew` é `true`. Os valores válidos são `request` ou `response`. O valor padrão é `request`. Se você omitir esse atributo, o Apigee criará uma solicitação ou uma resposta, dependendo de onde a política for executada.	Opcional	String

createNew

Determina se essa política cria uma nova mensagem ao atribuir valores.

Se for true, a política criará uma nova variável do tipo especificado por type (request ou response). Se você não especificar o nome da nova variável, a política criará uma nova solicitação ou um objeto de resposta com base no valor de type.

Se false, a política responderá de uma destas duas maneiras:

Se <AssignTo> puder resolver o nome da variável para uma solicitação ou resposta, ele continuará em processamento. Por exemplo, se a política estiver em um fluxo de solicitação, a variável será o objeto de solicitação. Se a política estiver em uma resposta, a variável será o objeto de resposta.
Se <AssignTo> não puder ser resolvido ou se for resolvido para um tipo de mensagem, a política emitirá um erro.

Se createNew não for especificado, a política responderá de duas maneiras:

Se <AssignTo> for resolvido para uma mensagem, o processamento avançará para a próxima etapa.
Se <AssignTo> não puder ser resolvido ou se for resolvido para um tipo que não seja de mensagem, será criada uma nova variável de tipo especificada em type.

Opcional

Booleano

transport

Especifica o tipo de transporte para o tipo de mensagem de solicitação ou resposta.

O valor padrão é http (o único valor compatível).

Opcional

String

type

Especifica o tipo da nova mensagem, quando createNew é true. Os valores válidos são request ou response.

O valor padrão é request. Se você omitir esse atributo, o Apigee criará uma solicitação ou uma resposta, dependendo de onde a política for executada.

Opcional

String

`<DisplayName>`

Use além do atributo name para rotular a política no editor de proxy da IU de gerenciamento com um nome de som diferente e mais natural.

O elemento <DisplayName> é comum a todas as políticas.

Valor padrão	N/A
Obrigatório?	Opcional. Se você omitir `<DisplayName>`, o valor do atributo `name` da política será usado
Tipo	String
Elemento pai	<`PolicyElement`>
Elemento filho	Nenhum

O elemento <DisplayName> usa a seguinte sintaxe:

Sintaxe

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Exemplo

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

O elemento <DisplayName> não tem atributos ou elementos filhos.

`<IgnoreUnresolvedVariables>`

Determina se o processamento é interrompido quando uma variável não resolvida é encontrada.

Valor padrão	Falso
Obrigatório?	Opcional
Tipo	Booleano
Elemento pai	`<HTTPModifier>`
Elemento filho	Nenhum

Defina como true para ignorar variáveis não resolvidas e continuar o processamento. Caso contrário, utilize false. O valor padrão é false.

Definir <IgnoreUnresolvedVariables> como true"true" é diferente de definir o continueOnError de <HTTPModifier> como true porque ele é específico para definir e receber valores de variáveis. Se você definir continueOnError como true, a Apigee ignorará todos os erros, não apenas os erros encontrados ao usar variáveis.

O elemento <IgnoreUnresolvedVariables> usa a seguinte sintaxe:

Sintaxe

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
   > na<me="POLICY_NAME">; 
  IgnoreU<nresolvedVariables[true|fa>l<se]/IgnoreUnr>esolvedVariables
/HTTPModifier

Exemplo 1

O exemplo a seguir define <IgnoreUnresolvedVariables> como true:

<HTTPModifier name="HM-Set-Hea>der<s&q>uot;
<  Set
 >   Head<ers
      Header name=&#>39;new-header'{possibly<-defin>ed-va<riable}H>ead<er
 >   </Headers
  /Set
  IgnoreU>nres<olvedVariablestrue/IgnoreU>n<resolvedVaria>bles
/HTTPModifier

Como <IgnoreUnresolvedVariables> é definido como true, se a variável possibly-defined-variable não for definida, essa política não gerará uma falha.

`<Remove>`

Remove cabeçalhos, parâmetros de consulta ou parâmetros de formulário de uma mensagem. Uma tag vazia remove todos os parâmetros correspondentes, incluindo cabeçalhos, parâmetros de formulário e parâmentros de consulta.

A mensagem afetada pode ser uma solicitação ou uma resposta. Você especifica em que mensagem <Remove> atua usando o elemento <AssignTo>.

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	Tipo complexo
Elemento pai	`<HTTPModifier>`
Elemento filho	`<FormParams>` `<Headers>` `<QueryParams>`

Um caso de uso comum de <Remove> é excluir um parâmetro de consulta com informações confidenciais do objeto de solicitação recebida para evitar transmiti-lo ao servidor de back-end.

O elemento <Remove> usa a seguinte sintaxe:

Sintaxe

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
   > na<me="POLICY_NAME" 
  !-- Can also be empty to remove< everyt>hing fro<m the >messa<ge (Remove/) -->
  Remove
    !-- Can also be an empty< array to r>emove all <FormParams> (FormP<arams/) -->
    FormParams
 >     FormParam <name=">;FORMPARAM_NAME<"FORMP>ARAM_<VALUE/FormParam
      ...
    /FormParams
    !-- Can <also be >an empty a<rray to> remove< all Headers (Headers/) ->->
    He<aders
 >     Header nam<e=">HEADE<R_NAME"HEADER_VALUE/Header
      ...
    /Headers
   < !-- Can als>o be an em<pty array t>o remov<e all QueryParams (QueryParams/) >-->
    Query<Params
    >  QueryParam na<me="QUE>RYP<ARAM_NA>M<E"QUERYP>ARAM_VALUE/QueryParam
      ...
    /QueryParams
  /Remove
/HTTPModifier

Exemplo 1

O exemplo a seguir remove todos os parâmetros de formulário e um parâmetro de consulta do objeto request:

<HTTPModifier name="HM-remo>ve-<2">;
  R<emove
    !<-- Empty (F>ormParams/) removes all form par>amete<rs --
    F>ormPa<rams/
    Q>ueryPar<ams
      QueryParam n>ame=&<quot;qp1&quo>t;/<
    /Q>uer<yParams
>  /Remo<ve
  Assi>g<nTorequest/As>signTo
/HTTPModifier

Exemplo 2

O exemplo a seguir remove tudo de um objeto de mensagem:

<HTTPModifier name="HM-remo>ve-<3">
  <Remove/
>  Assig<nToreques>t</AssignTo
/HT>TPModifier

Normalmente, isso é feito apenas ao usar o elemento <Set> para definir alguns valores de substituição na mensagem.

`<FormParams>` (filho de `<Remove>`)

Remove os parâmetros de formulário especificados da solicitação. Esse elemento não afeta respostas.

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	Matriz de elementos `<FormParam>` ou uma matriz vazia
Elemento pai	`<Remove>`
Elemento filho	`<FormParam>`

O elemento <FormParams> usa a seguinte sintaxe:

Sintaxe

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
   > na<me="POLICY_NAME" 
  !-- Can also be empty to remove< everyt>hing fro<m the >messa<ge (Remove/) -->
  Remove
    !-- Can also be an empty< array to r>emove all <FormParams> (FormP<arams/) -->
    FormParams
 >     FormParam <name=">;FORMPARAM_NAME<"FORMP>ARA<M_VALUE>/<FormParam
   >   ...
    /FormParams
  /Remove
/HTTPModifier

Exemplo 1

O exemplo a seguir remove três parâmetros do formulário da solicitação:

<HTTPModifier name="HM-remove-formpara>ms-<1">;
  R<emove
    >FormPar<ams
      FormParam name=">;form_p<aram_1"/
      FormParam >name=&q<uot;form_param_2"/
      >FormP<aram name=&>quo<t;form_>par<am_3&quo>t;/
   < /FormPar>a<ms
  /Remove
>  AssignTorequest/AssignTo
/HTTPModifier

Exemplo 2

O exemplo a seguir remove todos os parâmetros de formulário da solicitação:

<HTTPModifier name="HM-remove-formpara>ms-<2">;
  R<emove
    F>orm<Params/>
  </Remove
>  Assig<nToreques>t</AssignTo
/HT>TPModifier

Exemplo 3

Se houver vários parâmetros do formulário com o mesmo nome, use a seguinte sintaxe:

<HTTPModifier name="HM-remove-formpara>ms-<3">;
  R<emove
    >FormPar<ams
      FormParam >name=&q<uot;f1"/
      >FormPar<am name="f2">/
   <   FormPara>m n<ame=&qu>ot;<f3.2&quo>t;/
   < /FormPar>a<ms
  /Remove
>  AssignTorequest/AssignTo
/HTTPModifier

Este exemplo remove f1, f2 e o segundo valor de f3. Se f3 tiver apenas um valor, ele não será removido.

Use <FormParams> somente quando os seguintes critérios forem atendidos:

Tipo de mensagem: solicitação
Content-Type: application/x-www-form-urlencoded

`<Headers>` (filho de `<Remove>`)

Remove os cabeçalhos HTTP especificados da solicitação ou resposta, conforme especificado pelo elemento <AssignTo>.

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	Matriz de elementos `<Header>` ou uma matriz vazia
Elemento pai	`<Remove>`
Elemento filho	`<Header>`

O elemento <Headers> usa a seguinte sintaxe:

Sintaxe

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
   > na<me="POLICY_NAME" 
  !-- Can also be empty to remove< everyt>hing fro<m the >messa<ge (Remove/) -->
  Remove
    !-- Can also be an em<pty arra>y to remov<e all H>eaders <(Headers/) -->
    Hea>ders
      H<eader n>ame="HEADE<R_NAME&q>uot<;HEADER>_<VALUE/Header
>      ...
    /Headers
  /Remove
/HTTPModifier

Exemplo 1

O exemplo a seguir remove o cabeçalho user-agent da solicitação:

<HTTPModifier name="HM-remove-one-he>ade<r">;
  R<emove
 >   Head<ers
      Header name=&qu>ot;us<er-agent>&qu<ot;/
  >  /<Headers
>  /Remo<ve
  Assi>g<nTorequest/As>signTo
/HTTPModifier

Exemplo 2

O exemplo a seguir remove todos os cabeçalhos da solicitação:

<HTTPModifier name="HM-remove-all-hea>der<s">;
  R<emove
  >  H<eaders/>
  </Remove
>  Assig<nToreques>t</AssignTo
/HT>TPModifier

Exemplo 3

Se houver vários cabeçalhos com o mesmo nome, use a seguinte sintaxe:

<HTTPModifier name="HM-remove-heade>rs-<3">;
  R<emove
 >   Head<ers
      Header >name=&q<uot;h1"/
   >   Head<er name="h2&qu>ot;/
<      He>ade<r name=>&qu<ot;h3.2&>quot;/
<    /Head>e<rs
  /Remove
>  AssignTorequest/AssignTo
/HTTPModifier

Este exemplo remove h1, h2 e o segundo valor de h3 da solicitação. Se h3 tiver apenas um valor, ele não será removido.

`<QueryParams>` (filho de `<Remove>`)

Remove os parâmetros de consulta especificados da solicitação. Esse elemento não afeta respostas.

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	Matriz de elementos `<QueryParam>` ou uma matriz vazia
Elemento pai	`<Remove>`
Elemento filho	`<QueryParam>`

O elemento <QueryParams> usa a seguinte sintaxe:

Sintaxe

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
   > na<me="POLICY_NAME" 
  !-- Can also be empty to remove< everyt>hing fro<m the >messa<ge (Remove/) -->
  Remove
    !-- Can also be an empty <array to rem>ove all Qu<eryParams (>QueryPa<rams/) -->
    QueryParams
   >   QueryParam na<me="QU>ERYPARAM_NAME&q<uot;QUERYPAR>AM_<VALUE/Q>u<eryParam
    >  ...
    /QueryParams
  /Remove
/HTTPModifier

Exemplo 1

O exemplo a seguir remove um único parâmetro de consulta da solicitação:

<HTTPModifier name="HM-remove-querypara>ms-<1">;
  Rem<ove
      Q>ueryParam<s
        QueryParam n>ame=&qu<ot;qp1">/
 <     /Q>uer<yParams
>  /Remo<ve
  Assi>g<nTorequest/As>signTo
/HTTPModifier

Exemplo 2

O exemplo a seguir remove todos os parâmetros de consulta da solicitação:

<HTTPModifier name="HM-remove-querypara>ms-&tl;2">;
  Rem<ove
      Qu>ery<Params/>
  </Remove
>  Assig<nToreques>t</AssignTo
/HT>TPModifier

Exemplo 3

Se houver vários parâmetros de consulta com o mesmo nome, use a seguinte sintaxe:

<HTTPModifier name="HM-remove-querypara>ms-<3">;
  Rem<ove
      Q>ueryParam<s
        QueryParam n>ame="<;qp1"/
        Qu>eryParam <name="qp2"/
  >      Q<ueryParam na>me=<"q>p3.<2"/>
      </QueryPar>a<ms
  /Remove
>  AssignTorequest/AssignTo
/HTTPModifier

Este exemplo remove qp1, qp2 e o segundo valor de qp3 da solicitação. Se qp3 tiver apenas um valor, ele não será removido.

Exemplo 4

O exemplo a seguir remove o parâmetro de consulta apikey da solicitação:

<HTTPModifier name="HM-remove-query-p>ara<m">;
  R<emove
    Q>ueryPar<ams
      QueryParam name>=&quo<t;apikey&quo>t;/<
    /Q>uer<yParams
>  /Remo<ve
  Assi>g<nTorequest/As>signTo
/HTTPModifier

Use <QueryParams> somente quando os seguintes critérios forem atendidos:

Verbos HTTP: GET e POST
Tipo de mensagem: solicitação

`<Set>`

Define informações na mensagem de solicitação ou resposta especificada pelo elemento <AssignTo>. <Set> substitui os cabeçalhos ou parâmetros de consulta ou de formulário que já existem na mensagem original ou adiciona novos quando eles não existem.

Os cabeçalhos e os parâmetros de consulta e de formulário em uma mensagem HTTP podem conter vários valores. Para adicionar mais valores para um cabeçalho ou parâmetro, use o elemento <Add>.

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	Tipo complexo
Elemento pai	`<HTTPModifier>`
Elemento filho	`<FormParams>` `<Headers>` `<Path>` `<QueryParams>` `<StatusCode>` `<Verb>` `<Version>`

Observação: os subelementos de <Set> são compatíveis com o recurso de substituição de strings dinâmicas chamado modelo de mensagem.

O elemento <Set> usa a seguinte sintaxe:

Sintaxe

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
   > na<me=>"<;POLICY_NA>ME"<; 
  Set
    FormParams
      F>ormParam name=&<quot;FORMP>ARAM_NAME"<FORMPARAM_V>ALUE/<FormPar>am
    <  ...
    /FormParams
   > Headers
   <   Head>er name="H<EADER_NA>ME&qu<ot;H>EADE<R_VAL>UE/He<ader
      >...
   < /Headers
    PathPATH/Path
    Q>ueryParams
     < QueryParam> name="QUE<RYPARAM_NAME>"<;QUERYPARA>M_VALUE/QueryParam
      ...
 <   /QueryPa>rams
<    >StatusCodeHTTP_STATUS_CODE or {variabl<e}/St>atusC<ode
   > Verb[GET|POST|PUT|P<ATCH|>DEL<ETE|>{<variable}]/Ve>rb
    Version[1.0|1.1|{variable}]/Verb
  /Set
/HTTPModifier

Exemplo

O exemplo a seguir define um cabeçalho específico. Quando essa política é anexada no fluxo de solicitações, o sistema upstream pode receber um cabeçalho extra que não foi incluído na solicitação de entrada original.

<HTTPModifier name="HM-Set-He>ade<r&q>uot;
<  Set
 >   Header<s
        Header name="authentic>ated-developer"{verifyapikey<.VAK-1.>devel<oper.id}>/He<ader>
  <  /Heade>rs
  /S<et
  Assi>g<nTorequest/As>signTo
/HTTPModifier

`<FormParams>` (filho de `<Set>`)

Substitui os parâmetros de formulário atuais em uma solicitação e os substitui pelos novos valores especificados com este elemento. Esse elemento não afeta respostas.

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	Matriz de elementos `<FormParam>`
Elemento pai	`<Set>`
Elemento filho	`<FormParam>`

O elemento <FormParams> usa a seguinte sintaxe:

Sintaxe

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
   > na<me=>&quot<;POLICY_NA>ME"<; 
  Set
    FormParams
      F>ormParam name=&<quot;FORMP>ARAM_NAME"<FORMPARAM_V>ALU<E/Fo>r<mParam
      >...
    /FormParams
  /Set
/HTTPModifier

Exemplo 1

No exemplo a seguir, definimos um parâmetro de formulário chamado myparam como o valor da variável request.header.myparam em uma nova solicitação personalizada:

<HTTPModifier name="HM-set-formpara>ms-<1&q>uot;
<  Set
    >FormPar<ams
      FormParam name>="myparam"{req<uest.heade>r.myp<aram}/FormP>ara<m
  >  /<FormParams
  /Set
  AssignTo createNew="true" >>transport="<;http&quo>t<; type=">requestMyCustomRequest/AssignTo
/HTTPModifier

Use <FormParams> somente quando os seguintes critérios forem atendidos:

Verbo HTTP: POST
Tipo de mensagem: solicitação

Se você definir parâmetros de formulário vazios na política (<Add><FormParams/></Add>), a política não adicionará parâmetros de formulário. Isso é o mesmo que omitir <FormParams>.

<Set> altera o Content-Type da mensagem para application/x-www-form-urlencoded antes de enviá-la para o endpoint de destino.

`<Headers>` (filho de `<Set>`)

Substitui os cabeçalhos HTTP atuais na solicitação ou na resposta, conforme especificado pelo elemento <AssignTo>.

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	Matriz de elementos `<Header>`
Elemento pai	`<Set>`
Elemento filho	`<Header>`

O elemento <Headers> usa a seguinte sintaxe:

Sintaxe

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
   > na<me=>&quot<;POLICY>_NAME&q<uot; 
  Set
    Headers
 >     Header <name=&q>uot;HEADER_NAME<"HE>ADE<R_VA>L<UE/Header
   >   ...
    /Headers
  /Set
/HTTPModifier

Exemplo 1

O exemplo a seguir define o cabeçalho x-ratelimit-remaining como o valor da variável ratelimit.Quota-1.available.count:

<HTTPModifier name="HM-Set-RateLimit-He>ade<r&q>uot;
<  Set
 >   Head<ers
      Header name="X-RateL>imit-Remaining"{ratelimit.Quot<a-1.ava>ilabl<e.count}>/He<ader>
  <  /Heade>rs
  /Se<t
  Assig>n<Toresponse/As>signTo
/HTTPModifier

Se você definir cabeçalhos vazios na política (<Set><Headers/></Set>), a política não adicionará cabeçalhos. Isso terá o mesmo efeito que a omissão de <Headers>.

`<Path>` (filho de `<Set>`)

`<QueryParams>` (filho de `<Set>`)

Substitui os parâmetros de consulta atuais na solicitação por novos valores. Esse elemento não tem efeito em uma resposta.

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	Matriz de elementos `<QueryParam>`
Elemento pai	`<Set>`
Elemento filho	`<QueryParam>`

O elemento <QueryParams> usa a seguinte sintaxe:

Sintaxe

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
   > na<me=>&quot<;POLICY_NAM>E"< 
  Set
    QueryParams
      Que>ryParam name=&qu<ot;QUERYPAR>AM_NAME"QU<ERYPARAM_VAL>UE/<Quer>y<Param
      .>..
    /QueryParams
  /Set
/HTTPModifier

Exemplo 1

No exemplo a seguir, o parâmetro de consulta address é definido como o valor da variável request.header.address:

<HTTPModifier name="HM-set-querypara>ms-<1&q>uot;
<  Set
    Q>ueryPar<ams
      QueryParam name>="address"{req<uest.header>.addr<ess}/QueryPa>ram<
   > </QueryParams
>  /Set
/HTTPModifier

Use <QueryParams> somente quando os seguintes critérios forem atendidos:

Verbos HTTP: GET e POST
Tipo de mensagem: solicitação

Se você definir parâmetros de consulta vazios na política (<Set><QueryParams/></Set>), a política não adicionará parâmetros de consulta. Isso é o mesmo que omitir <QueryParams>.

`<StatusCode>` (filho de `<Set>`)

Define o código de status da resposta. Esse elemento não afeta solicitações.

Valor padrão	'200' (quando o atributo `createNew` de `<AssignTo>` for definido como 'true')
Obrigatório?	Opcional
Tipo	String ou `VARIABLE`
Elemento pai	`<Set>`
Elemento filho	Nenhum

O elemento <StatusCode> usa a seguinte sintaxe:

Sintaxe

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
   > na<me=>&quot<;POLICY_NA>ME" 
  Set
    StatusCode<HTTP_STATUS>_CO<DE o>r< {variable}/S>tatusCode
  /Set
/HTTPModifier

Exemplo 1

O exemplo a seguir define um código de status simples:

<HTTPModifier name="HM-set-statuscode>-40<4&q>uot;
<  Set
    >Stat<usCode404&>lt;<Stat>usC<ode
  /S>et
  Ass<ignToresp>o<nse/AssignTo
>/HTTPModifier

Exemplo 2

O conteúdo de <StatusCode> é tratado como um modelo de mensagem. Isso significa que um nome de variável entre chaves será substituído no ambiente de execução pelo valor da variável referenciada, como mostrado no exemplo a seguir:

<HTTPModifier name="set-statusco>de-<2&q>uot;
<  Set
    >StatusCode{calloutresponse.st<atus.code}/>Sta<tusC>ode<
  /Set
>  Assign<Torespons>e</AssignTo
/HT>TPModifier

Use <StatusCode> somente quando os seguintes critérios forem atendidos:

Tipo de mensagem: resposta

`<Verb>` (filho de `<Set>`)

Define o verbo HTTP na solicitação. Esse elemento não afeta respostas.

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	String ou `VARIABLE`
Elemento pai	`<Set>`
Elemento filho	Nenhum

O elemento <Verb> usa a seguinte sintaxe:

Sintaxe

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
   > na<me=>&quot<;POL>ICY_NAME" 
  Set
    Verb[GET|POS<T|PUT>|PA<TCH|>D<ELETE|{variab>le}]/Verb
  /Set
/HTTPModifier

Exemplo 1

No exemplo a seguir, definimos um verbo simples na solicitação:

<HTTPModifier name="HM-set-ve>rb-<1&q>uot;
<  Se>t
  <  Ver>bPO<ST/V>erb<
  /Set
>  Assig<nToreques>t</AssignTo
/HT>TPModifier

Exemplo 2

O conteúdo de <Verb> é tratado como um modelo de mensagem. Isso significa que um nome de variável entre chaves será substituído no ambiente de execução pelo valor da variável referenciada.

O exemplo a seguir usa uma variável para preencher um verbo:

<HTTPModifier name="HM-set-verb-to-dynamic-v>alu<e&q>uot;
<  Se>t
    Verb{my<_vari>abl<e}/V>erb<
  /Set
>  Assig<nToreques>t</AssignTo
/HT>TPModifier

Use <Verb> somente quando os seguintes critérios forem atendidos:

Tipo de mensagem: solicitação

`<Version>` (filho de `<Set>`)

Define a versão HTTP em uma solicitação. Esse elemento não afeta respostas.

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	String ou `VARIABLE`
Elemento pai	`<Set>`
Elemento filho	Nenhum

O elemento <Version> usa a seguinte sintaxe:

Sintaxe

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
   > na<me=>&quot<;POLICY>_NAME" 
  Set
 <   Ve>rsi<on[1>.<0|1.1|{variab>le}]/Verb
  /Set
/HTTPModifier

Exemplo 1

O exemplo a seguir define o número da versão como 1.1:

<HTTPModifier name="HM-set-versi>on-<1&q>uot;
<  Set
 >   <Version1>.1/<Vers>i<on
  /Set
/HT>TPModifier

Exemplo 2

O exemplo a seguir usa uma variável entre chaves para definir o número da versão:

<HTTPModifier name="HM-set-versi>on-<2&q>uot;
<  Set
 >   Version{m<y_versio>n}/<Vers>ion<
  /Set
>  Assig<nToreques>t</AssignTo
/HT>TPModifier

O conteúdo de <Version> é tratado como um modelo de mensagem. Isso significa que um nome de variável entre chaves será substituído no ambiente de execução pelo valor da variável referenciada.

Use <Version> somente quando os seguintes critérios forem atendidos:

Tipo de mensagem: solicitação

Criar mensagens de solicitação personalizadas

Use HTTPModifier para criar uma mensagem de solicitação personalizada. Depois de criar uma solicitação personalizada, ela pode ser usada das seguintes maneiras:

Acessar as variáveis em outras políticas
Passar para um serviço externo

Para criar uma mensagem de solicitação personalizada, use o elemento <AssignTo> na política HTTPModifier. Defina createNew como true e especifique o nome da nova mensagem no corpo do elemento, como no exemplo a seguir:

<HTTPModifier name="assign>to-3&<quot;
    AssignTo createNew="true" transport=&>quot;http"< type=&qu>ot;request&<quot;MyReques>tObject/AssignTo
    ...
  /HTTPModifier

Por padrão, o Apigee não faz nada com a mensagem de solicitação personalizada. Depois de criá-la, a Apigee continuará no fluxo com a solicitação original. Para usar a solicitação personalizada, adicione uma política que use a mensagem de solicitação e faça referência explícita à mensagem de solicitação recém-criada na configuração associada. Com isso, será possível transmitir a solicitação personalizada para um endpoint de serviço externo.

Os exemplos a seguir criam mensagens de solicitação personalizadas:

Exemplo 1

O seguinte exemplo cria um objeto de solicitação personalizado com HTTPModifier:

<HTTPModifier name="HTTPModifi>er-<3"
  AssignTo createNew="true&>quot; type=&quo<t;request>&qu<ot;>MyCus<tomRequest/>AssignT<o
  Set
    QueryParams
 >     QueryParam name=&quo<t;address&q>uot;{<request.quer>ypara<m.ad>dy}</Quer>yPa<ram<>/span>
   < /QueryParams
    VerbGET>/Verb<
  /Set
  IgnoreUnresolved>V<ariablesfalse>/IgnoreUnresolvedVariables
/HTTPModifier

Este exemplo:

Cria um novo objeto de mensagem de solicitação chamado MyCustomRequest.
Em MyCustomRequest, esta política:
- Define o parâmetro de consulta address na mensagem personalizada para o valor do parâmetro de consulta addy da solicitação recebida.
- Define o verbo HTTP como GET.
Define <IgnoreUnresolvedVariables> como false. Quando <IgnoreUnresolvedVariables> for false, se uma das variáveis referenciadas na configuração da política não existir, a Apigee inserirá o estado de falha no fluxo da API.

Exemplo 2

Veja outro exemplo que demonstra como criar um objeto de solicitação personalizado com HTTPModifier.

<HTTPModifier name="HTTPModifi>er-<2"
  AssignTo createNew="true&>quot; type=&quo<t;request>&qu<ot;>partn<er.r>eque<st/As>sig<nTo<>/span>
 < Set
    Verb>POST/Verb
  /Set
/HTTPModifier

Neste exemplo, você cria uma nova solicitação personalizada chamada partner.request. Em seguida, ela define <Verb> na nova solicitação.

É possível acessar as várias propriedades de uma mensagem personalizada em outra política HTTPModifier que ocorra posteriormente no fluxo. O exemplo a seguir recebe o valor de um cabeçalho de uma resposta personalizada nomeada e o coloca em um novo cabeçalho na mensagem da solicitação:

<HTTPModifier name="HM-Set-He>ade<r"
>  Assig<nToreques>t/A<ssi>gnTo
<  Set
 >   Head<ers
      Header name="inject>ed-approval-id"{MyCalloutResponse<.header>.appr<oval-id}>/He<ader>
<    /Headers
>  /Set
/HTTPModifier

Códigos de erro

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Cause	Fix
`entities.UnresolvedVariable`	`500`	Message Template Variable in Undefined or out of scope.
`steps.httpmodifier.InvalidStatusCode`	`500`	The resolved value of the status code is not valid. See the fault string for more information.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name	Cause	Fix
`InvalidIndex`	If the index specified in the `<Remove>` elements of the `HTTPModifier` policy is `0` or a negative number, then deployment of the API Proxy fails.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

Variables	Where	Example
`httpmodifier.POLICY_NAME.failed`	`POLICY_NAME` is the user-specified name of the policy that threw the fault.	`httpmodifier.HM-SetResponse.failed = true`

Example error response

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{
   "fault":{
      "detail":{
         "errorcode":"steps.httpmodifier.InvalidStatusCode"
      },
      "faultstring":"HTTPModifier[HM-SetResponse]: Invalid status code bad_request"
   }
}

Example fault rule

<FaultRule name="HTTPModifier Faults">
    <Step>
        <Name>HM-CustomNonMessageTypeErrorResponse</Name>
        <Condition>(fault.name Matches "InvalidStatusCode")</Condition>
    </Step>
    <Condition>(httpmodifier.failed = true)</Condition>
</FaultRule>

Esquemas

Cada tipo de política é definido por um esquema XML (.xsd). Para referência, os esquemas de política estão disponíveis no GitHub.

Política HTTPModifier Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Casos de uso

Elemento <HTTPModifier>

Sintaxe

Política padrão

Exemplos

1: Adicionar cabeçalho

2: Modificar resposta

3: Remover o parâmetro de consulta

Referência a elementos filhos

<Add>

Sintaxe

Exemplo 1

Exemplo 2

Exemplo 3

<FormParams> (filho de <Add>)

Sintaxe

Exemplo 1

Exemplo 2

Exemplo 3

<Headers> (filho de <Add>)

Sintaxe

Exemplo 1

<QueryParams> (filho de <Add>)

Sintaxe

Exemplo 1

<AssignTo>

Sintaxe

Exemplo 1

Exemplo 2

Exemplo 3

<DisplayName>

Sintaxe

Exemplo

<IgnoreUnresolvedVariables>

Sintaxe

Exemplo 1

<Remove>

Sintaxe

Exemplo 1

Exemplo 2

<FormParams> (filho de <Remove>)

Sintaxe

Exemplo 1

Exemplo 2

Exemplo 3

<Headers> (filho de <Remove>)

Sintaxe

Exemplo 1

Exemplo 2

Exemplo 3

<QueryParams> (filho de <Remove>)

Sintaxe

Exemplo 1

Exemplo 2

Exemplo 3

Exemplo 4

<Set>

Sintaxe

Exemplo

<FormParams> (filho de <Set>)

Sintaxe

Exemplo 1

<Headers> (filho de <Set>)

Sintaxe

Exemplo 1

<Path> (filho de <Set>)

<QueryParams> (filho de <Set>)

Sintaxe

Exemplo 1

<StatusCode> (filho de <Set>)

Sintaxe

Exemplo 1

Exemplo 2

<Verb> (filho de <Set>)

Sintaxe

Exemplo 1

Exemplo 2

<Version> (filho de <Set>)

Sintaxe

Política HTTPModifier

Elemento `<HTTPModifier>`

`<Add>`

`<FormParams>` (filho de `<Add>`)

`<Headers>` (filho de `<Add>`)

`<QueryParams>` (filho de `<Add>`)

`<AssignTo>`

`<DisplayName>`

`<IgnoreUnresolvedVariables>`

`<Remove>`

`<FormParams>` (filho de `<Remove>`)

`<Headers>` (filho de `<Remove>`)

`<QueryParams>` (filho de `<Remove>`)

`<Set>`

`<FormParams>` (filho de `<Set>`)

`<Headers>` (filho de `<Set>`)

`<Path>` (filho de `<Set>`)

`<QueryParams>` (filho de `<Set>`)

`<StatusCode>` (filho de `<Set>`)

`<Verb>` (filho de `<Set>`)

`<Version>` (filho de `<Set>`)