Esta página se aplica à Apigee e à Apigee híbrida.
Confira a documentação da
Apigee Edge.
Fluxos são os elementos básicos de proxies de API. Os fluxos permitem que você programe o comportamento de uma API permitindo configurar a sequência em que as políticas e o código são executados por um proxy de API.
Os fluxos são estágios sequenciais ao longo do caminho de processamento da solicitação da API. Quando uma lógica de proxy é adicionada, por exemplo, para verificar uma chave de API, você a adiciona como uma etapa na sequência especificada por um fluxo. Ao definir uma condição para especificar se e quando a lógica será executada, você adicionará a condição a um fluxo.
O exemplo de configuração de fluxo a seguir define um fluxo no qual a política VerifyAPIKey
é executada se o caminho da solicitação recebida terminar com / e o verbo HTTP da
solicitação for GET.
<Flow name="Get Food Carts">
<Description>Get Food Carts</Description>
<Request>
<Step>
<Name>Verify-API-Key</Name>
</Step>
</Request>
<Condition>(proxy.pathsuffix MatchesPath "/") and (request.verb = "GET")</Condition>
</Flow>
O valor Verify-API-Key no elemento <Name> do fluxo serve
para incluir uma política configurada em outro lugar no proxy com XML como o seguinte:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key">
<DisplayName>Verify API Key</DisplayName>
<Properties/>
<APIKey ref="request.header.x-api-key"/>
</VerifyAPIKey>
Como projetar a sequência de execução de fluxo
Você estrutura fluxos para que a lógica seja executada na sequência correta ao longo do caminho de processamento.
Ao decidir onde adicionar a lógica, você primeiro escolherá se quer adicioná-la a um endpoint de proxy ou de destino. Um proxy de API divide seu código entre código que interage com o cliente do proxy (endpoint proxy) e código opcional que interage com o destino de back-end do proxy, se houver (endpoint de destino).
Ambos os endpoints contêm fluxos, conforme descrito aqui:
| Tipo de endpoint | Descrição | Fluxos compatíveis |
|---|---|---|
| ProxyEndpoint | Contém os fluxos de proxy de API mais próximos do cliente. Fornece locais para a lógica que atuará primeiro na solicitação do cliente e, em seguida, por último na resposta ao cliente. | Pré-fluxo, fluxos condicionais, PostFlow, PostClientFlow |
| TargetEndpoint | Contém o proxy da API flui mais próximo do recurso de back-end. Fornece locais para lógica e preparar uma solicitação e, em seguida, processar a resposta de um recurso de back-end. | Pré-fluxo, fluxos condicionais, PostFlow |
Você configura um fluxo com XML que especifica o que deve acontecer e em que ordem. A ilustração a seguir mostra como os fluxos são ordenados sequencialmente dentro de um endpoint de proxy e de destino de destino:
O endpoint do proxy e o endpoint de destino contêm fluxos que podem ser organizados na seguinte sequência:
| Posição | Tipo de fluxo | Descrição |
|---|---|---|
| 1 | Pré-fluxo |
Útil quando você precisa garantir que determinado código seja executado antes de qualquer outra coisa. Se o PreFlow estiver em um endpoint de destino, ele será executado após o PostFlow do endpoint de proxy. |
| 2 | Fluxo condicional |
Local para lógica condicional. Executado após o PréFlow e antes do PostFlow. Somente um fluxo condicional é executado por segmento: o primeiro fluxo cuja condição é avaliada como verdadeira. Isso significa que é possível executar um fluxo condicional como parte de cada um dos seguintes elementos:
|
| 3 | Pós-fluxo |
Um bom local para registrar dados, enviar uma notificação de que algo aconteceu durante o processamento da solicitação e assim por diante. Executado após fluxos condicionais e PreFlow. Se o PostFlow estiver em um ponto de extremidade de proxy e houver um ponto de extremidade de destino, ele será executado antes do ponto de extremidade de destino. |
| 4 | PostClientFlow (somente fluxo de proxy) | Um fluxo para registrar mensagens após o retorno de uma resposta ao cliente. |
Executar o código primeiro com um PreFlow
Um PreFlow é útil quando você precisa garantir que determinado código seja executado antes que algo aconteça.
Em um endpoint de proxy, um PreFlow é um ótimo lugar para código que autentica um cliente e limita o tráfego de clientes. Em um endpoint de destino, onde começa a preparar o envio de uma solicitação para um destino de back-end, um PreFlow é bom para as primeiras etapas na preparação para enviar a solicitação.
Por exemplo, normalmente não quer atender a um cliente que tenha excedido a cota. Para atender a esses requisitos, coloque as políticas de segurança e cota no segmento do PreFlow. Dessa forma, você não precisa se preocupar se uma condição não for avaliada em um fluxo condicional posterior. As políticas deste fluxo sempre serão executadas antes de qualquer outro processamento ocorrer.
No exemplo a seguir, as políticas de SpikeArrest e Quota são executadas antes de o processamento passar para fluxos condicionais.
<PreFlow name="MyPreFlow">
<Request>
<Step>
<Name>Spike-Arrest</Name>
</Step>
<Step>
<Name>Quota</Name>
</Step>
</Request>
<Response/>
</PreFlow>
Como executar código condicionalmente com um fluxo condicional
Entre um PreFlow e um PostFlow, você pode ter fluxos que são executados condicionalmente. Isso permite que você configure várias sequências de lógica, mas tenha apenas uma execução baseada no estado do proxy. Um fluxo condicional será opcional se você puder executar toda a lógica no PreFlow ou PostPost e nenhuma condição for necessária (em outras palavras, apenas um caminho por meio do endpoint será aceito).
Cada fluxo especifica uma condição que testa diferentes valores de estado. Isso faz branch de execuções eficaz com base nas condições. Por exemplo, talvez você queira converter XML para JSON somente quando o app solicitante estiver em execução em um dispositivo móvel.
Aqui, as restrições de cota serão aplicadas somente se a solicitação for GET com um
padrão de URI de /issue/** (/issue/ com qualquer elemento no URI após a última
barra).
<Flow name="MyFlow">
<Description/>
<Request>
<Step>
<Name>Quota</Name>
</Step>
</Request>
<Response/>
<Condition>(proxy.pathsuffix MatchesPath "/issue/**") and (request.verb = "GET")</Condition>
</Flow>
Use variáveis de fluxo para especificar condições. Para saber mais sobre como usar variáveis em condições, consulte Condições com variáveis de fluxo.
Para ver exemplos de como usar a correspondência de padrões em condições, consulte Correspondência de padrões.
Como executar código após a lógica central com um PostFlow
Um PostFlow é um ótimo lugar para executar ações depois da lógica principal do endpoint e antes o processamento do endpoint. Um PostFlow é executado após fluxos condicionais e PreFlow.
Um PostFlow é um bom lugar para registrar alguns dados, enviar uma notificação de que algo aconteceu, transformar o formato da mensagem de resposta e assim por diante.
No exemplo a seguir, uma política AssignMessage chamada SetResponseHeaders define cabeçalhos da mensagem de resposta antes que a Apigee envie a resposta de volta para o cliente.
<PostFlow>
<Response>
<Step>
<Name>SetResponseHeaders</Name>
</Step>
</Response>
</PostFlow>
Como executar código depois que o cliente receber a resposta do seu proxy com um PostClientFlow
Um PostClientFlow pode incluir apenas as seguintes políticas: Nenhuma outra política pode ser usada em um PostClientFlow:
* A política FlowCallout só pode chamar fluxos compartilhados que atendam aos critérios de estar no PostClientFlow (ou seja, contenham apenas políticas compatíveis).
Se você incluir um, um PostClientFlow será o último fluxo a ser executado, executado após uma resposta ser enviada ao cliente.
Um PostClientFlow é bom para gerar registros finais. Além disso, é possível registrar os carimbos de data/hora de início e término da mensagem de resposta.
Veja um exemplo de PostClientFlow com uma política MessageLogging anexada.
<ProxyEndpoint name="endpoint1">
...
<PostFlow name="PostFlow">
<Request/>
<Response/>
</PostFlow>
<PostClientFlow>
<Response>
<Step>
<Name>Message-Logging-1</Name>
</Step>
</Response>
</PostClientFlow>
...
</ProxyEndpoint>
Para mais informações, consulte a Referência de configuração do proxy da API.
Como adicionar lógica aos fluxos
Ao adicionar lógica ao proxy, você faz isso adicionando políticas aos fluxos do proxy. Assim como os fluxos são executados em uma sequência (PreFlow, depois Flow e PostFlow, conforme descrito neste tópico), o conteúdo de um fluxo é executado em uma sequência.
O exemplo de configuração de fluxo de exemplo a seguir refere-se a três políticas (configuradas em outro lugar nos próprios arquivos XML). A política referenciada por Verify-API-Key é executada antes da política referenciada por Assign-Message; ambos são seguidos pela política representada por Quota.
<Flow name="Get Food Cart Menus">
<Description>Get Food Cart Menus</Description>
<Request>
<Step>
<Name>Verify-API-Key</Name>
</Step>
<Step>
<Name>Assign-Message</Name>
</Step>
<Step>
<Name>Quota</Name>
</Step>
</Request>
<Condition>(proxy.pathsuffix MatchesPath "/") and (request.verb = "GET")</Condition>
</Flow>
Fluxos de depuração
A Ferramenta de depuração oferece uma maneira gráfica de entender como a lógica no proxy da API é executada após uma solicitação. A ferramenta ilustra o processamento entre solicitação e resposta. Ele não ilustra especificamente a separação entre o pré-fluxo, os fluxos condicionais e o PostFlow.
Para saber mais sobre proxies de depuração, consulte Como usar a ferramenta de depuração.
Como processar erros em fluxos
É possível gerar falhas de vários lugares em um proxy de API, inclusive dos fluxos.
O exemplo a seguir é a estrofe de resposta de um PreFlow em um endpoint de destino. Em outras
palavras, é o código executado imediatamente após receber a resposta de um destino de back-end.
No exemplo, uma falha é gerada se a resposta do destino não for 200 (sucesso).
<PreFlow name="PreFlow">
<Response>
<Step>
<Name>RaiseFault</Name>
<Condition>(response.status.code GreaterThan "200")</Condition>
</Step>
</Response>
</PreFlow>
Para mais informações sobre tratamento de erros, consulte Como lidar com falhas.