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
gatewayetschemaVersionsont 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 :
- Si la liste
parametersdu modèle comporte une entrée dont la valeurnamecorrespond et dont la valeurdefaultn'est pas vide, la CLI utilise cette valeur. Si la caractéristique définit unuid, le nom de l'entrée du modèle doit êtreFEATURE_NAME.UID.PARAMETER_NAME. - Sinon, la CLI utilise la valeur
defaultdu paramètre de fonctionnalité. - 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
contentne comporte qu'une seule clé, qui doit correspondre à la valeurtypede 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>devientFoo: {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
pathssur un paramètre (JSONPath). Son utilisation entraîne l'échec de la compilation.testssur 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.