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 présentation conceptuelle, consultez Configurer un proxy avec YAML. Pour obtenir un tutoriel, consultez Créer un proxy d'API à partir d'un modèle YAML.

Conventions

  • Les noms de champs utilisent le format camelCase. Par exemple, schemaVersion, basePath, displayName, faultRules, defaultFaultRule, httpTargetConnection.
  • Le schéma est strict. Les champs inconnus provoquent une erreur lors de l'importation du fichier.
  • Champs obligatoires. Seuls gateway et schemaVersion sont validés lorsqu'un fichier est analysé. Les autres champs marqués Oui dans les tableaux suivants sont requis en pratique pour produire un proxy d'API opérationnel.

Champs courants de premier niveau

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 par l'humain. 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 les 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 fichiers de caractéristiques à composer dans le proxy. Chaque entrée est un chemin d'accès à un fichier de caractéristiques, relatif au répertoire contenant le modèle (par exemple, ./features/spike-arrest.yaml). [] Non
parameters Liste de paramètres qui définissent les valeurs des paramètres des caractéristiques. La valeur default d'une entrée remplace la valeur default du paramètre de caractéristique par la même valeur name. Consultez paramètre. [] Non
endpoints Une liste de points de terminaison qui définissent les chemins d'accès et les routes de base. [] Non
targets Liste de 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 contribuer aux flux, aux points de terminaison et aux cibles du proxy compilé. En plus des champs de premier niveau courants, une caractéristique comporte les champs suivants.

Nom Description Par défaut Obligatoire ?
displayName Nom à afficher lisible par l'humain. N/A Non
uid Identifiant unique qui sépare les règles et les ressources de la fonctionnalité lorsqu'un modèle inclut la fonctionnalité plusieurs fois. Si la fonctionnalité définit un uid, la CLI ajoute le préfixe UID- à chacun de ses noms de règles et de ressources, et met à jour les références à ces noms. Si la fonctionnalité ne définit pas de uid, la CLI utilise les noms tels qu'ils sont écrits. N/A Non
documentation Documentation étendue pour la fonctionnalité. N/A Non
categories Liste de libellés de catégorie de forme libre. [] Non
parameters Liste des paramètres définis par la caractéristique. [] 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-le pour associer les règles d'une fonctionnalité au flux de requête ou de réponse. N/A Non
defaultTarget Une cible de proxy utilisée comme connexion de backend par défaut. N/A Non
endpoints Liste des points de terminaison de 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 Une liste de règles fournies par la fonctionnalité. Si la fonctionnalité définit un uid, la CLI ajoute le préfixe UID- à chaque nom de règle lors de la compilation, par exemple sa1-SA-SpikeArrest. Sinon, la CLI utilise les noms de règles tels qu'ils sont écrits. [] Non
resources Liste des ressources fournies par la fonctionnalité, telles que des fichiers JavaScript ou de propriétés. [] Non

Type de document : procuration

Un proxy est le document entièrement résolu que la CLI produit lorsqu'elle compile un modèle avec ses fonctionnalités. En règle générale, vous ne créez 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 ou 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 caractéristique. Une fonctionnalité déclare ses paramètres, et un modèle peut définir leurs valeurs dans sa propre liste parameters. Lorsque la CLI compile un modèle, elle résout chaque paramètre de fonctionnalité comme suit :

  1. Si la liste parameters du modèle comporte une entrée dont la valeur name correspond et dont la valeur default n'est pas vide, la CLI utilise cette valeur. Si la caractéristique définit un uid, le nom de l'entrée du modèle doit être FEATURE_NAME.UID.PARAMETER_NAME.
  2. Sinon, la CLI utilise la valeur default du paramètre de fonctionnalité.
  3. Si aucune valeur n'est définie, le paramètre est résolu en une chaîne vide. La CLI ne signale pas d'erreur.

Il n'existe pas de flag de ligne de commande permettant de définir les valeurs des paramètres au moment de l'importation. Pour modifier une valeur, modifiez le modèle.

Nom Description Par défaut Obligatoire ?
name Nom du paramètre. Référencé dans la sélection de contenus en tant que {name}. N/A Oui
displayName Nom lisible par l'humain. N/A Non
description Description du paramètre. N/A Non
default Dans une caractéristique, valeur utilisée lorsque le modèle n'en définit pas. Dans un modèle, valeur du paramètre de caractéristique portant le même nom. La CLI ignore une valeur vide. La CLI remplace la valeur résolue par {name} dans les chaînes de la fonctionnalité. N/A Non
examples Liste d'exemples de valeurs. [] Non
maps Mappage 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 compatible avec 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 Une liste de routes qui mappent les requêtes vers des cibles. [] Non

proxyEndpoint

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

Nom Description Par défaut Obligatoire ?
flows Liste de 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 qui 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 la route. N/A Oui
target Nom du point de terminaison cible vers lequel effectuer le routage. N/A Non
condition Condition qui doit être vraie 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 sur la réponse. Request Non
condition Condition qui doit être vraie pour que le flux s'exécute. N/A Non
steps Liste numérotée d'étapes (appels de règles). [] 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.

Le champ mode hérité de flow ne s'applique pas à une règle d'erreur. Étant donné qu'une règle d'erreur s'exécute après l'échec d'une requête, elle ne comporte pas de phase de requête ni de réponse. Ses étapes s'exécutent toujours directement. Si vous définissez mode sur une règle d'erreur, l'outil consigne un avertissement et ignore le champ.

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'une route. 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 habilitations 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 éléments defaultTarget et targets d'une fonctionnalité, ainsi que dans un proxy compilé. Étend la cible avec la gestion des flux et les remplacements de connexion brute.

Nom Description Par défaut Obligatoire ?
flows Liste des flux qui s'exécutent sur la requête ou la réponse cible. [] Non
faultRules Liste des flux utilisés comme règles d'erreur. [] Non
defaultFaultRule Règle de défaillance. N/A Non
httpTargetConnection Représentation brute de l'élément HTTPTargetConnection, pour une configuration avancée. S'il est défini, il 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 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 code XML de la règle à l'aide de la convention ci-dessous. {} Oui

Convention de contenu des règles

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

  • Le dictionnaire content ne comporte qu'une seule clé, qui doit correspondre à la valeur type de la règle.
  • Les attributs d'élément sont placés sous une clé metadata.
  • Le texte de l'élément est placé 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 en tant que valeur.
  • Les éléments enfants sont imbriqués sous leur nom de balise. Les balises répétées deviennent une liste.

Par exemple, cette règle de fonctionnalité :

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 ce fichier XML de stratégie :

<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 Le nom du fichier, par exemple hello-world.js. Si la fonctionnalité définit un uid, la CLI ajoute le préfixe UID- au nom de la ressource lors de la compilation. Sinon, la CLI utilise le nom tel qu'il est écrit. N/A Oui
type Le type de ressource, qui détermine le sous-répertoire dans le bundle, par exemple jsc (JavaScript) ou properties. N/A Oui
content Contenu du fichier brut. N/A Non

Champs non compatibles avec cette version

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

Limites

Le bundle de proxy d'API généré ne doit pas dépasser 10 Mio non compressé ou 256 fichiers.

Étapes suivantes