Controllo dei proxy API con i flussi

Questa pagina si applica a Apigee e Apigee ibrido.

Visualizza la documentazione di Apigee Edge.

I flussi sono i componenti di base di base dei proxy API. I flussi ti consentono di programmare il comportamento di un'API consentendoti di configurare la sequenza in cui i criteri e il codice vengono eseguiti da un proxy API.

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, 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 viene eseguito il criterioVerifyAPIKey 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 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

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

Nota: consulta Creare il tuo primo proxy API per un semplice tutorial sulla creazione di un flusso. Per le specifiche sulla configurazione dei flussi, consulta Configurazione dei flussi.

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 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 alla logica le posizioni in cui la logica deve agire prima sulla richiesta inviata dal 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 la logica per preparare una richiesta e quindi gestire la risposta da 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 di destinazione:

L'endpoint proxy e l'endpoint di destinazione 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 che accada. Se PreFlow si trova in un endpoint di destinazione, viene eseguito dopo il PostFlow dell'endpoint proxy.
2	Flusso condizionale	Il posto per la logica condizionale. Viene eseguito dopo il preFlow e prima del 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: Pipeline di richieste di ProxyEndpoint Pipeline di richieste di TargetEndpoint Pipeline di risposta di ProxyEndpoint Pipeline di risposta di TargetEndpoint
3	PostFlow	Un posto ideale in cui registrare i dati, inviare una notifica indicante che 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, quest'ultimo 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 per primo 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 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 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 in 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 richieste condizioni (in altre parole, è supportato un solo percorso attraverso l'endpoint).

Ogni flusso specifica una condizione che verifica i diversi valori di stato. Questo ramifica efficacemente l'esecuzione in base alle condizioni. Ad esempio, potresti voler convertire il file XML in JSON solo quando l'app che la richiede è in esecuzione su un dispositivo mobile.

Nota: in un flusso condizionale, la condizione viene valutata sia nella richiesta che nella risposta. Non puoi avere condizioni distinte per la richiesta e la risposta. Viene eseguito un solo flusso condizionale: il primo flusso la cui condizione viene valutata su true.

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 usare 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.

Fare in modo che il codice venga eseguito dopo la logica principale con un PostFlow

Un PostFlow è un ottimo posto 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 PreFlow.

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

Nell'esempio seguente, un criterioAssignMessage chiamato SetResponseHeaders imposta le intestazioni del messaggio di risposta prima che Apigee 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 solo i seguenti criteri. Non è possibile utilizzare altri criteri in un PostClientFlow:

• Norme relative ai callout di flusso^*
• Criterio MessageLogging
• Norme relative a 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, un PostClientFlow sarà l'ultimo flusso da eseguire, in esecuzione dopo l'invio di una risposta al client.

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

Ecco un esempio di PostClientFlow con un criterio MessageLogging collegato.

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

Per ulteriori informazioni, consulta Riferimento alla configurazione del proxy API.

Aggiunta della logica ai flussi

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

Nota: per ulteriori informazioni sui criteri, incluso come aggiungerli nella console e nel codice, consulta Che cos'è un criterio? Per maggiori dettagli sul collegamento dei criteri ai flussi, consulta Flussi condizionali.

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 Assign-Message; 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>Assign-Message</Name>
    </Step>
    <Step>
      <Name>Quota</Name>
    </Step>
  </Request>
  <Condition>(proxy.pathsuffix MatchesPath "/") and (request.verb = "GET")</Condition>
</Flow>

Nota: nel codice riportato sopra la condizione del percorso, (proxy.pathsuffix MatchesPath "/"), è sempre vera perché "/" corrisponde sempre. Quindi puoi semplicemente rimuoverla dall'elemento Condition e utilizzare solo la condizione del verbo:

    <Condition>request.verb = "GET"</Condition>

Flussi di debug

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

Per scoprire di più sui proxy di debug, vedi Utilizzo dello strumento di debug.

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 dal target non è 200 (riuscito).

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