Documentation de référence sur la configuration YAML des proxys d'API

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

Consultez la documentation d' Apigee Edge.

Cette page décrit le format YAML des modèles de fonctionnalités Apigee : les types de documents template, feature et proxy, ainsi que tous leurs champs. Pour une introduction conceptuelle, consultez Configurer un proxy avec YAML. Pour obtenir une procédure détaillée, consultez Créer un proxy d'API à partir d'un modèle YAML.

Conventions

  • Les noms de champ utilisent camelCase. Par exemple, schemaVersion, basePath, displayName, faultRules, defaultFaultRule, httpTargetConnection.
  • Le schéma est strict. Les champs inconnus entraînent une erreur lorsque vous importez le fichier.
  • Champs obligatoires. Seuls gateway et schemaVersion sont validés lors de l'analyse d'un fichier. Les autres champs marqués Oui dans les tableaux suivants sont requis en pratique pour produire un proxy d'API fonctionnel.

Champs de premier niveau courants

Chaque document template, feature et proxy commence par les champs suivants.

Nom Description Par défaut Obligatoire ?
gateway Passerelle cible. doit être apigee N/A Oui
schemaVersion Version du schéma du document. doit être 1.0.0 N/A Oui
name Nom du document. Pour un modèle ou un proxy, il s'agit du nom du proxy d'API écrit dans le bundle. N/A Oui
type Type de document : template, feature ou proxy. N/A Oui
description Description lisible. N/A Non
priority Entier qui contrôle l'ordre dans lequel les caractéristiques sont appliquées lors de la compilation. Les nombres les plus faibles sont appliqués en premier. 100 Non

Type de document : modèle

Un modèle est le point d'entrée que vous importez. Il compose des fonctionnalités et définit les points de terminaison et les routes du proxy. Un modèle ne contient pas de règles ni de ressources. Celles-ci proviennent des fonctionnalités auxquelles il fait référence.

Nom Description Par défaut Obligatoire ?
features Liste des noms de fichiers de caractéristiques à composer dans le proxy. Chaque nom doit correspondre à un fichier du même répertoire que le modèle. [] Non
parameters Liste des valeurs de paramètres qui fournissent des valeurs par défaut aux caractéristiques. [] Non
endpoints Liste des points de terminaison qui définissent les chemins de base et les routes. [] Non
targets Liste des cibles qui définissent les connexions de backend. [] Non

Type de document : fonctionnalité

Une fonctionnalité est une unité de configuration réutilisable que vous incluez dans un modèle. Une fonctionnalité contient des règles et des ressources, et peut ajouter des flux, des points de terminaison et des cibles au proxy compilé. En plus des champs de niveau supérieur communs, une fonctionnalité comporte les champs suivants.

Nom Description Par défaut Obligatoire ?
displayName Nom à afficher lisible par l'humain. N/A Non
uid Identifiant unique utilisé pour définir l'espace de noms des règles et des ressources de la fonctionnalité. Si ce paramètre n'est pas défini, name est utilisé. N/A Non
documentation Documentation étendue pour la fonctionnalité. N/A Non
categories Liste des libellés de catégorie de forme libre. [] Non
parameters Liste des paramètres définis par la fonctionnalité. [] Non
defaultEndpoint Un point de terminaison de proxy dont les flux et la règle d'erreur par défaut sont fusionnés dans chaque point de terminaison du proxy compilé. Utilisez cette option pour associer les règles d'une fonctionnalité au flux de requêtes ou de réponses. N/A Non
defaultTarget Une cible de proxy utilisée comme connexion backend par défaut. N/A Non
endpoints Liste des points de terminaison du proxy à ajouter au proxy. Un point de terminaison portant le même nom qu'un point de terminaison existant le remplace. [] Non
targets Liste des cibles de proxy à ajouter au proxy. Une cible portant le même nom qu'une cible existante la remplace. [] Non
policies Liste des règles fournies par la fonctionnalité. Les noms de règles sont automatiquement préfixés avec le uid (ou name) de la fonctionnalité lors de la compilation. [] Non
resources Liste des ressources fournies par la fonctionnalité, telles que des fichiers JavaScript ou de propriétés. [] Non

Type de document : proxy

Un proxy est le document entièrement résolu que la CLI produit lorsqu'elle compile un modèle avec ses fonctionnalités. Vous ne créez généralement pas ce type directement. Il est décrit ici, car il s'agit de la forme qui devient le bundle de proxy d'API.

Un proxy comporte les mêmes champs qu'une fonctionnalité, sauf qu'il utilise endpoints et targets (et non defaultEndpoint ni defaultTarget) et représente toujours un proxy complet et déployable. Son type est proxy.

Objets imbriqués

paramètre

Un paramètre fournit une valeur à une fonctionnalité. La valeur d'un paramètre correspond à son default.

Nom Description Par défaut Obligatoire ?
name Nom du paramètre. Mentionné dans le contenu de la fonctionnalité en tant que {name}. N/A Oui
displayName Nom lisible. N/A Non
description Description du paramètre. N/A Non
default Valeur par défaut. Remplacé par {name} dans les chaînes de la fonctionnalité. N/A Non
examples Liste d'exemples de valeurs. [] Non
maps Carte des remplacements de valeurs. Si la valeur résolue est une clé dans le mappage, elle est remplacée par la valeur mappée. N/A Non
paths Liste d'expressions JSONPath. Non pris en charge dans cette version : son utilisation entraîne une erreur. N/A Non

endpoint

Utilisé dans la liste endpoints d'un modèle.

Nom Description Par défaut Obligatoire ?
name Nom du point de terminaison. N/A Oui
basePath Chemin de base que les clients utilisent pour appeler le proxy, par exemple /v1/gemini. N/A Non
routes Liste des routes qui mappent les requêtes aux cibles. [] Non

proxyEndpoint

Utilisé dans les defaultEndpoint et endpoints d'une fonctionnalité, ainsi que dans un proxy compilé. Étend le point de terminaison avec la gestion du flux.

Nom Description Par défaut Obligatoire ?
flows Liste des flux. Les flux nommés PreFlow ou PostFlow sont mappés au flux Apigee correspondant. Tout autre nom est placé dans le conteneur de flux génériques. [] Non
postClientFlow Un seul flux s'exécute après l'envoi de la réponse au client. N/A Non
faultRules Liste des flux utilisés comme règles d'erreur. [] Non
defaultFaultRule Une règle d'erreur qui s'exécute lorsqu'aucune autre règle d'erreur ne correspond. N/A Non

route

Nom Description Par défaut Obligatoire ?
name Nom de l'itinéraire. N/A Oui
target Nom du point de terminaison cible vers lequel effectuer le routage. N/A Non
condition Condition qui doit être remplie pour que cette route s'applique. N/A Non

Flow

Nom Description Par défaut Obligatoire ?
name Nom du flux. Utilisez PreFlow ou PostFlow pour les flux de requête/réponse standards. N/A Oui
mode Request ou Response. Détermine si les étapes s'exécutent sur la requête ou la réponse. Request Non
condition Condition qui doit être vraie pour que le flux s'exécute. N/A Non
steps Liste ordonnée d'étapes (appels de stratégie). [] Non

étape

Une étape exécute une règle dans un flux.

Nom Description Par défaut Obligatoire ?
name Nom de la règle à exécuter. Dans une fonctionnalité, utilisez le nom local de la règle. Le compilateur le réécrit en nom avec espace de noms. N/A Oui
condition Condition qui doit être vraie pour que l'étape s'exécute. N/A Non

faultRule

Étend flow avec un champ supplémentaire.

Nom Description Par défaut Obligatoire ?
alwaysEnforce Si la valeur est true, la règle d'erreur par défaut est toujours appliquée. false Non

cible

Utilisé dans la liste targets d'un modèle.

Nom Description Par défaut Obligatoire ?
name Nom de la cible. Référencé par le target d'un itinéraire. N/A Oui
url URL du backend. N/A Non
auth Schéma d'authentification pour un backend Google Cloud, par exemple GoogleAccessToken ou GoogleIDToken. N/A Non
scopes Liste des champs d'application OAuth à demander. S'applique lorsque auth est défini. [] Non
aud Audience du jeton. S'applique lorsque auth est défini. N/A Non

proxyTarget

Utilisé dans les defaultTarget et targets d'une fonctionnalité, ainsi que dans un proxy compilé. Étend target avec la gestion des flux et les remplacements de connexion bruts.

Nom Description Par défaut Obligatoire ?
flows Liste des flux qui s'exécutent sur la requête ou la réponse cibles. [] Non
faultRules Liste des flux utilisés comme règles d'erreur. [] Non
defaultFaultRule Une règle de défaillance. N/A Non
httpTargetConnection Représentation brute de l'élément HTTPTargetConnection pour la configuration avancée. Si elle est définie, elle est prioritaire sur url, auth, scopes et aud. N/A Non
localTargetConnection Représentation brute d'un élément LocalTargetConnection. Si elle est définie, elle est prioritaire sur une connexion HTTP. N/A Non

stratégie

Une règle est définie dans une fonctionnalité. Sa configuration est écrite sous content à l'aide de la convention d'attribut/texte décrite dans Convention de contenu des règles.

Nom Description Par défaut Obligatoire ?
name Nom de la règle. N/A Oui
type Type de règle Apigee, par exemple VerifyAPIKey, SpikeArrest ou Javascript. Doit correspondre à la clé unique de premier niveau dans content. N/A Oui
content Dictionnaire à clé unique dont la clé est égale à type. La valeur imbriquée décrit le fichier XML de la règle à l'aide de la convention ci-dessous. {} Oui

Conventions relatives au contenu des règles

Les règles Apigee sont au format XML. Dans YAML, vous représentez ce XML dans content avec les règles suivantes :

  • Le dictionnaire content ne comporte qu'une seule clé, qui doit correspondre à la type de la règle.
  • Les attributs d'élément sont placés sous une clé metadata.
  • Le texte de l'élément se trouve sous une clé _text. Par exemple, <Foo bar="baz">qux</Foo> devient Foo: {metadata: {bar: "baz"}, _text: "qux"}. Si un élément ne contient que du texte et aucun attribut, vous pouvez écrire le texte directement comme valeur.
  • Les éléments enfants sont imbriqués sous le nom de leur balise. Les tags répétés deviennent une liste.

Par exemple, cette règle relative aux fonctionnalités :

policies:
- name: VA-VerifyAPIKey
  type: VerifyAPIKey
  content:
    VerifyAPIKey:
      metadata:
        name: VA-VerifyAPIKey
        enabled: "true"
        continueOnError: "false"
      DisplayName: VA-VerifyAPIKey
      APIKey:
        metadata:
          ref: request.header.x-api-key

est compilé dans le fichier XML de règle suivant :

<VerifyAPIKey continueOnError="false" enabled="true" name="verify-api-key-VA-VerifyAPIKey">
  <APIKey ref="request.header.x-api-key"></APIKey>
  <DisplayName>VA-VerifyAPIKey</DisplayName>
</VerifyAPIKey>

ressource

Une ressource est un fichier qu'une fonctionnalité ajoute au bundle, comme un fichier JavaScript ou un fichier de propriétés.

Nom Description Par défaut Obligatoire ?
name Nom du fichier, par exemple hello-world.js. Les noms de ressources sont préfixés avec le uid (ou name) de la fonctionnalité lors de la compilation. N/A Oui
type Type de ressource, qui détermine le sous-répertoire du bundle, par exemple jsc (JavaScript) ou properties. N/A Oui
content Contenu brut du fichier. N/A Non

Champs non disponibles dans cette version

  • paths sur un paramètre (JSONPath). Son utilisation entraîne l'échec de la compilation.
  • tests dans n'importe quel document. Le champ est accepté, mais ignoré et n'est pas inclus dans le bundle généré.

Limites

Le groupe de proxys d'API généré ne doit pas dépasser 10 Mio non compressés ni 256 fichiers.

Étapes suivantes