Política AssignMessage

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

Confira a documentação da Apigee Edge.

O que

A política AssignMessage pode alterar uma mensagem de solicitação ou resposta existente ou criar uma nova mensagem de solicitação ou resposta durante o fluxo de proxy da API. 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
• Copiar propriedades atuais de uma mensagem para outra
• Remover cabeçalhos, parâmetros de consulta, parâmetros de formulário e payloads de mensagens
• Definir o valor das properties em uma mensagem

A AssignMessage também permite definir variáveis de contexto arbitrárias, independentemente de qualquer uma das operações acima que podem se aplicar a uma mensagem.

A política AssignMessage pode ser usada para adicionar, alterar ou remover propriedades da solicitação ou da resposta. Por outro lado, é possível usar a política AssignMessage para criar uma mensagem de resposta ou solicitação personalizada e transmiti-la para um destino alternativo, conforme descrito em Criar mensagens de solicitação personalizadas.

Esta é uma política extensível. O uso dela pode ter implicações no custo ou na utilização, dependendo da sua licença da Apigee. Para informações sobre tipos de política e implicações de uso, consulte Tipos de política.

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.
• Inserir o conteúdo da mensagem JSON ou XML antes de enviar uma resposta.
• Gerar mensagens completas de solicitação ou resposta. Por exemplo, é possível usar uma política ServiceCallout para invocar uma API remota de um proxy de API. A política AssignMessage pode ser usada para criar uma mensagem de solicitação personalizada e atribuí-la a uma variável. Em seguida, use ServiceCallout para enviar essa mensagem à API remota.
• Adicionar cabeçalhos a solicitações e respostas para depuração e solução de problemas.

Vídeos

Assista aos vídeos abaixo para saber mais sobre a política AssignMessage.

Vídeo	Descrição
Por que a política "Atribuir mensagem"?	Saiba mais sobre os benefícios de usar a política AssignMessage para modificar a solicitação ou a resposta da API sem modificar o código de back-end.
Copiar elementos da API usando a política AssignMessage	Copie elementos de uma solicitação ou resposta de API e crie uma nova solicitação ou objeto de resposta usando a política AssignMessage.
Remover elementos da API usando a política AssignMessage	Remova os elementos da API e modifique a API antes de ela atingir o back-end de destino usando a política AssignMessage.
Adicionar e definir elementos da API usando a política AssignMessage	Altere a solicitação ou a resposta da API adicionando parâmetros de consulta, cabeçalhos, parâmetros de formulário ou payloads usando a política AssignMessage.
Criar variáveis personalizadas usando a política AssignMessage	Defina variáveis de fluxo personalizadas usando a política AssignMessage e utilize as variáveis em outras políticas no proxy da API.
Criar novos objetos de solicitação ou resposta usando a política AssignMessage	Crie novos objetos de solicitação ou resposta de API usando a política AssignMessage no ambiente de execução da API.
Criar uma API de simulação usando a política AssignMessage	Crie uma API REST simples de simulação adicionando a política AssignMessage ao fluxo de resposta.
Definir ou modificar o payload usando a política AssignMessage	Converta uma solicitação REST em solicitação SOAP ao configurar o payload SOAP com uma política AssignMessage no ambiente de execução da API.

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

• <Add>
• <Copy>
• <Set>
• <Remove>
• <AssignTo>
• <AssignVariable>

A ordem em que você organiza os parâmetros <Add>, <Copy>, <Set> e Os elementos <Remove> são importantes. 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>.

Elemento <AssignMessage>

Define uma política AssignMessage.

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> <AssignVariable> <Copy> <DisplayName> <IgnoreUnresolvedVariables> <Remove> <Set>

O elemento <AssignMessage> usa a seguinte sintaxe:

Sintaxe

O elemento <AssignMessage> usa a seguinte sintaxe:

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <!-- All AssignMessage 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>

  <AssignVariable>
    <Name>VARIABLE_NAME</Name>
    <PropertySetRef>SOURCE_VARIABLE</PropertySetRef>
    <Ref>SOURCE_VARIABLE</Ref>
    <ResourceURL>RESOURCE_URL_OR_TEMPLATE</ResourceURL>
    <Template>MESSAGE_TEMPLATE</Template>
    or
    <Template ref='TEMPLATE_VARIABLE'></Template>
    <Value>VARIABLE_VALUE</Value>
  </AssignVariable>

  <Copy source="VARIABLE_NAME">
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
    <!-- Copy all headers -->
    <Headers/>
    <!-- or, copy specific headers by name -->
    <Headers>
      <Header name="HEADER_NAME"/>
      <!-- or -->
      <Header name="HEADER_NAME">[false|true]</Header>
      ...
    </Headers>
    <Path>[false|true]</Path>
    <Payload>[false|true]</Payload>
    <!-- Can also be an empty array (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME">QUERYPARAM_VALUE</QueryParam>
      ...
    </QueryParams>
    <StatusCode>[false|true]</StatusCode>
    <Verb>[false|true]</Verb>
    <Version>[false|true]</Version>
  </Copy>

  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>

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

  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Remove all form parameters -->
    <FormParams/>
    <!-- or, remove specific form parameters by name -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME"/>
      <!-- or -->
      <FormParam name="FORMPARAM_NAME">[false|true]</FormParam>
      ...
    </FormParams>
    <!-- Remove all headers -->
    <Headers/>
    <!-- or, remove specific headers by name -->
    <Headers>
      <Header name="HEADER_NAME"/>
      <!-- or -->
      <Header name="HEADER_NAME">[false|true]</Header>
      ...
    </Headers>
    <Payload>[false|true]</Payload>
    <!-- Remove all query parameters -->
    <QueryParams/>
    <!-- or, remove specific query parameters by name -->
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME"/>
      <!-- or -->
      <QueryParam name="QUERYPARAM_NAME">[false|true]</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>
    <Payload contentType="CONTENT_TYPE" variablePrefix="PREFIX"
        variableSuffix="SUFFIX">NEW_PAYLOAD</Payload>
    <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>

</AssignMessage>

Política padrão

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

<AssignMessage continueOnError="false" enabled="true" name="assign-message-default">
  <DisplayName>Assign Message-1</DisplayName>
  <Properties/>
  <Copy source="request">
    <Headers/>
    <QueryParams/>
    <FormParams/>
    <Payload/>
    <Verb/>
    <StatusCode/>
    <Path/>
  </Copy>
  <Remove>
    <Headers>
      <Header name="h1"/>
    </Headers>
    <QueryParams>
      <QueryParam name="q1"/>
    </QueryParams>
    <FormParams>
      <FormParam name="f1"/>
    </FormParams>
    <Payload/>
  </Remove>
  <Add>
    <Headers/>
    <QueryParams/>
    <FormParams/>
  </Add>
  <Set>
    <Headers/>
    <QueryParams/>
    <FormParams/>
    <!-- <Verb>GET</Verb> -->
    <Path/>
  </Set>
  <AssignVariable>
    <Name>name</Name>
    <Value/>
    <Ref/>
  </AssignVariable>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

Quando você insere uma nova política AssignMessage na IU do 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, se você quiser executar uma operação de cópia, use o elemento <Copy> e remova <Add>, <Remove> e outros elementos filhos da política para 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 <AssignMessage>:

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>.
<Copy>	Opcional	Copia as informações da mensagem especificadas pelo atributo source para o objeto de mensagem especificado pelo elemento <AssignTo>.
<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 AssignMessage funciona. Pode ser a solicitação ou a resposta padrão ou uma nova mensagem personalizada.
<AssignVariable>	Opcional	Atribui um valor a uma variável de fluxo. Se a variável não existir, ela será criada por <AssignVariable>.
<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 exemplos a seguir mostram algumas maneiras de usar a política AssignMessage:

1: Adicionar cabeçalho

O exemplo a seguir adiciona um cabeçalho à solicitação com o elemento <Add>:

<AssignMessage name="AM-add-headers-1">
  <Add>
    <Headers>
      <Header name="partner-id">{verifyapikey.VAK-1.developer.app.partner-id}</Header>
    </Headers>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

2: Remover payload

O exemplo a seguir exclui o payload da resposta com o elemento <Remove>:

<AssignMessage name="AM-remove-1">
  <DisplayName>remove-1</DisplayName>
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo>response</AssignTo>
</AssignMessage>

3: Modificar resposta

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

<AssignMessage name="AM-modify-response">
  <Set>
    <Headers>
      <Header name="Cache-Hit">{lookupcache.LookupCache-1.cachehit}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignTo>response</AssignTo>
</AssignMessage>

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 "Atribuir mensagem" 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.

4: Definir conteúdo dinâmico

É possível usar a política AssignMessage para incorporar conteúdo dinâmico ao payload de mensagens de resposta e de solicitação.

Para incorporar variáveis de fluxo do Edge em um payload XML, una a variável designada entre chaves, conforme mostrado a seguir: {prefix.name}.

O exemplo a seguir incorpora o valor da variável de fluxo de cabeçalho HTTP user-agent em um elemento XML chamado User-agent:

<AssignMessage name="AM-set-dynamic-content">
  <AssignTo>response</AssignTo>
  <Set>
    <Payload contentType="text/xml">
      <User-agent>{request.header.user-agent}</User-agent>
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

Para payloads JSON, é possível inserir variáveis usando os atributos variablePrefix e variableSuffix com caracteres delimitadores, conforme mostrado no exemplo a seguir:

<AssignMessage name="set-payload">
  <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
  {
     "user-agent": "@request.header.user-agent#"
  }
  </Payload>
</AssignMessage>

Para uma lista completa de variáveis de fluxo, consulte Referência de variáveis de fluxo.

Você também pode usar as chaves para inserir variáveis.

5: Remover parâmetro de consulta

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

<AssignMessage name="AM-remove-query-param">
  <Remove>
    <QueryParams>
      <QueryParam name="apikey"/>
    </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

6: Definir/encontrar variáveis

O exemplo a seguir mostra três usos de políticas AssignMessage:

1. Criar três variáveis de fluxo na solicitação, com valores estáticos
2. Encontrar as variáveis de fluxo dinamicamente em uma segunda política no fluxo de solicitação
3. Definir as variáveis no payload da resposta.

<!-- Policy #1: Set variables in the request -->
<AssignMessage name="AM-set-variables">
    <!-- Create a variable named myAppSecret -->
    <AssignVariable>
        <Name>myAppSecret</Name>
        <Value>42</Value>
    </AssignVariable>
    <!-- Create a variable named config.environment -->
    <AssignVariable>
        <Name>config.environment</Name>
        <Value>test</Value>
    </AssignVariable>
    <!-- Create a variable named config.protocol -->
    <AssignVariable>
        <Name>config.protocol</Name>
        <Value>gopher</Value>
    </AssignVariable>
</AssignMessage>

Na primeira política, o elemento <AssignVariable> cria e define três variáveis na solicitação. Cada elemento <Name> especifica um nome de variável e <Value> especifica o valor.

A segunda política usa o elemento <AssignVariable> para ler os valores e cria três novas variáveis:

<!-- Policy #2: Get variables from the request -->
<AssignMessage continueOnError="false" enabled="true" name="get-variables">
  <AssignTo createNew="false" transport="http" type="request"/>
  <!-- Get the value of myAppSecret and create a new variable, secret -->
  <AssignVariable>
    <Name>secret</Name>
    <Ref>myAppSecret</Ref>
    <Value>0</Value>
  </AssignVariable>
  <!-- Get the value of config.environment and create a new variable, environment -->
  <AssignVariable>
    <Name>environment</Name>
    <Ref>config.environment</Ref>
    <Value>default</Value>
  </AssignVariable>
  <!-- Get the value of config.protocol and create a new variable, protocol -->
  <AssignVariable>
    <Name>protocol</Name>
    <Ref>config.protocol</Ref>
    <Value>default</Value>
  </AssignVariable>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Na segunda política, o elemento <Ref> referencia a variável de origem, e os elementos <Name> especificam os nomes das novas variáveis. Se a variável referenciada pelo elemento <Ref> não estiver acessível, use o valor especificado pelo elemento <Value>.

Para testar esse conjunto de políticas:

1. Adicione as políticas 1 e 2 ao fluxo de solicitação. Certifique-se de colocar a política 1 antes da política 2.
2. Adicione a terceira política no fluxo de resposta.
3. A terceira política usa o elemento <Set> para adicionar as variáveis à resposta. No exemplo a seguir, é criado um payload XML na resposta que o Edge retorna ao cliente:

   <!-- Policy #3: Add variables to the response -->
   <AssignMessage continueOnError="false" enabled="true" name="put-em-in-the-payload">
     <DisplayName>put-em-in-the-payload</DisplayName>
     <Set>
       <Payload contentType="application/xml">
         <wrapper>
           <secret>{secret}</secret>
           <config>
             <environment>{environment}</environment>
             <protocol>{protocol}</protocol>
           </config>
         </wrapper>
       </Payload>
     </Set>
     <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
     <AssignTo createNew="false" transport="http" type="response"/>
   </AssignMessage>

   Observe que a sintaxe para acessar as variáveis de fluxo em <Set> é colocá-las entre chaves.

   Defina o atributo contentType do elemento <Payload> como application/xml.

4. Envie uma solicitação para o proxy da API. por exemplo:

   curl -vL https://ahamilton-eval-test.apigee.net/myproxy

   Como opção, é possível canalizar os resultados por um utilitário como xmllint para que o XML seja exibido em uma estrutura bem formatada:

   curl -vL https://ahamilton-eval-test.apigee.net/myproxy | xmllint --format -

   O corpo da resposta será semelhante a este:

   <wrapper>
     <secret>42</secret>
     <config>
       <environment>test</environment>
       <protocol>gopher</protocol>
     </config>
   </wrapper>

7: Receber cabeçalhos de resposta de ServiceCallout

No exemplo a seguir, digamos que uma política ServiceCallout esteja na solicitação de proxy de API e que a resposta da chamada contenha vários cabeçalhos de mesmo nome (Set-Cookie). Supondo que a variável de resposta da chamada de serviço seja a calloutResponse padrão, a política a seguir mostrará o segundo valor de cabeçalho Set-Cookie.

<AssignMessage name="AM-Payload-from-SC-header">
  <Set>
    <Payload contentType="application/json">
      {"Cookies from Service Callout":" {calloutResponse.header.Set-Cookie.2}"}
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo>response</AssignTo>
</AssignMessage>

Para listar todos os valores de cabeçalho, use a seguinte variável:

{calloutResponse.header.Set-Cookie.values}

8: Armazenar e remover parâmetros de formulário, cabeçalhos e parâmetros de consulta

Se você quiser usar <Remove> para excluir cabeçalhos, parâmetros de consulta ou parâmetros de formulário, mas manter o acesso aos valores posteriormente no fluxo da política, armazene-os usando <AssignVariable>.

<AssignMessage async="false" continueOnError="false" enabled="true" name="AM-StoreAndRemove">
  <DisplayName>AM-StoreAndRemove</DisplayName>
  <AssignVariable>
    <Name>var_grant_type</Name>
    <Ref>request.formparam.grant_type</Ref>
  </AssignVariable>
  <Remove>
    <Headers/>
    <FormParams/>
    <Payload/>
  </Remove>
  <Set>
    <Headers>
      <Header name="Content-Type">application/x-www-form-urlencoded</Header>
      <Header name="Accept">application/json</Header>
      <Header name="Grant-Type">{var_grant_type}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

Observação: os parâmetros de formulário, cabeçalhos e parâmetros de consulta removidos usando <Remove> na política "Atribuir mensagem" não podem ser acessados após a conclusão do fluxo da política, a menos que seus valores sejam armazenados em variáveis, conforme descrito neste exemplo.

Cada elemento filho nesta referência tem exemplos extras. Para ainda mais exemplos, consulte Exemplo de AssignMessage (em inglês) no GitHub.

Referência a elementos filhos

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

<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	<AssignMessage>
Elemento filho	<FormParams> <Headers> <QueryParams>

O elemento <Add> usa a seguinte sintaxe:

Sintaxe

<AssignMessage
    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>
</AssignMessage>

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:

<AssignMessage name="AM-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>
</AssignMessage>

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:

<AssignMessage name="AM-add-headers-1">
  <Add>
    <Headers>
      <Header name="partner-id">{verifyapikey.VAK-1.developer.app.partner-id}</Header>
    </Headers>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

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:

<AssignMessage name="AM-add-queryparams-1">
  <Add>
    <QueryParams>
      <QueryParam name="myParam">42</QueryParam>
    </QueryParams>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

Este exemplo usa <Add> no pré-fluxo de solicitação. Se você observar os resultados em uma ferramenta como a Visão geral do Debug, 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

<AssignMessage
    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>
</AssignMessage>

Exemplo 1

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

<AssignMessage name="AM-add-formparams-1">
  <Add>
    <FormParams>
      <FormParam name="answer">42</FormParam>
    </FormParams>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

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:

<AssignMessage name="AM-Swap-QueryParam-to-FormParams">
  <Add>
    <FormParam name="name">{request.queryparam.name}</FormParam>
  </Add>
  <Remove>
    <QueryParam name="name"/>
  </Remove>
</AssignMessage>

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:

<AssignMessage name="AM-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>
</AssignMessage>

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 Visão geral 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:

• Verbo HTTP: POST
• Tipo de mensagem: solicitação
• Um ou ambos os itens a seguir:
  • Dados do formulário: defina como algum valor ou "" (a 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

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Add>
    <Headers>
      <Header name="HEADER_NAME">HEADER_VALUE</Header>
      ...
    </Headers>
  </Add>
</AssignMessage>

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.

<AssignMessage name="AM-add-headers-1">
  <Add>
    <Headers>
      <Header name="partner-id">{verifyapikey.VAK-1.developer.app.partner-id}</Header>
    </Headers>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

<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

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Add>
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME">QUERYPARAM_VALUE</QueryParam>
      ...
    </QueryParams>
  </Add>
</AssignMessage>

Exemplo 1

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

<AssignMessage name="AM-add-queryparams-1">
  <Add>
    <QueryParams>
      <QueryParam name="myParam">42</QueryParam>
    </QueryParams>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

• Verbos HTTP: GET, POST, PATCH, DELETE
• 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 AssignMessage 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 AssignMessage 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	<AssignMessage>
Elemento filho	Nenhum

Se você não especificar <AssignTo> ou se especificar o elemento <AssignTo>, mas não especificar um valor de texto para o elemento, a política vai atuar na solicitação ou resposta padrão, que é com base 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

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <AssignTo createNew="[true|false]" transport="http"
    type="[request|response]">DESTINATION_VARIABLE_NAME</AssignTo>
</AssignMessage>

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.

<AssignMessage name="assignto-1">
  <AssignTo createNew="false" transport="http" type="request"/> <!-- no-op -->
  ...
</AssignMessage>

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

Exemplo 2

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

<AssignMessage name="assignto-2">
  <AssignTo createNew="true" transport="http" type="request"/>
  ...
</AssignMessage>

Ao criar um novo objeto de solicitação ou resposta, os outros elementos da política AssignMessage (como <Add>, <Set> e <Copy>) 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:

<AssignMessage name="assignto-2">
  <AssignTo createNew="true" transport="http" type="request">MyRequestObject</AssignTo>
  ...
</AssignMessage>

Ao criar um novo objeto de solicitação ou resposta, os outros elementos da política AssignMessage (como <Add>, <Set> e <Copy>) 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	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

<AssignVariable>

Atribui um valor a uma variável de fluxo de destino (como uma variável com valor definido pela política AssignMessage). Se a variável de fluxo não existir, <AssignVariable> será criada por ela. É possível usar vários elementos AssignVariable na política AssignMessage. Eles são executados em ordem de aparência na configuração da política.

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	Tipo complexo
Elemento pai	<AssignMessage>
Elemento filho	<Name> (obrigatório) <PropertySetRef> <Ref> <ResourceURL> <Template> <Value>

O valor atribuído à variável de fluxo de destino pode ser um dos seguintes:

• String literal: use o elemento filho <Value> para especificar um valor de string literal para a variável de fluxo de destino.
• Variável de fluxo: use o elemento filho <Ref> para especificar o valor de uma variável de fluxo atual para a variável de fluxo de destino. Para uma lista completa de variáveis de fluxo que podem ser usadas como origem, consulte Referência de variáveis de fluxo.
• Propriedade definida: use o elemento filho <PropertySetRef> para recuperar o valor de um par nome/chave de conjunto de propriedades e armazená-lo em uma variável de fluxo. Permite acessar conjuntos de propriedades dinamicamente.
• URL do recurso: use o elemento filho <ResourceURL> para especificar um URL para um recurso de texto, do tipo XSL, XSD, WSDL, JavaScript ou Especificação OpenAPI. Isso atribui o conteúdo do recurso à variável de fluxo nomeada.
• Modelo de mensagem: use o elemento filho <Template> para especificar um modelo de mensagem para a variável de fluxo de destino.

A ordem de precedência desses elementos filhos é: ResourceURL, Template, Ref, Value, PropertySetRef.

O elemento <AssignVariable> usa a seguinte sintaxe:

Sintaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <AssignVariable>
    <Name>VARIABLE_NAME</Name>
    <PropertySetRef>SOURCE_VARIABLE</PropertySetRef>
    <Ref>SOURCE_VARIABLE</Ref>
    <ResourceURL>RESOURCE_URL_OR_TEMPLATE</ResourceURL>
    <Template>MESSAGE_TEMPLATE</Template>
    or
    <Template ref='TEMPLATE_VARIABLE'></Template>
    <Value>VARIABLE_VALUE</Value>
  </AssignVariable>
</AssignMessage>

Use o elemento <Ref> para especificar a variável de origem. Se a variável referenciada por <Ref> não estiver acessível, a Apigee usará o valor especificado pelo elemento <Value>. Se você definir <Template>, ele terá precedência sobre os elementos irmãos <Ref> e <Value>.

Exemplo 1

O exemplo a seguir define o valor de uma nova variável, myvar, como o valor literal 42:

<AssignMessage name="assignvariable-1">
  <AssignVariable>
    <Name>myvar</Name>
    <Value>42</Value>
  </AssignVariable>
</AssignMessage>

Exemplo 2

O exemplo a seguir atribui o valor da variável de fluxo request.header.user-agent para a variável do fluxo de destino myvar e o valor do parâmetro de consulta country para a variável do fluxo de destino Country:

<AssignMessage name="assignvariable-2">
  <AssignVariable>
    <Name>myvar</Name>
    <Ref>request.header.user-agent</Ref>
    <Value>ErrorOnCopy</Value>
  </AssignVariable>
  <AssignVariable>
    <Name>Country</Name>
    <Ref>request.queryparam.country</Ref>
    <Value>ErrorOnCopy</Value>
  </AssignVariable>
</AssignMessage>

Se qualquer atribuição falhar, a Apigee atribuirá o valor ErrorOnCopy à variável de fluxo de destino.

Se as variáveis de fluxo myvar ou Country não existirem, elas serão criadas por <AssignVariable>.

Exemplo 3

O exemplo a seguir usa o elemento filho <Template> para concatenar duas variáveis de contexto com uma string literal (um hífen) entre elas:

<AssignMessage name='AV-via-template-1'>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>my_destination_variable</Name>
    <Value>BADDBEEF</Value>
    <Template>{system.uuid}-{messageid}</Template>
  </AssignVariable>
</AssignMessage>

Exemplo 4

O exemplo a seguir usa <AssignVariable> para desativar o comportamento padrão de propagação do sufixo de caminho da solicitação do proxy para a solicitação de destino:

<AssignMessage name='AM-PathSuffixFalse'>
  <AssignVariable>
    <Name>target.copy.pathsuffix</Name>
    <Value>false</Value>
  </AssignVariable>
</AssignMessage>

Um uso comum de <AssignVariable> é definir um valor padrão para um parâmetro de consulta, cabeçalho ou outro valor que possa ser passado com a solicitação. Isso é feito com uma combinação dos elementos filhos <Ref> e <Value>. Para mais informações, consulte os exemplos de <Ref>.

<Name> (filho de <AssignVariable>)

Especifica o nome da variável de fluxo de destino (como a variável com valor definido pela política AssignMessage). Se a variável nomeada em <Name> não existir, a política criará uma com esse nome.

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

O elemento <Name> usa a seguinte sintaxe:

Sintaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <AssignVariable>
    <Name>VARIABLE_NAME</Name>
  </AssignVariable>
</AssignMessage>

Exemplo 1

O exemplo a seguir especifica a variável de destino como myvar e a define como o valor literal 42:

<AssignMessage name="assignvariable-1">
  <AssignVariable>
    <Name>myvar</Name>
    <Value>42</Value>
  </AssignVariable>
</AssignMessage>

Se myvar não existir, ele será criado por <AssignVariable>.

Observação: o nome ratelimit é reservado. Para mais informações, consulte Política de cota gera NullPointerException (em inglês) na comunidade do Apigee.

<PropertySetRef> (filho de <AssignVariable>)

Esse elemento permite recuperar o valor de um par nome/chave de conjunto de propriedades dinamicamente. Para saber mais sobre os conjuntos de propriedades, consulte Como usar conjuntos de propriedades.

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

Um conjunto de propriedades é composto por um par de nome/chave. Por exemplo: propset1.id=12345, em que propset1 é o nome do conjunto de propriedades, id é uma chave e 12345 é o valor da chave.

O elemento filho PropertySetRef permite selecionar nomes e/ou chaves do conjunto de propriedades de forma dinâmica. Suponha que você tenha 200 regras de roteamento em um arquivo de conjunto de propriedades. É possível acessar as regras do conjunto de propriedades da seguinte maneira, em que routingrules é o nome do conjunto de propriedades e rule1, rule2, rulen são chaves:

propertyset.routingrules.rule1
propertyset.routingrules.rule2
propertyset.routingrules.rulen

Para acessar essas propriedades em um fluxo de proxy da API, é necessário saber qual regra você quer selecionar no momento do projeto. No entanto, suponha que o nome da regra esteja no cabeçalho da solicitação ou no payload. Uma maneira de selecionar a regra é usar uma política JavaScript com código como o seguinte:

context.getVariables("propertyset.routingrules." + ruleName); //assuming ruleName was populated earlier.

Por outro lado, com o recurso PropertySetRef AssignMessage, você seleciona uma chave de propriedade dinamicamente sem introduzir o JavaScript.

É possível usar uma combinação de variáveis de fluxo e valores de string literal no elemento <PropertySetRef>. Veja os exemplos para mais detalhes.

Observação: ao usar esse recurso, não consulte o conjunto de propriedades usando o prefixo propertyset, como em: propertyset.PROPNAME.KEY. O prefixo propertyset é usado.

O elemento <PropertySetRef> usa a seguinte sintaxe:

Sintaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <AssignVariable>
    <PropertySetRef>SOURCE_VARIABLE</PropertySetRef>
  </AssignVariable>
</AssignMessage>

Exemplo 1

Este exemplo atribui o valor de uma chave de conjunto de propriedades em uma variável de fluxo. Neste caso, o nome do conjunto de propriedades é obtido no cabeçalhopropset_name, a chave será fornecida no cabeçalho propset_key e o valor atribuído à chave será armazenado na variável flow_variable.

<AssignMessage async="false" continueOnError="false" enabled="true" name="assignMessage">
  <DisplayName>Assign Message-1</DisplayName>
  <Properties/>
  <AssignVariable>
    <Name>flow_variable</Name>
    <PropertySetRef>{request.header.propset_name}.{request.header.propset_key}</PropertySetRef>
  </AssignVariable>
</AssignMessage>

Qualquer combinação de variáveis de fluxo e strings literais pode ser usada no elemento <PropertySetRef>.

Exemplo 2

Este exemplo atribui o valor de uma chave de conjunto de propriedades para uma variável de fluxo usando um nome de chave fixo (string literal). Nesse caso, o nome do conjunto de propriedades é obtido no cabeçalho propset_name, a chave é a string literal key1 e o valor atribuído à chave é armazenado na variável flow_variable.

<AssignMessage async="false" continueOnError="false" enabled="true" name="assignMessage">
  <DisplayName>Assign Message-1</DisplayName>
  <Properties/>
  <AssignVariable>
    <Name>flow_variable</Name>
    <PropertySetRef>{request.header.propset_name}.key1</PropertySetRef>
  </AssignVariable>
</AssignMessage>

Qualquer combinação de variáveis de fluxo e strings literais pode ser usada no elemento <PropertySetRef>.

<Ref> (filho de <AssignVariable>)

Especifica a origem da atribuição como uma variável de fluxo. A variável pode ser uma das variáveis de fluxo predefinidas, conforme listado na Referência de variáveis de fluxo, ou uma variável personalizada criada por você.

O valor de <Ref> é sempre interpretado como uma variável de fluxo. não é possível especificar uma string literal como o valor. Para atribuir um valor de string literal, use o elemento <Value>.

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

Ao especificar uma variável de fluxo com <Ref>, omita as chaves {} que você normalmente usaria para referenciar uma variável de fluxo. Por exemplo, para definir o valor da nova variável como o valor da variável de fluxo client.host:

  DO specify the variable name without brackets:
  <Ref>client.host</Ref>

  DO NOT use brackets:
  <Ref>{client.host}</Ref>

Para definir um valor padrão para a variável de fluxo de destino, use <Value> com <Ref>. Se a variável de fluxo especificada por <Ref> não existir, não puder ser lida ou for nula, o Apigee atribuirá o valor de <Value> à variável de fluxo de destino.

O elemento <Ref> usa a seguinte sintaxe:

Sintaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <AssignVariable>
    <Name>VARIABLE_NAME</Name>
    <Ref>SOURCE_VARIABLE</Ref>
  </AssignVariable>
</AssignMessage>

Exemplo 1

O exemplo a seguir atribui o valor da variável de fluxo request.header.user-agent para a variável do fluxo de destino myvar e o valor do parâmetro de consulta country para a variável Country:

<AssignMessage name="assignvariable-4">
  <AssignVariable>
    <Name>myvar</Name>
    <Ref>request.header.user-agent</Ref>
  </AssignVariable>
  <AssignVariable>
    <Name>Country</Name>
    <Ref>request.queryparam.country</Ref>
  </AssignVariable>
</AssignMessage>

Neste exemplo, o Apigee não tem um valor padrão (ou substituto) especificado para nenhuma atribuição.

Exemplo 2

O exemplo a seguir atribui o valor da variável de fluxo request.header.user-agent para a variável do fluxo de destino myvar e o valor do parâmetro de consulta country para a variável Country:

<AssignMessage name="assignvariable-2">
  <AssignVariable>
    <Name>myvar</Name>
    <Ref>request.header.user-agent</Ref>
    <Value>ErrorOnCopy</Value>
  </AssignVariable>
  <AssignVariable>
    <Name>Country</Name>
    <Ref>request.queryparam.country</Ref>
    <Value>ErrorOnCopy</Value>
  </AssignVariable>
</AssignMessage>

Neste exemplo, se os valores da variável de fluxo request.header.user-agent ou do parâmetro de consulta Country forem nulos, ilegíveis ou malformados, o Apigee atribuirá o valor ErrorOnCopy às novas variáveis.

Exemplo 3

Um caso de uso comum de <AssignVariable> é definir o valor padrão de um parâmetro de consulta, cabeçalho ou outro valor que pode ser transmitido com a solicitação. Por exemplo, você cria um proxy de API de clima em que a solicitação usa um único parâmetro de consulta chamado w. Esse parâmetro contém o ID da cidade para que você quer saber a previsão do tempo. O URL da solicitação tem o seguinte formato:

http://myCO.com/v1/weather/forecastrss?w=CITY_ID

Para definir um valor padrão para w, crie uma política AssignMessage como a seguinte:

<AssignMessage continueOnError="false" enabled="true" name="assignvariable-3">
  <AssignTo createNew="false" transport="http" type="request"/>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>request.queryparam.w</Name>
    <Ref>request.queryparam.w</Ref>
    <Value>12797282</Value>
  </AssignVariable>
</AssignMessage>

Neste exemplo, <AssignVariable> encontra o valor de request.queryparam.w e o atribui a si mesmo. Se a variável de fluxo for nula, o que significa que o parâmetro de consulta w foi omitido da solicitação, então este exemplo usará o valor padrão do elemento <Value>. Portanto, é possível fazer uma solicitação para esse proxy de API que omita o parâmetro de consulta w:

http://myCO.com/v1/weather/forecastrss

...e ainda assim fazer com que o proxy de API retorne um resultado válido.

O valor de <Ref> precisa ser uma variável de fluxo, como uma propriedade de request, response ou target ou o nome de uma variável de fluxo personalizada.

Se você especificar uma variável de fluxo que não existe para o valor de <Ref> e o valor de <IgnoreUnresolvedVariables> é false, a Apigee gera um erro.

<ResourceURL> (filho de <AssignVariable>)

Especifica o URL de um recurso de texto como a origem da atribuição da variável. A Apigee carrega a variável de fluxo especificada em <Name> com o conteúdo do recurso referenciado. O recurso pode ser do tipo XSD, XSL, WSDL, JavaScript, conjunto de propriedades ou OpenAPI Spec.

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

Se o recurso especificado por <ResourceURL> não existir, então: se o valor de <IgnoreUnresolvedVariables> for true, a Apigee atribuirá o valor null à variável de fluxo de destino, mas se o valor de <IgnoreUnresolvedVariables> é false, a Apigee gerará um erro.

O elemento <ResourceURL> usa a seguinte sintaxe:

Sintaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <AssignVariable>
    <Name>VARIABLE_NAME</Name>
    <ResourceURL>RESOURCE_URL_OR_TEMPLATE</ResourceURL>
  </AssignVariable>
</AssignMessage>
      

O valor de texto usa um valor de string e é interpretado como um modelo de mensagem. Qualquer um destes é válido:

<ResourceURL>jsc://my-js-file.js</ResourceURL>
<ResourceURL>wsdl://{variable-goes-here}</ResourceURL>
<ResourceURL>{variable-goes-here}</ResourceURL>

Exemplo 1

O exemplo a seguir atribui o valor de um recurso JSON, carregado no proxy na pasta jsc, na variável de fluxo assigned-variable:

<AssignMessage name='AM-From-ResourceURL-Proxy-JSC'>
  <AssignVariable>
    <Name>assigned-variable</Name>
    <ResourceURL>jsc://settings.json</ResourceURL>
  </AssignVariable>
</AssignMessage>

Exemplo 2

O exemplo a seguir atribui o valor de um recurso OpenAPI Spec, carregado no proxy na pasta oas, na variável de fluxo assigned-variable e, em seguida, define esse valor como Payload. no corpo da resposta:

<AssignMessage name='AM-Response'>
  <AssignVariable>
    <Name>assigned-variable</Name>
    <ResourceURL>oas://Fulfillment.yaml</ResourceURL>
  </AssignVariable>
  <Set>
    <Payload contentType='application/yaml'>{assigned-variable}</Payload>
  </Set>
</AssignMessage>

<Template> (filho de <AssignVariable>)

Especifica um modelo de mensagem. Um modelo de mensagem permite realizar a substituição de strings variáveis quando a política é executada e pode combinar strings literais com nomes de variáveis entre chaves. Além disso, os modelos de mensagem são compatíveis com funções como escape e conversão de maiúsculas e minúsculas.

Use o atributo ref para especificar uma variável de fluxo em que o valor da variável é um modelo de mensagem. Por exemplo, é possível armazenar um modelo de mensagem como um atributo personalizado em um app de desenvolvedor. Quando o Apigee identifica o app de desenvolvedor após verificar a chave de API ou o token de segurança (por meio de uma política extra), o elemento <AssignVariable> pode usar o modelo de mensagem do atributo personalizado do app, que está disponível como uma variável de fluxo da política de segurança. No exemplo a seguir, presume-se que o modelo de mensagem está disponível em um atributo do cliente chamado message_template no app de desenvolvedor que faz a chamada de API, em que a política VerifyAPIKey foi usada para verificar a chave de API do app:

<Template ref='verifyapikey.myVerifyAPIKeyPolicy.app.name.message_template'/>

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

O elemento <Template> usa a seguinte sintaxe:

Sintaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <AssignVariable>
    <Template>MESSAGE_TEMPLATE</Template>
    or
    <Template ref='TEMPLATE_VARIABLE'></Template>
  </AssignVariable>
</AssignMessage>

Exemplo 1

O exemplo a seguir usa a sintaxe de modelo de mensagem para concatenar duas variáveis de contexto com uma string literal (um hífen) entre elas:

<AssignMessage name='AV-via-template-1'>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>my_destination_variable</Name>
    <Value>BADDBEEF</Value>
    <Template>{system.uuid}-{messageid}</Template>
  </AssignVariable>
</AssignMessage>

Exemplo 2

O exemplo a seguir especifica uma variável de fluxo, em que o valor da variável é um modelo de mensagem predefinido. Use essa opção se quiser injetar um modelo predefinido no ambiente de execução, sem precisar modificar a política:

<AssignMessage name='AV-via-template-indirectly'>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>my_destination_variable</Name>
    <Value>BADDBEEF</Value>
    <Template ref='my_template_variable'/>
  </AssignVariable>
</AssignMessage>

Exemplo 3

O exemplo a seguir especifica uma variável de fluxo e um valor de texto. Nesse caso, se a variável referenciada não for nula, esse valor será usado como o modelo. Se o valor referenciado for nulo, o valor de texto (neste caso, {system.uuid}-{messageid}) será usado como modelo. Esse padrão é útil para fornecer um valor override, em que, em alguns casos, você quer substituir o modelo padrão (a parte de texto) pelos valores definidos dinamicamente. Por exemplo, uma instrução condicional pode capturar um valor de um mapa de chave-valor e definir a variável referenciada para esse valor:

<AssignMessage name='AV-template-with-fallback'>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>my_destination_variable</Name>
    <Template ref='my_variable'>{system.uuid}-{messageid}</Template>
  </AssignVariable>
</AssignMessage>

<Value> (filho de <AssignVariable>)

Define o valor da variável de fluxo de destino definida com <AssignVariable>. O valor é sempre interpretado como uma string literal. Não é possível usar uma variável de fluxo como o valor, mesmo que você coloque o valor entre chaves ({}). Para usar uma variável de fluxo, use <Ref>.

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

Quando usado com o elemento <Ref>, <Value> atua como o valor padrão (ou substituto). Se <Ref> não for especificado, não puder ser resolvido ou for nulo, o valor de <Value> será usado.

O elemento <Value> usa a seguinte sintaxe:

Sintaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <AssignVariable>
    <Name>VARIABLE_NAME</Name>
    <Value>VARIABLE_VALUE</Value>
  </AssignVariable>
</AssignMessage>

Exemplo 1

O exemplo a seguir define o valor da variável do fluxo de destino, myvar, para o valor literal 42:

<AssignMessage name="assignvariable-1">
  <AssignVariable>
    <Name>myvar</Name>
    <Value>42</Value>
  </AssignVariable>
</AssignMessage>

Exemplo 2

O exemplo a seguir atribui o valor da variável de fluxo request.header.user-agent para a variável de fluxo myvar e o valor do parâmetro de consulta country para a variável Country:

<AssignMessage name="assignvariable-2">
  <AssignVariable>
    <Name>myvar</Name>
    <Ref>request.header.user-agent</Ref>
    <Value>ErrorOnCopy</Value>
  </AssignVariable>
  <AssignVariable>
    <Name>Country</Name>
    <Ref>request.queryparam.country</Ref>
    <Value>ErrorOnCopy</Value>
  </AssignVariable>
</AssignMessage>

Se qualquer atribuição falhar, <AssignVariable> atribui o valor ErrorOnCopy à variável de fluxo de destino.

<Copy>

Copia os valores da mensagem especificada pelo atributo source para a mensagem especificada pelo elemento <AssignTo>. Se você não especificar um destino com <AssignTo>, essa política copiará os valores para a solicitação ou resposta, dependendo do local no fluxo em que a política é executada.

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

Se você não especificar elementos filhos abaixo do elemento <Copy>, ele copiará todas as partes da mensagem de origem designada.

O elemento <Copy> usa a seguinte sintaxe:

Sintaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
    <Copy source="VARIABLE_NAME">
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
    <!-- Copy all headers -->
    <Headers/>
    <!-- or, copy specific headers by name -->
    <Headers>
      <Header name="HEADER_NAME"/>
      <!-- or -->
      <Header name="HEADER_NAME">[false|true]</Header>
      ...
    </Headers>
    <Path>[false|true]</Path>
    <Payload>[false|true]</Payload>
    <!-- Can also be an empty array (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME">QUERYPARAM_VALUE</QueryParam>
      ...
    </QueryParams>
    <StatusCode>[false|true]</StatusCode>
    <Verb>[false|true]</Verb>
    <Version>[false|true]</Version>
  </Copy>
  <!-- Used as the destination for the <Copy> values -->
  <AssignTo createNew="[true|false]" transport="http"
    type="[request|response]">DESTINATION_VARIABLE_NAME</AssignTo>
</AssignMessage>
  

Exemplo 1

O exemplo a seguir copia um cabeçalho, três parâmetros de formulário, o caminho e todos os parâmetros de consulta da mensagem requestda solicitação para uma nova solicitação personalizada newRequest:

<AssignMessage name="AM-copy-1">
  <AssignTo createNew="true" transport="http" type="request">newRequest</AssignTo>
  <Copy source="request">
    <Headers>
      <Header name="Header_Name_1"/>
    </Headers>
    <FormParams>
      <FormParam name="Form_Param_Name_1"/>
      <FormParam name="Form_Param_Name_2"/>
      <FormParam name="Form_Param_Name_3"/>
    </FormParams>
    <Path>true</Path>
    <QueryParams/>
  </Copy>
</AssignMessage>

Como elementos como <Payload> e <Verb> não estão presentes, a política não copia essas partes da mensagem.

Exemplo 2

O exemplo a seguir remove primeiro tudo na mensagem response atual e, em seguida, copia todos os valores de uma mensagem diferente chamada secondResponse para a mensagem response:

<AssignMessage name='AM-Copy-Response'>
  <AssignTo createNew="false" transport="http" type="response">response</AssignTo>
  <!-- first remove any existing values -->
  <Remove/>
  <!-- then copy everything from the designated message -->
  <Copy source="secondResponse"/>
</AssignMessage>

O elemento <Copy> tem um único atributo:

Atributo	Descrição	Obrigatório?	Tipo
fonte	Especifica o objeto de origem da cópia. Se source não for especificado, o padrão será message, que assumirá um valor diferente dependendo do fluxo em que a política for executada. Se a política for executada no fluxo de solicitação, a variável message fará referência ao objeto request. Se a política for executada no fluxo de resposta, a variável message fará referência ao objeto response. Se a variável especificada no atributo source não puder ser resolvida ou resolvida para um tipo não mensagem, <Copy> não terá efeito. Verifique se o valor especificado para source é diferente da mensagem de destino, seja a mensagem de destino padrão ou um destino especificado explicitamente com <AssignTo>. Se o source for igual à mensagem de destino, <Copy> não terá efeito.	Opcional	String

<FormParams> (filho de <Copy>)

Copia os parâmetros do formulário de solicitação especificados pelo atributo source do elemento <Copy> para a solicitação especificada pelo <AssignTo>. 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	<Copy>
Elemento filho	<FormParam>

O elemento <FormParams> usa a seguinte sintaxe:

Sintaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
  </Copy>
</AssignMessage>

Exemplo 1

O exemplo a seguir copia um único parâmetro de formulário da solicitação para a solicitação personalizada MyCustomRequest:

<AssignMessage name="copy-formparams-1">
  <Copy source="request">
    <FormParams>
      <FormParam name="paramName">Form param value 1</FormParam>
    </FormParams>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

Exemplo 2

O exemplo a seguir copia todos os parâmetros do formulário para a solicitação personalizada MyCustomRequest:

<AssignMessage name="copy-formparams-2">
  <Copy source="request">
    <FormParams/>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

Exemplo 3

O exemplo a seguir copia três parâmetros de formulário para a solicitação personalizada MyCustomRequest:

<AssignMessage name="copy-formparams-3">
  <Copy source="request">
    <FormParams>
      <FormParam name="paramName1"/>
      <FormParam name="paramName2"/>
      <FormParam name="paramName3"/>
    </FormParams>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

Exemplo 4

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

<AssignMessage name="copy-formparams-4">
  <Copy source="request">
    <FormParams>
      <FormParam name="f1"/>
      <FormParam name="f2"/>
      <FormParam name="f3.2"/>
    </FormParams>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

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

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

• Verbo HTTP: POST
• Tipo de mensagem: resposta
• Um ou ambos os itens a seguir:
  • Dados do formulário: defina como algum valor ou "" (a 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). Por exemplo, com curl adicione -H "Content-Length: 0" à solicitação.

Quando você copia <FormParams>, <Copy> define Content-Type da mensagem como application/x-www-form-urlencoded antes de enviar a mensagem para o serviço de destino.

<Headers> (filho de <Copy>)

Copia os cabeçalhos HTTP da mensagem de solicitação ou resposta especificada pelo atributo source do elemento <Copy> para a mensagem de solicitação ou resposta especificada pelo elemento <AssignTo>.

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

O elemento <Headers> usa a seguinte sintaxe:

Sintaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <!-- Copy all headers -->
    <Headers/>
    <!-- or, copy specific headers by name -->
    <Headers>
      <Header name="HEADER_NAME"/>
      <!-- or -->
      <Header name="HEADER_NAME">[false|true]</Header>
      ...
    </Headers>
  </Copy>
</AssignMessage>

Exemplo 1

O exemplo a seguir copia o cabeçalho user-agent da solicitação para o novo objeto de solicitação personalizado:

<AssignMessage name="AM-copy-headers-1">
  <Copy source="request">
    <Headers>
      <Header name="user-agent"/>
    </Headers>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

Exemplo 2

Para copiar todos os cabeçalhos, use um elemento <Headers> vazio, como mostra o exemplo a seguir:

<AssignMessage name="copy-headers-2">
  <Copy source="request">
    <Headers/>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

Exemplo 3

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

<AssignMessage name="copy-headers-3">
  <Copy source="request">
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

Este exemplo copia h1, h2 e o segundo valor de h3. Se h3 tiver apenas um valor, ele não será copiado.

<Path> (filho de <Copy>)

Determina se o caminho precisa ser copiado da solicitação de origem para a solicitação de destino. Esse elemento não afeta respostas.

Setrue, essa política copia o caminhode a mensagem de solicitação especificada pelo <Copy> do elementosource atributoà a mensagem de solicitação especificada pelo<AssignTo>.

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

O elemento <Path> usa a seguinte sintaxe:

Sintaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <Path>[false|true]</Path>
  </Copy>
</AssignMessage>

Exemplo 1

O exemplo a seguir indica que AssignMessage precisa copiar o caminho da solicitação de origem para o novo objeto de solicitação personalizado:

<AssignMessage name="copy-path-1">
  <Copy source="request">
    <Path>true</Path>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

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

• Tipo de mensagem: solicitação

<Payload> (filho de <Copy>)

Determina se o payload precisa ser copiado da origem para o destino. A origem e o destino podem ser solicitações ou respostas.

Se true, essa política copia o payload de a mensagem especificada pelo atributo source do elemento <Copy> para a mensagem especificada pelo elemento <AssignTo>.

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

O elemento <Payload> usa a seguinte sintaxe:

Sintaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <Payload>[false|true]</Payload>
  </Copy>
</AssignMessage>

Exemplo 1

O exemplo a seguir define <Payload> como true para que o payload de solicitação seja copiado da solicitação para a resposta:

<AssignMessage name="AM-copy-payload-1">
  <Copy source="request">
    <Payload>true</Payload>
  </Copy>
  <AssignTo>response</AssignTo>
</AssignMessage>

<QueryParams> (filho de <Copy>)

Copia os parâmetros da string de consulta da solicitação especificada pelo atributo source do elemento <Copy> para a solicitação especificada pelo elemento <AssignTo>. 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	<QueryParam>
Elemento filho	Nenhum

O elemento <QueryParams> usa a seguinte sintaxe:

Sintaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <!-- Can also be an empty array (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME">QUERYPARAM_VALUE</QueryParam>
      ...
    </QueryParams>
  </Copy>
</AssignMessage>

Exemplo 1

No exemplo a seguir, copiamos o parâmetro de consulta my_param da solicitação para um novo objeto de solicitação personalizado:

<AssignMessage name="copy-queryparams-1">
  <Copy source="request">
    <QueryParams>
      <QueryParam name="my_param"/>
    </QueryParams>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

Exemplo 2

O exemplo a seguir copia todos os parâmetros de consulta da solicitação para um novo objeto de solicitação personalizada:

<AssignMessage name="copy-queryparams-2">
  <Copy source="request">
    <QueryParams/>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

Exemplo 3

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

<AssignMessage name="copy-queryparams-3">
  <Copy source="request">
    <QueryParams>
      <QueryParam name="qp1"/>
      <QueryParam name="qp2"/>
      <QueryParam name="qp3.2"/>
    </QueryParams>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

Este exemplo copia qp1, qp2 e o segundo valor de qp3. Se qp3 tiver apenas um valor, ele não será copiado.

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

• Verbos HTTP: GET, POST, PATCH, DELETE
• Tipo de mensagem: solicitação

<StatusCode> (filho de <Copy>)

Determina se o código de status é copiado da resposta de origem para a resposta de destino. Esse elemento não afeta solicitações.

Setrue, essa política copia o código de statusde a mensagem de resposta especificada pelo atributo source do elemento <Copy> à a mensagem de resposta especificada pelo<AssignTo>.

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

O elemento <StatusCode> usa a seguinte sintaxe:

Sintaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <StatusCode>[false|true]</StatusCode>
  </Copy>
</AssignMessage>

Exemplo 1

No exemplo a seguir, definimos <StatusCode> como true, que copia o código de status do objeto de resposta padrão para um novo objeto de resposta personalizado:

<AssignMessage name="copy-statuscode-1">
  <Copy source="response">
    <StatusCode>true</StatusCode>
  </Copy>
  <AssignTo createNew="true" transport="http" type="response">MyCustomResponse</AssignTo>
</AssignMessage>

Só é possível usar <StatusCode> quando as mensagens de origem e de destino são do tipo "Resposta".

Um uso comum de <StatusCode> é para definir o código de status da resposta do proxy com um valor diferente do recebido do destino.

<Verb> (filho de <Copy>)

Determina se o verbo HTTP é copiado da solicitação de origem para a solicitação de destino. Esse elemento não afeta respostas.

Se for true, copia o verbo encontrado no atributo source do elemento <Copy> para a solicitação especificada no elemento <AssignTo>.

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

O elemento <Verb> usa a seguinte sintaxe:

Sintaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <Verb>[false|true]</Verb>
  </Copy>
</AssignMessage>

Exemplo 1

No exemplo a seguir, definimos <Verb> como true, que copia o verbo da solicitação padrão para uma nova solicitação personalizada:

<AssignMessage name="copy-verb-1">
  <Copy source="request">
    <Verb>true</Verb>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

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

• Tipo de mensagem: solicitação

<Version> (filho de <Copy>)

Determina se a versão HTTP é copiada da solicitação de origem para a solicitação de destino. Esse elemento não afeta respostas.

Se for true, copia a versão HTTP encontrada no atributo source do elemento <Copy> para o objeto especificado pelo elemento <AssignTo>.

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

O elemento <Version> usa a seguinte sintaxe:

Sintaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Copy source="VARIABLE_NAME">
    <Version>[false|true]</Version>
  </Copy>
</AssignMessage>

Exemplo 1

No exemplo a seguir, definimos <Version> como true na solicitação, que copia a versão do objeto de solicitação padrão para um novo objeto de solicitação personalizado:

<AssignMessage name="copy-version-1">
  <Copy source="request">
    <Version>true</Version>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

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

• Tipo de mensagem: solicitação

<DisplayName>

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, more natural-sounding name.

The <DisplayName> element is common to all policies.

Default Value	N/A
Required?	Optional. If you omit <DisplayName>, the value of the policy's name attribute is used.
Type	String
Parent Element	<PolicyElement>
Child Elements	None

The <DisplayName> element uses the following syntax:

Syntax

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

Example

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

The <DisplayName> element has no attributes or child elements.

<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	<AssignMessage>
Elemento filho	Nenhum

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

Definir <IgnoreUnresolvedVariables> como true"true" é diferente de definir o continueOnError de <AssignMessage> 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

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>
</AssignMessage>

Exemplo 1

O exemplo a seguir define <IgnoreUnresolvedVariables> como true:

<AssignMessage name="AM-Set-Headers">
  <Set>
    <Headers>
      <Header name='new-header'>{possibly-defined-variable}<Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

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, parâmetros de formulário e/ou o payload da mensagem. Uma tag <Remove> vazia remove tudo na mensagem.

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	<AssignMessage>
Elemento filho	<FormParams> <Headers> <Payload> <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

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Remove all form parameters -->
    <FormParams/>
    <!-- or, remove specific form parameters by name -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME"/>
      <!-- or -->
      <FormParam name="FORMPARAM_NAME">[false|true]</FormParam>
      ...
    </FormParams>
    <!-- Remove all headers -->
    <Headers/>
    <!-- or, remove specific headers by name -->
    <Headers>
      <Header name="HEADER_NAME"/>
      <!-- or -->
      <Header name="HEADER_NAME">[false|true]</Header>
      ...
    </Headers>
    <Payload>[false|true]</Payload>
    <!-- Remove all query parameters -->
    <QueryParams/>
    <!-- or, remove specific query parameters by name -->
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME"/>
      <!-- or -->
      <QueryParam name="QUERYPARAM_NAME">[false|true]</QueryParam>
      ...
    </QueryParams>
  </Remove>
</AssignMessage>

Exemplo 1

O exemplo a seguir remove o corpo da mensagem da resposta:

<AssignMessage name="AM-remove-1">
  <DisplayName>remove-1</DisplayName>
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo>response</AssignTo>
</AssignMessage>

No fluxo de resposta, essa política remove o corpo da resposta, retornando apenas cabeçalhos HTTP para o cliente.

Exemplo 2

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

<AssignMessage name="AM-remove-2">
  <Remove>
    <!-- Empty (<FormParams/>) removes all form parameters -->
    <FormParams/>
    <QueryParams>
      <QueryParam name="qp1"/>
    </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

Exemplo 3

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

<AssignMessage name="AM-remove-3">
  <Remove/>
  <AssignTo>request</AssignTo>
</AssignMessage>

Normalmente, isso é feito apenas se você usar o <Set> ou<Copy> 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

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Remove all form parameters -->
    <FormParams/>
    <!-- or, remove specific form parameters by name -->
    <FormParams>
      <FormParam name="FORMPARAM_NAME"/>
      <!-- or -->
      <FormParam name="FORMPARAM_NAME">[false|true]</FormParam>
      ...
    </FormParams>
  </Remove>
</AssignMessage>

Exemplo 1

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

<AssignMessage name="AM-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>
</AssignMessage>

Exemplo 2

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

<AssignMessage name="AM-remove-formparams-2">
  <Remove>
    <FormParams/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

Exemplo 3

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

<AssignMessage name="AM-remove-formparams-3">
  <Remove>
    <FormParams>
      <FormParam name="f1"/>
      <FormParam name="f2"/>
      <FormParam name="f3.2"/>
    </FormParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Remove all headers -->
    <Headers/>
    <!-- or, remove specific headers by name -->
    <Headers>
      <Header name="HEADER_NAME"/>
      <!-- or -->
      <Header name="HEADER_NAME">[false|true]</Header>
      ...
    </Headers>
  </Remove>
</AssignMessage>

Exemplo 1

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

<AssignMessage name="AM-remove-one-header">
  <Remove>
    <Headers>
      <Header name="user-agent"/>
    </Headers>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

Exemplo 2

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

<AssignMessage name="AM-remove-all-headers">
  <Remove>
    <Headers/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

Exemplo 3

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

<AssignMessage name="AM-remove-headers-3">
  <Remove>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

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.

<Payload> (filho de <Remove>)

Determina se <Remove> exclui o payload na solicitação ou na resposta, conforme especificado pelo elemento <AssignTo>. Defina como true para limpar o payload. Caso contrário, false. O valor padrão é false.

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

O elemento <Payload> usa a seguinte sintaxe:

Sintaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <Payload>[false|true]</Payload>
  </Remove>
</AssignMessage>

Exemplo 1

No exemplo a seguir, <Payload> é definido como true para que o payload da solicitação seja apagado:

<AssignMessage name="AM-remove-payload-1">
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

<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

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <!-- Can also be empty to remove everything from the message (<Remove/>) -->
  <Remove>
    <!-- Remove all query parameters -->
    <QueryParams/>
    <!-- or, remove specific query parameters by name -->
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME"/>
      <!-- or -->
      <QueryParam name="QUERYPARAM_NAME">[false|true]</QueryParam>
      ...
    </QueryParams>
  </Remove>
</AssignMessage>

Exemplo 1

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

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

Exemplo 2

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

<AssignMessage name="AM-remove-queryparams-2">
  <Remove>
      <QueryParams/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

Exemplo 3

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

<AssignMessage name="AM-remove-queryparams-3">
  <Remove>
      <QueryParams>
        <QueryParam name="qp1"/>
        <QueryParam name="qp2"/>
        <QueryParam name="qp3.2"/>
      </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

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:

<AssignMessage name="AM-remove-query-param">
  <Remove>
    <QueryParams>
      <QueryParam name="apikey"/>
    </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

• Verbos HTTP: GET, POST, PATCH, DELETE
• 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 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	<AssignMessage>
Elemento filho	<FormParams> <Headers> <Payload> <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

<AssignMessage
    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>
    <Payload contentType="CONTENT_TYPE" variablePrefix="PREFIX"
        variableSuffix="SUFFIX">NEW_PAYLOAD</Payload>
    <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>
</AssignMessage>

Exemplo 1

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.

<AssignMessage name="AM-Set-Header">
  <Set>
    <Headers>
        <Header name="authenticated-developer">{verifyapikey.VAK-1.developer.id}</Header>
    </Headers>
  </Set>
  <AssignTo>request</AssignTo>
</AssignMessage>

Exemplo 2

No exemplo a seguir, o payload de uma resposta e o cabeçalho Content-Type são substituídos.

<AssignMessage name="AM-Overwrite-Payload">
  <Set>
    <Payload contentType="application/json">{ "status" : 42 }</Payload>
  </Set>
  <AssignTo>response</AssignTo>
</AssignMessage>

<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

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Set>
    <FormParams>
      <FormParam name="FORMPARAM_NAME">FORMPARAM_VALUE</FormParam>
      ...
    </FormParams>
  </Set>
</AssignMessage>

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:

<AssignMessage name="AM-set-formparams-1">
  <Set>
    <FormParams>
      <FormParam name="myparam">{request.header.myparam}</FormParam>
    </FormParams>
  </Set>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

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

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Set>
    <Headers>
      <Header name="HEADER_NAME">HEADER_VALUE</Header>
      ...
    </Headers>
  </Set>
</AssignMessage>

Exemplo 1

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

<AssignMessage name="AM-Set-RateLimit-Header">
  <Set>
    <Headers>
      <Header name="X-RateLimit-Remaining">{ratelimit.Quota-1.available.count}</Header>
    </Headers>
  </Set>
  <AssignTo>response</AssignTo>
</AssignMessage>

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. Isso funciona para definir o caminho em ServiceCallouts, conforme mostrado no exemplo do Aprenda com o exemplo abaixo.

Às vezes, pode ser necessário enviar uma mensagem para um URL diferente do URL definido no TargetEndpoint do proxy de API. Se você quiser reescrever o URL de destino, substitua a variável target.url em TargetEndpoint usando o elemento <AssignVariable>. Não é possível substituir target.url no ProxyEndpoint, porque a Apigee define a variável no TargetEndpoint.

O exemplo a seguir mostra como uma política AssignMessage substitui target.url. Novamente, adicione a política à solicitação TargetEndpoint. Com essa política, o proxy chamaria o URL abaixo, em vez do URL definido no TargetEndpoint.

<AssignMessage name="Assign-Message-1">
...
  <AssignVariable>
    <Name>target.url</Name>
    <Value>http://mocktarget.apigee.net/user?user=Dude</Value>
  </AssignVariable>
...

Também é possível usar uma política JavaScript no TargetEndpoint para substituir o target.url.

<Payload> (filho de <Set>)

Define o corpo da mensagem para uma solicitação ou resposta, que é especificada pelo elemento <AssignTo>. O payload pode ser qualquer tipo de conteúdo válido, como texto simples, JSON ou XML.

Valor padrão	String vazia
Obrigatório?	Opcional
Tipo	String
Elemento pai	<Set>
Elemento filho	Nenhum

O elemento <Payload> usa a seguinte sintaxe:

Sintaxe

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Set>
    <Payload contentType="CONTENT_TYPE" variablePrefix="PREFIX"
        variableSuffix="SUFFIX">NEW_PAYLOAD</Payload>
  </Set>
</AssignMessage>

Exemplo 1

O exemplo a seguir define um payload de texto simples:

<AssignMessage name="set-payload-1">
  <Set>
    <Payload contentType="text/plain">42</Payload>
  </Set>
</AssignMessage>

Exemplo 2

O exemplo a seguir define um payload JSON:

<AssignMessage name="set-payload-2">
  <Set>
    <Payload contentType="application/json">
      {"name":"foo", "type":"bar"}
    </Payload>
  </Set>
</AssignMessage>

Exemplo 3

O exemplo a seguir insere valores de variáveis no payload colocando nomes de variáveis entre chaves:

<AssignMessage name="set-payload-3">
  <Set>
    <Payload contentType="application/json">
      {"name":"foo", "type":"{variable_name}"}
    </Payload>
  </Set>
</AssignMessage>

Em versões mais antigas do Apigee, por exemplo, antes da versão de 16.08.17, não era possível usar chaves para indicar referências de variáveis em payloads JSON. Nessas versões, você precisava usar os atributos variablePrefix e variableSuffix para especificar caracteres delimitadores e usá-los para agrupar nomes de variáveis, como:

<AssignMessage name="set-payload-3b">
  <Set>
    <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
      {"name":"foo", "type":"@variable_name#"}
    </Payload>
  </Set>
</AssignMessage>

Essa sintaxe mais antiga ainda funciona.

Exemplo 4

O conteúdo de <Payload> é tratado como um modelo de mensagem. Isso significa que a política AssignMessage substitui as variáveis entre chaves pelo valor das variáveis referenciadas no ambiente de execução.

O exemplo a seguir usa a sintaxe de chaves para definir parte do payload como um valor de variável:

<AssignMessage name="set-payload-4">
  <Set>
    <Payload contentType="text/xml">
      <root>
        <e1>sunday</e1>
        <e2>funday</e2>
        <e3>{var1}</e3>
      </root>
    </Payload>
  </Set>
</AssignMessage>

Observação: não inclua a prólogo em XML no payload. Caso contrário, você receberá erros de validação XML.

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

Atributo	Descrição	Presence	Tipo
contentType	Se especificado, o valor de contentType é atribuído ao cabeçalho HTTP Content-Type.	Opcional	String
variablePrefix	Opcionalmente, especifica o delimitador inicial em uma variável de fluxo. O padrão é "{". Para mais informações, consulte a referência de variáveis de fluxo.	Opcional	Caracteres
variableSuffix	Opcionalmente, especifica o delimitador final em uma variável de fluxo. O padrão é "}". Para mais informações, consulte a referência de variáveis de fluxo.	Opcional	Caracteres

<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

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Set>
    <QueryParams>
      <QueryParam name="QUERYPARAM_NAME">QUERYPARAM_VALUE</QueryParam>
      ...
    </QueryParams>
  </Set>
</AssignMessage>

Exemplo 1

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

<AssignMessage name="AM-set-queryparams-1">
  <Set>
    <QueryParams>
      <QueryParam name="address">{request.header.address}</QueryParam>
    </QueryParams>
  </Set>
</AssignMessage>

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

• Verbos HTTP: GET, POST, PATCH, DELETE
• 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

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

Exemplo 1

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

<AssignMessage name="AM-set-statuscode-404">
  <Set>
    <StatusCode>404</StatusCode>
  </Set>
  <AssignTo>response</AssignTo>
</AssignMessage>

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:

<AssignMessage name="set-statuscode-2">
  <Set>
    <StatusCode>{calloutresponse.status.code}</StatusCode>
  </Set>
  <AssignTo>response</AssignTo>
</AssignMessage>

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

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

Exemplo 1

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

<AssignMessage name="AM-set-verb-1">
  <Set>
    <Verb>POST</Verb>
  </Set>
  <AssignTo>request</AssignTo>
</AssignMessage>

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:

<AssignMessage name="AM-set-verb-to-dynamic-value">
  <Set>
    <Verb>{my_variable}</Verb>
  </Set>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

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

Exemplo 1

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

<AssignMessage name="AM-set-version-1">
  <Set>
    <Version>1.1</Version>
  </Set>
 </AssignMessage>

Exemplo 2

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

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

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 a política AssignMessage 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 AssignMessage. Defina createNew como true e especifique o nome da nova mensagem no corpo do elemento, como no exemplo a seguir:

<AssignMessage name="assignto-2">
  <AssignTo createNew="true" transport="http" type="request">MyRequestObject</AssignTo>
  ...
</AssignMessage>

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 como a política ServiceCallout ao seu proxy e faça referência explícita à mensagem de solicitação recém-criada na configuração dessa política. 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 exemplo a seguir cria um objeto de solicitação personalizado com AssignMessage:

<AssignMessage name="AssignMessage-3">
  <AssignTo createNew="true" type="request">MyCustomRequest</AssignTo>
  <Copy>
    <Headers>
      <Header name="user-agent"/>
    </Headers>
  </Copy>
  <Set>
    <QueryParams>
      <QueryParam name="address">{request.queryparam.addy}</QueryParam>
    </QueryParams>
    <Verb>GET</Verb>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

Este exemplo:

• Cria um novo objeto de mensagem de solicitação chamado MyCustomRequest.
• Em MyCustomRequest, esta política:
  • Copia o valor do cabeçalho HTTP user-agent da solicitação recebida para a nova mensagem. Como <Copy> não especifica o atributo source, a Apigee usará a mensagem request como origem para a cópia.
  • 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 AssignMessage.

<AssignMessage name="AssignMessage-2">
  <AssignTo createNew="true" type="request">partner.request</AssignTo>
  <Set>
    <Verb>POST</Verb>
    <Payload contentType="text/xml">
      <request><operation>105</operation></request>
    </Payload>
  </Set>
</AssignMessage>

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

É possível acessar as várias propriedades de uma mensagem personalizada em outra política AssignMessage que ocorra mais adiante 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:

<AssignMessage name="AM-Copy-Custom-Header">
  <AssignTo>request</AssignTo>
  <Set>
    <Headers>
      <Header name="injected-approval-id">{MyCalloutResponse.header.approval-id}</Header>
    </Headers>
  </Set>
</AssignMessage>

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 corrigido para ver informações detalhadas sobre solução de problemas.

Código de falha	Status HTTP	Causa	Correção
steps.assignmessage.SetVariableFailed	500	Não foi possível definir uma variável na política. Veja a string de falha para o nome da variável não resolvida.
steps.assignmessage.VariableOfNonMsgType	500	Esse erro ocorrerá se o atributo source no elemento <Copy> estiver definido como uma variável diferente do tipo message. As variáveis do tipo Message representam solicitações e respostas HTTP completas. As variáveis integradas do fluxo da Apigee request, response e message são do tipo "menssagem". Para saber mais sobre variáveis de mensagens, consulte a referência de variáveis.
steps.assignmessage.UnresolvedVariable	500	Esse erro ocorrerá se uma variável especificada na política AssignMessage: Fora do escopo (não disponível no fluxo específico em que a política está sendo executada) ou Não é possível resolver (não está definida)

Erros na 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	Correção
InvalidIndex	Se o índice especificado nos elementos <Copy> e/ou <Remove> da política AssignMessage for 0 ou um número negativo, a implantação do proxy da API falhará.
InvalidVariableName	Se o elemento filho <Name> estiver vazio ou não for especificado no elemento <AssignVariable>, a implantação do proxy de API falhará porque não há um nome de variável válido para atribuir um valor. Um nome de variável válido é obrigatório.
InvalidPayload	Um payload especificado na política é inválido.

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
fault.name="FAULT_NAME"	FAULT_NAME é o nome da falha, conforme listado na tabela Erros de ambiente de execução acima. O nome da falha é a última parte do código de falha.	fault.name Matches "UnresolvedVariable"
assignmessage.POLICY_NAME.failed	POLICY_NAME é o nome especificado pelo usuário da política que causou a falha.	assignmessage.AM-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.assignmessage.VariableOfNonMsgType"
      },
      "faultstring":"AssignMessage[AM-SetResponse]: value of variable is not of type Message"
   }
}

Exemplo de regra de falha

<FaultRule name="Assign Message Faults">
    <Step>
        <Name>AM-CustomNonMessageTypeErrorResponse</Name>
        <Condition>(fault.name Matches "VariableOfNonMsgType") </Condition>
    </Step>
    <Step>
        <Name>AM-CustomSetVariableErrorResponse</Name>
        <Condition>(fault.name = "SetVariableFailed")</Condition>
    </Step>
    <Condition>(assignmessage.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.

Temas relacionados

As amostras de trabalho da política AssignMessage estão disponíveis nas amostras da API Platform.

Para um exemplo mais avançado de como substituir o target.url do ProxyEndpoint, consulte este artigo da comunidade do Apigee.

Para ver um caminho de definição em ação em uma política de destaque de serviço, veja este exemplo nas amostras do GitHub do Apigee. Basta clonar o repositório e seguir as instruções nele. O exemplo usa AssignMessage para definir um caminho de solicitação e, em seguida, usa uma política ServiceCallout para fazer a solicitação a um serviço externo.