Você está visualizando a documentação do Apigee Edge.
Acesse a documentação da
Apigee X. informações
Qualquer modelo de programação de aplicativo inclui uma maneira de controlar o fluxo de processamento. Em um proxy de API, isso é feito com fluxos. Nos fluxos, você adiciona lógica, instruções de condição, tratamento de erros e assim por diante. Use fluxos para controlar o que acontece e quando.
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 em que 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 são aplicadas somente se a solicitação for GET com um
padrão de URI de /issue/** (/issue/, com algo 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 os cabeçalhos da mensagem de resposta antes que o Apigee Edge envie a resposta 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 as seguintes políticas:
* 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 depois que uma resposta for 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.
...
<PostFlow name="PostFlow">
<Request/>
<Response/>
</PostFlow>
<PostClientFlow>
<Request/>
<Response>
<Step>
<Name>Message-Logging-1</Name>
</Step>
</Response>
</PostClientFlow>
...
Vídeo: confira este vídeo curto que mostra como criar um PostClientFlow usando a política MessageLogging da série "Vídeos de quatro minutos para desenvolvedores" (4MV4D).
Confira mais informações em:
- Referência de configuração de proxy da API
- Tutorial : Apigee Edge - artigo da comunidade do fluxo de clientes
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 Remove-API-Key; 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>Remove-API-Key</Name>
</Step>
<Step>
<Name>Quota</Name>
</Step>
</Request>
<Condition>(proxy.pathsuffix MatchesPath "/") and (request.verb = "GET")</Condition>
</Flow>
O console do Apigee Edge apresenta essa sequência de políticas como uma linha de ícones, em que cada ícone representa a política.
Fluxos de depuração
A ferramenta Apigee Edge Trace oferece uma maneira gráfica de 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 rastreamento, consulte Como usar a ferramenta Trace.
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.