Como controlar como um proxy é executado com fluxos

Esta é a documentação do Apigee Edge.
Acesse 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:

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:

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:

• Política ExtensionCallout
• Política FlowCallout^*
• Política MessageLogging
• Política ServiceCallout

^* 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, que será executado após um a resposta da solicitação é 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>
    ...

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.