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 dei proxy API. I flussi ti consentono di programmare il comportamento di un'API configurando 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.

L'esempio di configurazione del flusso seguente 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 a includere una policy configurata 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 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 informazioni specifiche sulla configurazione dei flussi, vedi 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 il codice che interagisce con il client del proxy (endpoint proxy) e il codice facoltativo che interagisce con la destinazione di 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 del proxy API più vicini al client. Fornisce posizioni in cui la logica deve agire prima sulla richiesta del client e poi per ultima 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 gestire la risposta di una risorsa di backend.	PreFlow, flussi condizionali, PostFlow

Configuri il flusso con 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 proxy e l'endpoint di destinazione contengono ciascuno flussi che puoi disporre nella seguente sequenza:

Posizione	Tipo di flusso	Descrizione
1	PreFlow	Utile quando devi assicurarti che un determinato codice venga eseguito prima di qualsiasi altra operazione. Se PreFlow si trova in un endpoint di destinazione, viene eseguito dopo PostFlow dell'endpoint proxy.
2	Flusso condizionale	Il luogo in cui inserire la logica condizionale. Viene eseguito dopo PreFlow e prima di PostFlow. Viene eseguito un solo flusso condizionale per segmento, ovvero 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 buon punto in cui registrare i dati, inviare una notifica che indica che si è verificato un problema durante l'elaborazione della richiesta e così via. Viene eseguito dopo i flussi condizionali e PreFlow. Se PostFlow si trova in un endpoint proxy e c'è un endpoint di destinazione, PostFlow dell'endpoint proxy viene eseguito prima di PreFlow dell'endpoint di destinazione.
4	PostClientFlow (solo flusso proxy)	Un flusso per registrare i messaggi dopo che una risposta viene restituita al client.

Esecuzione del codice prima con un PreFlow

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

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

Ad esempio, in genere non vuoi servire un cliente che ha superato la quota. Per supportare questi requisiti, inserisci le norme relative a 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 in questo flusso verranno sempre eseguiti prima di qualsiasi altra elaborazione.

Nell'esempio seguente, le norme SpikeArrest e Quota vengono eseguite 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>

Esecuzione condizionale del codice con un flusso condizionale

Tra un PreFlow e un PostFlow, puoi avere flussi che vengono eseguiti in modo condizionale. In questo modo puoi configurare più sequenze di logica, ma 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 attraverso l'endpoint).

Ogni flusso specifica una condizione che verifica valori di stato diversi. In questo modo, l'esecuzione viene ramificata in base alle condizioni. Ad esempio, potresti voler convertire 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 separate per la richiesta e la risposta. Viene eseguito un solo flusso condizionale, il primo la cui condizione restituisce il 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'ultima barra obliqua).

<Flow name="MyFlow">
    <Description/>
    <Request>
        <Step>
            <Name>Quota</Name>
        </Step>
    </Request>
    <Response/>
    <Condition>(proxy.pathsuffix MatchesPath "/issue/**") and (request.verb = "GET")</Condition>
</Flow>

Utilizzi 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 di utilizzo della corrispondenza dei pattern nelle condizioni, vedi Corrispondenza dei pattern.

Esecuzione del codice dopo la logica principale con un PostFlow

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

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

Nell'esempio seguente, una policy AssignMessage denominata 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>

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

Un PostClientFlow può includere solo i seguenti criteri. Nessun'altra norma può essere utilizzata in un PostClientFlow:

• Norme FlowCallout^*
• Norme MessageLogging
• Norme ServiceCallout

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

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

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

Aggiungere la logica ai flussi

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

Nota: per saperne di più sulle norme, incluso come aggiungerle con la console e nel codice, consulta Che cos'è una norma? Per informazioni dettagliate sull'allegato di policy ai flussi, vedi Flussi condizionali.

La seguente configurazione del flusso di esempio fa riferimento a tre criteri (configurati altrove nei rispettivi 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. Pertanto, potresti semplicemente rimuoverlo dall'elemento Condition e utilizzare solo la condizione del verbo:

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

Eseguire il debug dei flussi

Lo strumento di debug 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 in modo specifico la separazione tra PreFlow, flussi condizionali e PostFlow.

Per ulteriori informazioni sul debug dei proxy, consulta Utilizzo dello strumento di debug.

Gestione degli errori nei flussi

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

L'esempio seguente è la sezione 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 della destinazione non è 200 (operazione riuscita).

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