Règle ExtensionCallout

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

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 des services Google Cloud Platform tels 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 l'article Qu'est-ce qu'une extension ?. Pour accéder au tutoriel d'introduction, consultez le 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.

Samples

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 suivre 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 à partir d'un proxy d'API.

Avant d'utiliser cette stratégie, vous devez disposer des éléments suivants:

  • Voici quelques informations sur la ressource externe à laquelle vous souhaitez accéder depuis cette stratégie. Ces détails seront spécifiques à la ressource. Par exemple, si la règle accède à votre base de données Cloud Firestore, vous devez connaître la collection et le nom 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 la gestion des requêtes et des réponses de cette stratégie.
  • 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 comptez utiliser 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 restreindre l'accès à la ressource, telles qu'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. PostClientFlow s'exécute après l'envoi de la réponse au client à l'origine de la demande, 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 l'indicateur features.allowExtensionsInPostClientFlow est défini sur true dans votre organisation.

  • Si vous êtes un client Apigee Edge pour Public Cloud, l'option features.allowExtensionsInPostClientFlow est définie sur true par défaut.

  • Si vous êtes un client Apigee Edge pour Private Cloud, utilisez l'API Mettre à jour les propriétés de l'organisation pour définir l'option features.allowExtensionsInPostClientFlow sur true.

Toutes les restrictions concernant l'appel de la règle MessageLogging à partir de 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 :

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.

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.

Présence Facultatif
Type Chaîne

Élément <Action>

Action exposée par l'extension que la stratégie doit appeler.

<Action>action-exposed-by-extension</Action>
Par défaut Aucun
Présence Obligatoire
Type Chaîne

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 que vous appelez avec cette stratégie, 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 à l'échelle de l'environnement donné à l'extension lors de sa configuration pour le déploiement dans un environnement.

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

Par défaut Aucun
Présence Obligatoire
Type Chaîne

Les valeurs de configuration d'une extension 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 au niveau des fonctionnalités d'exécution entre les extensions configurées à partir du même package. Veillez donc à spécifier la bonne extension à appeler.

Élément <Input>

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

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

Par défaut Aucun
Présence Facultatif ou obligatoire, selon l'extension.
Type Chaîne

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'extensions pour en savoir plus sur les propriétés de chaque action.

Bien que de nombreuses valeurs d'éléments <Input> fonctionnent correctement sans être placées dans une section <![CDATA[]]>, les règles JSON autorisent des valeurs qui ne seront pas analysées au format XML. Nous vous recommandons de placer le JSON sous la forme d'une section CDATA pour éviter les erreurs d'analyse lors de l'exécution.

La valeur de l'élément <Input> est un fichier 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 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 le fichier JSON <Input>

Le contenu de <Input> est traité comme un modèle de message. Cela signifie qu'au moment de l'exécution, le nom d'une variable entre accolades sera remplacé 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 fichier JSON soit placée 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 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 variables 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 se résolvent 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 JSON et représente 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 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 -->

Par défaut Aucun
Présence Facultatif ou obligatoire, selon l'extension.
Type Objet ou chaîne analysés, en fonction du paramètre d'attribut parsed.

Lorsque la réponse est reçue, la valeur de la réponse est placée dans la variable que vous spécifiez ici, où vous pouvez y accéder à partir d'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 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 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 de <Output>

Attribut Description Par défaut Présence
analysés Analyse l'objet JSON renvoyé par l'extension, ce qui permet à d'autres règles d'accéder aux données de l'objet JSON en tant que variables. true Facultatif

Variables de flux

Aucune

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.

Nom de l'erreur État HTTP Cause
ExecutionFailed 500 L'extension renvoie une erreur.

Erreurs de déploiement

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

Nom de l'erreur Se produit quand Corriger
InvalidConnectorInstance L'élément <Connector> est vide.
ConnectorInstanceDoesNotExists L'extension spécifiée dans l'élément <Connector> n'existe pas dans l'environnement.
InvalidAction Il manque l'élément <Action> dans la règle ExtensionExtension ou il est défini sur une valeur vide.
AllowExtensionsInPostClientFlow Il est interdit d'avoir une règle ExtensionExtension dans un flux PostClient.