Como usar variáveis de fluxo

Você está visualizando a documentação do Apigee Edge.
Acesse a documentação da Apigee X. info

Conceitualmente, as variáveis de fluxo são objetos que podem ser acessados de dentro das políticas ou de utilitários (como a ferramenta Trace). Elas permitem que você mantenha o estado associado a uma transação da API processada pelo Apigee Edge.

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 o Edge recebe uma solicitação;
  • dados derivados quando uma política é executada. Por exemplo, após a execução de uma política que valida um token OAuth, o Edge 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 "integradas" ao Edge e são preenchidas automaticamente sempre que 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, Node.js 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 fazer referência a variáveis de fluxo para direcionar o fluxo de uma API usando o Edge, da mesma forma que a instrução de chave funciona na programação

    Por exemplo, uma política para retornar uma falha só pode ser executada quando uma determinada variável de fluxo é definida. Por fim, é possível receber e definir variáveis de fluxo em um aplicativo de destino do Node.js.

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 incorporadas do Edge.

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 Noções básicas sobre o escopo de variáveis de fluxo.

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"));

A técnica de uso de JavaScript para ler e definir variáveis é semelhante ao que é possível fazer com a política AssignMessage, mostrada anteriormente. Essa é apenas mais uma maneira de realizar as mesmas taregas no Edge. Lembre-se de que o JavaScript executado pela política JavaScript tem acesso a todas as variáveis de fluxo existentes e que estão em escopo no fluxo do proxy de API.

Variáveis de fluxo no código Node.js

Ao exigir o módulo apigee-access, é possível definir e acessar variáveis de fluxo no código Node.js implantado no Edge.

Confira um exemplo simples em que uma variável chamada custom.foo é definida como o valor Bar. Depois de definida, essa nova variável fica disponível para qualquer política ou outro código que ocorra no fluxo de proxy após a execução do código Node.js.

var http = require('http');
var apigee = require('apigee-access');

http.createServer(function (request, response) {
  apigee.setVariable(request, "custom.foo", "Bar");
  response.writeHead(200, {'Content-Type': 'text/plain'});
  response.end('Hello World\n');
}).listen(8124);

console.log('Server running at http://127.0.0.1:8124/');

Leia mais sobre como usar apigee-access para trabalhar com variáveis em Como acessar variáveis de fluxo no Node.js.

Noções básicas sobre o escopo da variável de fluxo

O escopo da variável está relacionado ao fluxo ou ao "ciclo de vida" geral de uma chamada de proxy de 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.

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.

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 integrada do Edge chamada client.ip. Essa variável tem o escopo "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.

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.

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 incorporadas no Apigee Edge seguem uma convenção de nomenclatura de anotação de ponto. Essa convenção facilita a determinação da finalidade da variável. Por exemplo, system.time.hour e request.content.

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. Confira mais informações em:

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. Por exemplo, variáveis criadas no código Node.js são restritas a número, string, booleano, nulo ou indefinido.

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. Você pode usar a ferramenta Trace, 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, "Extrair variáveis" analisa uma mensagem de resposta e armazena dados específicos 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 objetos JavaScript da Apigee, o JavaScript em execução no Edge tem acesso direto às variáveis de fluxo do proxy.

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 as variáveis do 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.

Também é possível receber/definir variáveis de fluxo de proxy no código Java que você executa com a política JavaCalling.

Como acessar variáveis de fluxo em aplicativos Node.js

É possível receber, definir e excluir variáveis de fluxo do código Node.js implantado no Edge. Basta "requerer" o módulo apigee-access no código. Para mais detalhes, consulte Como acessar variáveis de fluxo em Node.js.

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 a política JavaScript, e no código Node.js.
  • 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.
  • É possível receber e definir muitas variáveis de fluxo no Node.js usando JavaScript direto (e nosso modelo de objeto JavaScript) ou a política JavaCallout, que executa o código no Edge.

Exemplos de código relacionados

As amostras de proxy de API estão no GitHub e são fáceis de fazer o download e de usar. Consulte Como usar os proxies de API de amostra para informações sobre como fazer o download e usar as amostras. Consulte a lista de amostras para ver uma descrição das amostras de proxy de API e o que elas fazem.

Os proxies de exemplo que apresentam o uso de variáveis e processamento de variáveis incluem:

  • variáveis (em inglês): demonstra como extrair e definir variáveis com base no transporte e no conteúdo de mensagens JSON e XML.
  • policy-mash-cookbook (em inglês): um aplicativo completo que usa a composição de política para chamar duas APIs públicas, combina resultados e gera uma resposta enriquecida do app cliente. Para mais informações sobre essa amostra, consulte Como usar a composição de política.
  • conditional-policy (em inglês): implementa a aplicação simples de política condicional com base em valores de variáveis.

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.