Usar variáveis de fluxo

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

As variáveis de fluxo são objetos aos quais pode aceder a partir das suas políticas ou utilitários (como a ferramenta de depuração). Permitem-lhe manter o estado associado a uma transação de API processada pelo Apigee.

Início rápido: para ver uma lista completa de todas as variáveis de fluxo e respetivas propriedades, consulte o artigo Referência de variáveis de fluxo.

Vídeo

Nota: o vídeo seguinte mostra o editor de proxy clássico na IU do Apigee. A Apigee está a introduzir uma nova versão do Proxy Editor, que tem um design diferente da versão clássica apresentada no vídeo.

O vídeo seguinte apresenta as 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 acompanham o estado numa transação de API da mesma forma que as variáveis com nome acompanham o estado num programa de software. As variáveis de fluxo armazenam informações como:

• O endereço IP, os cabeçalhos, o caminho do URL e a carga útil enviados a partir da app que está a fazer o pedido
• Informações do sistema, como a data e a hora em que o Apigee recebe um pedido
• Dados derivados quando uma política é executada. Por exemplo, após a execução de uma política que valida um token OAuth, o Apigee cria variáveis de fluxo que contêm informações como o nome da aplicação que está a fazer o pedido.
• Informações sobre a resposta do sistema de destino

Algumas variáveis estão incorporadas no Apigee e são preenchidas automaticamente sempre que é recebido um pedido de API. Estão disponíveis durante uma transação de API. Também pode criar as suas próprias variáveis personalizadas através de políticas como a política AssignMessage ou em JavaScript e código Java.

Como vai ver, as variáveis têm âmbito, e o local onde são acessíveis depende, em parte, do momento em que são criadas no fluxo do proxy de API. Em geral, quando uma variável é criada, fica disponível para todas as políticas e código que são executados mais tarde no fluxo de transações da API.

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

As variáveis de fluxo são usadas em políticas e fluxos condicionais:

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

  Por exemplo, uma política VerifyJWT pode obter o token a validar a partir de uma variável de fluxo e, em seguida, efetuar a validação no mesmo. Como outro exemplo, uma política de JavaScript pode obter 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 através do Apigee, de forma semelhante ao funcionamento de uma declaração switch na programação.

  Por exemplo, uma política para devolver uma falha pode ser executada apenas quando uma variável de fluxo específica é definida.

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

Variáveis de fluxo nas políticas

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

Por exemplo, a seguinte política AssignMessage usa o valor da variável de fluxo client.ip e coloca-o num cabeçalho do pedido denominado My-Client-IP. Se for adicionada ao fluxo request, esta política define um cabeçalho que é transmitido ao destino de back-end. Se for definido no fluxo de resposta, o cabeçalho é enviado de volta para a app 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>

Por outro lado, quando uma política de quotas é executada, várias variáveis de fluxo são preenchidas com valores relacionados com a política. Uma destas variáveis chama-se ratelimit.my-quota-policy.used.count (em que my-quota-policy é o nome da política de quotas que lhe interessa).

Posteriormente, pode executar um fluxo condicional que indique "se a contagem atual da quota for inferior a 50% do máximo e for entre as 09:00 e as 17:00, aplique uma quota diferente". Esta condição pode depender do valor da contagem de quotas atual e de uma variável de fluxo denominada system.time, que é uma das variáveis incorporadas do 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. As condições são normalmente usadas para alterar o comportamento dos fluxos, dos passos e das regras de encaminhamento.

Segue-se um fluxo condicional que avalia o valor da variável request.verb num passo de fluxo de proxy. Neste caso, se o verbo de pedido for POST, a política VerifyAPIKey é executada. Este é 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, pode perguntar-se de onde vêm variáveis como request.verb, client.ip e system.time. Quando são instanciados e preenchidos com um valor? Para ajudar a compreender quando as variáveis são criadas e quando estão disponíveis, consulte o artigo 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 de JavaScript, pode executar código JavaScript a partir do contexto de um fluxo de proxy de API. O JavaScript executado por esta política usa o modelo de objeto JavaScript do Apigee, que fornece ao seu código personalizado acesso a objetos de pedido, resposta e contexto associados ao fluxo do proxy de API no qual o seu código está a ser executado. Por exemplo, este 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"));

Esta técnica de utilização do JavaScript para ler e definir variáveis é semelhante ao trabalho que pode fazer com a política AssignMessage (mostrada anteriormente). É apenas outra forma de realizar os mesmos tipos de tarefas no Apigee. A chave a lembrar é que o JavaScript executado pela política de JavaScript tem acesso a todas as variáveis de fluxo existentes e no âmbito no fluxo do proxy de API.

Visualizar o fluxo de um proxy de API

Para compreender o âmbito das variáveis de fluxo, é importante compreender ou visualizar a forma como as mensagens fluem através de um proxy de API. Um proxy de API consiste numa série de passos de processamento de mensagens organizados como um fluxo. Em cada passo de um fluxo de proxy, o proxy avalia as informações disponíveis e decide o que fazer a seguir. Ao longo do processo, o proxy pode executar código de política ou realizar ramificações condicionais.

A figura seguinte ilustra esta sequência de fluxos. Repare como os fluxos são compostos por quatro segmentos principais: pedido ProxyEndpoint , pedido TargetEndpoint , resposta TargetEndpoint e resposta ProxyEndpoint .

Tenha em atenção esta estrutura de fluxo à medida que começamos a explorar as variáveis de fluxo ao longo do resto deste tópico.

Leituras adicionais Se quiser ler acerca da estrutura do fluxo de proxy mais detalhadamente, consulte o artigo Configurar fluxos.

Como o âmbito das variáveis está relacionado com o fluxo do proxy

Assim que conseguir visualizar o fluxo de mensagens através de um proxy, conforme descrito anteriormente, pode começar a compreender o âmbito das variáveis. Por âmbito, referimo-nos ao ponto no ciclo de vida do fluxo de proxy em que uma variável é instanciada pela primeira vez.

Por exemplo, se tiver uma política anexada ao segmento de pedido ProxyEndpoint, essa política não vai poder aceder a nenhuma variável com âmbito no segmento de pedido TargetEndpoint. O motivo é que o segmento de pedido TargetEndpoint do fluxo ainda não foi executado, pelo que o proxy da API ainda não teve oportunidade de preencher as variáveis nesse âmbito.

A tabela seguinte lista o conjunto completo de âmbitos das variáveis e indica quando ficam disponíveis no fluxo do proxy.

Nota: depois de uma variável de fluxo ser preenchida no respetivo âmbito, permanece disponível durante o resto do ciclo de vida do fluxo de proxy. Se tentar aceder a uma variável que ainda não esteja no âmbito, recebe um erro ou um valor NULL.

Âmbito da variável	Onde estas variáveis são preenchidas
pedido de proxy	O segmento de pedido ProxyEndpoint
pedido de destino	O segmento de pedido TargetEndpoint
resposta-alvo	O segmento de resposta TargetEndpoint
resposta do proxy	O segmento de resposta ProxyEndpoint
sempre disponível	Assim que o proxy recebe um pedido. Estas variáveis estão disponíveis durante todo o ciclo de vida do fluxo de proxy.

Por exemplo, existe uma variável Apigee incorporada denominada client.ip. Esta variável tem o âmbito de pedido de proxy. É preenchido automaticamente com o endereço IP do cliente que chamou o proxy. É preenchido quando um pedido atinge pela primeira vez o ProxyEndpoint e permanece disponível durante todo o ciclo de vida do fluxo do proxy.

Nota: os âmbitos de todas as variáveis Apigee incorporadas estão listados na referência de variáveis de fluxo.

Existe outra variável incorporada denominada target.url. O âmbito desta variável é o pedido de destino. É preenchido no segmento de pedido TargetEndpoint com o URL de pedido enviado para o destino de back-end. Se tentar aceder a target.url no segmento da solicitação ProxyEndpoint, recebe um valor NULL. Se tentar definir esta variável antes de estar no âmbito, o proxy não faz nada: não gera um erro nem define a variável.

Nota: é possível configurar algumas políticas para gerar um erro ou devolver NULL quando é acedida uma variável indefinida. Consulte as páginas de referência das políticas individuais para ver detalhes.

Segue-se um exemplo simples que demonstra como pensar no âmbito das variáveis. Suponhamos que quer copiar todo o conteúdo de um objeto de pedido (cabeçalhos, parâmetros, corpo) e atribuí-lo à carga útil de resposta a ser enviada de volta para a app de chamada. Pode usar a política AssignMessage para esta tarefa. O código da política tem o seguinte aspeto:

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

Esta política copia simplesmente o objeto request e atribui-o ao objeto response. Mas onde deve esta política ser colocada no fluxo de proxy? A resposta é que tem de ser colocada na resposta TargetEndpoint, porque o âmbito da variável de resposta é resposta-alvo.

Referenciar variáveis de fluxo

Todas as variáveis incorporadas no Apigee seguem uma convenção de nomenclatura de notação de pontos. Esta convenção facilita a determinação da finalidade da variável. Por exemplo, system.time.hour e request.content.

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

Por exemplo, approval.code e approval.status podem referir-se a uma funcionalidade de aprovação no fluxo.

O Apigee reserva vários prefixos para organizar as variáveis relevantes de forma adequada. Estes prefixos incluem:

• request
• response
• system
• target

Para fazer referência a uma variável numa política, coloque-a entre chavetas. Por exemplo, a seguinte política AssignMessage usa o valor da variável client.ip e coloca-o num cabeçalho do pedido denominado 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>

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

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

Também pode fazer referência a variáveis de fluxo em código JavaScript e Java. Para mais informações, consulte:

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

Tipo de dados das 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. Pode encontrar os tipos de dados indicados na referência de variáveis de fluxo. Para variáveis criadas por uma política, consulte o tópico de referência da política específica para obter informações sobre o tipo de dados.

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

Usar variáveis de fluxo em políticas

Muitas políticas criam variáveis de fluxo como parte da respetiva execução normal. O documento de referência da política documenta todas estas variáveis específicas da política.

À medida que trabalha com proxies e políticas, certifique-se de que consulta a referência da política para saber que variáveis são criadas e para que são usadas. Por exemplo, a política de quotas cria um conjunto de variáveis que contêm informações sobre as contagens de quotas e os limites, a hora de validade, etc.

Algumas variáveis de política são úteis para a depuração. Pode usar a ferramenta de depuração), por exemplo, para ver que variáveis foram definidas numa instância específica num fluxo de proxy.

A política ExtractVariables permite-lhe preencher variáveis personalizadas com dados extraídos de mensagens. Pode extrair parâmetros de consulta, cabeçalhos e outros dados. Por exemplo, pode analisar mensagens de pedidos e respostas usando padrões para extrair dados específicos das mensagens.

No exemplo seguinte, 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-lhes valores.

<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, tenha em atenção que muitas políticas criam variáveis automaticamente. Pode aceder a essas variáveis no contexto do fluxo de proxy, e estas estão documentadas na referência de políticas em cada tópico de política individual.

Trabalhar com variáveis de fluxo em código JavaScript

Pode aceder e definir variáveis diretamente no código JavaScript que está a ser executado no contexto de um proxy de API. Através do modelo de objeto JavaScript do Apigee, o JavaScript executado no Apigee tem acesso direto às variáveis de fluxo do proxy.

Nota: pode chamar JavaScript a partir de um proxy através da política de JavaScript.

Para aceder a variáveis no código JavaScript, chame métodos getter/setter em qualquer um destes objetos:

• context
• proxyRequest
• proxyResponse
• targetRequest
• targetResponse

Como pode ver, estas referências de objetos são mapeadas para os segmentos familiares do modelo de fluxo de proxy, conforme explicado anteriormente em Visualizar o fluxo de um proxy de API.

O objeto context corresponde a variáveis disponíveis globalmente, como variáveis do sistema. Por exemplo, pode chamar getVariable() no objeto context para obter o ano atual:

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

Da mesma forma, pode chamar setVariable() para definir o valor de uma variável personalizada ou de quaisquer variáveis prontas a usar graváveis. Aqui, criamos uma variável personalizada denominada organization.name.myorg e atribuímos-lhe um valor.

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

Uma vez que esta variável é criada com o objeto context, vai estar disponível para todos os segmentos do fluxo (essencialmente, é como criar uma variável global).

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

Também pode obter ou definir variáveis de fluxo de proxy no código Java que executa com a política JavaCallout.

O que precisa de lembrar-se

Seguem-se alguns aspetos importantes a ter em atenção acerca das variáveis de fluxo:

• Algumas variáveis out-of-the-box são instanciadas e preenchidas automaticamente pelo próprio proxy. Estes são documentados na referência de variáveis de fluxo.
• Pode criar variáveis personalizadas que estão disponíveis para utilização no fluxo de proxy. É possível criar variáveis através de políticas como a política AssignMessage e a política JavaScript.
• As variáveis têm âmbito. Por exemplo, algumas variáveis são preenchidas automaticamente quando o primeiro proxy recebe um pedido de uma app. Outras variáveis são preenchidas no segmento de fluxo de resposta do proxy. Estas variáveis de resposta permanecem indefinidas até que o segmento de resposta seja executado.
• Quando as políticas são executadas, podem criar e preencher variáveis específicas das políticas. A documentação de cada política indica todas estas variáveis relevantes específicas da política.
• Normalmente, os fluxos condicionais avaliam uma ou mais variáveis. Tem de compreender as variáveis se 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.

Sugestão: encontra vários exemplos que usam variáveis de uma forma ou de outra. Procure as que usam a política ExtractVariables, que é usada frequentemente para processar variáveis num fluxo de proxy.

Tópicos relacionados

• Todas as variáveis preenchidas automaticamente num proxy de API estão listadas na Referência de variáveis de fluxo. A referência também indica o tipo e o âmbito de cada variável.
• Se quiser saber que variáveis uma política específica preenche, consulte o tópico de referência da política. Por exemplo, consulte as Variáveis de fluxo na referência da Política de quotas.