Controllo dell'esecuzione di un proxy con i flussi

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X. info

Qualsiasi modello di programmazione di applicazioni include un modo per controllare il flusso di elaborazione. In un proxy API, questa operazione viene eseguita con i flussi. Ai flussi aggiungi logica, istruzioni condizionali, gestione degli errori e così via. Utilizzi i flussi per controllare cosa succede e quando.

I flussi sono fasi sequenziali lungo il percorso di elaborazione delle richieste API. Quando aggiungi la logica del proxy, ad esempio per verificare una chiave API, aggiungi la logica come passaggio nella sequenza specificata da un flusso. Quando definisci una condizione per specificare se e quando viene eseguita la logica, aggiungi la condizione a un flusso.

L'esempio di configurazione del flusso seguente definisce un flusso in cui la policy VerifyAPIKey viene eseguita se il percorso della richiesta in entrata termina con / e il verbo HTTP della richiesta è 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>

Il valore Verify-API-Key nell'elemento <Name> del flusso serve a includere una policy configurata altrove nel proxy con XML come il seguente:

<?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>

Progettazione della sequenza di esecuzione del flusso

Strutturi i flussi in modo da poter eseguire la logica nella sequenza corretta lungo il percorso di elaborazione.

Quando decidi dove aggiungere la logica, devi prima scegliere se aggiungerla a un endpoint proxy o a un endpoint di destinazione. Un proxy API divide il codice tra il codice che interagisce con il client del proxy (endpoint proxy) e il codice facoltativo che interagisce con la destinazione di backend del proxy, se presente (endpoint di destinazione).

Entrambi gli endpoint contengono flussi, come descritto di seguito:

Configuri il flusso con XML che specifica cosa deve succedere e in quale ordine. La seguente illustrazione mostra come i flussi vengono ordinati in sequenza all'interno di un endpoint proxy e di destinazione endpoint:

L'endpoint proxy e l'endpoint di destinazione contengono ciascuno flussi che puoi disporre nella seguente sequenza:

Esecuzione del codice con un PreFlow

Un PreFlow è utile quando devi assicurarti che un determinato codice venga eseguito prima di qualsiasi altra operazione accada.

In un endpoint proxy, un PreFlow è un ottimo posto per il codice che autentica un client e limita il traffico dai client. In un endpoint di destinazione, dove inizia la preparazione per l'invio di una richiesta a una destinazione di backend, un PreFlow è utile per i primi passaggi della preparazione all'invio della richiesta.

Ad esempio, in genere non vuoi servire un client che ha superato la sua quota. Per supportare questi requisiti, inserisci le policy di sicurezza e di quota nel segmento PreFlow. In questo modo, non devi preoccuparti che una condizione non venga valutata in un flusso condizionale successivo. Le policy in questo flusso verranno sempre eseguite prima di qualsiasi altra elaborazione.

Nell'esempio seguente, le policy SpikeArrest e Quota vengono eseguite prima che l'elaborazione passi a flussi condizionali.

<PreFlow name="MyPreFlow">
    <Request>
        <Step>
            <Name>Spike-Arrest</Name>
        </Step>
        <Step>
            <Name>Quota</Name>
        </Step>
    </Request>
    <Response/>
</PreFlow>

Esecuzione condizionale del codice con un flusso condizionale

Tra un PreFlow e un PostFlow, puoi avere flussi che vengono eseguiti in modo condizionale. In questo modo puoi configurare più sequenze di logica, ma solo una viene eseguita in base allo stato del proxy. Un flusso condizionale è facoltativo se puoi eseguire tutta la logica in PreFlow o PostFlow e non sono richieste condizioni (in altre parole, è supportato un solo percorso tramite l'endpoint è supportato).

Ogni flusso specifica una condizione che verifica valori di stato diversi. In questo modo, l'esecuzione viene ramificata in base alle condizioni. Ad esempio, potresti voler convertire XML in JSON solo quando l'app che effettua la richiesta è in esecuzione su un dispositivo mobile.

Qui, i vincoli di quota vengono applicati solo se la richiesta è una richiesta GET con un pattern URI /issue/** (/issue/ con qualsiasi elemento nell'URI dopo l'ultima barra ).

<Flow name="MyFlow">
    <Description/>
    <Request>
        <Step>
            <Name>Quota</Name>
        </Step>
    </Request>
    <Response/>
    <Condition>(proxy.pathsuffix MatchesPath "/issue/**") and (request.verb = "GET")</Condition>
</Flow>

Utilizzi le variabili di flusso per specificare le condizioni. Per saperne di più sull'utilizzo delle variabili nelle condizioni, consulta Condizioni con variabili di flusso.

Per esempi di utilizzo della corrispondenza di pattern nelle condizioni, consulta Corrispondenza di pattern.

Esecuzione del codice dopo la logica principale con un PostFlow

Un PostFlow è un ottimo posto per eseguire azioni dopo la logica principale dell'endpoint e prima che l'elaborazione dell'endpoint termini. Un PostFlow viene eseguito dopo i flussi condizionali e il PreFlow.

Un PostFlow è un buon posto per registrare alcuni dati, inviare una notifica che indica che si è verificato un evento, trasformare il formato del messaggio di risposta e così via.

Nell'esempio seguente, una policy AssignMessage denominata SetResponseHeaders imposta le intestazioni del messaggio di risposta prima che Apigee Edge invii la risposta al client.

<PostFlow>
    <Response>
        <Step>
            <Name>SetResponseHeaders</Name>
        </Step>
    </Response>
 </PostFlow>

Esecuzione del codice dopo che il client riceve la risposta del proxy con un PostClientFlow

Un PostClientFlow può includere le seguenti policy:

• Policy ExtensionCallout
• Policy FlowCallout^*
• Policy MessageLogging
• Policy ServiceCallout

^* La policy FlowCallout può chiamare solo flussi condivisi che soddisfano i criteri per essere inclusi in PostClientFlow (ovvero, contengono solo policy compatibili).

Se ne includi uno, un PostClientFlow sarà l'ultimo flusso da eseguire, dopo l'invio di una risposta al client.

Un PostClientFlow è utile per la registrazione finale. Inoltre, puoi registrare i timestamp di inizio e fine del messaggio di risposta.

Ecco un esempio di PostClientFlow con una policy MessageLogging allegata.

    ...
    <PostFlow name="PostFlow">
        <Request/>
        <Response/>
    </PostFlow>
    <PostClientFlow>
        <Request/>
        <Response>
            <Step>
                <Name>Message-Logging-1</Name>
            </Step>
        </Response>
    </PostClientFlow>
    ...

Per ulteriori informazioni, vedi:

• Riferimento per la configurazione dei proxy API
• Tutorial : articolo della community di Apigee Edge - Post Client Flow

Aggiungere logica ai flussi

Quando aggiungi logica al proxy, devi aggiungere policy ai flussi del proxy. Proprio come i flussi vengono eseguiti in sequenza (PreFlow, Flow e PostFlow, come descritto in questo argomento), anche i contenuti di un flusso vengono eseguiti in sequenza.

La seguente configurazione del flusso di esempio fa riferimento a tre policy (configurate altrove in nei rispettivi file XML). La policy a cui fa riferimento Verify-API-Key viene eseguita prima della policy a cui fa riferimento Remove-API-Key; entrambe sono seguite dalla policy rappresentata da 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>

La console Apigee Edge presenta questa sequenza di policy come una riga di icone in cui ogni icona rappresenta la policy.

Eseguire il debug dei flussi

Lo strumento Trace di Apigee Edge fornisce un modo grafico per vedere come viene eseguita la logica nel proxy API dopo una richiesta. Lo strumento illustra l'elaborazione tra richiesta e risposta. Non illustra in modo specifico la separazione tra PreFlow, flussi condizionali e PostFlow.

Per saperne di più sul tracciamento dei proxy, consulta Utilizzare lo strumento Trace.

Gestire gli errori nei flussi

Puoi generare errori da varie posizioni in un proxy API, inclusi i flussi.

L'esempio seguente è la sezione di risposta di un PreFlow in un endpoint di destinazione, in altre parole, è il codice che viene eseguito immediatamente dopo aver ricevuto la risposta da una destinazione di backend. Nell'esempio, viene generato un errore se la risposta della destinazione non è 200 (operazione riuscita).

<PreFlow name="PreFlow">
    <Response>
        <Step>
            <Name>RaiseFault</Name>
            <Condition>(response.status.code GreaterThan "200")</Condition>
        </Step>
    </Response>
</PreFlow>

Per saperne di più sulla gestione degli errori, consulta Gestire gli errori.