Como usar variáveis de fluxo

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

Confira a documentação da Apigee Edge.

Variáveis de fluxo são objetos que podem ser acessados de acordo com suas políticas ou utilitários (como a ferramenta Debug). Elas permitem manter o estado associado a uma transação de API processada pela Apigee.

Guia de início rápido: para uma lista completa de todas as variáveis de fluxo e as propriedades delas, consulte a referência de variáveis de fluxo.

Vídeo

Observação: o vídeo a seguir mostra o editor clássico de proxy na interface da Apigee. A Apigee está introduzindo uma nova versão do Editor de Proxy, que tem um design diferente da versão clássica mostrada no vídeo.

O vídeo a seguir fornece uma introdução às variáveis de fluxo:

O que são variáveis de fluxo?

As variáveis de fluxo existem no contexto de um fluxo de proxy de API e rastreiam o estado em uma transação da API do mesmo modo que as variáveis nomeadas rastreiam o estado em um programa de software. As variáveis de fluxo armazenam informações como:

• o endereço IP, os cabeçalhos, o caminho do URL e o payload enviado pelo app solicitante;
• Informações do sistema, como a data e a hora em que a Apigee recebe uma solicitação
• dados derivados quando uma política é executada. Por exemplo, depois que uma política que valida um token do OAuth é executada, a Apigee cria variáveis de fluxo que contêm informações como o nome do aplicativo solicitante.
• informações sobre a resposta do sistema de destino.

Algumas variáveis são incorporadas à Apigee e preenchidas automaticamente quando uma solicitação de API é recebida. Elas estão disponíveis em uma transação de API. Você também pode criar suas próprias variáveis personalizadas usando políticas como a política AssignMessage ou em código JavaScript e Java.

Como você verá, as variáveis têm escopo e onde elas são acessíveis depende em parte quando são criadas no fluxo do proxy de API. Em geral, quando uma variável é criada, ela fica disponível para todas as políticas e códigos que são executados posteriormente no fluxo de transação de API.

Como as variáveis de fluxo são usadas?

A variável de fluxo é usada em políticas e em fluxos condicionais:

• As políticas podem recuperar o estado das variáveis de fluxo e usá-los para realizar o trabalho.

  Por exemplo, uma política VerifyJWT pode recuperar o token a ser verificado a partir de uma variável de fluxo e, em seguida, executar a verificação. Outro exemplo, uma política JavaScript pode recuperar variáveis de fluxo e codificar os dados contidos nessas variáveis.

• Os fluxos condicionais podem referenciar as variáveis de fluxo para direcionar o fluxo de uma API por meio da Apigee, da mesma forma que uma instrução de chave funciona na programação.

  Por exemplo, uma política para retornar uma falha pode ser executada somente quando uma determinada variável de fluxo é definida.

Vejamos exemplos de como as variáveis são usadas em cada um desses contextos.

Variáveis de fluxo em políticas

Algumas políticas usam variáveis de fluxo como entrada.

Por exemplo, a política AssignMessage a seguir recebe o valor da variável de fluxo client.ip e o coloca em um cabeçalho de solicitação chamado My-Client-IP. Se adicionada ao fluxo request, essa política definirá um cabeçalho que será transmitido para o destino de back-end. Se configurado no fluxo response, o cabeçalho será enviado de volta ao aplicativo cliente.

<AssignMessage name="set-ip-in-header">
    <AssignTo createNew="false" transport="http" type="request">request</AssignTo>
    <Set>
        <Headers>
            <Header name="My-Client-IP">{client.ip}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Outro exemplo: quando uma política de cotas é executada, várias variáveis de fluxo são preenchidas com valores relacionados à política. Uma dessas variáveis é chamada ratelimit.my-quota-policy.used.count, em que my-quota-policy é o nome da política de cotas em que você tem interesse.

Posteriormente, você pode executar um fluxo condicional que diz "se a contagem atual da cota estiver abaixo de 50% do máximo e estiver entre 9h e 17h, aplique uma cota diferente". Essa condição pode depender do valor da contagem de cota atual e de uma variável de fluxo chamada system.time, que é uma das variáveis predefinidas da Apigee.

Variáveis de fluxo em fluxos condicionais

Os fluxos condicionais avaliam as variáveis de fluxo e permitem que os proxies se comportem dinamicamente. Normalmente, as condições são usadas para alterar o comportamento de fluxos, etapas e regras de rota.

Aqui está um fluxo condicional que avalia o valor da variável request.verb em uma etapa de fluxo de proxy. Nesse caso, se o verbo de solicitação for POST, a política VerifyAPIKey será executada. Esse é um padrão comum usado nas configurações de proxy de API.

<PreFlow name="PreFlow">
    <Request>
        <Step>
            <Condition>request.verb equals "POST"</Condition>
            <Name>VerifyApiKey</Name>
        </Step>
    </Request>
</PreFlow>

Agora, você pode se perguntar: de onde vêm variáveis como request.verb, client.ip e system.time? Quando elas são instanciadas e preenchidas com um valor? Para entender quando as variáveis são criadas e quando elas estão disponíveis para você, consulte Como visualizar o fluxo de um proxy de API.

Variáveis de fluxo no código JavaScript chamadas com a política de JavaScript

Com a política JavaScript, é possível executar o código JavaScript no contexto de um fluxo de proxy de API. O JavaScript executado por esta política usa o modelo de objeto JavaScript da Apigee, que fornece ao código personalizado acesso à solicitação, resposta e objetos de contexto associados ao fluxo de proxy de API em que seu código está sendo executado. Por exemplo, esse código define um cabeçalho de resposta com o valor obtido da variável de fluxo target.name.

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"));

Essa técnica de uso de JavaScript para ler e definir variáveis é semelhante ao trabalho que você faz com a política AssignMessage, mostrada anteriormente. Essa é apenas mais uma maneira de realizar os mesmos tipos de coisas na Apigee. A chave a ser lembrada é que o JavaScript executado pela política JavaScript tem acesso a todas as variáveis de fluxo atuais e que estão no escopo dentro do fluxo do proxy da API.

Como visualizar o fluxo de um proxy de API

Para entender o escopo da variável de fluxo, é importante entender ou visualizar como as mensagens passam por um proxy de API. Um proxy de API consiste em uma série de etapas de processamento de mensagens organizadas como fluxo. Em cada etapa de um fluxo de proxy, o proxy avalia as informações disponíveis para ele e decide o que fazer em seguida. Durante o processo, o proxy pode executar um código de política ou realizar ramificação condicional.

A figura a seguir ilustra essa sequência de fluxos. Observe como os fluxos são compostos por quatro segmentos principais: a solicitação ProxyEndpoint, a solicitação TargetEndpoint, a resposta de TargetEndpoint e a resposta ProxyEndpoint.

Lembre-se dessa estrutura de fluxo conforme começamos a explorar as variáveis de fluxo no restante deste tópico.

Leia mais Se quiser ler a estrutura de fluxo de proxy em mais detalhes, consulte Como configurar fluxos.

Como o escopo da variável está relacionado ao fluxo de proxy

É possível começar a entender o escopo da variável assim que for possível visualizar como as mensagens passam por um proxy, conforme descrito anteriormente. Escopo significa o ponto no ciclo de vida do fluxo de proxy quando uma variável é instanciada pela primeira vez.

Por exemplo, se você tiver uma política anexada ao segmento da solicitação ProxyEndpoint, essa política não poderá acessar nenhuma variável com escopo no segmento de solicitação TargetEndpoint. O motivo disso é que o segmento de solicitação TargetEndpoint do fluxo ainda não foi executado. Portanto, o proxy de API não teve a chance de preencher variáveis nesse escopo.

A tabela a seguir lista o conjunto completo de escopos de variáveis e indica quando eles estarão disponíveis no fluxo do proxy.

Observação: depois que uma variável de fluxo é preenchida no escopo fornecido, ela permanece disponível durante o restante do ciclo de vida do fluxo de proxy. Se você tentar acessar uma variável que ainda não está no escopo, receberá um erro ou um valor NULL.

Escopo de variáveis	Onde essas variáveis são preenchidas
Solicitação de proxy	O segmento da solicitação ProxyEndpoint
Solicitação de destino	O segmento da solicitação TargetEndpoint
Resposta de destino	O segmento da resposta TargetEndpoint
Resposta do proxy	Segmento da resposta ProxyEndpoint
Sempre disponível	Assim que o proxy receber uma solicitação. Essas variáveis estão disponíveis em todo o ciclo de vida do fluxo do proxy.

Por exemplo, há uma variável predefinida da Apigee chamada client.ip. Essa variável tem o escopo de solicitação de proxy. Ela é preenchida automaticamente com o endereço IP do cliente que chamou o proxy. Ela é preenchida quando uma solicitação atinge o ProxyEndpoint pela primeira vez e permanece disponível durante todo o ciclo de vida de fluxo do proxy.

Observação: os escopos de todas as variáveis predefinidas da Apigee estão listados na Referência de variáveis de fluxo.

Há outra variável incorporada chamada target.url. O escopo dessa variável é solicitação de destino. Ele é preenchido no segmento de solicitação TargetEndpoint com o URL de solicitação enviado ao destino de back-end. Se você tentar acessar target.url no segmento de solicitação ProxyEndpoint, receberá um valor NULL. Se você tentar definir essa variável antes que ela esteja no escopo, o proxy não fará nada, não gerará um erro e não definirá a variável.

Observação: é possível configurar algumas políticas para emitir um erro ou retornar NULL quando uma variável indefinida for acessada. Consulte as páginas individuais de referências de políticas para mais detalhes.

Veja um exemplo simples que demonstra como pensar sobre o escopo da variável. Suponha que você queira copiar todo o conteúdo de um objeto de solicitação (cabeçalhos, parâmetros, corpo) e atribuí-lo ao payload de resposta para ser enviado de volta ao aplicativo de chamada. É possível usar a política AssignMessage para essa tarefa. O código da política é semelhante a este:

<AssignMessage name="CopyRequestToResponse">
    <AssignTo type="response" createNew="false">response</AssignTo>
    <Copy source="request"/>
</AssignMessage>

Essa política simplesmente copia o objeto request e o atribui ao objeto response. Mas onde essa política deve ser colocada no fluxo do proxy? A resposta é que ela precisa ser colocada na resposta TargetEndpoint, porque o escopo da variável da resposta é resposta de destino.

Como fazer referência a variáveis de fluxo

Todas as variáveis predefinidas da Apigee seguem uma convenção de nomenclatura de ponto. Essa convenção facilita a determinação da finalidade da variável. Por exemplo, system.time.hour e request.content.

Prática recomendada: o Google recomenda que você use a convenção de nomenclatura de ponto ao criar variáveis de fluxo personalizadas. Pode ser útil usar os pontos para organizar uma hierarquia das variáveis personalizadas.

Por exemplo, approval.code e approval.status podem se referir a um recurso de aprovação dentro do fluxo.

A Apigee reserva vários prefixos para organizar as variáveis relevantes adequadamente. Esses prefixos incluem:

• request
• response
• system
• target

Para fazer referencia uma variável em uma política, coloque-a entre chaves. Por exemplo, a política AtribuirMessage a seguir usa o valor da variável client.ip e o coloca em um cabeçalho de solicitação chamado Client-IP.

<AssignMessage name="set-ip-in-header">
    <AssignTo createNew="false" transport="http" type="request">request</AssignTo>
    <Set>
        <Headers>
            <Header name="Client-IP">{client.ip}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Em fluxos condicionais, as chaves não são necessárias. A condição de exemplo a seguir avalia a variável request.header.accept:

<Step>
    <Condition>request.header.accept = "application/json"</Condition>
    <Name>XMLToJSON</Name>
</Step>

Também é possível fazer referência a variáveis de fluxo em código JavaScript e Java. Veja mais informações em:

• Como trabalhar com variáveis de fluxo no código JavaScript
• Política de JavaScript

Tipo de dados de variáveis de fluxo

Cada propriedade de uma variável de fluxo tem um tipo de dados bem definido, como String, Long, Integer, Boolean ou Collection. Veja os tipos de dados listados na Referência de variáveis de fluxo. Para as variáveis criadas por uma política, consulte o tópico de referência da política específica para informações de tipo de dados.

As variáveis criadas manualmente assumem o tipo fornecido quando foram criadas e dependem dos tipos de valores permitidos.

Como usar variáveis de fluxo em políticas

Muitas políticas criam variáveis de fluxo como parte da execução normal. A Referência de políticas documenta todas essas variáveis específicas da política.

Ao trabalhar com proxies e políticas, consulte a referência da política para saber quais variáveis são criadas e para que elas são usadas. Por exemplo, a Política de cotas cria um conjunto de variáveis que contêm informações sobre contagens e limites de cota, tempo de validade e assim por diante.

Algumas variáveis de política são úteis para depuração. Use a ferramenta Debug, por exemplo, para ver quais variáveis foram definidas em uma instância específica em um fluxo de proxy.

A política ExtractVariables permite preencher variáveis personalizadas com dados extraídos de mensagens. É possível extrair parâmetros de consulta, cabeçalhos e outros dados. Por exemplo, é possível analisar mensagens de solicitação e resposta usando padrões para extrair dados específicos das mensagens.

No exemplo a seguir, a política ExtractVariables analisa uma mensagem de resposta e armazena dados específicos retirados da resposta. A política cria duas variáveis personalizadas, geocoderesponse.latitude e geocoderesponse.longitude, e atribui valores a elas.

<ExtractVariables name="ParseGeocodingResponse">
  <Source>response</Source>
  <VariablePrefix>geocoderesponse</VariablePrefix>
  <JSONPayload>
    <Variable name="latitude">
      <JSONPath>$.results[0].geometry.location.lat</JSONPath>
    </Variable>
    <Variable name="longitude">
      <JSONPath>$.results[0].geometry.location.lng</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

Mais uma vez, saiba que muitas políticas criam variáveis automaticamente. É possível acessar essas variáveis no contexto do fluxo de proxy e elas são documentadas na referência da política em cada tópico individual de política.

Como trabalhar com variáveis de fluxo no código JavaScript

É possível acessar e definir variáveis diretamente no código JavaScript que está sendo executado no contexto de um proxy de API. Por meio do modelo de objeto JavaScript da Apigee, o JavaScript executado na Apigee tem acesso direto às variáveis de fluxo do proxy.

Observação: é possível chamar o JavaScript de um proxy usando a política JavaScript.

Para acessar variáveis no código JavaScript, chame os métodos getter/setter em qualquer um desses objetos:

• context
• proxyRequest
• proxyResponse
• targetRequest
• targetResponse

Como você pode ver, essas referências de objeto mapeiam para os segmentos conhecidos do modelo de fluxo de proxy, conforme explicado anteriormente em Como visualizar o fluxo de um proxy de API.

O objeto context corresponde a variáveis disponíveis globalmente, como variáveis de sistema. Por exemplo, é possível chamar getVariable() no objeto context para receber o ano atual:

var year = context.getVariable('system.time.year');

Da mesma forma, é possível chamar setVariable() para definir o valor de uma variável personalizada ou para qualquer variável gravável pronta para uso. Aqui, criamos uma variável personalizada chamada organization.name.myorg e atribuímos um valor a ela.

var org = context.setVariable('organization.name.myorg', value);

Como essa variável é criada com o objeto context, ela estará disponível para todos os segmentos de fluxo. Basicamente, é como criar uma variável global.

Observação: referência de variáveis de fluxo indica quais variáveis são graváveis e quais são somente leitura. Para mais informações, consulte o modelo de objeto JavaScript.

Também é possível receber ou definir variáveis de fluxo de proxy no código Java executado com a política JavaCallout.

Do que você precisa lembrar

Veja a seguir algumas observações importantes sobre as variáveis de fluxo:

• Algumas variáveis prontas para uso são instanciadas e preenchidas automaticamente pelo próprio proxy. Elas estão documentados na referência de variáveis de fluxo.
• É possível criar variáveis personalizadas disponíveis para uso no fluxo do proxy. É possível criar variáveis usando políticas como a política AssignMessage e política JavaScript.
• As variáveis têm escopo. Por exemplo, algumas variáveis são preenchidas automaticamente quando o primeiro proxy recebe uma solicitação de um app. Outras variáveis são preenchidas no segmento do fluxo de resposta do proxy. Essas variáveis de resposta permanecem indefinidas até que o segmento de resposta seja executado.
• Quando as políticas são executadas, elas podem criar e preencher variáveis específicas da política. A documentação de cada política lista todas essas variáveis relevantes específicas de políticas.
• Os fluxos condicionais normalmente avaliam uma ou mais variáveis. É preciso entender as variáveis se você quiser criar fluxos condicionais.
• Muitas políticas usam variáveis como entrada ou saída. Talvez uma variável criada por uma política seja usada posteriormente por outra.

Dica: você encontrará várias amostras que usam variáveis de uma forma ou de outra. Procure as que usam a política ExtractVariables, que costuma ser usada para processar variáveis em um fluxo de proxy.

Temas relacionados

• Todas as variáveis que são preenchidas automaticamente em um proxy de API estão listadas na Referência de variáveis de fluxo. A referência também lista o tipo e o escopo de cada variável.
• Se você quiser saber quais variáveis uma política específica preenche, consulte o tópico de referência da política. Por exemplo, consulte Variáveis de fluxo na referência da Política de cotas.