Como controlar como um proxy é executado com fluxos

Você está vendo 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 if 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:

Solicitação do cliente HTTP que passa pelo Proxy Endpoint para o Endpoint de destino no back-end para acessar o serviço HTTP. Cada painel de solicitação e resposta mostra o pré-fluxo, fluxos condicionais e fluxo posterior. Além disso, são fornecidos exemplos do endpoint do proxy e do endpoint de destino.

O endpoint do proxy e o endpoint de destino contêm fluxos que podem ser organizados na seguinte sequência:

Cargo Tipo de fluxo Descrição
1 PreFlow

Ú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:
  • Pipeline de solicitação do ProxyEndpoint
  • Pipeline de solicitações do TargetEndpoint
  • Pipeline de resposta do ProxyEndpoint
  • Pipeline de resposta do TargetEndpoint
3 PostFlow

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>

Executar o código depois que o cliente recebe a resposta do 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, que 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 Four Minute Video for Developers (4MV4D).

Veja mais informações nos links abaixo:

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.

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. Os ícones mostrados no caminho da solicitação incluem: verificar chave de API, remover chave de API e cota

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.