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, questo viene fatto con i flussi. Ai flussi aggiungi logica, istruzioni di condizione, 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 di proxy, ad esempio per verificare una chiave API, la aggiungi 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 VerifyAPIKey viene eseguito 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 consente di 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
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 target. Un proxy API divide il suo codice tra codice che interagisce con il client del proxy (endpoint proxy) e codice facoltativo che interagisce con la destinazione backend del proxy, se presente (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 punti in cui la logica può intervenire prima sulla richiesta del client e poi sulla risposta al client. | PreFlow, flussi condizionali, PostFlow, PostClientFlow |
| TargetEndpoint | Contiene i flussi del proxy API più vicini alla risorsa di backend. Fornisce spazi per la logica per preparare una richiesta e poi gestire la risposta di una risorsa di backend. | PreFlow, flussi condizionali, PostFlow |
Configuri il flusso con un file XML che specifica cosa deve accadere e in quale ordine. L'illustrazione seguente mostra come i flussi vengono ordinati in sequenza all'interno di un endpoint proxy e di un endpoint target:
L'endpoint proxy e l'endpoint target contengono ciascuno flussi che puoi organizzare nella seguente sequenza:
| Posizione | Tipo di flusso | Descrizione |
|---|---|---|
| 1 | PreFlow |
È utile quando devi assicurarti che un determinato codice venga eseguito prima di qualsiasi altro. Se PreFlow si trova in un endpoint di destinazione, viene eseguito dopo il PostFlow dell'endpoint proxy. |
| 2 | Flusso condizionale |
Il luogo per la logica condizionale. Viene eseguito dopo PreFlow e prima di PostFlow.
Viene eseguito un solo flusso condizionale per segmento: il primo flusso la cui condizione
restituisce true. Ciò significa che puoi eseguire un flusso condizionale come parte di
ciascuno dei seguenti elementi:
|
| 3 | PostFlow |
Un buon punto per registrare i dati, inviare una notifica che qualcosa è successo durante l'elaborazione della richiesta e così via. Viene eseguita dopo i flussi condizionali e PreFlow. Se il post-flusso si trova in un endpoint proxy e esiste un endpoint di destinazione, il post-flusso dell'endpoint proxy viene eseguito prima del pre-flusso dell'endpoint di destinazione. |
| 4 | PostClientFlow (solo flusso proxy) | Un flusso per la registrazione dei messaggi dopo che una risposta viene restituita al client. |
Eseguire il codice prima con un PreFlow
Un PreFlow è utile quando devi assicurarti che un determinato codice venga eseguito prima che accada.
In un endpoint proxy, PreFlow è un ottimo posto per il codice che autentica un client e limita il traffico proveniente dai client. In un endpoint di destinazione, in cui inizia a prepararsi per l'invio di una richiesta a un target di backend, un PreFlow è ideale per i primi passaggi di preparazione all'invio della richiesta.
Ad esempio, in genere non è consigliabile fornire assistenza a un client che ha superato la quota disponibile. Per supportare questi requisiti, inserisci i criteri di sicurezza e quota nel segmento PreFlow. In questo modo, non dovrai 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 che l'elaborazione passi ai flussi condizionali.
<PreFlow name="MyPreFlow">
<Request>
<Step>
<Name>Spike-Arrest</Name>
</Step>
<Step>
<Name>Quota</Name>
</Step>
</Request>
<Response/>
</PreFlow>
Fare in modo che il codice venga eseguito in modo condizionale con un flusso condizionale
Tra un PreFlow e un PostFlow, puoi avere flussi che vengono eseguiti in modo condizionale. In questo modo, hai l'opportunità di configurare più sequenze di logica, ma eseguirne una sola in base allo stato del proxy. Un flusso condizionale è facoltativo se puoi eseguire tutta la logica in PreFlow o PostFlow e non sono necessarie condizioni (in altre parole, è supportato solo un percorso attraverso l'endpoint).
Ogni flusso specifica una condizione che verifica la presenza di valori di stato diversi. In questo modo, l'esecuzione viene suddivisa 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 /issue/** (/issue/ con qualsiasi elemento nell'URI dopo l'ultimo slash вперед).
<Flow name="MyFlow">
<Description/>
<Request>
<Step>
<Name>Quota</Name>
</Step>
</Request>
<Response/>
<Condition>(proxy.pathsuffix MatchesPath "/issue/**") and (request.verb = "GET")</Condition>
</Flow>
Le variabili di flusso vengono utilizzate per specificare le condizioni. Per saperne di più sull'utilizzo delle variabili nelle condizioni, consulta la sezione Condizioni con variabili di flusso.
Per esempi di utilizzo della corrispondenza dei pattern nelle condizioni, vedi Corrispondenza dei pattern.
Eseguire il codice dopo la logica di base con un PostFlow
Un post-flusso è un ottimo posto per eseguire azioni dopo la logica di base dell'endpoint e prima del completamento dell'elaborazione dell'endpoint. Un PostFlow viene eseguito dopo i flussi condizionali e PreFlow.
Un PostFlow è un buon posto per registrare alcuni dati, inviare una notifica che qualcosa è successo, trasformare il formato del messaggio di risposta e così via.
Nell'esempio seguente, un criterio AssignMessage 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 ha ricevuto la risposta del proxy con un PostClientFlow.
Un PostClientFlow può includere i seguenti criteri:
- Norme sui callout estensioni
- Norme sui callout di flusso*
- Criterio MessageLogging
- Norme di ServiceCallout
* Il criterio FlowCallout può chiamare solo i flussi condivisi che a loro volta soddisfano i criteri di presenza in PostClientFlow (ovvero che contengono solo criteri compatibili).
Se ne includi uno, PostClientFlow sarà l'ultimo flusso da eseguire, dopo che è stata inviata 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 di registrazione dei messaggi 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 mostra come creare un PostClientFlow utilizzando il criterio MessageLogging della serie Four Minute Video For Developers (4MV4D).
Per ulteriori informazioni, vedi:
- Riferimento per la configurazione dei proxy API
- Tutorial : Apigee Edge - Articolo della community post-client
Aggiunta della logica ai flussi
Quando aggiungi la logica al proxy, lo fai aggiungendo i criteri 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 configurazione del flusso di esempio seguente fa riferimento a tre criteri (configurati altrove nei relativi 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.
Flussi di debug
Lo strumento Apigee Edge Trace fornisce un modo grafico per vedere come viene eseguita la logica nel proxy API in seguito a una richiesta. Lo strumento illustra l'elaborazione tra richiesta e risposta. Non illustra specificamente la separazione tra PreFlow, flussi condizionali e PostFlow.
Per saperne di più sul monitoraggio dei proxy, vedi Utilizzare lo strumento di monitoraggio.
Gestione degli errori nei flussi
Puoi generare 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 da una destinazione di backend. Nell'esempio, viene generato un errore se la risposta del target non è 200 (esito positivo).
<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 Gestione degli errori.