Controllo dell'esecuzione di un proxy con i flussi

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X. informazioni

Qualsiasi modello di programmazione di un'applicazione include un modo per controllare il flusso di elaborazione. In un proxy API, puoi farlo con i flussi. Ai flussi puoi aggiungere logica, istruzioni di condizione, gestione degli errori e così via. Puoi utilizzare i flussi per controllare cosa succede e quando.

I flussi sono fasi sequenziali lungo il percorso di elaborazione delle richieste API. Quando aggiungi una logica proxy, ad esempio per verificare una chiave API, aggiungila 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.

Il seguente esempio di configurazione del flusso definisce un flusso in cui il criterio VerificationAPIKey viene eseguito if 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 deve includere un criterio configurato 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

Struttura i flussi in modo che la logica venga eseguita 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 suddivide il proprio codice tra il codice che interagisce con il client del proxy (endpoint proxy) e il codice facoltativo che interagisce con l'eventuale destinazione del backend del proxy (endpoint di destinazione).

Entrambi gli endpoint contengono flussi, come descritto qui:

Tipo di endpoint Descrizione Flussi supportati
ProxyEndpoint Contiene i flussi proxy API più vicini al client. Fornisce posizioni in cui la logica interviene prima sulla richiesta del client, poi sull'ultima risposta alla risposta del client. PreFlow, flussi condizionali, PostFlow, PostClientFlow
TargetEndpoint Contiene i flussi proxy API più vicini alla risorsa di backend. Fornisce posizioni per la logica per la preparazione di una richiesta e gestisce la risposta da una risorsa di backend. PreFlow, flussi condizionali, PostFlow

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

Richiesta dal client HTTP che passa attraverso l&#39;endpoint proxy all&#39;endpoint di destinazione sul backend per raggiungere il servizio HTTP. Ogni riquadro di richiesta e risposta mostra il pre-flusso, i flussi condizionali e il flusso post. Inoltre, vengono forniti esempi di endpoint proxy e di endpoint di destinazione.

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

Posizione Tipo di flusso Descrizione
1 PreFlow

Utile quando è necessario assicurarsi che un determinato codice venga eseguito prima che succeda qualsiasi altra cosa.

Se il preFlow si trova in un endpoint di destinazione, viene eseguito dopo il PostFlow dell'endpoint proxy.
2 Flusso condizionale

L'area della logica condizionale. Viene eseguita dopo il PreFlow e prima del PostFlow.

Viene eseguito un solo flusso condizionale per segmento, il primo flusso la cui condizione è considerata vera. Ciò significa che puoi eseguire un flusso condizionale come parte di ciascuno dei seguenti elementi:
  • Pipeline di richiesta di ProxyEndpoint
  • Pipeline di richiesta di TargetEndpoint
  • Pipeline di risposta di ProxyEndpoint
  • Pipeline di risposta di TargetEndpoint
3 PostFlow

Un buon posto in cui registrare i dati, inviare una notifica quando si è verificato un problema durante l'elaborazione della richiesta e così via. Viene eseguita dopo i flussi condizionali e PreFlow.

Se PostFlow si trova in un endpoint proxy ed è presente un endpoint di destinazione, l'endpoint proxy PostFlow viene eseguito prima dell'endpoint di destinazione PreFlow.
4 PostClientFlow (solo flusso proxy) Flusso per il logging dei messaggi dopo che una risposta viene restituita al client.

Fare in modo che il codice venga eseguito prima con un Pre-flow

Un PreFlow è utile quando è necessario assicurarsi che un determinato codice venga eseguito prima che succeda qualsiasi altra cosa.

In un endpoint proxy, PreFlow è la soluzione ideale per il codice che autentica un client e limita il traffico proveniente dai client. In un endpoint di destinazione, in cui inizia la preparazione per inviare una richiesta a una destinazione del backend, un PreFlow è utile per i primi passaggi della preparazione all'invio della richiesta.

Ad esempio, in genere non si vuole servire un client che ha superato la propria quota. Per supportare questi requisiti, inserisci i criteri di sicurezza e per le quote nel segmento PreFlow. In questo modo, non devi preoccuparti che una condizione non venga valutata in un flusso condizionale successivo. I criteri di questo flusso verranno sempre eseguiti prima di qualsiasi altra elaborazione.

Nell'esempio seguente, i criteri SpikeArrest e Quota vengono eseguiti prima di elaborare i passaggi ai flussi condizionali.

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

Eseguire il codice in modo condizionale con un flusso condizionale

Tra un PreFlow e un PostFlow, puoi avere flussi che vengono eseguiti in modo condizionale. Questo ti offre l'opportunità di configurare più sequenze di logica, ma di farne eseguire solo una 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 nell'endpoint).

Ogni flusso specifica una condizione che verifica valori di stato diversi. Questa diramazione in modo efficace dell'esecuzione in base alle condizioni. Ad esempio, potresti voler convertire XML in JSON solo quando l'app richiedente è in esecuzione su un dispositivo mobile.

In questo caso, i vincoli di quota vengono applicati solo se la richiesta è una richiesta GET con un pattern URI di /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>

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

Per esempi sull'utilizzo della corrispondenza di pattern in condizioni, consulta Corrispondenza di pattern.

Fare in modo che il codice venga eseguito dopo la logica di base con PostFlow

Un postFlow è ideale per eseguire azioni dopo la logica di base dell'endpoint e prima del termine dell'elaborazione dell'endpoint. Un PostFlow viene eseguito dopo i flussi condizionali e il PreFlow.

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

Nell'esempio seguente, un criterio AssegnaMessage denominato 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>

Fare in modo che il codice venga eseguito dopo che il client riceve la risposta del proxy con un PostClientFlow

Un PostClientFlow può includere i seguenti criteri:

* La norma FlowCallout può chiamare solo i flussi condivisi che soddisfano i criteri per essere presenti nel PostClientFlow (ovvero, che contengono solo norme compatibili).

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

Un PostClientFlow è ideale per il logging finale. Inoltre, puoi registrare i timestamp di inizio e fine del messaggio di risposta.

Ecco un esempio di PostClientFlow con un criterio MessageLogging associato.

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

Video: guarda questo breve video che ti mostra come creare un PostClientFlow utilizzando la norma MessageLogging della serie Four Minute Video For Developers (4MV4D).

Per ulteriori informazioni, vedi:

Aggiungere logica ai flussi

Puoi aggiungere logica al proxy aggiungendo criteri ai flussi del proxy. Proprio come i flussi vengono eseguiti in una sequenza (PreFlow, poi Flow e poi PostFlow, come descritto in questo argomento), i contenuti di un flusso vengono eseguiti in sequenza.

La seguente configurazione del flusso di esempio fa riferimento a tre criteri (configurati altrove nei propri file XML). Il criterio a cui fa riferimento Verify-API-Key viene eseguito prima del criterio a cui fa riferimento Remove-API-Key; entrambi sono seguiti dal criterio rappresentato 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 criteri come una riga di icone in cui ogni icona rappresenta il criterio.

La console Apigee Edge presenta questa sequenza di criteri come una riga di icone in cui ogni icona rappresenta il criterio. Le icone mostrate nel percorso di richiesta includono: Verifica chiave API, Rimuovi chiave API e Quota.

Flussi di debug

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

Per saperne di più sull'analisi dei proxy, consulta Utilizzo dello strumento Trace.

Gestione degli errori nei flussi

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

L'esempio seguente è la stanza di risposta di un PreFlow in un endpoint di destinazione, in altre parole, è il codice che viene eseguito immediatamente dopo aver ricevuto la risposta dalla destinazione di un backend. Nell'esempio, viene segnalato un errore se la risposta del target non è 200 (riuscita).

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

Per ulteriori informazioni sulla gestione degli errori, consulta la sezione Gestione degli errori.