Règle ExtensionCallout

Vous consultez la documentation Apigee Edge.
Accédez à la documentation Apigee X.

Utilisez la règle ExtensionCallout pour intégrer une extension dans un proxy d'API.

Une extension permet d'accéder à une ressource spécifique externe à Apigee Edge. La ressource peut être un service Google Cloud Platform tel que Cloud Storage ou Cloud Speech-to-Text. Toutefois, la ressource peut être n'importe quelle ressource externe accessible via HTTP ou HTTPS.

Pour obtenir une présentation des extensions, consultez Que sont les extensions ? Pour suivre un tutoriel d'introduction, consultez Tutoriel : Ajouter et utiliser une extension.

Avant d'accéder à une extension à partir de la règle ExtensionCallout, vous devez ajouter, configurer et déployer l'extension à partir d'un package d'extension déjà installé dans votre organisation Apigee Edge.

Exemples

Vous trouverez ci-dessous un exemple de règle à utiliser avec l'extension Cloud Logging :

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="false" enabled="true" name="Logging-Extension">
        <DisplayName>Logging Extension</DisplayName>
        <Connector>cloud-extension-sample</Connector>
        <Action>log</Action>
        <Input>{
                "logName" : "example-log",
                "metadata" : "test-metadata",
                "message" : "This is a test"
        }</Input>
    <Output>cloud-extension-example-log</Output>
</ConnectorCallout>

Consultez le tutoriel sur l'utilisation des extensions pour obtenir un tutoriel complet sur l'utilisation de l'extension Cloud Logging.

Pour obtenir des exemples de toutes les extensions disponibles, consultez Présentation de la documentation de référence sur les extensions.

À propos de la règle ExtensionCallout

Utilisez la règle ExtensionCallout lorsque vous souhaitez utiliser une extension configurée pour accéder à une ressource externe depuis un proxy d'API.

Avant d'utiliser ce règlement, vous devez disposer des éléments suivants :

• Quelques détails sur la ressource externe à laquelle vous souhaitez accéder à partir de cette règle. Ces informations seront spécifiques à la ressource. Par exemple, si la stratégie doit accéder à votre base de données Cloud Firestore, vous devez connaître le nom de la collection et du document que vous souhaitez créer ou auxquels vous souhaitez accéder. Vous utiliserez généralement des informations spécifiques aux ressources pour configurer le traitement des requêtes et des réponses de cette règle.
• Une extension ajoutée, configurée et déployée dans l'environnement où votre proxy d'API sera déployé. En d'autres termes, si vous souhaitez utiliser cette règle pour accéder à un service Google Cloud spécifique, une extension déployée pour ce service doit exister dans votre environnement. Les détails de configuration incluent généralement les informations requises pour limiter l'accès à la ressource, comme un ID de projet ou un nom de compte.

Utiliser la règle ExtensionCallout dans un PostClientFlow

Vous pouvez appeler la règle ExtensionCallout à partir du PostClientFlow d'un proxy d'API. Le PostClientFlow s'exécute une fois la réponse envoyée au client à l'origine de la requête, ce qui garantit que toutes les métriques sont disponibles pour la journalisation. Pour plus de détails sur l'utilisation de PostClientFlow, consultez la documentation de référence sur la configuration du proxy d'API.

Si vous souhaitez utiliser la règle ExtensionCallout pour appeler l'extension Google Cloud Logging à partir d'un PostClientFlow, assurez-vous que le flag features.allowExtensionsInPostClientFlow est défini sur true dans votre organisation.

• Si vous êtes un client Apigee Edge pour le cloud public, l'indicateur features.allowExtensionsInPostClientFlow est défini sur true par défaut.

• Si vous êtes client Apigee Edge pour un cloud privé, utilisez l'API Update organization properties pour définir l'indicateur features.allowExtensionsInPostClientFlow sur true.

Toutes les restrictions concernant l'appel de la règle MessageLogging à partir du PostClientFlow s'appliquent également à la règle ExtensionCallout. Pour en savoir plus, consultez les Remarques sur l'utilisation.

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="false" enabled="true" name="Extension-Callout-1">
    <DisplayName/>
    <Connector/>
    <Action/>
    <Input/>
    <Output/>
</ConnectorCallout>

Attributs <ConnectorCallout>

<ConnectorCallout name="Extension-Callout-1" continueOnError="false" enabled="true" async="false">

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

Action exposée par l'extension que la règle doit appeler.

<Action>action-exposed-by-extension</Action>

Chaque extension expose son propre ensemble d'actions qui permettent d'accéder aux fonctionnalités de la ressource que l'extension représente. Vous pouvez considérer une action comme une fonction que vous appelez avec cette règle, en utilisant le contenu de l'élément <Input> pour spécifier les arguments de la fonction. La réponse de l'action est stockée dans la variable que vous spécifiez avec l'élément <Output>.

Pour obtenir la liste des fonctions de l'extension, consultez la documentation de référence de l'extension que vous appelez à partir de cette règle.

Élément <Connector>

Nom de l'extension configurée à utiliser. Il s'agit du nom à portée d'environnement donné à l'extension lorsqu'elle a été configurée pour le déploiement dans un environnement.

<Connector>name-of-configured-extension</Connector>

Une extension possède des valeurs de configuration qui peuvent différer d'une autre extension déployée basée sur le même package d'extension. Ces valeurs de configuration peuvent représenter des différences importantes dans la fonctionnalité d'exécution entre les extensions configurées à partir du même package. Veillez donc à spécifier l'extension correcte à appeler.

Élément <Input>

JSON contenant le corps de la requête à envoyer à l'extension.

<Input><![CDATA[ JSON-containing-input-values ]]></Input>

Il s'agit essentiellement d'un argument pour l'action que vous spécifiez avec l'élément <Action>. La valeur de l'élément <Input> varie en fonction de l'extension et de l'action que vous appelez. Pour en savoir plus sur les propriétés de chaque action, consultez la documentation sur le package d'extension.

Notez que si de nombreuses valeurs d'éléments <Input> fonctionneront correctement sans être incluses dans une section <![CDATA[]]>, les règles JSON autorisent les valeurs qui ne seront pas analysées en tant que XML. Il est recommandé d'inclure le JSON dans une section CDATA pour éviter les erreurs d'analyse lors de l'exécution.

La valeur de l'élément <Input> est un JSON bien formé dont les propriétés spécifient les valeurs à envoyer à l'action d'extension à appeler. Par exemple, l'action log de l'extension Google Cloud Logging prend des valeurs spécifiant le journal dans lequel écrire (logName), les métadonnées à inclure dans l'entrée (metadata) et le message du journal (data). Voici un exemple :

<Input><![CDATA[{
    "logName" : "example-log",
    "metadata" : {
        "resource": {
            "type": "global",
            "labels": {
                "project_id": "my-test"
            }
        }
    },
    "message" : "This is a test"
}]]></Input>

Utiliser des variables de flux dans le JSON <Input>

Le contenu de <Input> est traité comme un modèle de message. Cela signifie qu'un nom de variable placé entre accolades sera remplacé au moment de l'exécution par la valeur de la variable référencée.

Par exemple, vous pouvez réécrire le bloc <Input> précédent pour utiliser la variable de flux client.ip afin d'obtenir l'adresse IP du client appelant le proxy d'API :

<Input><![CDATA[{
    "logName" : "example-log",
    "metadata" : {
        "resource": {
            "type": "global",
            "labels": {
                "project_id": "my-test"
            }
        }
    },
    "message" : "{client.ip}"
}]]></Input>

Si vous souhaitez qu'une valeur de propriété dans le JSON soit entre guillemets au moment de l'exécution, veillez à utiliser des guillemets dans votre code JSON. Cela est vrai même lorsque vous spécifiez une variable de flux comme valeur de propriété JSON à résoudre au moment de l'exécution.

L'exemple <Input> suivant inclut deux références de variables de flux :

<Input><![CDATA[{
  "logName" : "example-log",
  "metadata" : {my.log.entry.metadata},
  "message" : "{client.ip}"
}]]></Input>

Lors de l'exécution, les valeurs des propriétés JSON sont résolues comme suit :

• Valeur de la propriété logName : littéral de chaîne example-log.
• Valeur de la propriété metadata : valeur de la variable de flux my.log.entry.metadata sans guillemets. Cela peut être utile si la valeur de la variable est elle-même un JSON représentant un objet.
• Valeur de la propriété message : valeur de la variable de flux client.ip avec des guillemets.

Élément <Output>

Nom d'une variable qui stocke la réponse de l'action d'extension.

<Output>variable-name</Output> <!-- The JSON object inside the variable is parsed -->

ou

<Output parsed="false">variable-name</Output>  <!-- The JSON object inside the variable is raw, unparsed -->

Lorsque la réponse est reçue, la valeur de la réponse est placée dans la variable que vous spécifiez ici, à partir de laquelle vous pouvez y accéder depuis un autre code de proxy d'API.

Les objets de réponse d'extension sont au format JSON. La stratégie peut gérer le fichier JSON de deux manières :

• Analysé (par défaut) : la règle analyse l'objet JSON et génère automatiquement des variables avec les données JSON. Par exemple, si le fichier JSON contient "messageId" : 12345; et que vous nommez votre variable de sortie extensionOutput, vous pouvez accéder à cet ID de message dans d'autres règles à l'aide de la variable {extensionOutput.messageId}.
• Non analysé : la variable de sortie contient la réponse JSON brute et non analysée de l'extension. (Si vous le souhaitez, vous pouvez toujours analyser la valeur de la réponse dans une étape distincte à l'aide de la règle JavaScript.)

Attributs <Output>

Variables de flux

Aucune.

Codes d'erreur

Les erreurs renvoyées par les règles Apigee Edge suivent un format cohérent, comme décrit dans la documentation de référence sur les erreurs liées aux règles.

Cette section décrit les messages d'erreur et les variables de flux définis lorsque cette règle déclenche une erreur. Cette information est importante à savoir si vous développez des règles d'erreur pour un proxy. Pour en savoir plus, consultez Ce qu'il faut savoir sur les erreurs de stratégie et Gérer les erreurs.

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.