Criterio FlowCallout

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Utilizza il criterio FlowCallout per chiamare un flusso condiviso da un proxy API o da un altro flusso condiviso.

In un flusso condiviso, crei una sequenza di passaggi che puoi riutilizzare in fase di runtime da più posizioni. Questi passaggi vengono implementati come criteri, come all'interno di un proxy API. La norma FlowCallout ti consente di richiamare il flusso condiviso da proxy API e altri flussi condivisi. Funziona come una chiamata di funzione in un linguaggio di programmazione tradizionale.

• Ad esempio, supponiamo di aver creato un flusso condiviso con funzionalità di sicurezza come verifica della chiave API, convalida del token OAuth e protezione delle espressioni regolari. Questo flusso condiviso rappresenta la tua convenzione per un modo di controllare le richieste in entrata. Utilizzando i criteri FlowCallout, puoi richiamare il flusso condiviso da più proxy API.
• Puoi chiamare un flusso condiviso da un altro implementando un criterio FlowCallout all'interno di un flusso condiviso.

Queste norme sono estensibili e il loro utilizzo potrebbe avere implicazioni in termini di costi o di utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni di utilizzo, consulta Tipi di criteri.

Nota:per ulteriori informazioni sui flussi condivisi, vedi Flussi condivisi riutilizzabili. Puoi anche chiamare un flusso condiviso dal codice del proxy API esterno per applicare la pre-elaborazione delle richieste o la post-elaborazione delle risposte per tutti i proxy API di cui è stato eseguito il deployment in un ambiente. Per saperne di più, vedi Collegamento di un flusso condiviso utilizzando un hook di flusso.

Esempi

Verifica la chiave API nel flusso condiviso

In questo esempio, un flusso condiviso viene utilizzato per eseguire attività comuni relative alla sicurezza. Qui il flusso condiviso convalida una chiave API. I proxy API e altri flussi condivisi possono utilizzare il criterio FlowCallout per effettuare chiamate a questo flusso condiviso.

La seguente definizione di flusso condiviso include una policy Verify-API-Key che viene eseguita quando il flusso condiviso viene chiamato da una policy FlowCallout in un proxy API.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SharedFlow name="default">
    <Step>
        <Name>Verify-API-Key</Name>
    </Step>
</SharedFlow>

Il criterio VerifyAPIKey all'interno del flusso condiviso precedente recupera il valore della chiave e lo verifica.

<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key">
    <DisplayName>Verify API Key</DisplayName>
    <APIKey ref="request.queryparam.apikey"/>
</VerifyAPIKey>

La seguente policy FlowCallout, utilizzata in un proxy API, chiama il flusso condiviso precedente per verificare la chiave API. Il bundle di flussi condivisi verify-apikey-shared (non mostrato qui) configura il flusso condiviso nello stesso modo in cui un bundle APIProxy configura un proxy.

<FlowCallout async="false" continueOnError="false" enabled="true" name="Auth-Flow-Callout">
    <DisplayName>Auth Flow Callout</DisplayName>
    <SharedFlowBundle>verify-apikey-shared</SharedFlowBundle>
</FlowCallout>

Trasferire parametri a un flusso condiviso

Questo esempio mostra come passare i parametri da un criterio FlowCallout a un flusso condiviso. In questo caso, un criterio FlowCallout chiama un flusso condiviso progettato per eseguire funzioni comuni di gestione delle stringhe. Il flusso condiviso include JavaScript che concatena l'input, lo converte in minuscolo o entrambe le cose. Il criterio FlowCallout definisce i parametri che specificano l'input, l'output e cosa fare con l'input della stringa.

1. Il criterio String-Handler FlowCallout chiama il flusso condiviso, passando i parametri che specificano la variabile in cui memorizzare l'output del flusso condiviso, l'operazione del flusso condiviso da utilizzare e l'input da utilizzare (in questo caso, un valore letterale stringa, ma potrebbe anche essere una variabile di flusso). Gli elementi Parameter specificano i nomi e i valori delle variabili da creare in fase di runtime. Il flusso condiviso può recuperare queste variabili per utilizzarle nel proprio codice.

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <FlowCallout async="false" continueOnError="false" enabled="true" name="String-Handler">
     <DisplayName>String Handler</DisplayName>
     <Parameters>
       <Parameter name="input">Gladys Kravitz</Parameter>
       <Parameter name="operations">concatenate tolowercase</Parameter>
       <Parameter name="outputVariable">string.handler.output</Parameter>
     </Parameters>
     <SharedFlowBundle>StringHandler</SharedFlowBundle>
   </FlowCallout>

2. Il seguente flusso condiviso default include una norma SharedStringFunctions JavaScript che viene eseguita quando il flusso condiviso viene chiamato da una norma FlowCallout.

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <SharedFlow name="default">
     <Step>
       <Name>SharedStringFunctions</Name>
     </Step>
   </SharedFlow>

3. Nel flusso condiviso, la seguente norma JavaScript SharedStringFunctions specifica il file JavaScript SharedStringFunctions.js con il codice da eseguire.

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="SharedStringFunctions">
     <DisplayName>SharedStringFunctions</DisplayName> <Properties/>
     <ResourceURL>jsc://SharedStringFunctions.js</ResourceURL>
   </Javascript>

4. Il seguente JavaScript, SharedStringFunctions.js, viene eseguito dai criteri JavaScript SharedStringFunctions. Questo script recupera i valori dalle variabili create dagli elementi FlowCallout del criterio Parameter.

   // Input value from the calling API proxy.
   var handledString = context.getVariable("input");
   // Variable to use for output from this script.
   var outputVariable = context.getVariable("outputVariable");
   // A space-separated list of things to do to the input string.
   // Convert to lower case to handle unintentional capitals in configuration.
   var operation = context.getVariable("operations").toLowerCase();
   
   // If "lowercase" was given as an operation, convert the input to lowercase.
   if (operation.includes("tolowercase")) {
       handledString = handledString.toLowerCase();
   }
   
   // If "concatenate" was given as an operation, concatenate the input.
   if (operation.includes("concatenate")) {
       handledString = handledString.replace(/\s+/g, '');
   }
   // Assign the resulting string to the output variable specified by
   // the calling API proxy.
   context.setVariable(outputVariable, handledString);

5. L'esecuzione torna dalla norma JavaScript al flusso condiviso, quindi alla norma FlowCallout nel proxy API di origine.

Riferimento elemento

Di seguito sono riportati gli elementi e gli attributi che puoi configurare in queste norme:

<FlowCallout async="false" continueOnError="false" enabled="true" name="Flow-Callout-1">
    <DisplayName>Custom label used in UI</DisplayName>
    <SharedFlowBundle>thereferencedsharedflowbundle</SharedFlowBundle>
</FlowCallout>

Attributi <FlowCallout>

<FlowCallout async="false" continueOnError="false" enabled="true" name="Flow-Callout-1">

La tabella seguente descrive gli attributi comuni a tutti gli elementi principali dei criteri:

Attributo	Descrizione	Predefinito	Presence
name	Il nome interno del criterio. Il valore dell'attributo name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri. Se vuoi, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.	N/D	Obbligatorio
continueOnError	Imposta su false per restituire un errore quando un criterio non va a buon fine. Questo è un comportamento previsto per la maggior parte dei criteri. Imposta su true per continuare l'esecuzione del flusso anche dopo un fallimento del criterio. Vedi anche: Le regole di errore vengono attivate SOLO in uno stato di errore (informazioni su continueOnError) Gestione degli errori all'interno del flusso corrente	falso	Facoltativo
enabled	Imposta su true per applicare il criterio. Imposta su false per disattivare il criterio. Il criterio non verrà applicato anche se rimane collegato a un flusso.	true	Facoltativo
async	Questo attributo è stato ritirato.	falso	Deprecato

Elemento <DisplayName>

Da utilizzare insieme all'attributo name per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.

<DisplayName>Policy Display Name</DisplayName>

Predefinito	N/D Se ometti questo elemento, viene utilizzato il valore dell'attributo name del criterio.
Presence	Facoltativo
Tipo	Stringa

Elemento <SharedFlowBundle>

Specifica il nome del flusso condiviso da chiamare. Il valore di questo elemento deve essere uguale al valore dell'attributo name dell'elemento <SharedFlowBundle> di destinazione.

<SharedFlowBundle/>

Nell'esempio più semplice, fornisci il nome del flusso condiviso chiamato come valore per questo elemento. ovvero il valore di questo elemento deve essere uguale al valore dell'attributo name del flusso condiviso.

<SharedFlowBundle>Shared-Flow-Name</SharedFlowBundle>

Predefinito	N/D
Presenza	Obbligatorio
Tipo	N/D

Attributi

Nessuno.

Elemento <Parameter>

Specifica un parametro e un valore (o un'origine valore) da passare come variabile nel flusso condiviso chiamato da questo criterio.

Utilizzando un parametro, puoi specificare un valore (o una variabile contenente un valore) da trasmettere al flusso condiviso chiamato dal criterio. Questo è concettualmente simile alla specifica di un parametro in una chiamata di funzione. Come per un parametro di funzione, il valore di un parametro FlowCallout può variare in base al contesto della chiamata del flusso condiviso.

I parametri FlowCallout sono visibili solo durante l'esecuzione del flusso condiviso.

Sintassi

Puoi utilizzare questo elemento con una delle seguenti forme di sintassi. Tieni presente che quando utilizzi un valore letterale, il formato del valore specificato dipende dal codice che lo utilizza.

<!- A literal value in an attribute. --/>
<Parameter name="parameter-name" value='parameter-value' />
<!- A reference to a variable in an attribute. --/>
<Parameter name="parameter-name" ref='source-variable-name' />
<!- A literal value in the element content. --/>
<Parameter name="parameter-name">parameter-value</Parameter>
<!- An reference to an attribute in the element content. --/>
<Parameter name="parameter-name">{source-variable-name}</Parameter>

Esempio

Questo criterio String-Handler FlowCallout passa parametri che specificano dove memorizzare l'output del flusso condiviso e quale input utilizzare. Gli elementi Parameter specificano i nomi e i valori delle variabili da creare in fase di runtime. Il flusso condiviso può recuperare queste variabili per utilizzarle nel proprio codice.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<FlowCallout async="false" continueOnError="false" enabled="true" name="String-Handler">
  <DisplayName>String Handler</DisplayName>
  <Parameters>
    <Parameter name="input">Gladys Kravitz</Parameter>
    <Parameter name="outputVariable">string.handler.output</Parameter>
  </Parameters>
  <SharedFlowBundle>StringHandler</SharedFlowBundle>
</FlowCallout>

Predefinito	N/D
Presenza	Obbligatorio
Tipo	N/D

Attributi

Attributo	Descrizione	Predefinito	Presenza	Tipo
name	Il nome della variabile di runtime da creare con questo parametro.	Nessuno	Obbligatorio	Stringa
ref	La variabile che contiene il valore da utilizzare in fase di runtime. Ometti questo attributo se stai specificando un valore letterale da utilizzare.	Nessuno	Facoltativo	Stringa
value	Il valore da utilizzare nella variabile di runtime creata con questo parametro. Ometti questo attributo se stai specificando il nome di una variabile che deve essere l'origine del valore.	Nessuno	Facoltativo	Stringa

Elemento <Parameters>

Specifica l'insieme di elementi <Parameter> da passare come variabili nel flusso condiviso chiamato da questa norma.

Sintassi

<Parameters>
  <Parameter name="parameter-name" value='parameter-value' />
</Parameters>

Predefinito	N/D
Presenza	Facoltativo
Tipo	N/D

Attributi

Nessuno.

Schemi

Esempio: consulta i nostri esempi nel repository GitHub per gli schemi più recenti.

Variabili di flusso

Le variabili di flusso consentono il comportamento dinamico di criteri e flussi in fase di runtime, in base alle intestazioni HTTP, al contenuto dei messaggi o al contesto del flusso. Per ulteriori informazioni sulle variabili di flusso, consulta Riferimento alle variabili.

Variabile	Descrizione
apigee.edge.sharedflow.name	Ambito: durante l'esecuzione del flusso condiviso Tipo: stringa Autorizzazione: lettura Il valore dell'attributo name del flusso condiviso.
apigee.edge.flowhook.name	Ambito: durante l'esecuzione del flusso condiviso collegato all'hook di flusso. Type: String Permission: Read Il nome dell'hook del flusso.

Messaggi di errore

Questa sezione descrive i codici di errore e i messaggi di errore restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti se stai sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta Che cosa devi sapere sugli errori relativi alle norme e Gestione degli errori.

Errori di runtime

Questi errori possono verificarsi durante l'esecuzione del criterio.

Suggerimento:hai bisogno di aiuto per risolvere un errore? Fai clic su nella colonna Correzione per informazioni dettagliate sulla risoluzione dei problemi.

Utilizza il monitoraggio delle API per esaminare i codici di errore e diagnosticare i problemi più rapidamente.

Codice guasto	Stato HTTP	Causa	Correggi
flow.SharedFlowNotFound	500	Il flusso condiviso non esiste o esiste, ma non è stato di cui è stato eseguito il deployment.

Errori di deployment

N/D

Argomenti correlati

• Creazione di flussi condivisi: Flussi condivisi riutilizzabili
• Esecuzione di flussi condivisi in più proxy: Collegamento di un flusso condiviso utilizzando un hook di flusso