Criterio IntegrationCallout

Questa pagina si applica ad Apigee e Apigee hybrid.

Panoramica

Il criterio IntegrationCallout consente di eseguire un'integrazione di Application Integration con un trigger API. Tuttavia, prima di eseguire un'integrazione, devi eseguire il criterio SetIntegrationRequest. Il criterio SetIntegrationRequest crea un oggetto richiesta e lo rende disponibile al criterio IntegrationCallout come variabile di flusso. L'oggetto richiesta contiene i dettagli dell'integrazione, come il nome del trigger API, l'ID progetto di integrazione, il nome dell'integrazione e altri dettagli configurati nel criterio SetIntegrationRequest. Il criterio IntegrationCallout utilizza la variabile di flusso dell'oggetto richiesta per eseguire l'integrazione. Puoi configurare il criterio IntegrationCallout per salvare la risposta dell'esecuzione dell'integrazione in una variabile di flusso.

Il criterio IntegrationCallout è utile se vuoi eseguire l'integrazione a metà del flusso del proxy. In alternativa, anziché configurare il criterio IntegrationCallout, puoi anche eseguire un'integrazione specificando un endpoint di integrazione come endpoint di destinazione. Per ulteriori informazioni, consulta IntegrationEndpoint.

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 eseguire il criterio IntegrationCallout è necessario un token di autenticazione. Tuttavia, non esiste un elemento Authentication esplicito nella definizione delle norme. Apigee aggiunge un token di autenticazione alla richiesta in background. Affinché il criterio IntegrationCallout venga autenticato correttamente, devi eseguire il deployment del proxy API con un account di servizio che disponga dei ruoli IAM richiesti per eseguire un'integrazione. Per informazioni sui ruoli richiesti, consulta Ruoli IAM per le integrazioni. Per maggiori dettagli sul deployment di un proxy API, vedi Deployment su Apigee.

<IntegrationCallout>

Specifica il criterio IntegrationCallout.

Valore predefinito	N/D
Obbligatorio?	Obbligatorio
Tipo	Tipo complesso
Elemento principale	N/D
Elementi secondari	<DisplayName> <AsyncExecution> <Request> <Response>

La tabella seguente fornisce una descrizione generale degli elementi secondari di <IntegrationCallout>:

Elemento secondario	Obbligatorio?	Descrizione
<DisplayName>	Facoltativo	Un nome personalizzato per il criterio.
<AsyncExecution>	Facoltativo	Specifica se l'integrazione deve essere eseguita in modalità sincrona o asincrona.
<Request>	Obbligatorio	La variabile di flusso contenente l'oggetto richiesta creato dal criterio SetIntegrationRequest.
<Response>	Facoltativo	La variabile di flusso in cui salvare la risposta dell'integrazione.

L'elemento <IntegrationCallout> utilizza la seguente sintassi:

Sintassi

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<IntegrationCallout continueOnError="[true|false]" enabled="[true|false]" name=POLICY_NAME>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  <AsyncExecution>BOOLEAN_ASYNC_EXECUTION</AsyncExecution>
  <Request clearPayload="[true|false]">REQUEST_FLOW_VARIABLE_NAME</Request>
  <Response>RESPONSE_FLOW_VARIABLE_NAME</Response>
</IntegrationCallout>

Esempio

L'esempio seguente mostra la definizione del criterio IntegrationCallout:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<IntegrationCallout continueOnError="false" enabled="true" name="Integration-Callout">
  <DisplayName>Integration-Callout-1</DisplayName>
  <AsyncExecution>true</AsyncExecution>
  <Request clearPayload="true">my_request_flow_var</Request>
  <Response>my_response_flow_var</Response>
</IntegrationCallout>

Questo elemento ha i seguenti attributi comuni a tutti i criteri:

Attributo	Predefinito	Obbligatorio?	Descrizione
name	N/D	Obbligatorio	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.
continueOnError	falso	Facoltativo	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
enabled	true	Facoltativo	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.
async	falso	Ritirato	Questo attributo è stato ritirato.

Riferimento all'elemento secondario

Questa sezione descrive gli elementi secondari di <IntegrationCallout>.

<DisplayName>

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

L'elemento <DisplayName> è comune a tutti i criteri.

Valore predefinito	N/D
Obbligatorio?	Facoltativo. Se ometti <DisplayName>, viene utilizzato il valore dell'attributo name del criterio.
Tipo	Stringa
Elemento principale	<PolicyElement>
Elementi secondari	Nessuno

La sintassi dell'elemento <DisplayName> è la seguente:

Sintassi

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Esempio

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

L'elemento <DisplayName> non ha attributi o elementi secondari.

<AsyncExecution>

Specifica la modalità di esecuzione dell'integrazione. Puoi eseguire l'integrazione in modo sincrono o asincrono.

Se impostato su true, l'integrazione viene eseguita in modo asincrono. Se è impostato su false, l'integrazione viene eseguita in modo sincrono.

• Modalità asincrona: quando la richiesta di esecuzione dell'integrazione raggiunge l'endpoint, quest'ultimo restituisce immediatamente gli ID di esecuzione dell'integrazione, ma avvia l'esecuzione dell'integrazione all'ora specificata dall'elemento <ScheduleTime>. Se non hai impostato l'elemento <ScheduleTime>, l'integrazione è pianificata per l'esecuzione immediata. Anche se l'integrazione è pianificata per l'esecuzione immediata, l'esecuzione potrebbe iniziare dopo alcuni secondi. Quando l'integrazione inizia a essere eseguita, si verificano due cose:
  • L'integrazione restituisce il codice di stato HTTP 200 OK in modo che il chiamante possa continuare l'elaborazione.
  • Il criterio IntegrationCallout viene completato.
  Una volta avviata, l'integrazione avrà un limite di tempo massimo di 50 minuti per completare l'esecuzione.
• Modalità sincrona: quando la richiesta di esecuzione dell'integrazione raggiunge l'endpoint, quest'ultimo avvia immediatamente l'esecuzione dell'integrazione e attende la risposta. Il limite di tempo massimo per completare l'esecuzione è di 2 minuti. Al termine dell'esecuzione, l'endpoint restituisce una risposta con gli ID esecuzione e altri dati di risposta.

Valore predefinito	falso
Obbligatorio?	Facoltativo
Tipo	Booleano
Elemento principale	<IntegrationCallout>
Elementi secondari	Nessuno

L'elemento <AsyncExecution> utilizza la seguente sintassi:

Sintassi

<AsyncExecution>BOOLEAN</AsyncExecution>

Esempio

L'esempio seguente imposta l'esecuzione asincrona su true:

<AsyncExecution>true</AsyncExecution>

<Request>

Specifica la variabile di flusso contenente l'oggetto richiesta creato dal criterio SetIntegrationRequest. Il criterio IntegrationCallout invia questo oggetto richiesta ad Application Integration per l'esecuzione dell'integrazione.

Valore predefinito	N/D
Obbligatorio?	Obbligatorio
Tipo	Stringa
Elemento principale	<IntegrationCallout>
Elementi secondari	Nessuno

L'elemento <Request> utilizza la seguente sintassi:

Sintassi

<Request clearPayload="true">FLOW_VARIABLE_NAME</Request>

Esempio

Il seguente esempio specifica che l'oggetto richiesta è disponibile nella variabile di flusso my_request_flow_var:

<Request clearPayload="true">my_request_flow_var</Request>

La tabella seguente descrive gli attributi di <Request>:

Attributo	Obbligatorio?	Tipo	Descrizione
clearPayload	Facoltativo	boolean	Specifica se l'oggetto richiesta deve essere cancellato dalla memoria dopo l'invio della richiesta di esecuzione dell'integrazione. Se impostato su true, Apigee cancella l'oggetto richiesta. Se impostato su false, Apigee non cancella l'oggetto richiesta. Se non specifichi questo attributo, il valore predefinito è true e l'oggetto richiesta viene cancellato dalla memoria.

<Response>

Specifica la variabile di flusso per salvare la risposta dell'integrazione.

Se non specifichi questo elemento, il criterio salva la risposta nella variabile di flusso integration.response.

Valore predefinito	integration.response
Obbligatorio?	Facoltativo
Tipo	Stringa
Elemento principale	<IntegrationCallout>
Elementi secondari	Nessuno

L'output dell'integrazione è accessibile da integration.response.content o flow_variable.content. L'elemento <Response> utilizza la seguente sintassi:

Sintassi

<Response>FLOW_VARIABLE_NAME</Response>

Esempio

Il seguente esempio salva la risposta dell'esecuzione dell'integrazione nella variabile di flusso my_response_flow_var:

<Response>my_response_flow_var</Response>

Codici di errore

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

Errori di runtime

Questi errori possono verificarsi durante l'esecuzione del criterio.

Codice guasto	Stato HTTP	Causa
entities.UnresolvedVariable	500	Questo errore si verifica se Apigee non riesce a risolvere le variabili integration.project.id o integration.name.
steps.integrationcallout.ExecutionFailed	500	Questo errore può verificarsi se il servizio di destinazione di backend restituisce uno stato di errore HTTP come 4xx o 5xx. Ecco alcune possibili cause: L'account di servizio di cui è stato eseguito il deployment con il proxy ha le autorizzazioni errate per eseguire l'integrazione. L'integrazione o l'attivatore API non esiste. L'integrazione delle applicazioni non è attivata per il tuo progetto Google Cloud. Hai configurato l'elemento <ScheduleTime> nel criterio SetIntegrationRequest e il criterio IntegrationCallout ha impostato AsyncExecution su false.
steps.integrationcallout.NullRequestVariable	500	Questo errore si verifica se la variabile di flusso specificata in <Request> è null.
steps.integrationcallout.RequestVariableNotMessageType	500	Questo errore si verifica quando la variabile di flusso specificata dall'elemento Request non è di tipo message.
steps.integrationcallout.RequestVariableNotRequestMessageType	500	Questo errore si verifica quando la variabile di flusso specificata dall'elemento Request non è di tipo Messaggio di richiesta.
messaging.adaptors.http.filter.GoogleTokenGenerationFailure	500	Questo errore può verificarsi a causa di una configurazione errata dell'account di servizio. Ecco alcune possibili cause: L'account di servizio di cui è stato eseguito il deployment con il proxy non esiste nel progetto. L'account di servizio di cui è stato eseguito il deployment con il proxy è disattivato.

Variabili di errore

Ogni volta che si verificano errori di esecuzione in un criterio, Apigee genera messaggi di errore. Puoi visualizzare questi messaggi di errore nella risposta di errore. Spesso i messaggi di errore generati dal sistema potrebbero non essere pertinenti nel contesto del tuo prodotto. Ti consigliamo di personalizzare i messaggi di errore in base al tipo di errore per renderli più significativi.

Per personalizzare i messaggi di errore, puoi utilizzare le regole di errore o il criterio RaiseFault. Per informazioni sulle differenze tra le regole di errore e il criterio RaiseFault, consulta Regole di errore e criterio RaiseFault. Devi verificare la presenza di condizioni utilizzando l'elemento Condition sia nelle regole di errore sia nel criterio RaiseFault. Apigee fornisce variabili di errore univoche per ogni criterio e i valori delle variabili di errore vengono impostati quando un criterio attiva errori di runtime. Utilizzando queste variabili, puoi verificare la presenza di condizioni di errore specifiche e intraprendere le azioni appropriate. Per ulteriori informazioni sul controllo delle condizioni di errore, consulta Condizioni di compilazione.

La tabella seguente descrive le variabili di errore specifiche per questo criterio.

Variabili	Dove	Esempio
fault.name	fault.name può corrispondere a uno dei problemi elencati nella tabella Errori di runtime. Il nome dell'errore è l'ultima parte del codice dell'errore.	fault.name Matches "UnresolvedVariable"
IntegrationCallout.POLICY_NAME.failed	POLICY_NAME è il nome specificato dall'utente del criterio che ha generato l'errore.	IntegrationCallout.integration-callout-1.failed = true

Per ulteriori informazioni sugli errori relativi alle norme, consulta Informazioni importanti sugli errori relativi alle norme.

Argomenti correlati

Se vuoi saperne di più sulla funzionalità Application Integration, consulta la panoramica di Application Integration.