Règle ExtensionCallout

<ph type="x-smartling-placeholder"></ph> Vous consultez la documentation Apigee Edge.
Accédez à la page Documentation sur Apigee X. En savoir plus

Utilisez la règle ExtensionCall 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, il peut s'agir de n'importe quelle ressource externe accessible via HTTP ou HTTPS.

Pour en savoir plus sur les extensions, consultez Que sont les extensions ? Pour accéder à un tutoriel d'introduction, consultez le tutoriel Ajouter et utiliser une extension.

Avant d'accéder à une extension à partir de la stratégie ExtensionAccroche, 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 Utiliser des extensions pour découvrir un tutoriel complet utilisant l'extension Cloud Logging.

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

À propos de la règle ExtensionCall

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

Avant d'utiliser cette règle, vous devez:

• Quelques détails sur la ressource externe à laquelle vous souhaitez accéder à partir de cette stratégie. Ces informations sont spécifiques à la ressource. Par exemple, si la règle 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 utilisez généralement des informations spécifiques à la ressource pour configurer la gestion des requêtes et des réponses de cette stratégie.
• Une extension ajoutée, configurée et déployée à l'environnement dans lequel votre proxy d'API sera déployé. Autrement dit, si vous utilisez cette stratégie pour accéder à un service Google Cloud particulier, 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 le filtrage l'accès à la ressource, comme un ID de projet ou un nom de compte.

Utiliser la règle ExtensionAccroche dans un PostClientFlow

Vous pouvez appeler la règle ExtensionAccroche à partir du PostClientFlow d'un proxy d'API. Le PostClientFlow s'exécute après que la réponse a été envoyée au client demandeur, 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 ExtensionAccroche pour appeler l'extension Google Cloud Logging à partir d'un PostClientFlow, assurez-vous que l'option features.allowExtensionsInPostClientFlow est défini sur true dans votre organisation.

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

• Si vous êtes un client Apigee Edge pour Private Cloud, utilisez la API Update Organization Properties pour définir l'option features.allowExtensionsInPostClientFlow sur true.

Toutes les restrictions sur l'appel de la règle MessageLogging à partir de PostClientFlow s'appliquent également à la règle ExtensionAccroche. Pour en savoir plus, consultez la section 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>

&lt;ConnectorCallout&gt; Attributs

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

&lt;Action&gt; élément

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 donnent accès aux fonctionnalités de la ressource représentée par l'extension. Vous pouvez considérer une action comme une fonction appelée 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 spécifiée 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.

<Connecteur> élément

Nom de l'extension configurée à utiliser. Il s'agit du nom à l'échelle de l'environnement attribué à l'extension lors de sa configuration pour le déploiement dans un environnement.

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

Les valeurs de configuration d'une extension peuvent différer de celles 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 de fonctionnement d'exécution importantes entre les extensions configurées à partir d'un même package. Veillez donc à spécifier l'extension appropriée à appeler.

&lt;Input&gt; élément

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 de 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. Consultez la documentation du package d'extension pour en savoir plus sur les propriétés de chaque action.

Notez que si de nombreuses valeurs d'éléments <Input> fonctionneront correctement sans être incluses dans une section <![CDATA[]]>, les règles du format JSON autorisent les valeurs qui ne seront pas analysées au format XML. Nous vous recommandons de placer le fichier JSON dans une section CDATA pour éviter les erreurs d'analyse d'exécution.

La valeur de l'élément <Input> est un fichier JSON bien formé dont les propriétés spécifient des valeurs à envoyer à l'action de l'extension à appeler. Par exemple, Extension Google Cloud Logging l'action log de l'extension prend des valeurs spécifiant le journal dans lequel écrire (logName) ; métadonnées à inclure avec l'entrée (metadata) et le message de 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 un fichier JSON <Input>

Le contenu de <Input> est traité comme 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 qui appelle 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 code JSON soit placée entre guillemets lors de l'exécution, veillez à les mettre entre guillemets dans votre code JSON. Cela est vrai même lorsque vous spécifiez une variable de flux en tant que valeur de propriété JSON à résoudre au moment de l'exécution.

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

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

Au moment de l'exécution, les valeurs des propriétés JSON seront 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 fermants. Cela peut être utile si la valeur de la variable est elle-même un fichier JSON représentant un objet.
• Valeur de la propriété message : valeur de la variable de flux client.ip avec des guillemets ouvrants.

&lt;Output&gt; élément

Nom d'une variable qui stocke la réponse de l'action de l'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, d'où vous pouvez y accéder à partir d'un autre code proxy d'API.

Les objets de réponse de l'extension sont au format JSON. Deux options s'offrent à vous pour gérer le fichier JSON:

• Analysé (par défaut): la stratégie 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 dans d'autres règles à l'aide de la variable {extensionOutput.messageId}.
• Non analysée: la variable de sortie contient la réponse JSON brute 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 stratégie JavaScript.

&lt;Output&gt; Attributs

Variables de flux

Aucun

Codes d'erreur

Les erreurs renvoyées par les stratégies Apigee Edge suivent un format cohérent, comme décrit dans la documentation de référence sur les erreurs de stratégie.

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.