Règle ServiceCallout

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

Consultez la documentation d'Apigee Edge.

icône de la règle

Événement

La règle ServiceCallout vous permet d'appeler un autre service à partir du flux proxy de votre 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).

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.

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

Appel local à un proxy interne

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

Cet exemple crée un appel vers un proxy d'API local (c'est-à-dire dans la même organisation et le même environnement) appelé data-manager, en spécifiant son point de terminaison de proxy dont le nom est default.

URL en tant que variable

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

Cet exemple utilise une variable dans l'URL pour renseigner l'URL de la cible de manière dynamique. La partie protocole de l'URL, http://http://, ne peut pas être spécifiée par une variable. De plus, vous devez utiliser des variables distinctes pour la partie domaine de l'URL et pour le reste de l'URL.

Requête de géocodage/définition Google

<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>https://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>

Au lieu d'utiliser une règle telle que la règle AssignMessage pour créer l'objet de la requête, vous pouvez la définir directement dans la règle ServiceCallout. Dans cet exemple, la règle ServiceCallout définit les valeurs de trois paramètres de requête transmis au service externe. Vous pouvez créer un message de requête complet dans la règle ServiceCalling qui spécifie une charge utile, un type d'encodage tel que application/xml, des en-têtes, des paramètres de formulaire, etc.

Voici un autre exemple dans lequel la requête est créée avant d'atteindre la règle ServiceCallout.

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

Le contenu du message de requête est extrait d'une variable appelée GeocodingRequest (qui peut être renseignée, par exemple, par une règle AssignMessage). Le message de réponse est attribué à la variable appelée GeocodingResponse, où il peut être analysé par une règle ExtractVariables ou par un code personnalisé écrit en JavaScript ou Java. La règle attend la réponse de l'API Google Geocoding pendant 30 secondes avant d'expirer.

Appel de serveurs cibles

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

Cette règle utilise l'attribut LoadBalancer pour appeler les serveurs cibles et effectuer sur eux un équilibrage de charge. Dans cet exemple, la charge est répartie sur deux serveurs cibles nommés httpbin et yahoo. Pour en savoir plus sur la configuration des serveurs cibles pour votre proxy et la configuration de l'équilibrage de charge, consultez la section Équilibrage de charge sur les serveurs backend.

À propos de la règle ServiceCallout

Il existe de nombreux scénarios dans lesquels vous pouvez utiliser une règle ServiceCallout 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 : AssignMessage et ExtractVariables.

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

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

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

  1. Règle AssignMessage : 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 AssignMessage, 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 de ServiceCallout, comme décrit dans la section Comment puis-je conserver les résultats de la règle ServiceCallout dans le cache ? Et le récupérer ultérieurement ?

  3. Règle ExtractVariables : définit généralement une expression JSONPath ou XPath qui analyse le message généré par ServiceCallout. La règle définit ensuite des variables contenant les valeurs analysées à partir de la réponse de ServiceCallout.

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>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
         </Remove>
         <Copy>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Copy>
        <Add>
            <Headers/>
            <QueryParams/>
            <FormParams/>
        </Add>
        <Set>
            <Headers/>
            <QueryParams/>
            <FormParams/>
            <Payload/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Set>
    </Request>
    <Response>calloutResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
        <URL>http://example.com</URL>
        <LoadBalancer/>
        <SSLInfo/>
        <Properties/>
        <Authentication>
          <HeaderName ref="{variable}">STRING</HeaderName>
          <GoogleAccessToken>
            <Scopes>
              <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
            </Scopes>
            <LifetimeInSeconds ref="{variable}">3600</LifetimeInSeconds>
          </GoogleAccessToken>
        </Authentication>
        <Authentication>
          <HeaderName ref="{variable}">STRING</HeaderName>
          <GoogleIDToken>
            <Audience ref="{variable}" useTargetUrl="BOOLEAN">{hostname}</Audience>
            <IncludeEmail ref="{variable}">true</IncludeEmail>
          </GoogleIDToken>
        </Authentication>
    </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 :

Attribut Description Par défaut Présence
name

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, en utilisant un nom différent, en langage naturel.

 N/A Obligatoire
continueOnError

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 également :

 faux Facultatif
enabled

Définissez sur true pour appliquer la règle.

Définissez sur false pour désactiver la règle. La stratégie ne sera pas appliquée, même si elle reste associée à un flux.

 vrai Facultatif
async

Cet attribut est obsolète.

 faux Obsolète

É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>
Par défaut

N/A

Si vous omettez cet élément, la valeur de l'attribut name de la règle est utilisée.
Présence Facultatif
Type Chaîne

É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 ServiceCallout.

<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <Remove>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Remove>
    <Copy>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Copy>
    <Add>
        <Headers/>
        <QueryParams/>
        <FormParams/>
    </Add>
    <Set>
        <Headers/>
        <QueryParams/>
        <FormParams/>
        <Payload/>
        <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 AssignMessage.

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 ServiceCallout 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>
Par défaut Si vous omettez l'élément Request (Requête) ou l'un de ses attributs, Apigee attribue les valeurs par défaut suivantes :

<Request clearPayload="true" variable="servicecallout.request"/>

Examinons ce que signifient ces valeurs par défaut. Tout d'abord, clearPayload=true signifie qu'un nouvel objet de requête est créé à chaque exécution de la règle ServiceCallout. Cela signifie que la requête et le chemin de l'URI de la requête ne sont jamais réutilisés. Ensuite, le nom de variable par défaut, servicecallout.request, est un nom réservé attribué à la requête si vous ne fournissez pas de nom.

Il est important de connaître ce nom par défaut si vous utilisez le masquage de données. Si vous omettez le nom de la variable, vous devez ajouter servicecallout.request à votre configuration de masque. Par exemple, si vous souhaitez masquer l'en-tête "Autorisation" afin qu'il n'apparaisse pas dans les sessions Debug, vous devez ajouter le code suivant à votre configuration de masquage pour capturer le nom par défaut :

servicecallout.request.header.Authorization.
Présence Facultatif.
Type N/A

Attributs

Attribut Description Par défaut Présence
variable

Nom de la variable qui contiendra le message de requête.

 servicecallout.request Facultatif
clearPayload

Si la valeur est true, la variable contenant le message de requête est effacée après avoir envoyé la requête à la cible HTTP afin de libérer la mémoire utilisée par le message de la requête.

Définissez l'option clearPayload sur "false" uniquement si le message de requête est requis après l'exécution de ServiceCallout.

 vrai Facultatif

É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>
Par défaut false
Présence Facultatif
Type Booléen

É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>
Par défaut N/A
Présence Facultatif
Type Chaîne

Élément <Timeout>

Délai en millisecondes pendant lequel la règle ServiceCallout 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 ServiceCallout 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>
Par défaut 55 000 millisecondes (55 secondes), le délai avant expiration HTTP par défaut pour Apigee
Présence Facultatif
Type Entier

É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>
Par défaut N/A
Présence Requis
Type Non disponible

Élément <HTTPTargetConnection>/<Authentication>

Génère des jetons Google OAuth 2.0 ou OpenID Connect émis par Google pour effectuer des appels authentifiés aux services Google et aux services personnalisés exécutés sur certains produits Google Cloud, comme Cloud Functions et Cloud Run. L'utilisation de cet élément nécessite de suivre les étapes de configuration et de déploiement décrites dans la section Utiliser l'authentification Google. Avec une configuration appropriée, la règle crée un jeton d'authentification et l'ajoute à la demande de service.

Les éléments enfants, GoogleAccessToken et GoogleIDToken, vous permettent de configurer la règle pour générer des jetons Google OAuth ou OpenID Connect. Vous devez choisir l'un de ces éléments enfants en fonction du type de service que vous souhaitez appeler.

La règle ServiceCallout n'accepte que l'appel de services HTTP.

Par défaut Non disponible
Obligatoire ? Facultatif.
Type Type complexe
Élément parent <HTTPTargetConnection>
Éléments enfants <HeaderName>
<GoogleAccessToken>
<GoogleIDToken>

L'élément Authentication utilise la syntaxe suivante :

Syntaxe

<ServiceCallout>
...
  <HTTPTargetConnection>
    <Authentication>
      <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName>
      <GoogleAccessToken>
        <Scopes>
          <Scope>SCOPE</Scope>
          ...
        </Scopes>
        <!-- NOTE: The default value for LifetimeInSeconds is 3600. Change the default only
        if you want to limit the risk of leaked access tokens or improve performance. -->
        <LifetimeInSeconds ref="{variable}">INTEGER</LifetimeInSeconds>
      </GoogleAccessToken>

    --OR--
      <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName>
      <GoogleIDToken>
        <Audience ref="{variable}" useTargetUrl="BOOLEAN">STRING</Audience>
        <IncludeEmail ref="{variable}">BOOLEAN</IncludeEmail>
      </GoogleIDToken>
    </Authentication>
  </HTTPTargetConnection>
</ServiceCallout>

Utiliser GoogleAccessToken

L'exemple suivant montre l'élément GoogleAccessToken :

<Authentication>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

Utiliser GoogleIDToken

L'exemple suivant montre l'élément GoogleIDToken :

<Authentication>
  <GoogleIDToken>
      <Audience>https://httpserver0-bar.run.app</Audience>
      <IncludeEmail>false</IncludeEmail>
  </GoogleIDToken>
</Authentication>

Utiliser HeaderName

L'exemple suivant montre l'élément HeaderName :

  <Authentication>
    <HeaderName>X-Serverless-Authorization</HeaderName>
    <GoogleAccessToken>
      <Scopes>
        <Scope>"https://www.googleapis.com/auth/cloud-platform"</Scope>
      </Scopes>
    </GoogleAccessToken>
  </Authentication>

Utiliser LifetimeInSeconds

L'exemple suivant montre l'élément HeaderName :

  <Authentication>
    <GoogleAccessToken>
      <Scopes>
        <Scope>"https://www.googleapis.com/auth/cloud-platform"</Scope>
      </Scopes>
      <LifetimeInSeconds ref="variable">3600</LifetimeInSeconds>
    </GoogleAccessToken>
  </Authentication>

Attributs

None.

Élément enfant HeaderName

Par défaut, lorsqu'une configuration d'authentification est présente, Apigee génère un jeton de support et l'injecte dans l'en-tête Authorization du message envoyé au système cible. L'élément HeaderName vous permet de spécifier le nom d'un en-tête différent qui contient ce jeton de support. Cette fonctionnalité est particulièrement utile lorsque la cible est un service Cloud Run qui utilise l'en-tête X-Serverless-Authorization. L'en-tête Authorization, s'il est présent, est conservé tel quel et est également envoyé dans la requête.

Par défaut Non disponible
Obligatoire ? Non
Type Chaîne
Élément parent <Authentication>
Éléments enfants Aucune

L'élément HeaderName utilise la syntaxe suivante :

Syntaxe

<ServiceCallout>
...
  <Authentication>
    <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName>
    <GoogleAccessToken>
      ...
    </GoogleAccessToken>
  </Authentication>
  ...
</ServiceCallout>

Avec chaîne statique

Dans cet exemple, le jeton de support généré est ajouté par défaut à un en-tête nommé X-Serverless-Authorization qui est envoyé au système cible. L'en-tête Authorization, s'il est présent, est conservé tel quel et est également envoyé dans la requête.

<Authentication>
  <HeaderName>X-Serverless-Authorization</HeaderName>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

Avec une référence de variable

Dans cet exemple, le jeton de support généré est ajouté par défaut à un en-tête nommé X-Serverless-Authorization qui est envoyé au système cible. Si my-variable a une valeur, cette valeur est utilisée à la place de la chaîne par défaut. L'en-tête Authorization, s'il est présent, est conservé tel quel et est également envoyé dans la requête.

<Authentication>
  <HeaderName ref='my-variable'>X-Serverless-Authorization</HeaderName>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

Élément enfant GoogleAccessToken

Génère des jetons Google OAuth 2.0 pour effectuer des appels authentifiés aux services Google. Les jetons Google OAuth peuvent être utilisés pour appeler de nombreux types de services Google, tels que Cloud Logging et Secret Manager.

Par défaut Non disponible
Obligatoire ? L'élément enfant GoogleAccessToken ou GoogleIDToken doit être présent.
Type Chaîne
Élément parent <Authentication>
Éléments enfants <Scopes>
<LifetimeInSeconds>

L'élément GoogleAccessToken utilise la syntaxe suivante :

Syntaxe

<ServiceCallout>
...
  <Authentication>
    <GoogleAccessToken>
      <Scopes>
        <Scope>SCOPE_1</Scope>
        ...
      </Scopes>
      <!-- NOTE: The default value for LifetimeInSeconds is 3600. We do not recommend changing
      the default unless you want to limit the risk of leaked access tokens or improve performance. -->
      <LifetimeInSeconds ref="FLOW_VARIABLE">INTEGER</LifetimeInSeconds>
    </GoogleAccessToken>
  </Authentication>
  ...
</ServiceCallout>

Exemple 1

L'exemple suivant montre l'élément GoogleAccessToken :

<Authentication>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

Exemple 2

L'exemple suivant montre comment se connecter au gestionnaire de secrets pour récupérer un secret à l'aide de la règle ServiceCallout. 

<ServiceCallout name="ServiceCallout-sm">
  <Response>SecretManagerResponse</Response>
  <Timeout>30000</Timeout>
  <HTTPTargetConnection>
    <Authentication>
      <GoogleAccessToken>
        <Scopes>
          <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
        </Scopes>
      </GoogleAccessToken>
    </Authentication>
    <URL>
      https://secretmanager.googleapis.com/v1/projects/project-id/secrets/secret-id
    </URL>
  </HTTPTargetConnection>
</ServiceCallout>

Exemple 3

L'exemple suivant montre comment appeler Cloud Run à l'aide de la règle ServiceCallout. 

<ServiceCallout name="ServiceCallout-CloudRun">
  <Response>CloudRunResponse</Response>
  <Timeout>30000</Timeout>
  <HTTPTargetConnection>
    <Authentication>
      <GoogleIDToken>
        <Audience>https://cloudrun-hostname.a.run.app/test</Audience>
      </GoogleIDToken>
    </Authentication>
    <URL>https://cloudrun-hostname.a.run.app/test</URL>
  </HTTPTargetConnection>
</ServiceCallout>

Élément enfant Scopes

Identifie les champs d'application à inclure dans le jeton d'accès OAuth 2.0. Pour en savoir plus, consultez la section Champs d'application OAuth 2.0 pour les API Google. Vous pouvez ajouter un ou plusieurs éléments enfants <Scope> sous cet élément.

Par défaut Non disponible
Obligatoire ? Obligatoire
Type Chaîne
Élément parent <GoogleAccessToken>
Éléments enfants <Scope>

Élément enfant Scope

Spécifie un champ d'application d'API Google valide. Pour en savoir plus, consultez la section Champs d'application OAuth 2.0 pour les API Google.

Par défaut Non disponible
Obligatoire ? Veuillez indiquer au moins une valeur.
Type Chaîne
Élément parent <Scopes>
Éléments enfants None.

Élément enfant LifetimeInSeconds

Spécifie la durée de vie du jeton d'accès en secondes.

Par défaut 3600
Obligatoire ? Facultatif
Type Entier
Élément parent <GoogleAccessToken>
Éléments enfants None.

Élément enfant GoogleIDToken

Génère des jetons OpenID Connect émis par Google pour effectuer des appels authentifiés aux services Google.

Par défaut Non disponible
Obligatoire ? L'élément enfant GoogleAccessToken ou GoogleIDToken doit être présent.
Type Chaîne
Élément parent <Authentication>
Éléments enfants <Audience>
<IncludeEmail>

L'élément GoogleIDToken utilise la syntaxe suivante :

Syntaxe

<ServiceCallout>
...
  <Authentication>
    <GoogleIDToken>
        <Audience ref="{variable}" useTargetUrl="BOOLEAN">STRING</Audience>
        <IncludeEmail ref="{variable}">BOOLEAN</IncludeEmail>
    </GoogleIDToken>
  </Authentication>
</ServiceCallout>

Exemple 1

L'exemple suivant montre l'élément GoogleIDToken :

<Authentication>
  <GoogleIDToken>
      <Audience>https://httpserver0-bar.run.app</Audience>
      <IncludeEmail>true</IncludeEmail>
  </GoogleIDToken>
</Authentication>

Élément enfant Audience

Audience du jeton d'authentification généré, comme l'API ou le compte à laquelle ou auquel le jeton accorde l'accès.

Si la valeur de Audience est vide ou si la variable ref ne correspond pas à une valeur valide et que useTargetUrl est true, l'URL de la cible (sans les paramètres de requête) est utilisée comme audience. La valeur par défaut de useTargetUrl est false. 

<Audience>explicit-audience-value-here</Audience>

or:

<Audience ref='variable-name-here'/>

or:

<Audience ref='variable-name-here' useTargetUrl='true'/>

or:

<Audience useTargetUrl='true'/>
Par défaut Non disponible
Obligatoire ? Obligatoire
Type Chaîne
Élément parent <GoogleIDToken>
Éléments enfants None.

Élément enfant IncludeEmail

S'il est défini sur true, le jeton d'authentification généré contient les revendications du compte de service email et email_verified.

Par défaut faux
Obligatoire ? Facultatif
Type Booléen
Élément parent <GoogleIDToken>
Éléments enfants None.

É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>
Par défaut N/A
Présence Requis
Type Chaîne

Élément <HTTPTargetConnection>/<SSLInfo>

Configuration TLS/SSL au service de backend. Pour obtenir de l'aide sur la configuration TLS/SSL, reportez-vous aux sections Options de configuration de TLS et "Configuration de TLS/SSL TargetEndpoint" dans 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>
Par défaut N/A
Présence Facultatif
Type N/A

Élément <HTTPTargetConnection>/<Properties>

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>
Par défaut N/A
Présence Facultatif
Type N/A

É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 Appel point de terminaison cible/serveur, qui explique comment appeler des serveurs cibles à la fois depuis la règle ServiceCallout et en utilisant les règles de routage.

<HTTPTargetConnection> <LoadBalancer> <Algorithm>RoundRobin</Algorithm> <Server name="httpbin"/> <Server name="yahoo"/> </LoadBalancer> <Path>/get</Path> </HTTPTargetConnection>
Par défaut N/A
Présence Facultatif
Type N/A

É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>
Par défaut N/A
Présence Requis
Type N/A

É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>
Par défaut N/A
Présence Requis
Type Chaîne

É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>
Par défaut N/A
Présence Facultatif
Type N/A

É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>
Par défaut N/A
Présence Facultatif
Type N/A

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 ServiceCallout. Pour en savoir plus sur les variables de flux, consultez la documentation de référence sur les variables de flux.

Les ServiceCallouts 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 ServiceCallout.

Variable Description

Vous trouverez ci-dessous un exemple d'obtention d'en-têtes de requête et de réponse ServiceCallout, semblable à la manière dont vous pouvez obtenir des en-têtes à partir de la requête et de la réponse principale.

calloutResponse.header.HeaderName

myRequest.header.HeaderName

où calloutResponse est le nom de variable pour la réponse dans l'appel de service et myRequest est le nom de variable pour la requête. Exemple :

calloutResponse.header.Content-Length

renvoie l'en-tête "Content-Length" (longueur de contenu) de la réponse de ServiceCallout.

Champ d'application : à partir du transfert de ServiceCallout
Type : chaîne
Autorisation : lecture/écriture

En-tête de message dans la demande ou la réponse de ServiceCallout. Par exemple, si la cible du proxy d'API est http://example.com et que la cible de ServiceCallout est http://mocktarget.apigee.net, ces variables sont les en-têtes de l'appel à http://mocktarget.apigee.net.
servicecallout.requesturi

Champ d'application : à partir du transfert de requête de ServiceCallout
Type : chaîne
Autorisation : lecture/écriture

URI TargetEndpoint d'une règle ServiceCallout. L'URI correspond à l'URL TargetEndpoint sans protocole ni spécification de domaine.
servicecallout.{policy-name}.target.url

Champ d'application : à partir du transfert de requête de ServiceCallout
Type : chaîne
Autorisation : lecture/écriture

URL cible d'un ServiceCallout.

calloutResponse.content

où calloutResponse est le nom de la variable <Response> dans la configuration de ServiceCallout.

Champ d'application : à partir du transfert de réponse de ServiceCallout
Type : chaîne
Autorisation : lecture/écriture

Corps de la réponse de ServiceCallout.
servicecallout.{policy-name}.expectedcn

Champ d'application : à partir du transfert de requête de ServiceCallout
Type : chaîne
Autorisation : lecture/écriture

Nom commun attendu du TargetEndpoint, tel qu'il est mentionné dans une règle ServiceCallout. Cela n'a de sens que lorsque le TargetEndpoint fait référence à un point de terminaison TLS/SSL.
servicecallout.{policy-name}.failed

Champ d'application : à partir du transfert de réponse de ServiceCalloute
Type : booléen
Autorisation : lecture/écriture

Booléen indiquant si la règle a réussi, "false" ou si elle a échoué, 'true".

Erreurs

Cette section décrit les codes d'erreur et les messages d'erreur renvoyés et les variables d'erreur définies par Apigee lorsque cette règle 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.

Code d'erreur État HTTP Cause Corriger
steps.servicecallout.ExecutionFailed 500

Cette erreur peut se produire dans les cas suivants :

  • La règle doit traiter une entrée dont le format est incorrect ou non valide.
  • Le service cible du backend renvoie un état d'erreur (par défaut, 4xx ou 5xx).
steps.servicecallout.RequestVariableNotMessageType 500 La variable Request spécifiée dans la règle n'est pas du type Message. Par exemple, s'il s'agit d'une chaîne ou d'un type autre qu'un message, cette erreur s'affiche.
steps.servicecallout.RequestVariableNotRequestMessageType 500 La variable Request spécifiée dans la règle n'est pas du type RequestMessage. Par exemple, s'il s'agit d'un type de réponse, cette erreur s'affiche.
googletoken.EmptyIDTokenAudience 500

<GoogleIDToken> est activé, mais useTargetUrl est défini sur "false" et aucune valeur n'est fournie à <Audience> directement ou via une référence au moment de l'erreur.
messaging.adaptors.http.filter.GoogleTokenGenerationFailure 500 Cette erreur peut se produire si le proxy d'API est configuré avec l'élément <Authentication>. Les causes possibles sont les suivantes :
  • Le compte de service déployé avec le proxy :
    • n'existe pas dans votre projet
    • a été désactivé
    • (Apigee hybrid uniquement) n'a pas accordé le rôle roles/iam.serviceAccountTokenCreator au compte de service apigee-runtime.
  • L'API IAMCredentials est désactivée dans le projet source du compte de service apigee-runtime.
  • L'élément <GoogleAccessToken> est utilisé et un ou plusieurs champs d'application non valides ont été fournis. Par exemple, recherchez des fautes de frappe ou les champs d'application vides.

    • Pour Apigee hybrid uniquement, consultez le journal du conteneur d'exécution et recherchez GoogleTokenGenerationFailure pour trouver des messages d'erreur plus détaillés susceptibles de faciliter la résolution du problème.

    Erreurs de déploiement

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

    Nom de l'erreur Cause Corriger
    URLMissing L'élément <URL> dans <HTTPTargetConnection> est manquant ou vide.
    ConnectionInfoMissing Cette erreur se produit si la règle ne comporte pas d'élément <HTTPTargetConnection> ou <LocalTargetConnection>.
    InvalidTimeoutValue Cette erreur se produit si la valeur <Timeout> est négative ou égale à zéro.
    FAILED_PRECONDITION Cette erreur se produit si le compte de service est manquant lorsque le proxy est configuré avec la balise <Authentication>.

    Exemple : 

    Deployment of \"organizations/foo/apis/apiproxy/revisions/1\" requires a service
          account identity, but one was not provided with the request.
    PERMISSION_DENIED Cette erreur se produit en cas de problème d'autorisation avec le compte de service si le proxy est configuré avec le tag <Authentication>. Causes possibles :
    • Le compte de service n'existe pas.
    • Le compte de service n'a pas été créé dans le même projet Google Cloud que l'organisation Apigee.
    • Le déployeur dispose de l'autorisation iam.serviceAccounts.actAs sur le compte de service. Pour plus d'informations, voir Autorisations de compte de service.

    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.

    Variables Lieu Exemple
    fault.name="fault_name" fault_name est le nom de l'erreur, tel qu'indiqué dans le tableau Erreurs d'exécution ci-dessus. Le nom d'erreur est la dernière partie du code d'erreur. fault.name = "RequestVariableNotMessageType"
    servicecallout.policy_name.failed policy_name est le nom spécifié par l'utilisateur de la règle qui a provoqué l'erreur. servicecallout.SC-GetUserData.failed = true

    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="RequestVariableNotMessageType">
    <Step>
        <Name>AM-RequestVariableNotMessageType</Name>
    </Step>
    <Condition>(fault.name = "RequestVariableNotMessageType")</Condition>
</FaultRule>

    Articles associés