Política HTTPModifier

O que

A política HTTPModifier pode alterar uma solicitação ou uma mensagem de 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.

HTTPModifier fornece um subconjunto da funcionalidade da política AssignMessage. Consulte Política AssignMessage para mais funcionalidades, incluindo como atribuir variáveis, modificar payloads e copiar valores da mensagem.

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

• <Add>
• <Set>
• <Remove>
• <AssignTo>

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. Nem todos os usuários têm necessidade de saber sobre os tipos de política e 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. 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]"
    name="POLICY_NAME" >
  <!-- All HTTPModifier child elements are optional -->
  <Add>
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
    <Headers>
      <Header name="HEADER_NAME">HEADER_VALUE</Header>
      ...
    </Headers>
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME">QUERYPARAM_VALUE</QueryParam>
      ...
    </QueryParams>
  </Add>

  <AssignTo createNew="[true|false]" transport="http"
    type="[request|response]">DESTINATION_VARIABLE_NAME</AssignTo>

  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>

  <IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>

  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Can also be an empty array to remove all FormParams (<FormParams/>) -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
    <!-- Can also be an empty array to remove all Headers (<Headers/>) -->
    <Headers>
      <Header name="HEADER_NAME">HEADER_VALUE</Header>
      ...
    </Headers>
    <!-- Can also be an empty array to remove all QueryParams (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME">QUERYPARAM_VALUE</QueryParam>
      ...
    </QueryParams>
  </Remove>

  <Set>
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
    <Headers>
      <Header name="HEADER_NAME">HEADER_VALUE</Header>
      ...
    </Headers>
    <Path>PATH</Path>
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME">QUERYPARAM_VALUE</QueryParam>
      ...
    </QueryParams>
    <StatusCode>HTTP_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="http-modifier-default">
  <DisplayName>HTTP Modifier-1</DisplayName>
  <Properties/>
  <Remove>
    <Headers>
      <Header name="h1"/>
    </Headers>
    <QueryParams>
      <QueryParam name="q1"/>
    </QueryParams>
    <FormParams>
      <FormParam name="f1"/>
    </FormParams>
  </Remove>
  <Add>
    <Headers/>
    <QueryParams/>
    <FormParams/>
  </Add>
  <Set>
    <Headers/>
    <QueryParams/>
    <FormParams/>
    <!-- <Verb>GET</Verb> -->
    <Path/>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="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.

Examples

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-headers-1">
  <Add>
    <Headers>
      <Header name="partner-id">{verifyapikey.VAK-1.developer.app.partner-id}</Header>
    </Headers>
  </Add>
  <AssignTo>request</AssignTo>
</HTTPModifier>

2: Modificar resposta

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

<HTTPModifier name="HM-modify-response">
  <Set>
    <Headers>
      <Header name="Cache-Hit">{lookupcache.LookupCache-1.cachehit}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignTo>response</AssignTo>
</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.

Dica: esse padrão de configuração de cabeçalhos para depuração e solução de problemas é uma prática comum. Para ver qual valor de cabeçalho foi enviado, inspecione a resposta com a ferramenta Debug ou de outra maneira.

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-param">
  <Remove>
    <QueryParams>
      <QueryParam name="apikey"/>
    </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</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]"
    name="POLICY_NAME" >
  <Add>
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
    <Headers>
      <Header name="HEADER_NAME">HEADER_VALUE</Header>
      ...
    </Headers>
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME">QUERYPARAM_VALUE</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-formparams-3">
  <Add>
    <FormParams>
      <FormParam name="username">{request.queryparam.name}</FormParam>
      <FormParam name="zip_code">{request.queryparam.zipCode}</FormParam>
      <FormParam name="default_language">{request.queryparam.lang}</FormParam>
    </FormParams>
  </Add>
  <Remove>
    <QueryParams/>
  </Remove>
  <AssignTo>request</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-headers-1">
  <Add>
    <Headers>
      <Header name="partner-id">{verifyapikey.VAK-1.developer.app.partner-id}</Header>
    </Headers>
  </Add>
  <AssignTo>request</AssignTo>
</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-queryparams-1">
  <Add>
    <QueryParams>
      <QueryParam name="myParam">42</QueryParam>
    </QueryParams>
  </Add>
  <AssignTo>request</AssignTo>
</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]"
    name="POLICY_NAME" >
  <Add>
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
  <AssignTo createNew="[true|false]" transport="http"
    type="[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-formparams-1">
  <Add>
    <FormParams>
      <FormParam name="answer">42</FormParam>
    </FormParams>
  </Add>
  <AssignTo>request</AssignTo>
</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-FormParams">
  <Add>
    <FormParam name="name">{request.queryparam.name}
  </Add>
  <Remove>
    <QueryParam name="name"/>
  </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-formparams-3">
  <Add>
    <FormParams>
      <FormParam name="username">{request.queryparam.name}</FormParam>
      <FormParam name="zip_code">{request.queryparam.zipCode}</FormParam>
      <FormParam name="default_language">{request.queryparam.lang}</FormParam>
    </FormParams>
  </Add>
  <Remove>
    <QueryParams/>
  </Remove>
  <AssignTo>request</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.

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]"
    name="POLICY_NAME" >
  <Add>
    <Headers>
      <Header name="HEADER_NAME">HEADER_VALUE</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-headers-1">
  <Add>
    <Headers>
      <Header name="partner-id">{verifyapikey.VAK-1.developer.app.partner-id}</Header>
    </Headers>
  </Add>
  <AssignTo>request</AssignTo>
</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]"
    name="POLICY_NAME" >
  <Add>
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME">QUERYPARAM_VALUE</QueryParam>
      ...
    </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-queryparams-1">
  <Add>
    <QueryParams>
      <QueryParam name="myParam">42</QueryParam>
    </QueryParams>
  </Add>
  <AssignTo>request</AssignTo>
</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]"
    name="POLICY_NAME" >
  <AssignTo createNew="[true|false]" transport="http"
    type="[request|response]">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="assignto-1">
  <AssignTo createNew="false" transport="http" type="request"/>
  ...
</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="assignto-2">
  <AssignTo createNew="true" transport="http" 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="assignto-3">
  <AssignTo createNew="true" transport="http" type="request">MyRequestObject</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
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	Booleanos
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	Nenhuma

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	Booleanos
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]"
    name="POLICY_NAME" >
  <IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>
</HTTPModifier>

Exemplo 1

O exemplo a seguir define <IgnoreUnresolvedVariables> como true:

<HTTPModifier name="HM-Set-Headers">
  <Set>
    <Headers>
      <Header name='new-header'>{possibly-defined-variable}<Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</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]"
    name="POLICY_NAME" >
  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Can also be an empty array to remove all FormParams (<FormParams/>) -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
    <!-- Can also be an empty array to remove all Headers (<Headers/>) -->
    <Headers>
      <Header name="HEADER_NAME">HEADER_VALUE</Header>
      ...
    </Headers>
    <!-- Can also be an empty array to remove all QueryParams (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME">QUERYPARAM_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-remove-2">
  <Remove>
    <!-- Empty (<FormParams/>) removes all form parameters -->
    <FormParams/>
    <QueryParams>
      <QueryParam name="qp1"/>
    </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</HTTPModifier>

Exemplo 2

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

<HTTPModifier name="HM-remove-3">
  <Remove/>
  <AssignTo>request</AssignTo>
</HTTPModifier>

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]"
    name="POLICY_NAME" >
  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Can also be an empty array to remove all FormParams (<FormParams/>) -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_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-formparams-1">
  <Remove>
    <FormParams>
      <FormParam name="form_param_1"/>
      <FormParam name="form_param_2"/>
      <FormParam name="form_param_3"/>
    </FormParams>
  </Remove>
  <AssignTo>request</AssignTo>
</HTTPModifier>

Exemplo 2

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

<HTTPModifier name="HM-remove-formparams-2">
  <Remove>
    <FormParams/>
  </Remove>
  <AssignTo>request</AssignTo>
</HTTPModifier>

Exemplo 3

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

<HTTPModifier name="HM-remove-formparams-3">
  <Remove>
    <FormParams>
      <FormParam name="f1"/>
      <FormParam name="f2"/>
      <FormParam name="f3.2"/>
    </FormParams>
  </Remove>
  <AssignTo>request</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]"
    name="POLICY_NAME" >
  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Can also be an empty array to remove all Headers (<Headers/>) -->
    <Headers>
      <Header name="HEADER_NAME">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-header">
  <Remove>
    <Headers>
      <Header name="user-agent"/>
    </Headers>
  </Remove>
  <AssignTo>request</AssignTo>
</HTTPModifier>

Exemplo 2

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

<HTTPModifier name="HM-remove-all-headers">
  <Remove>
    <Headers/>
  </Remove>
  <AssignTo>request</AssignTo>
</HTTPModifier>

Exemplo 3

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

<HTTPModifier name="HM-remove-headers-3">
  <Remove>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
  </Remove>
  <AssignTo>request</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]"
    name="POLICY_NAME" >
  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Can also be an empty array to remove all QueryParams (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME">QUERYPARAM_VALUE</QueryParam>
      ...
    </QueryParams>
  </Remove>
</HTTPModifier>

Exemplo 1

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

<HTTPModifier name="HM-remove-queryparams-1">
  <Remove>
      <QueryParams>
        <QueryParam name="qp1"/>
      </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</HTTPModifier>

Exemplo 2

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

<HTTPModifier name="HM-remove-queryparams-2">
  &tl;Remove>
      <QueryParams/>
  </Remove>
  <AssignTo>request</AssignTo>
</HTTPModifier>

Exemplo 3

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

<HTTPModifier name="HM-remove-queryparams-3">
  <Remove>
      <QueryParams>
        <QueryParam name="qp1"/>
        <QueryParam name="qp2"/>
        <QueryParam name="qp3.2"/>
      </QueryParams>
  </Remove>
  <AssignTo>request</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-param">
  <Remove>
    <QueryParams>
      <QueryParam name="apikey"/>
    </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</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]"
    name="POLICY_NAME" >
  <Set>
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
    <Headers>
      <Header name="HEADER_NAME">HEADER_VALUE</Header>
      ...
    </Headers>
    <Path>PATH</Path>
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME">QUERYPARAM_VALUE</QueryParam>
      ...
    </QueryParams>
    <StatusCode>HTTP_STATUS_CODE or {variable}</StatusCode>
    <Verb>[GET|POST|PUT|PATCH|DELETE|{variable}]</Verb>
    <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-Header">
  <Set>
    <Headers>
        <Header name="authenticated-developer">{verifyapikey.VAK-1.developer.id}</Header>
    </Headers>
  </Set>
  <AssignTo>request</AssignTo>
</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]"
    name="POLICY_NAME" >
  <Set>
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </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-formparams-1">
  <Set>
    <FormParams>
      <FormParam name="myparam">{request.header.myparam}</FormParam>
    </FormParams>
  </Set>
  <AssignTo createNew="true" transport="http" type="request>>MyCustomRequest</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]"
    name="POLICY_NAME" >
  <Set>
    <Headers>
      <Header name="HEADER_NAME">HEADER_VALUE</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-Header">
  <Set>
    <Headers>
      <Header name="X-RateLimit-Remaining">{ratelimit.Quota-1.available.count}</Header>
    </Headers>
  </Set>
  <AssignTo>response</AssignTo>
</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>)

Observação:

No momento, esse elemento não está funcionando como projetado para substituir/regravar o URL de destino de um proxy.

Às vezes, pode ser necessário enviar uma mensagem para um URL diferente do URL definido no TargetEndpoint do proxy de API. (Não é possível substituir target.url em ProxyEndpoint, porque a Apigee define a variável em TargetEndpoint).

<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]"
    name="POLICY_NAME" >
  <Set>
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME">QUERYPARAM_VALUE</QueryParam>
      ...
    </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-queryparams-1">
  <Set>
    <QueryParams>
      <QueryParam name="address">{request.header.address}</QueryParam>
    </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	Nenhuma

O elemento <StatusCode> usa a seguinte sintaxe:

Sintaxe

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Set>
    <StatusCode>HTTP_STATUS_CODE or {variable}</StatusCode>
  </Set>
</HTTPModifier>

Exemplo 1

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

<HTTPModifier name="HM-set-statuscode-404">
  <Set>
    <StatusCode>404<<StatusCode>
  </Set>
  <AssignTo>response</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-statuscode-2">
  <Set>
    <StatusCode>{calloutresponse.status.code}</StatusCode>
  </Set>
  <AssignTo>response</AssignTo>
</HTTPModifier>

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	Nenhuma

O elemento <Verb> usa a seguinte sintaxe:

Sintaxe

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Set>
    <Verb>[GET|POST|PUT|PATCH|DELETE|{variable}]</Verb>
  </Set>
</HTTPModifier>

Exemplo 1

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

<HTTPModifier name="HM-set-verb-1">
  <Set>
    <Verb>POST</Verb>
  </Set>
  <AssignTo>request</AssignTo>
</HTTPModifier>

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-value">
  <Set>
    <Verb>{my_variable}</Verb>
  </Set>
  <AssignTo>request</AssignTo>
</HTTPModifier>

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	Nenhuma

O elemento <Version> usa a seguinte sintaxe:

Sintaxe

<HTTPModifier
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Set>
    <Version>[1.0|1.1|{variable}]</Verb>
  </Set>
</HTTPModifier>

Exemplo 1

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

<HTTPModifier name="HM-set-version-1">
  <Set>
    <Version>1.1</Version>
  </Set>
</HTTPModifier>

Exemplo 2

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

<HTTPModifier name="HM-set-version-2">
  <Set>
    <Version>{my_version}</Version>
  </Set>
  <AssignTo>request</AssignTo>
</HTTPModifier>

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

Observação: não é possível passar uma mensagem de solicitação personalizada para o endpoint de destino no fluxo. O Apigee passa apenas a solicitação original (com todas as modificações que você tenha feito) ao endpoint de destino.

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="assignto-3">
    <AssignTo createNew="true" transport="http" type="request">MyRequestObject</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="HTTPModifier-3">
  <AssignTo createNew="true" type="request">MyCustomRequest</AssignTo>
  <Set>
    <QueryParams>
      <QueryParam name="address">{request.queryparam.addy}</QueryParam>
    </QueryParams>
    <Verb>GET</Verb>
  </Set>
  <IgnoreUnresolvedVariables>false</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="HTTPModifier-2">
  <AssignTo createNew="true" type="request">partner.request</AssignTo>
  <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-Header">
  <AssignTo>request</AssignTo>
  <Set>
    <Headers>
      <Header name="injected-approval-id">{MyCalloutResponse.header.approval-id}</Header>
    </Headers>
  </Set>
</HTTPModifier>

Códigos de erro

Esta seção descreve os códigos de falha e as mensagens de erro que são retornadas e as variáveis de falha definidas pela Apigee quando essa política aciona um erro. Essas informações são importantes para saber se você está desenvolvendo regras de falha para lidar com falhas. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.

Erros de execução

Esses erros podem ocorrer quando a política é executada.

Dica: precisa de ajuda para resolver um erro? Clique em na coluna Correção para ver informações detalhadas de solução de problemas.

Código de falha	Status HTTP	Causa	Corrigir
entities.UnresolvedVariable	500	Variável do modelo de mensagem com status indefinido ou fora de escopo.
steps.httpmodifier.InvalidStatusCode	500	O valor resolvido do código de status não é válido. Consulte a string de falha para mais informações.

Erros de implantação

Esses erros podem ocorrer quando você implanta um proxy que contém esta política.

Dica: precisa de ajuda para resolver um erro? Clique em ao lado da descrição do erro para acessar a página de solução de problemas.

Nome do erro	Causa	Corrigir
InvalidIndex	Se o índice especificado nos elementos <Remove> da política HTTPModifier for 0 ou um número negativo, a implantação do proxy de API falhará.

Variáveis de falha

Essas variáveis são definidas quando essa política aciona um erro no ambiente de execução. Para mais informações, consulte O que você precisa saber sobre erros de política.

Variáveis	Onde	Exemplo
httpmodifier.POLICY_NAME.failed	POLICY_NAME é o nome da política especificada pelo usuário que gerou a falha.	httpmodifier.HM-SetResponse.failed = true

Exemplo de resposta de erro

Observação: para tratamento de erros, a prática recomendada é interceptar a parte errorcode da resposta de erro. Não confie no texto do faultstring, porque ele pode mudar.

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

Exemplo de regra de falha

<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.