Règle ServiceCallout

Vous consultez la documentation d'Apigee Edge.
Consultez la documentation Apigee X. en savoir plus

Quoi

La règle d'appel de service vous permet d'appeler un autre service à partir de votre flux de proxy d'API. Vous pouvez effectuer des appels à un service externe (par exemple, un point de terminaison de service RESTful externe) ou à des services internes (par exemple, un proxy d'API dans la même organisation et le même environnement).

• Dans un cas d'utilisation externe, vous appelez une API tierce externe à votre proxy. La réponse de l'API tierce est analysée et insérée dans le message de réponse de votre API afin d'enrichir et de "corréler" les données des utilisateurs finaux de l'application. Vous pouvez également effectuer une requête à l'aide de la règle Service Callout dans le flux de requête, puis transmettre les informations de la réponse au TargetEndpoint du proxy d'API.
• Dans un autre cas d'utilisation, vous appelez un proxy situé dans la même organisation et le même environnement que celui à partir duquel vous appelez. Par exemple, cette fonctionnalité peut vous être utile lorsque vous disposez d'un proxy qui propose une fonctionnalité discrète de bas niveau utilisée par un ou plusieurs autres proxys. Par exemple, un proxy qui expose les opérations de création/lecture/mise à jour/suppression avec un datastore backend peut être le proxy cible pour plusieurs autres proxys qui exposent les données aux clients.

La règle accepte les requêtes via HTTP et HTTPS.

Exemples

<LocalTargetConnection>
    <APIProxy>data-manager</APIProxy>
    <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>

<HTTPTargetConnection>
    <URL>http://example.com/{request.myResourcePath}</URL>
</HTTPTargetConnection>

<ServiceCallout name="ServiceCallout-GeocodingRequest1">
    <DisplayName>Inline request message</DisplayName>
    <Request variable="authenticationRequest">
      <Set>
        <QueryParams>
          <QueryParam name="address">{request.queryparam.postalcode}</QueryParam>
          <QueryParam name="region">{request.queryparam.country}</QueryParam>
          <QueryParam name="sensor">false</QueryParam>
        </QueryParams>
      </Set>
    </Request>
    <Response>GeocodingResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
      <URL>http://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>

<ServiceCallout name="ServiceCallout-GeocodingRequest2">
    <Request clearPayload="false" variable="GeocodingRequest"/>
    <Response>GeocodingResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
      <URL>http://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>

<ServiceCallout async="false" continueOnError="false" enabled="true" name="service-callout">
    <DisplayName>service-callout</DisplayName>
    <Properties/>
    <Request clearPayload="true" variable="myRequest">
        <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    </Request>
    <Response>myResponse</Response>
    <HTTPTargetConnection>
        <LoadBalancer>
            <Algorithm>RoundRobin</Algorithm>
            <Server name="httpbin"/>
            <Server name="yahoo"/>
        </LoadBalancer>
        <Path>/get</Path>
    </HTTPTargetConnection>
</ServiceCallout>

À propos de la règle Service Callout

Il existe de nombreux scénarios dans lesquels vous pouvez utiliser une règle Service Callout dans votre proxy d'API. Par exemple, vous pouvez configurer un proxy d'API pour effectuer des appels vers un service externe afin de fournir des données de géolocalisation, des avis de clients, des éléments du catalogue de vente d'un partenaire, etc.

Un appel est généralement utilisé avec deux autres règles : Assign Message et Extract Variables.

• Requête : Assign Message renseigne le message de requête envoyé au service distant.

• Réponse : Extract Variables analyse la réponse et extrait un contenu spécifique.

La composition des règles Service Callout implique généralement :

1. Règle Assign Message : crée un message de requête, renseigne les en-têtes HTTP, les paramètres de requête, définit le verbe HTTP, etc.
2. Règle Service Callout : référence un message créé par la règle Assign Message, définit une URL cible pour l'appel externe, et définit un nom pour l'objet de réponse renvoyé par le service cible.
   
   Pour améliorer les performances, vous pouvez également mettre en cache les réponses aux appels de service, comme décrit dans ce fil de discussion de la Communauté Apigee : https://community.apigee.com/questions/34110/how-can-i-store-the-results-of-the-servicecallout.html.
3. Règle Extract Variables : définit généralement une expression JSONPath ou XPath qui analyse le message généré par l'appel de service. La règle définit ensuite des variables contenant les valeurs analysées à partir de la réponse de l'appel de service.

Consultez la section Utiliser la composition de règle pour obtenir un exemple complet de proxy d'API utilisant la règle Service Callout ainsi que les règles Assign Message et Extract Variables.

Gestion des erreurs personnalisées

Documentation de référence des éléments

Voici les éléments et les attributs que vous pouvez configurer sur cette règle :

<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1">
    <DisplayName>Custom label used in UI</DisplayName>
    <Request clearPayload="true" variable="myRequest">
        <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
        <Remove>
            <ReasonPhrase/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
         </Remove>
         <Copy>
            <ReasonPhrase/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Copy>
        <Add>
            <Headers/>
            <QueryParams/>
            <FormParams/>
        </Add>
        <Set>
            <Headers/>
            <QueryParams/>
            <FormParams/>
            <Payload/>
            <ReasonPhrase/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Set>
    </Request>
    <Response>calloutResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
        <URL>http://example.com</URL>
        <LoadBalancer/>
        <SSLInfo/>
        <Properties/>
    </HTTPTargetConnection>
    <LocalTargetConnection>
        <APIProxy/>
        <ProxyEndpoint/>
        <Path/>
    </LocalTargetConnection>
</ServiceCallout>

Attributs <ServiceCallout>

<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1">

Le tableau suivant décrit les attributs communs à tous les éléments parents des règles :

Élément <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, en langage naturel.

<DisplayName>Policy Display Name</DisplayName>

Élément <Request>

Spécifie la variable contenant le message de requête envoyé par le proxy d'API à l'autre service. La variable peut être créée par une règle précédente dans le flux, ou vous pouvez la créer directement dans la règle Service Callout.

<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <Remove>
        <ReasonPhrase/>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Remove>
    <Copy>
        <ReasonPhrase/>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Copy>
    <Add>
        <Headers/>
        <QueryParams/>
        <FormParams/>
    </Add>
    <Set>
        <Headers/>
        <QueryParams/>
        <FormParams/>
        <Payload/>
        <ReasonPhrase/>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Set>
</Request>

La syntaxe des tags <Remove> (Supprimer), <Copy> (Copier), <Add> (Ajouter) et <Set> (Définir) est identique à la règle Assign Message.

La règle renvoie une erreur si le message de requête ne peut pas être résolu ou s'il s'agit d'un type de message de requête non valide.

Dans l'exemple le plus simple, vous transmettez une variable contenant le message de requête qui a été précédemment renseigné dans le flux du proxy d'API :

<Request clearPayload="true" variable="myRequest"/>

Vous pouvez également remplir le message de requête envoyé au service externe dans la règle d'appel de service elle-même :

<Request>
  <Set>
    <Headers>
      <Header name="Accept">application/json</Header>
    </Headers>
    <Verb>POST</Verb>
    <Payload contentType="application/json">{"message":"my test message"}</Payload>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</Request>

Attributs

Élément <Request>/<IgnoreUnresolvedVariables>

Lorsqu'elle est définie sur true, la règle ignore toute erreur de variable non résolue dans la requête.

<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</Request> 

Élément <Response>

Incluez cet élément lorsque la logique du proxy API nécessite la réponse de l'appel distant pour un traitement ultérieur.

Lorsque cet élément est présent, il spécifie le nom de la variable qui contiendra le message de réponse reçu du service externe. La réponse de la cible n'est attribuée à la variable que lorsque la réponse a bien été lue par la règle. Si l'appel distant échoue pour une raison quelconque, la règle renvoie une erreur.

Si cet élément est omis, le proxy d'API n'attend pas de réponse. L'exécution du flux du proxy d'API se poursuit avec toutes les étapes de flux suivantes. Bien évidemment, sans élément Response, la réponse de la cible n'est pas disponible pour le traitement par les étapes suivantes, et il n'y a aucun moyen de permettre au flux de proxy de détecter une erreur dans l'appel distant. L'omission de l'élément Response lors de l'utilisation de la règle ServiceCallout sert bien souvent à la journalisation des messages sur un système externe.

 <Response>calloutResponse</Response> 

Élément <Timeout>

Délai en millisecondes pendant lequel la règle d'appel de service attend une réponse de la cible. Vous ne pouvez pas définir cette valeur de manière dynamique lors de l'exécution. Si l'appel de service atteint le délai d'expiration, une réponse HTTP 500 est renvoyée, la règle échoue et le proxy de l'API passe à l'état "Error", comme décrit dans la section Gérer les pannes.

<Timeout>30000</Timeout>

Élément <HTTPTargetConnection>

Fournit des informations sur le transport, telles que les propriétés d'URL, TLS/SSL et HTTP. Consultez la documentation de référence sur la configuration de <TargetEndpoint>.

<HTTPTargetConnection>
    <URL>http://example.com</URL>
    <LoadBalancer/>
    <SSLInfo/>
    <Properties/>
</HTTPTargetConnection>

Élément <HTTPTargetConnection>/<URL>

URL du service appelé :

<HTTPTargetConnection>
    <URL>http://example.com</URL>
</HTTPTargetConnection>

Vous pouvez fournir une partie de l'URL de manière dynamique avec une variable. Toutefois, la partie protocole de l'URL, http:// ci-dessous, ne peut pas être spécifiée par une variable. Dans l'exemple suivant, vous utilisez une variable pour spécifier la valeur d'un paramètre de requête :

<URL>http://example.com/forecastrss?w=${request.header.woeid}</URL>

Vous pouvez également définir une partie du chemin de l'URL avec une variable :

<URL>http://example.com/{request.resourcePath}?w=${request.header.woeid}</URL>

Si vous souhaitez utiliser une variable pour spécifier le domaine et le port de l'URL, utilisez une variable pour le domaine et le port uniquement, et une autre pour toute autre partie de l'URL :

<URL>http://{request.dom_port}/{request.resourcePath}</URL>

Élément <HTTPTargetConnection>/<SSLInfo>

Configuration TLS/SSL au service de backend. Pour obtenir de l'aide sur la configuration de TLS/SSL, consultez les sections Configurer TLS/SSL depuis la périphérie vers le backend (Cloud et cloud privé) et "Configuration du point de terminaison cible TLS/SSL" dans la documentation de référence sur la configuration du proxy d'API.

<HTTPTargetConnection>
    <URL>https://example.com</URL>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <KeyStore>ref://mykeystoreref</KeyStore>  ## Use of a reference is recommended
        <KeyAlias>myKey</KeyAlias>
        <TrustStore>myTruststore</TrustStore>
        <Ciphers/>
        <Protocols/>
    </SSLInfo>
</HTTPTargetConnection>

Propriétés de transport HTTP au service de backend. Pour plus d'informations, consultez la documentation de référence sur les propriétés des points de terminaison.

<HTTPTargetConnection>
    <URL>http://example.com</URL>
    <Properties>
        <Property name="allow.http10">true</Property>
        <Property name="request.retain.headers">
          User-Agent,Referer,Accept-Language
        </Property>
    </Properties>
</HTTPTargetConnection>

Élément <HTTPTargetConnection>/<LoadBalancer>

Appelez un ou plusieurs serveurs cibles et procédez à un équilibrage de charge. Consultez l'exemple Appeler des serveurs cibles dans la section Exemples. Voir également Équilibrage de charge sur les serveurs backend. Consultez également ce post destiné à la communauté, qui explique comment appeler des serveurs cibles à la fois depuis la règle d'appel de service et en utilisant les règles de routage.

<HTTPTargetConnection> <LoadBalancer> <Algorithm>RoundRobin</Algorithm> <Server name="httpbin"/> <Server name="yahoo"/> </LoadBalancer> <Path>/get</Path> </HTTPTargetConnection>

Élément <LocalTargetConnection>

Spécifie un proxy local (c'est-à-dire un proxy dans la même organisation et le même environnement) que la cible des appels de services.

Pour spécifier davantage la cible, utilisez les éléments <APIProxy> et <ProxyEndpoint>, ou l'élément <Path>.

<LocalTargetConnection>
   <APIProxy/>
   <ProxyEndpoint/>
   <Path/>
</LocalTargetConnection>

Élément <LocalTargetConnection>/<APIProxy>

Nom d'un proxy d'API qui est la cible d'un appel local. Le proxy doit appartenir à la même organisation et au même environnement que le proxy effectuant l'appel.

<LocalTargetConnection>
   <APIProxy>data-manager</APIProxy>
   <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>

Outre l'élément <APIProxy>, incluez l'élément <ProxyEndpoint> pour spécifier le nom du point de terminaison du proxy à cibler pour l'appel.

<LocalTargetConnection>
   <APIProxy/>
   <ProxyEndpoint/>
</LocalTargetConnection> 

Élément <LocalTargetConnection>/<ProxyEndpoint>

Nom du point de terminaison du proxy qui doit être la cible des appels. Il s'agit d'un point de terminaison de proxy dans le proxy d'API spécifié avec l'élément <APIProxy>.

<LocalTargetConnection>
   <APIProxy>data-manager</APIProxy>
   <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>

Élément <LocalTargetConnection>/<Path>

Chemin d'accès au point de terminaison ciblé. Le point de terminaison doit faire référence à un proxy de la même organisation et du même environnement que le proxy effectuant l'appel.

Utilisez cette valeur à la place d'une paire <APIProxy>/<ProxyEndpoint> lorsque vous ne connaissez pas le nom du proxy, ou que vous ne pouvez pas compter sur lui. Le chemin peut être une cible fiable.

<LocalTargetConnection>
   <Path>/data-manager</Path>
</LocalTargetConnection>

Schémas

Variables de flux

Les variables de flux permettent un comportement dynamique des règles et des flux lors de l'exécution, en fonction des en-têtes HTTP, du contenu des messages ou du contexte du flux. Les variables de flux prédéfinies suivantes sont disponibles après l'exécution d'une règle d'appel de service. Pour en savoir plus sur les variables de flux, consultez la documentation de référence sur les variables.

Les appels de service possèdent leur propre requête et leur propre réponse, et vous pouvez accéder à ces données via des variables. Comme le message principal utilise les préfixes de variable request.* et response.*, utilisez les préfixes myrequest.* et calloutResponse.* (valeurs par défaut dans la configuration de l'appel de service) pour obtenir des données de message spécifiques à l'appel de service. Le premier exemple du tableau suivant montre comment obtenir des en-têtes HTTP dans l'appel de service.

Erreurs

Cette section décrit les codes d'erreur et les messages d'erreur renvoyés, ainsi que les variables d'erreur définies par Edge lorsque cette stratégie déclenche une erreur. Ces informations sont importantes 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.

Erreurs de déploiement

Ces erreurs peuvent se produire lorsque vous déployez un proxy contenant cette règle.

Variables de panne

Ces variables sont définies lorsqu'une erreur d'exécution se produit. Pour en savoir plus, consultez la section Ce que vous devez savoir sur les erreurs liées aux règles.

Exemple de réponse d'erreur

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.servicecallout.RequestVariableNotMessageType"
      },
      "faultstring":"ServiceCallout[ServiceCalloutGetMockResponse]: 
            request variable data_str value is not of type Message"
   }
}

Exemple de règle de défaillance

<faultrule name="VariableOfNonMsgType"></faultrule><FaultRule name="RequestVariableNotMessageType">
    <Step>
        <Name>AM-RequestVariableNotMessageType</Name>
    </Step>
    <Condition>(fault.name = "RequestVariableNotMessageType")</Condition>
</FaultRule>

Articles associés

• Générer ou modifier des messages : Règle d'attribution des messages
• Extraire des variables : Règle d'extraction de variables
• Variables : Documentation de référence sur les variables
• Configuration TLS/SSL
  • Configuration de TLS de Edge vers le backend (cloud et cloud privé)
  • "Configuration TLS/SSL TargetEndpoint" dans la Documentation de référence sur la configuration du proxy d'API
• Propriétés de transport HTTP : Documentation de référence sur les propriétés du point de terminaison
• Alternative à l'appel de service: HTTPClient écrit en JavaScript, consultez la page Modèle d'objet JavaScript.