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 Apigee 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 ND
Obligatoire ? Obligatoire
Type Type complexe
Élément parent ND
É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 Requis ? 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> Requis 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>

Cet élément possède les attributs suivants qui sont communs à toutes les règles :

Attribut Par défaut Obligatoire ? Description
name ND Obligatoire

Nom interne de la règle. La valeur de l'attribut name peut contenir des lettres, des chiffres, des espaces, des tirets, des traits de soulignement et des points. Cette valeur ne peut pas dépasser 255 caractères.

Vous pouvez également utiliser l'élément <DisplayName> pour ajouter un libellé à la règle dans l'éditeur de proxy de l'interface utilisateur de gestion avec un nom différent, en langage naturel.
continueOnError faux Facultatif Définissez sur false pour afficher une erreur en cas d'échec d'une règle. Il s'agit du comportement attendu pour la plupart des règles. Définissez sur true pour que l'exécution du flux se poursuive même après l'échec d'une règle. Voir aussi :
enabled true Facultatif Définissez sur true pour appliquer la règle. Définissez sur false pour désactiver la règle. La règle ne sera pas appliquée même si elle reste associée à un flux.
async   faux Obsolète Cet attribut est obsolète.

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

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 faux
Obligatoire ? Facultatif
Type Booléen
Élément parent <IntegrationCallout>
Éléments enfants Aucune

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 à Apigee Integration pour l'exécution de l'intégration.

Valeur par défaut ND
Obligatoire ? Obligatoire
Type Chaîne
Élément parent <IntegrationCallout>
Éléments enfants Aucune

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 Requis ? 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
Requis ? Facultatif
Type Chaîne
Élément parent <IntegrationCallout>
Éléments enfants Aucune

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

Cette section décrit les codes d'erreur, les messages d'erreur et les variables d'erreur définies par Apigee lorsque cette règle déclenche une erreur. Ces informations sont essentielles si vous développez des règles de défaillance afin de gérer les pannes. Pour en savoir plus, consultez les pages Ce que vous devez savoir à propos des erreurs liées aux règles et Gérer les pannes.

Erreurs d'exécution

Ces erreurs peuvent se produire lors de l'exécution de la règle.

Code d'erreur État HTTP Cause
entities.UnresolvedVariable 500 Cette erreur se produit si Apigee ne peut pas résoudre les variables integration.project.id ou integration.name.
steps.integrationcallout.ExecutionFailed 500

Cette erreur peut se produire si le service cible du backend renvoie un état d'erreur HTTP, tel que 4xx ou 5xx. Les causes possibles sont les suivantes :

  • Le compte de service déployé avec le proxy ne dispose pas des autorisations nécessaires pour exécuter l'intégration.
  • L'intégration ou le déclencheur d'API n'existe pas.
  • Application Integration n'est pas activé pour votre projet Google Cloud.
  • Vous avez configuré l'élément <ScheduleTime> dans votre règle SetIntegrationRequest et la règle IntegrationCallout doit avoir la valeur AsyncExecution définie sur false.
steps.integrationcallout.NullRequestVariable 500 Cette erreur se produit si la variable de flux spécifiée dans <Request> est nulle.
steps.integrationcallout.RequestVariableNotMessageType 500 Cette erreur se produit lorsque la variable de flux spécifiée par l'élément Request n'est pas de type message.
steps.integrationcallout.RequestVariableNotRequestMessageType 500 Cette erreur se produit lorsque la variable de flux spécifiée par l'élément Request n'est pas de type Message de requête.
messaging.adaptors.http.filter.GoogleTokenGenerationFailure 500

Cette erreur peut se produire en raison d'une configuration de compte de service incorrecte. Les causes possibles sont les suivantes :

  • Le compte de service déployé avec le proxy n'existe pas dans votre projet.
  • Le compte de service déployé avec le proxy est désactivé.

Variables de panne

Chaque fois qu'une règle comporte des erreurs d'exécution, Apigee génère des messages d'erreur. Vous pouvez afficher ces messages d'erreur dans la réponse d'erreur. Souvent, les messages d'erreur générés par le système peuvent ne pas être pertinents dans le contexte de votre produit. Vous pouvez personnaliser les messages d'erreur en fonction du type d'erreur pour rendre les messages plus significatifs.

Pour personnaliser les messages d'erreur, vous pouvez utiliser des règles d'erreur ou la règle RaiseFault. Pour en savoir plus sur les différences entre les règles d'erreur et la règle RaiseFault, consultez la section Règles d'erreur et règle RaiseFault. Vous devez vérifier les conditions à l'aide de l'élément Condition dans les règles d'erreur et dans la règle RaiseFault. Apigee fournit des variables d'erreur propres à chaque règle et les valeurs des variables d'erreur sont définies lorsqu'une règle déclenche des erreurs d'exécution. En utilisant ces variables, vous pouvez vérifier des conditions d'erreur spécifiques et prendre les mesures appropriées. Pour en savoir plus sur la vérification des conditions d'erreur, consultez la page Conditions de création.

Le tableau suivant décrit les variables d'erreur spécifiques à cette règle.

Variables Lieu Exemple
fault.name L'élément fault.name peut correspondre à n'importe quelle erreur affichée dans le tableau Erreurs d'exécution. Le nom d'erreur est la dernière partie du code d'erreur. fault.name Matches "UnresolvedVariable"
IntegrationCallout.POLICY_NAME.failed POLICY_NAME est le nom spécifié par l'utilisateur de la règle qui a provoqué l'erreur. IntegrationCallout.integration-callout-1.failed = true
Pour en savoir plus sur les erreurs de règles, consultez la section Ce que vous devez savoir sur les erreurs liées aux règles.

Articles associés

Pour en savoir plus sur la fonctionnalité d'intégration d'Apigee, consultez la page Qu'est-ce qu'Apigee Integration ?