Configurer un proxy avec YAML

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

Consultez la documentation d'Apigee Edge.

Bêta

Cette fonctionnalité est en version bêta et peut donc encore changer. Elle est couverte par les Conditions des offres avant disponibilité générale des conditions d'utilisation de Google Cloud. Les fonctionnalités pré-DG sont susceptibles de présenter une compatibilité limitée, et les modifications apportées à ces fonctionnalités peuvent ne pas être compatibles avec d'autres versions pré-DG. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Vous pouvez définir un proxy d'API Apigee en YAML et le déployer avec la Google Cloud CLI, au lieu de créer le groupe de proxys XML traditionnel. Vous décrivez les points de terminaison, les routes, les règles et les cibles de backend d'un proxy dans des fichiers YAML appelés modèles de fonctionnalités Apigee, et Apigee les compile dans un groupe de proxys d'API standard.

Étant donné que le résultat est un groupe de proxys d'API Apigee ordinaire, un proxy que vous créez de cette manière s'exécute sur le même environnement d'exécution Apigee, avec les mêmes règles et le même comportement qu'un proxy que vous créez dans l'interface utilisateur Apigee ou à partir d'un groupe XML.

Remarque : Cette page décrit la création de proxys avec YAML. Elle ne modifie pas le fonctionnement des proxys existants. Lorsque vous résolvez un problème lié à un proxy dans l'interface utilisateur Apigee, vous voyez toujours la configuration XML générée, et non la source YAML.

Pourquoi utiliser YAML pour définir des proxys ?

Le format de proxy d'API Apigee traditionnel est une archive ZIP de fichiers XML. YAML offre une alternative que de nombreux développeurs trouvent plus rapide à lire, à écrire et à examiner, et qui fonctionne bien avec les outils d'assistance et d'agent basés sur l'IA. Les modèles de fonctionnalités Apigee sont conçus pour les cas suivants :

• Les développeurs et architectes d'API qui préfèrent un format concis et déclaratif et qui souhaitent conserver la configuration du proxy dans le contrôle des sources.
• Les professionnels de l'IA qui souhaitent une méthode standardisée pour placer une passerelle Apigee devant un backend de modèle.
• Les équipes de plate-forme et DevOps qui souhaitent regrouper des éléments réutilisables de configuration de proxy et les appliquer de manière cohérente à de nombreux proxys.

Concepts clés

Les modèles de fonctionnalités Apigee utilisent trois types de documents. Chacun est un fichier YAML identifié par son champ type.

Type de document	Valeur type	Objectif
Modèle	template	Point d'entrée que vous déployez. Un modèle comprend une ou plusieurs fonctionnalités et définit les points de terminaison et les routes du proxy.
Fonctionnalité	feature	Unité de configuration réutilisable (telle qu'une vérification d'authentification , une limite de débit ou une cible de backend) que vous incluez dans un modèle. Les fonctionnalités contiennent les règles et les ressources.
Proxy	proxy	Proxy entièrement résolu que la CLI produit lorsqu'elle compile un modèle avec ses fonctionnalités. Bien qu'il s'agisse généralement d'un résultat intermédiaire généré par la CLI, vous pouvez également importer directement un fichier proxy pour le traduire en bundle de proxys d'API.

Vous créez des modèles et des fonctionnalités. Apigee génère le proxy pour vous lors de la compilation.

Remarque : Un modèle comprend des fonctionnalités, mais ne contient pas de règles ni de ressources propres. Pour ajouter des règles (par exemple, de sécurité, de gestion du trafic ou de transformation des messages), vous les définissez dans des fonctionnalités et vous y faites référence à partir de votre modèle.

Fonctionnement

Lorsque vous importez un modèle, la Google Cloud CLI effectue les étapes suivantes en local, puis importe le résultat dans Apigee :

1. Compiler. La CLI lit votre modèle et les fichiers de fonctionnalités auxquels il fait référence, les fusionne et produit une seule définition de proxy.
2. Convertir. La CLI convertit la définition de proxy en groupe de proxys d'API Apigee standard (le fichier ZIP de fichiers XML attendu par Apigee ).
3. Importer. La CLI importe le groupe dans Apigee, qui crée une nouvelle révision de proxy d'API.

L'importation d'un proxy ne le rend pas actif. Dans une étape distincte, vous déployez la révision dans un environnement, exactement comme vous le feriez pour n'importe quel autre proxy d'API :

YAML template + feature files
  |  gcloud beta apigee apis import --from-template
  v
API proxy revision   (created, not yet serving traffic)
  |  gcloud apigee apis deploy
  v
Deployed proxy       (serving traffic in an environment)

Pour obtenir des instructions détaillées, consultez Créer un proxy d'API à partir d'un modèle YAML.

Exemple minimal

Le modèle suivant définit un proxy qui comprend deux fonctionnalités : l'une qui ajoute une cible de backend et l'autre qui ajoute un message de réponse :

gateway: apigee
schemaVersion: 1.0.0
name: HelloWorld-v1
type: template
description: API proxy for HelloWorld-v1
features:
- proxy-apigeemock.yaml
- response-helloworld.yaml

Chaque fichier de fonctionnalité référencé doit se trouver dans le même répertoire que le modèle. Pour obtenir un exemple complet et exécutable, ainsi que les fichiers de fonctionnalités qu'il utilise, consultez Créer un proxy d'API à partir d'un modèle YAML.

Ce que vous pouvez faire

• Définissez les points de terminaison, les chemins de base, les routes, les flux et les cibles de backend d'un proxy en YAML.
• Regroupez les règles et les ressources réutilisables en tant que fonctionnalités et composez-les dans un modèle.
• Ajoutez l'authentification du backend pour les cibles Google Cloud (par exemple, un jeton d'accès Google pour un backend Vertex AI).
• Importez un modèle en tant que nouvelle révision de proxy d'API avec la Google Cloud CLI, puis déployez-le avec la commande de déploiement standard.

Limites

Tenez compte des points suivants lorsque vous créez des modèles et des fonctionnalités :

• Les fonctionnalités sont des fichiers locaux. Un modèle ne peut référencer que les fichiers de fonctionnalités qui se trouvent dans le même répertoire. Il n'est pas possible de référencer des fonctionnalités par URL ou à partir d'un catalogue partagé.
• Les valeurs des paramètres utilisent leurs valeurs par défaut. Les fonctionnalités peuvent définir des paramètres, mais les valeurs des paramètres sont résolues en fonction de la valeur par défaut définie dans la fonctionnalité. Il n'existe aucune option de ligne de commande permettant de remplacer les valeurs des paramètres lors de l'importation.
• Les paramètres JSONPath ne sont pas compatibles. Un paramètre qui utilise une paths (JSONPath) expression entraîne l'échec de la compilation.
• Les tests ne sont pas compatibles. Une section tests est acceptée par le schéma, mais elle est ignorée et n’est pas incluse dans le groupe généré.
• Le schéma est strict. Les champs inconnus provoquent une erreur. Seuls gateway: apigee et schemaVersion: 1.0.0 sont compatibles.
• La résolution des problèmes utilise le code XML généré. L'interface utilisateur et l'environnement d'exécution Apigee fonctionnent avec le groupe généré. Il n'y a pas de retour à votre source YAML dans l'interface utilisateur.

Étapes suivantes

• Créer un proxy d'API à partir d'un modèle YAML
• Documentation de référence sur la configuration YAML des proxys d' API
• Comprendre les API et les proxys d'API