Règle IntegrationCallout

Cette page s'applique à Apigee et à Apigee hybrid.

icône de la règle

Présentation

La règle IntegrationCallout vous permet d'exécuter une intégration Application Integration dotée d'un déclencheur d'API. Toutefois, avant d'exécuter une intégration, vous devez exécuter la règle SetIntegrationRequest. La règle SetIntegrationRequest crée un objet de requête et le met à la disposition de la règle IntegrationCallout en tant que variable de flux. L'objet de la requête contient les détails d'intégration tels que le nom du déclencheur d'API, l'ID du projet d'intégration, le nom de l'intégration et d'autres détails configurés dans la règle SetIntegrationRequest. La règle IntegrationCallout utilise la variable de flux de l'objet de requête pour exécuter l'intégration. Vous pouvez configurer la règle IntegrationCallout pour enregistrer la réponse d'exécution d'intégration dans une variable de flux.

La règle IntegrationCallout est utile si vous souhaitez exécuter l'intégration au milieu de votre flux de proxy. Au lieu de configurer la règle IntegrationCallout, vous pouvez également exécuter une intégration en spécifiant un point de terminaison d'intégration comme point de terminaison cible. Pour en savoir plus, consultez la section IntegrationEndpoint.

Cette règle est une règle extensible et son utilisation peut avoir des conséquences sur le coût ou l'utilisation, en fonction de votre licence Apigee. Pour en savoir plus sur les types de règles et les implications en termes d'utilisation, consultez la section Types de règles.

<IntegrationCallout>

Spécifie la règle IntegrationCallout.

Valeur par défaut N/A
Obligatoire ? Obligatoire
Type Type complexe
Élément parent N/A
Éléments enfants <DisplayName>
<AsyncExecution>
<Request>
<Response>

Le tableau suivant fournit une description détaillée des éléments enfants de <IntegrationCallout> :

Élément enfant Obligatoire ? Description
<DisplayName> Facultatif Nom personnalisé de la règle.
<AsyncExecution> Facultatif Indique si l'intégration doit s'exécuter en mode synchrone ou asynchrone.
<Request> Obligatoire Variable de flux dont l'objet de requête est créé par la règle SetIntegrationRequest.
<Response> Facultatif Variable de flux permettant d'enregistrer la réponse de l'intégration.

L'élément <IntegrationCallout> utilise la syntaxe suivante :

Syntaxe

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

Exemple

L'exemple suivant illustre la définition de la règle 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.

Référence d'élément enfant

Cette section décrit les éléments enfants de <IntegrationCallout>.

<DisplayName>

Utilisez-le, en plus de l'attribut name, pour appliquer un libellé à la règle dans l'éditeur de proxys de l'interface de gestion en utilisant un nom différent et plus naturel.

L'élément <DisplayName> est commun à toutes les règles.

Valeur par défaut N/A
Obligatoire ? Facultatif. Si vous omettez <DisplayName>, la valeur de l'attribut name de la règle est utilisée.
Type Chaîne
Élément parent <PolicyElement>
Éléments enfants Aucun

L'élément <DisplayName> utilise la syntaxe suivante :

Syntaxe

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

Exemple

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

L'élément <DisplayName> ne comporte aucun attribut ni élément enfant.

<AsyncExecution>

Spécifie le mode d'exécution de l'intégration. Vous pouvez exécuter l'intégration de manière synchrone ou asynchrone.

Si ce champ est défini sur true, l'intégration s'exécute de manière asynchrone. Et s'il est défini sur false, l'intégration s'exécute de manière synchrone.

  • Mode asynchrone : lorsque la requête d'exécution de l'intégration atteint le point de terminaison, le point de terminaison renvoie immédiatement les ID d'exécution de l'intégration, mais commence l'exécution de l'intégration à l'heure spécifiée par l'élément <ScheduleTime>. Si vous n'avez pas défini l'élément <ScheduleTime>, l'intégration est planifiée pour s'exécuter immédiatement. Même si l'intégration est planifiée pour s'exécuter immédiatement, son exécution peut ne démarrer qu'au bout de quelques secondes. Lorsque l'intégration commence à s'exécuter, deux choses se produisent :
    • L'intégration renvoie le code d'état HTTP 200 OK afin que l'appelant puisse continuer le traitement.
    • La règle IntegrationCallout se termine.
    Une fois lancée, la durée maximale de l'intégration est de 50 minutes.
  • Mode synchrone : lorsque la requête d'exécution de l'intégration atteint le point de terminaison, le point de terminaison démarre immédiatement l'exécution de l'intégration et attend la réponse. Le délai maximal pour l'exécution est de 2 minutes. Une fois l'exécution terminée, le point de terminaison renvoie une réponse avec les ID d'exécution et d'autres données de réponse.
Valeur par défaut false
Obligatoire ? Facultatif
Type Booléen
Élément parent <IntegrationCallout>
Éléments enfants Aucun

L'élément <AsyncExecution> utilise la syntaxe suivante :

Syntaxe

<AsyncExecution>BOOLEAN</AsyncExecution>

Exemple

L'exemple suivant définit l'exécution asynchrone sur true :

<AsyncExecution>true</AsyncExecution>

<Request>

Spécifie la variable de flux dont l'objet de requête est créé par la règle SetIntegrationRequest. La règle IntegrationCallout envoie cet objet de requête à Application Integration pour l'exécution de l'intégration.

Valeur par défaut N/A
Obligatoire ? Obligatoire
Type Chaîne
Élément parent <IntegrationCallout>
Éléments enfants Aucun

L'élément <Request> utilise la syntaxe suivante :

Syntaxe

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

Exemple

L'exemple suivant indique que l'objet de la requête est disponible dans la variable de flux my_request_flow_var :

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

Le tableau suivant décrit les attributs de <Request> :

Attribut Obligatoire ? Type Description
clearPayload Facultatif boolean

Indique si l'objet de la requête doit être effacé de la mémoire après l'envoi de la requête pour l'exécution de l'intégration.

  • Si la valeur est true, Apigee efface l'objet de la requête.
  • Si la valeur est false, Apigee n'efface pas l'objet de la requête.

Si vous ne spécifiez pas cet attribut, la valeur par défaut est true et l'objet de la requête est effacé de la mémoire.

<Response>

Spécifie la variable de flux pour enregistrer la réponse de l'intégration.

Si vous ne spécifiez pas cet élément, la règle enregistre la réponse dans la variable de flux integration.response.

Valeur par défaut integration.response
Obligatoire ? Facultatif
Type Chaîne
Élément parent <IntegrationCallout>
Éléments enfants Aucun

La sortie de l'intégration est accessible via integration.response.content ou flow_variable.content. L'élément <Response> utilise la syntaxe suivante :

Syntaxe

<Response>FLOW_VARIABLE_NAME</Response>

Exemple

L'exemple suivant enregistre la réponse de l'exécution de l'intégration dans la variable de flux my_response_flow_var :

<Response>my_response_flow_var</Response>

Codes d'erreur

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.

Articles associés

Pour en savoir plus sur la fonctionnalité Application Integration, consultez la présentation d'Application Integration.