Controllo dei proxy API con i flussi

Questa pagina si applica ad Apigee e Apigee hybrid.

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, aggiungi la logica come passaggio nella sequenza specificata da un flusso. Quando definisci una condizione per specificare se e quando viene eseguita la logica, la aggiungi 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 serve per includere un criterio configurato altrove nel proxy con XML, ad esempio 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.

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 target. Il codice di un proxy API è diviso tra il codice che interagisce con il client del proxy (endpoint del proxy) e il codice facoltativo che interagisce con il target del backend del proxy, se esistente (endpoint target).

Entrambi gli endpoint contengono flussi, come descritto qui:

Tipo di endpoint	Descrizione	Flussi supportati
ProxyEndpoint	Contiene i flussi del proxy API più vicini al client. Fornisce luoghi in cui la logica può agire 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

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

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 altra . Se PreFlow si trova in un endpoint di destinazione, viene eseguito dopo PostFlow dell'endpoint proxy.
2	Flusso condizionale	Il luogo per la logica condizionale. Viene eseguito dopo PreFlow e prima di PostFlow. Per ogni segmento viene eseguito un solo flusso condizionale, ovvero il primo flusso la cui condizione viene valutata come vera. Ciò significa che puoi avere un flusso condizionale eseguito nell'ambito di ciascuno dei seguenti elementi: Pipeline delle richieste di ProxyEndpoint Pipeline di richieste di TargetEndpoint Pipeline di risposta di ProxyEndpoint Pipeline di risposta di TargetEndpoint
3	PostFlow	È un buon posto per registrare i dati e inviare una notifica per informare che si è verificato un problema mentre l'elaborazione della richiesta e così via. Viene eseguito 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 con un comando PreFlow

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

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 target, dove inizia la preparazione per l'invio di una richiesta a un target di backend, un PreFlow è utile per i primi passaggi di preparazione all'invio della richiesta.

Ad esempio, in genere non vuoi fornire assistenza a un cliente che ha superato la sua quota. A che supportano questi requisiti, inserisci i criteri di sicurezza e quota 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 che l'elaborazione passi a condizionali.

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

Avere il codice viene eseguito in modo condizionale con un flusso condizionale

Tra un PreFlow e un PostFlow, puoi avere flussi che vengono eseguiti in modo condizionale. Ciò consente di puoi configurare più sequenze di logica, ma eseguirne una sola in base lo 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, dirama l'esecuzione in base alle condizioni. Ad esempio, potresti voler convertire solo da XML a JSON quando l'app che la richiede è in esecuzione su un dispositivo mobile.

Nota: in un flusso condizionale, la condizione viene valutata sia nella richiesta e risposta. Non puoi avere condizioni separate per la richiesta e la risposta. Viene eseguito un solo flusso condizionale, ovvero il primo flusso la cui condizione ha valore 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'ultimo inoltro 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 ulteriori informazioni sull'uso delle variabili nelle condizioni, consulta Condizioni con variabili di flusso.

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

Eseguire il codice dopo la logica di base con un PostFlow

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

PostFlow è un ottimo posto per registrare alcuni dati, inviare una notifica per informarsi 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 invii la risposta al client.

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

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

Un PostClientFlow può includere solo i seguenti criteri. In PostClientFlow non è possibile utilizzare altri criteri:

• Norme sui callout di flusso^*
• Criterio MessageLogging
• Norme di ServiceCallout

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

Se ne includi uno, un PostClientFlow sarà l'ultimo flusso da eseguire, che viene eseguito dopo l'invio di una risposta all'oggetto di alto profilo.

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 un criterio di registrazione dei messaggi associato.

  <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 il riferimento per la configurazione dei proxy API.

Aggiunta di logica ai flussi

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

Nota: per saperne di più sui criteri, inclusa la procedura per aggiungerli con la console e nel codice, consulta Cos'è un criterio? Per informazioni dettagliate sull'associazione dei criteri ai flussi, consulta Flusso condizionale.

La configurazione del flusso di esempio seguente fa riferimento a tre criteri (configurati altrove in propri 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 vero perché "/" è sempre corrispondente. Quindi puoi semplicemente rimuoverlo dall'elemento Condizione e utilizzare solo la condizione del verbo:

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

Flussi di debug

Lo strumento di debug consente di verificare in modo grafico come la logica nel proxy API viene eseguita a seguito di una richiesta. Lo strumento illustra l'elaborazione tra richiesta e risposta. it non illustra in modo specifico la separazione tra PreFlow, i flussi condizionali e PostFlow.

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

Gestione degli errori nei flussi

Puoi segnalare errori da vari punti in un proxy API, inclusi i flussi.

L'esempio seguente è la stanza di risposta di un PreFlow in un endpoint target, ovvero il codice che viene eseguito immediatamente dopo aver ricevuto la risposta da un target 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 Gestire gli errori.