Règle ServiceCallout

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

Consultez la documentation d'Apigee Edge.

icône de la règle

Quoi

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

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

 true Facultatif
async

Cet attribut est obsolète.

 false 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.
Presence 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.
Presence Facultatif.
Type N/A

Attributs

Attribut Description Par défaut Presence
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.

 true 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
Presence 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 NA
Presence 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
Presence 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
Presence Obligatoire
Type N/A

É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 N/A
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

Aucun objet.

Élément enfant HeaderName

Par défaut, lorsqu'une configuration d'authentification est présente, Apigee génère un jeton d'authentification 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 autre en-tête pour contenir 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 N/A
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 une chaîne statique

Dans cet exemple, le jeton d'authentification 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 d'authentification 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, celle-ci 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 N/A
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 N/A
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 N/A
Obligatoire ? Veuillez indiquer au moins une valeur.
Type Chaîne
Élément parent <Scopes>
Éléments enfants Aucune.

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

É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 N/A
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 N/A
Obligatoire ? Obligatoire
Type Chaîne
Élément parent <GoogleIDToken>
Éléments enfants Aucune.

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

É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
Presence Obligatoire
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
Presence 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
Presence 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
Presence 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
Presence Obligatoire
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
Presence Obligatoire
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
Presence 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
Presence 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

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know 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 Fix
steps.servicecallout.ExecutionFailed 500

This error can occur when:

  • The policy is asked to handle input that is malformed or otherwise invalid.
  • The backend target service returns an error status (by default, 4xx or 5xx).
steps.servicecallout.RequestVariableNotMessageType 500 The Request variable specified in the policy is not of type Message. For example, if it's a string or other non-message type, you'll see this error.
steps.servicecallout.RequestVariableNotRequestMessageType 500 The Request variable specified in the policy is not of type RequestMessage. For example, if it's a Response type, you'll see this error.
googletoken.EmptyIDTokenAudience 500

<GoogleIDToken> is enabled but useTargetUrl is set to false and no value is provided to <Audience> either directly or through reference at the time of error.
messaging.adaptors.http.filter.GoogleTokenGenerationFailure 500 This error can happen if the API proxy is configured with the <Authentication> element. Possible causes include:
  • The service account deployed with the proxy:
    • does not exist in your project
    • has been disabled
    • (Apigee hybrid only) has not granted the roles/iam.serviceAccountTokenCreator role on the apigee-runtime service account.
  • The IAMCredentials API is disabled in the source project of the apigee-runtime service account.
  • The <GoogleAccessToken> element is used and one or more invalid scopes are provided. For example, look for typos or empty scopes.

    • For Apigee hybrid only, check the runtime container's log and search for GoogleTokenGenerationFailure to find more detailed error messages that may help with debugging the problem.

    Deployment errors

    These errors can occur when you deploy a proxy containing this policy.

    Error name Cause Fix
    URLMissing The <URL> element inside <HTTPTargetConnection> is missing or empty.
    ConnectionInfoMissing This error happens if the policy does not have an <HTTPTargetConnection> or <LocalTargetConnection> element.
    InvalidTimeoutValue This error happens if the <Timeout> value is negative or zero.
    FAILED_PRECONDITION This error happens if the service account is missing when the proxy is configured with the <Authentication> tag.

    For example: 

    Deployment of \"organizations/foo/apis/apiproxy/revisions/1\" requires a service
          account identity, but one was not provided with the request.
    PERMISSION_DENIED This error happens if there is a permission problem with the service account if the proxy is configured with the <Authentication> tag. Possible causes:
    • The service account does not exist.
    • The service account was not created in the same Google Cloud project as the Apigee organization.
    • The deployer does have iam.serviceAccounts.actAs permission on the service account. For details, see About service account permissions.

    Fault variables

    These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

    Variables Where Example
    fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name = "RequestVariableNotMessageType"
    servicecallout.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. servicecallout.SC-GetUserData.failed = true

    Example error response

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

    Example fault rule

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

    Articles associés