Criterio IntegrationCallout

Questa pagina si applica ad Apigee e Apigee hybrid.

icona delle norme

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.

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

This element has the following attributes that are common to all policies:

Attribute Default Required? Description
name N/A Required

The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.
continueOnError false Optional Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails. See also:
enabled true Optional Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.
async   false Deprecated This attribute is deprecated.

Riferimento all'elemento secondario

Questa sezione descrive gli elementi secondari di <IntegrationCallout>.

<DisplayName>

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, more natural-sounding name.

The <DisplayName> element is common to all policies.

Default Value N/A
Required? Optional. If you omit <DisplayName>, the value of the policy's name attribute is used.
Type String
Parent Element <PolicyElement>
Child Elements None

The <DisplayName> element uses the following syntax:

Syntax

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

Example

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

The <DisplayName> element has no attributes or child elements.

<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

This section describes the fault codes, error messages, and the fault variables set by Apigee when this policy triggers an error. This information is essential if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause
entities.UnresolvedVariable 500 This error occurs if Apigee cannot resolve the integration.project.id or the integration.name variables.
steps.integrationcallout.ExecutionFailed 500

This error can occur if the backend target service returns an HTTP error status such as 4xx or 5xx. The possible causes include:

  • The service account deployed with the proxy has the incorrect permissions to run the integration.
  • The integration or the API trigger does not exist.
  • Application Integration is not enabled for your Google Cloud project.
  • You have configured the <ScheduleTime> element in your SetIntegrationRequest policy and the IntegrationCallout policy has the AsyncExecution set to false.
steps.integrationcallout.NullRequestVariable 500 This error occurs if the flow variable specified in the <Request> is null.
steps.integrationcallout.RequestVariableNotMessageType 500 This error occurs when the flow variable specified by the Request element is not of message type.
steps.integrationcallout.RequestVariableNotRequestMessageType 500 This error occurs when the flow variable specified by the Request element is not of Request message type.
messaging.adaptors.http.filter.GoogleTokenGenerationFailure 500

This error can occur because of an incorrect service account configuration. The possible causes include:

  • The service account deployed with the proxy does not exist in your project.
  • The service account deployed with the proxy is disabled.

Fault variables

Whenever there are execution errors in a policy, Apigee generates error messages. You can view these error messages in the error response. Many a time, system generated error messages might not be relevant in the context of your product. You might want to customize the error messages based on the type of error to make the messages more meaningful.

To customize the error messages, you can use either fault rules or the RaiseFault policy. For information about differences between fault rules and the RaiseFault policy, see FaultRules vs. the RaiseFault policy. You must check for conditions using the Condition element in both the fault rules and the RaiseFault policy. Apigee provides fault variables unique to each policy and the values of the fault variables are set when a policy triggers runtime errors. By using these variables, you can check for specific error conditions and take appropriate actions. For more information about checking error conditions, see Building conditions.

The following table describes the fault variables specific to this policy.

Variables Where Example
fault.name The fault.name can match to any of the faults listed in the Runtime errors table. The fault name is the last part of the fault code. fault.name Matches "UnresolvedVariable"
IntegrationCallout.POLICY_NAME.failed POLICY_NAME is the user-specified name of the policy that threw the fault. IntegrationCallout.integration-callout-1.failed = true
For more information about policy errors, see What you need to know about policy errors.

Argomenti correlati

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