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 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, 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 viene pubblicato per 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.

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

Quando decidi dove aggiungere la logica, scegli innanzitutto 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. Consente alla logica di agire prima sulla richiesta del client e infine in base alla risposta al client.	PreFlow, flussi condizionali, PostFlow, PostClientFlow
TargetEndpoint	Contiene i flussi proxy API più vicini alla risorsa di backend. Fornisce i luoghi per la logica per cui preparare una richiesta e poi gestisce 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. La seguente illustrazione mostra come i flussi sono ordinati in sequenza all'interno di un endpoint proxy e di un 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 altro. Se il PreFlow si trova in un endpoint di destinazione, viene eseguito dopo il PostFlow dell'endpoint proxy.
2	Flusso condizionale	Lo spazio della 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 è considerata true. Ciò significa che puoi eseguire un flusso condizionale come parte di ognuno dei seguenti: Pipeline di richiesta di ProxyEndpoint Pipeline di richiesta di TargetEndpoint Pipeline di risposta di ProxyEndpoint Pipeline di risposta di TargetEndpoint
3	PostFlow	È un buon punto in cui registrare i dati, inviare una notifica che si è verificato un problema durante l'elaborazione della richiesta e così via. Esegue 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 del PreFlow dell'endpoint di destinazione.
4	PostClientFlow (solo flusso proxy)	Flusso per la registrazione dei messaggi dopo che una risposta viene restituita al client.

Fai in modo che il codice venga eseguito prima con un preFlow

Un preFlow è utile quando è necessario assicurarsi che un determinato codice venga eseguito prima che succeda qualsiasi altro.

In un endpoint proxy, un 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 la preparazione per l'invio di una richiesta a una destinazione del backend, un preFlow è utile per i primi passaggi della preparazione all'invio della richiesta.

Ad esempio, di solito non è consigliabile servire un client che ha superato la propria quota. Per supportare questi requisiti, inserisci i criteri di sicurezza e delle quote 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 dell'esecuzione di qualsiasi altra elaborazione.

Nell'esempio seguente, i criteri SpikeArrest e Quota vengono eseguiti prima di elaborare i passaggi per i 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, possono essere presenti flussi che vengono eseguiti in modo condizionale. Questo ti offre l'opportunità di configurare più sequenze di logica, ma di avere solo una in esecuzione in base allo stato del proxy. Un flusso condizionale è facoltativo se puoi eseguire tutta la logica in PreFlow o PostFlow e se non sono richieste condizioni (in altre parole, è supportato un solo percorso attraverso l'endpoint).

Ogni flusso specifica una condizione che verifica valori di stato diversi. Questa operazione ramifica in modo efficace l'esecuzione in base alle condizioni. Ad esempio, potresti voler convertire il file XML in JSON solo quando l'app richiedente è 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 richiesta e risposta. Viene eseguito un solo flusso condizionale, il primo flusso la cui condizione risulta vera.

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 Condizioni con variabili di flusso.

Per esempi sull'utilizzo della corrispondenza di pattern in 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 di base dell'endpoint e prima che finisca l'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 dei messaggi 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>

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

Un PostClientFlow può includere solo i seguenti criteri. Nessun altro criterio può essere utilizzato in un PostClientFlow:

• Norme sui callout di flusso^*
• Norme di MessageLogging
• Norme sui callout di servizio

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

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

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

Ecco un esempio di PostClientFlow con un criterio MessageLogging allegato.

  <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 la sezione Riferimento alla configurazione del proxy API.

Aggiunta della logica ai flussi

L'aggiunta di logica al proxy comporta l'aggiunta di criteri ai flussi del proxy. Proprio come i flussi vengono eseguiti in sequenza (PreFlow, poi Flow e poi PostFlow, come descritto in questo argomento), i contenuti di un flusso vengono eseguiti in sequenza.

Nota: per saperne di più sui criteri, incluso come aggiungerli con la console e nel codice, consulta Cos'è un criterio? Per maggiori dettagli sul collegamento dei criteri ai flussi, consulta Flussi condizionali.

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 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 precedente, la condizione del percorso, (proxy.pathsuffix MatchesPath "/"), è sempre vera perché "/" trova sempre una corrispondenza. Potresti quindi rimuoverlo dall'elemento Condition e utilizzare solo la condizione verbale:

    <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 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ù sul debug dei proxy, consulta Utilizzare lo strumento di debug.

Gestione degli errori nei flussi

Puoi segnalare gli errori da varie posizioni in un proxy API, anche dai flussi.

L'esempio seguente è la stanza di risposta da un PreFlow in un endpoint di destinazione, ovvero il codice che viene eseguito immediatamente dopo aver ricevuto la risposta dalla destinazione di un backend. Nell'esempio, viene generato un errore se la risposta dalla destinazione 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.