Usando variáveis ​​de fluxo

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Esta página se aplica ao Apigee e ao Apigee híbrido .

Veja a documentação do Apigee Edge .

Variáveis ​​de fluxo são objetos que você pode acessar de dentro de suas políticas ou utilitários (como a ferramenta de depuração ). Elas permitem que você mantenha o estado associado a uma transação de API processada pela Apigee.

O que são variáveis ​​de fluxo?

Variáveis ​​de fluxo existem dentro do contexto de um fluxo de proxy de API e rastreiam o estado em uma transação de API da mesma forma que variáveis ​​nomeadas rastreiam o estado em um programa de software. Variáveis ​​de fluxo armazenam informações como:

• O endereço IP, cabeçalhos, caminho de URL e carga útil enviados do aplicativo 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, após a execução de uma política que valida um token OAuth, 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 ao Apigee e preenchidas automaticamente sempre que uma solicitação de API é recebida. Elas ficam disponíveis durante toda a transação da 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 o local onde elas são acessíveis depende, em parte, de quando são criadas no fluxo de proxy da API. Em geral, quando uma variável é criada, ela fica disponível para todas as políticas e códigos executados posteriormente no fluxo de transações da API.

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

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

• As políticas podem recuperar o estado de variáveis ​​de fluxo e usá-las para fazer seu trabalho.

  Por exemplo, uma política VerifyJWT pode recuperar o token a ser verificado de uma variável de fluxo e, em seguida, realizar a verificação nele. 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 variáveis ​​de fluxo para direcionar o fluxo de uma API por meio do Apigee, de forma semelhante à maneira como uma instrução switch funciona na programação.

  Por exemplo, uma política para retornar uma falha pode ser executada somente quando uma variável de fluxo específica é 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 pega 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 de solicitação , essa política define um cabeçalho que é passado ao destino do backend. Se definida no fluxo de resposta , o cabeçalho é 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>

Em outro exemplo, quando uma política de cota é executada, diversas variáveis ​​de fluxo são preenchidas com valores relacionados à política. Uma dessas variáveis ​​é chamada ratelimit.my-quota-policy.used.count (onde my-quota-policy é o nome da política de cota em que você está interessado).

Mais tarde, você pode executar um fluxo condicional que diz "se a contagem de cota atual estiver abaixo de 50% do máximo e for 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 ​​internas do Apigee.

Variáveis ​​de fluxo em fluxos condicionais

Fluxos condicionais avaliam variáveis ​​de fluxo e permitem que proxies se comportem dinamicamente. Condições são normalmente usadas para alterar o comportamento de fluxos, etapas e regras de roteamento.

Este é um fluxo condicional que avalia o valor da variável request.verb em uma etapa do fluxo de proxy. Nesse caso, se o verbo da solicitação for POST, a política VerifyAPIKey será executada. Este é um padrão comum usado em 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ê deve estar se perguntando: 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 ajudar você a entender quando as variáveis ​​são criadas e quando ficam disponíveis, consulte Visualizando o fluxo de um proxy de API .

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

Com a política JavaScript , você pode executar código JavaScript dentro do 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 seu código personalizado acesso a objetos de solicitação, resposta e contexto associados ao fluxo de proxy de API no qual seu código está sendo 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"));

Essa técnica de usar JavaScript para ler e definir variáveis ​​é semelhante ao trabalho que você pode fazer com a política AssignMessage (mostrada anteriormente). É apenas mais uma maneira de realizar o mesmo tipo de coisa na Apigee. O importante é lembrar que o JavaScript executado pela política JavaScript tem acesso a todas as variáveis ​​de fluxo existentes e que estão no escopo do fluxo do proxy da API.

Visualizando o fluxo de um proxy de API

Para entender o escopo da variável de fluxo, é importante entender ou visualizar a maneira como as mensagens fluem por meio de um proxy de API. Um proxy de API consiste em uma série de etapas de processamento de mensagens organizadas como um fluxo. A cada etapa de um fluxo de proxy, o proxy avalia as informações disponíveis e decide o que fazer em seguida. Ao longo do caminho, o proxy pode executar código de política ou realizar ramificações condicionais .

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

Tenha essa estrutura de fluxo em mente enquanto começamos a explorar variáveis ​​de fluxo no restante deste tópico.

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

Assim que você conseguir visualizar como as mensagens fluem por meio de um proxy, conforme descrito anteriormente, poderá começar a entender o escopo de variáveis. Por escopo, queremos dizer o ponto no ciclo de vida do fluxo do proxy em que uma variável é instanciada pela primeira vez.

Por exemplo, se você tiver uma política anexada ao segmento de solicitação ProxyEndpoint, essa política não poderá acessar nenhuma variável cujo escopo seja o segmento de solicitação TargetEndpoint. Isso ocorre porque o segmento de solicitação TargetEndpoint do fluxo ainda não foi executado, portanto, o proxy da API não teve a oportunidade de preencher as variáveis ​​nesse escopo.

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

Por exemplo, há uma variável interna do Apigee chamada client.ip . Essa variável tem 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 do fluxo de proxy.

Há outra variável interna chamada target.url . O escopo dessa variável é target request . Ela é preenchida no segmento de solicitação TargetEndpoint com a URL da solicitação enviada ao destino do 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.

Aqui está um exemplo simples que demonstra como pensar sobre o escopo de variáveis. 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 a ser enviado de volta ao aplicativo que fez a chamada. Você pode usar a política AssignMessage para essa tarefa. O código da política se parece com isto:

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

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

Referenciando variáveis ​​de fluxo

Todas as variáveis ​​integradas na Apigee seguem uma convenção de nomenclatura de notaçã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 referenciar uma variável em uma política, coloque-a entre chaves. Por exemplo, a política AssignMessage a seguir pega 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. O exemplo de condição a seguir avalia a variável request.header.accept :

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

Você também pode referenciar variáveis ​​de fluxo em código JavaScript e Java. Para mais informações, consulte:

• Trabalhando com variáveis ​​de fluxo em 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 dado bem definido, como String, Long, Integer, Boolean ou Collection. Você pode encontrar os tipos de dados listados na referência de variáveis ​​de fluxo . Para variáveis ​​que foram criadas por uma política, consulte o tópico de referência de política específica para obter informações sobre o tipo de dado.

Variáveis ​​que você cria manualmente assumem o tipo fornecido quando foram criadas e dependem dos tipos de valores permitidos.

Usando variáveis ​​de fluxo em políticas

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

Ao trabalhar com proxies e políticas, certifique-se de consultar a referência da política para descobrir quais variáveis ​​são criadas e para que são utilizadas. Por exemplo, a política de cota cria um conjunto de variáveis ​​que contêm informações sobre contagens e limites de cota, tempo de expiração e assim por diante.

Algumas variáveis ​​de política são úteis para depuração. Você pode usar o Ferramenta de depuração ), 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. Você pode extrair parâmetros de consulta, cabeçalhos e outros dados. Por exemplo, você pode 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 extraídos 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>

Novamente, esteja ciente de que muitas políticas criam variáveis ​​automaticamente. Você pode acessar essas variáveis ​​no contexto do fluxo de proxy, e elas estão documentadas na Referência de Política, em cada tópico de política individual.

Trabalhando com variáveis ​​de fluxo em código JavaScript

Você pode acessar e definir variáveis ​​diretamente no código JavaScript em execução no contexto de um proxy de API. Por meio do modelo de objeto JavaScript da Apigee, o JavaScript em execução na Apigee tem acesso direto às variáveis ​​de fluxo do proxy.

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

• context
• proxyRequest
• proxyResponse
• targetRequest
• targetResponse

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

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

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

Da mesma forma, você pode chamar setVariable() para definir o valor de uma variável personalizada ou de qualquer variá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 (essencialmente, isso é como criar uma variável global).

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

O que você precisa lembrar

Aqui estão algumas coisas importantes para lembrar sobre variáveis ​​de fluxo:

• Algumas variáveis ​​prontas para uso são instanciadas e preenchidas automaticamente pelo próprio proxy. Elas estão documentadas na referência de variáveis ​​de fluxo .
• Você pode criar variáveis ​​personalizadas disponíveis para uso no fluxo de proxy. É possível criar variáveis ​​usando políticas como AssignMessage e JavaScript .
• Variáveis ​​têm escopo. Por exemplo, algumas variáveis ​​são preenchidas automaticamente quando o primeiro proxy recebe uma solicitação de um aplicativo. Outras variáveis ​​são preenchidas no segmento de 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 da política.
• Fluxos condicionais geralmente avaliam uma ou mais variáveis. Você precisa entender 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 posteriormente usada por outra.

Tópicos relacionados

• Todas as variáveis ​​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.
• Para 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 .