Criterio IntegrationCallout

Questa pagina si applica ad Apigee e Apigee hybrid.

icona delle norme

Panoramica

Il criterio IntegrationCallout consente di eseguire un'integrazione Apigee 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 per il criterio IntegrationCallout come variabile di flusso. L'oggetto richiesta contiene i dettagli di 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 di richiesta per eseguire l'integrazione. Puoi configurare il criterio IntegrationCallout per salvare la risposta di esecuzione dell'integrazione in una variabile di flusso.

Il criterio IntegrationCallout è utile se vuoi eseguire l'integrazione nel bel mezzo del flusso 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.

Questo criterio è un criterio estendibile e il suo utilizzo potrebbe avere implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni di utilizzo, consulta Tipi di criteri.

<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 con l'oggetto di richiesta creato dal criterio SetIntegrationRequest.
<Response> Facoltativo Variabile di flusso per 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/A 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.

Facoltativamente, 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 in caso di errore del criterio. Questo è un comportamento previsto per la maggior parte dei criteri. Imposta su true per continuare l'esecuzione del flusso anche dopo un errore nel criterio. Vedi anche:
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 Deprecato Questo attributo è stato ritirato.

Riferimento elemento secondario

In questa sezione vengono descritti gli elementi secondari di <IntegrationCallout>.

<DisplayName>

Utilizzalo in aggiunta 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/A
Obbligatorio? Facoltativo. Se ometti <DisplayName>, viene utilizzato il valore dell'attributo name del criterio.
Tipo Stringa
Elemento principale <PolicyElement>
Elementi secondari Nessuna esperienza

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à per eseguire l'integrazione. Puoi eseguire l'integrazione in modo sincrono o asincrono.

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

  • Modalità asincrona: quando la richiesta di esecuzione dell'integrazione raggiunge l'endpoint, l'endpoint restituisce immediatamente gli ID esecuzione dell'integrazione, ma avvia l'esecuzione dell'integrazione nel momento specificato dall'elemento <ScheduleTime>. Se non hai impostato l'elemento <ScheduleTime>, l'integrazione è pianificata per l'esecuzione immediata. Anche se l'esecuzione dell'integrazione è pianificata per essere eseguita immediatamente, l'esecuzione potrebbe iniziare dopo alcuni secondi. Quando inizia l'esecuzione dell'integrazione, si verificano due cose:
    • L'integrazione restituisce il codice di stato HTTP 200 OK per consentire al chiamante di 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, l'endpoint 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 false
Obbligatorio? Facoltativo
Tipo Booleano
Elemento principale <IntegrationCallout>
Elementi secondari Nessun valore

L'elemento <AsyncExecution> utilizza la seguente sintassi:

Sintassi

<AsyncExecution>BOOLEAN</AsyncExecution>

Esempio

Nell'esempio seguente viene impostata l'esecuzione asincrona su true:

<AsyncExecution>true</AsyncExecution>

<Request>

Specifica la variabile di flusso con l'oggetto richiesta creato dal criterio SetIntegrationRequest. Il criterio IntegrationCallout invia questo oggetto di richiesta ad Apigee Integration per eseguire l'integrazione.

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

L'elemento <Request> utilizza la seguente sintassi:

Sintassi

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

Esempio

L'esempio seguente specifica che l'oggetto della 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 della richiesta deve essere cancellato dalla memoria dopo aver inviato la richiesta per eseguire l'integrazione.

  • Se impostato su true, Apigee cancella l'oggetto della richiesta.
  • Se è impostato su false, Apigee non cancella l'oggetto della richiesta.

Se non specifichi questo attributo, il valore predefinito è true e l'oggetto della 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 Nessun valore

L'elemento <Response> utilizza la seguente sintassi:

Sintassi

<Response>FLOW_VARIABLE_NAME</Response>

Esempio

L'esempio seguente 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 gli articoli Cosa devi sapere sugli errori relativi alle norme e Gestione degli errori.

Errori di runtime

Questi errori possono verificarsi quando il criterio viene eseguito.

Codice di errore 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 del backend restituisce uno stato di errore HTTP come 4xx o 5xx. Le possibili cause sono:

  • L'account di servizio di cui è stato eseguito il deployment con il proxy dispone delle autorizzazioni errate per eseguire l'integrazione.
  • L'integrazione o il trigger API non esiste.
  • Le integrazioni Apigee non sono abilitate per il tuo progetto Google Cloud.
  • Hai configurato l'elemento <ScheduleTime> nel criterio SetIntegrationRequest e nel criterio IntegrationCallout il valore AsyncExecution è impostato su false.
steps.integrationcallout.NullRequestVariable 500 Questo errore si verifica se la variabile di flusso specificata in <Request> è nulla.
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. Le possibili cause includono:

  • 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 è disabilitato.

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. Molte volte, i messaggi di errore generati dal sistema potrebbero non essere pertinenti nel contesto del prodotto. Per rendere i messaggi più significativi, potresti voler personalizzare i messaggi in base al tipo.

Per personalizzare i messaggi di errore, puoi utilizzare regole di errore o il criterio AlzaFault. Per informazioni sulle differenze tra le regole di errore e il criterio AlzaFault, consulta Confronto tra le regole di errore e il criterio AlzaFault. Devi verificare le condizioni utilizzando l'elemento Condition sia nelle regole di errore sia nel criterio AlzaFault. Apigee fornisce variabili di errore univoche per ciascun criterio e i relativi valori vengono impostati quando un criterio attiva gli errori di runtime. Utilizzando queste variabili, puoi verificare le condizioni di errore specifiche e intraprendere le azioni appropriate. Per saperne di più sul controllo delle condizioni di errore, consulta Condizioni degli edifici.

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

Variabili Dove Esempio
fault.name fault.name può corrispondere a qualsiasi errore elencato nella tabella Errori di runtime. Il nome del guasto è l'ultima parte del codice di 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 dei criteri, consulta la sezione Cosa devi sapere sugli errori dei criteri.

Argomenti correlati

Per saperne di più sulla funzionalità di integrazione di Apigee, consulta Che cos'è Apigee Integration?