Créer un proxy d'API à partir d'un modèle YAML

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

Consultez la documentation d' Apigee Edge.

Cette page vous explique comment définir un proxy d'API en tant que modèle de fonctionnalité Apigee au format YAML et le déployer avec la Google Cloud CLI. Vous allez d'abord créer un proxy simple, puis un exemple plus complet qui sert de façade à un modèle Gemini.

Pour en savoir plus, consultez Configurer un proxy avec YAML. Pour consulter le schéma complet, reportez-vous à la documentation de référence sur la configuration YAML des proxys d'API.

Avant de commencer

  • Activez l'API Vertex AI dans votre projet Google Cloud pour que le proxy puisse communiquer avec les modèles Gemini. 
    gcloud services enable aiplatform.googleapis.com
  • Installez et initialisez la Google Cloud CLI.
  • Pour accéder aux commandes utilisées dans ce tutoriel, installez le composant gcloud beta : 
    gcloud components install beta
  • Disposer d'une organisation Apigee et d'au moins un environnement. Notez les noms de l'organisation et de l'environnement. Les exemples utilisent ORG et ENV comme espaces réservés. La passerelle d'IA de la partie 2 nécessite également un environnement intermédiaire ou complet (et non un environnement de base). Pour en savoir plus, consultez Types d'environnement Apigee.
  • Assurez-vous de disposer des autorisations requises :
    • Pour importer (créer) un proxy d'API : le rôle Administrateur d'API (roles/apigee.apiAdmin) ou un rôle équivalent qui accorde apigee.proxies.create.
    • Pour déployer un proxy d'API, vous devez disposer du rôle Administrateur de l'environnement (roles/apigee.environmentAdmin) dans l'environnement cible et du rôle Lecteur d'API (roles/apigee.apiReaderV2) au niveau du projet.
    • Pour créer le produit d'API, le développeur et l'application qui génèrent la clé API dans la partie 2, étape 6 : administrateur d'API (roles/apigee.apiAdmin) et administrateur de développeur (roles/apigee.developerAdmin). Pour obtenir la liste complète des rôles, consultez Rôles Apigee.

Partie 1 : Créer un proxy d'API simple

Dans cette section, vous allez créer un proxy qui transfère les requêtes vers le service cible fictif Apigee et applique une limite de débit.

Étape 1 : Créez le modèle

Un modèle est le fichier que vous déployez. Il définit le chemin de base, les routes et la cible de backend de votre proxy, et liste les fonctionnalités à inclure.

Créez un répertoire pour votre proxy, puis créez un fichier nommé hello-proxy.yaml :

gateway: apigee
schemaVersion: 1.0.0
name: hello-proxy
type: template
description: A simple proxy to the Apigee mock target, protected by a rate limit.
features:
- spike-arrest.yaml
endpoints:
- name: default
  basePath: /hello
  routes:
  - name: default
    target: default
targets:
- name: default
  url: https://mocktarget.apigee.net

Ce modèle définit :

  • Un point de terminaison avec le chemin de base /hello. Les clients appellent le proxy à ce chemin d'accès.
  • Une route qui envoie les requêtes à la cible nommée default.
  • Une cible qui pointe vers l'URL du backend.
  • Une caractéristique, spike-arrest.yaml, que vous allez créer ensuite.

Étape 2 : Créez la fonctionnalité

Une fonctionnalité est une unité de configuration réutilisable qui contient des règles. Un modèle ne peut pas contenir de règles directement. La règle de limitation du débit se trouve donc dans une fonctionnalité.

Dans le même répertoire que le modèle, créez un fichier nommé spike-arrest.yaml :

gateway: apigee
schemaVersion: 1.0.0
name: spike-arrest
displayName: Spike Arrest
type: feature
description: Protects the backend by smoothing traffic spikes.
categories:
- traffic
parameters:
- name: RATE
  displayName: RATE
  description: Maximum request rate, for example 30ps (per second) or 100pm (per minute).
  default: 30ps
  examples:
  - 30ps
  - 100pm
defaultEndpoint:
  name: default
  flows:
  - name: PreFlow
    mode: Request
    steps:
    - name: SA-SpikeArrest
policies:
- name: SA-SpikeArrest
  type: SpikeArrest
  content:
    SpikeArrest:
      metadata:
        name: SA-SpikeArrest
        enabled: "true"
        continueOnError: "false"
      DisplayName: SA-SpikeArrest
      Rate: "{RATE}"

Cette fonctionnalité :

  • Définit une règle SpikeArrest qui limite le taux de requêtes.
  • Utilise defaultEndpoint.flows pour ajouter la règle au PreFlow de la requête, afin qu'elle s'exécute à chaque requête.
  • Déclare un paramètre, RATE, dont la valeur par défaut (30ps) est substituée à {RATE} lorsque le proxy est compilé.

Étape 3 : Importer le proxy

Importez le modèle pour créer une révision de proxy d'API. Exécutez cette commande à partir du répertoire contenant vos fichiers :

gcloud beta apigee apis import hello-proxy \
    --from-template=hello-proxy.yaml \
    --organization=ORG

La CLI compile le modèle et sa fonctionnalité dans un bundle de proxy d'API, l'importe et affiche la nouvelle révision du proxy. L'importation crée une révision, mais ne la déploie pas.

Étape 4 : Déployer le proxy

Déployez la révision dans un environnement :

gcloud apigee apis deploy \
    --api=hello-proxy \
    --environment=ENV \
    --organization=ORG

Par défaut, cette commande déploie la dernière révision. Pour déployer une révision spécifique, transmettez son numéro comme premier argument, par exemple gcloud apigee apis deploy 1 --api=hello-proxy --environment=ENV. Si un autre proxy est déjà déployé au même chemin de base, ajoutez --override pour le remplacer sans temps d'arrêt.

Étape 5 : Appeler le proxy

Pour appeler le proxy déployé sur le réseau, votre environnement doit être associé à un groupe d'environnements disposant d'un nom d'hôte routable. Si vous venez de créer votre organisation, vérifiez qu'elle est configurée avant d'appeler le proxy. Pour en savoir plus, consultez À propos des environnements et des groupes d'environnements.

Recherchez le nom d'hôte d'un groupe d'environnements contenant votre environnement :

  1. Dans la console Google Cloud , accédez à Apigee > Gestion > Environnements.
  2. Sélectionnez l'onglet Groupes d'environnements.
  3. Recherchez le groupe d'environnements qui contient votre environnement, puis copiez une valeur de sa colonne Noms d'hôte.

Appelez le proxy à ce nom d'hôte, en utilisant le chemin de base de votre modèle :

curl https://HOSTNAME/hello

Remplacez HOSTNAME par le nom d'hôte que vous avez copié. Une réponse réussie provient du service cible fictif.

Partie 2 : Créer une passerelle d'IA pour Gemini

Cette section crée un proxy plus complet : une passerelle d'IA qui transfère les requêtes vers un modèle Gemini sur Vertex AI, applique une limite de débit et nécessite une clé API. Il utilise un modèle, trois fonctionnalités et un compte de service.

Contrairement au proxy simple de la partie 1, ce proxy appelle un service Google Cloud (Vertex AI). La fonctionnalité gemini-target utilise auth: GoogleAccessToken. Apigee associe donc un jeton Google OAuth à chaque requête envoyée à Vertex AI. Ce jeton est émis pour un compte de service que vous créez et fournissez lorsque vous déployez le proxy. Cette partie ajoute donc une étape pour créer ce compte de service (Étape 3).

Étape 1 : Créez le modèle

Créez un fichier nommé ai-gateway.yaml :

gateway: apigee
schemaVersion: 1.0.0
name: ai-gateway
type: template
description: AI gateway that fronts a Gemini model with throttling and API key enforcement.
features:
- spike-arrest.yaml
- verify-api-key.yaml
- gemini-target.yaml
endpoints:
- name: gemini
  basePath: /v1/gemini
  routes:
  - name: default
    target: gemini

Étape 2 : Créer les caractéristiques

Dans le même répertoire, créez les trois fichiers de caractéristiques.

Réutilisez la fonctionnalité spike-arrest.yaml de la partie 1.

Créez verify-api-key.yaml pour exiger une clé API dans l'en-tête x-api-key :

gateway: apigee
schemaVersion: 1.0.0
name: verify-api-key
displayName: Verify API Key
type: feature
description: Requires a valid API key in the x-api-key request header.
categories:
- security
defaultEndpoint:
  name: default
  flows:
  - name: PreFlow
    mode: Request
    steps:
    - name: VA-VerifyAPIKey
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

Créez gemini-target.yaml pour rediriger vers un modèle Gemini, authentifié avec un jeton d'accès Google :

gateway: apigee
schemaVersion: 1.0.0
name: gemini-target
displayName: Gemini Target
type: feature
description: Routes requests to a Gemini model on Vertex AI, authenticated with a Google access token.
categories:
- llm
targets:
- name: gemini
  url: https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-2.5-flash:generateContent
  auth: GoogleAccessToken
  scopes:
  - https://www.googleapis.com/auth/cloud-platform

Remplacez PROJECT_ID par l'ID de votre projet Google Cloud et REGION par la région Vertex AI que vous utilisez (par exemple, us-central1). Cette fonctionnalité utilise auth: GoogleAccessToken pour qu'Apigee associe un jeton d'accès Google à chaque requête envoyée à Vertex AI.

Les modèles ne sont pas disponibles partout, et l'URL dépend de l'emplacement que vous utilisez. L'URL précédente est la forme régionale, qui fonctionne pour un modèle diffusé à partir d'une région spécifique, telle que gemini-2.5-flash dans us-central1. Les autres modèles ne sont diffusés qu'à partir du point de terminaison global, qui utilise un hôte et un locations/global différents :

  url: https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/MODEL:generateContent

Pour trouver les emplacements compatibles avec un modèle, consultez Emplacements d'IA générative sur Vertex AI.

Étape 3 : Créez un compte de service pour le proxy

Étant donné que la fonctionnalité gemini-target utilise auth: GoogleAccessToken, le proxy déployé appelle Vertex AI en tant que compte de service. Créez ce compte de service, accordez-lui l'accès à Vertex AI et laissez l'agent de service Apigee l'utiliser. Vous fournissez ce compte de service lorsque vous déployez le proxy à l'étape 5. Pour en savoir plus, consultez Utiliser l'authentification Google.

  1. Créez un compte de service géré par l'utilisateur dans le même projet Google Cloud que votre organisation Apigee. (Le compte de service Compute Engine par défaut n'est pas accepté.) Pour découvrir d'autres méthodes de création, consultez Créer et gérer des comptes de service. 
    gcloud iam service-accounts create SA_NAME \
    --project=PROJECT_ID \
    --display-name="Apigee AI gateway"

    Le compte de service SA_NAME@PROJECT_ID.iam.gserviceaccount.com est alors créé.

  2. Accordez au compte de service l'accès au backend qu'il appelle. Pour une cible Vertex AI, accordez le rôle Utilisateur Vertex AI (roles/aiplatform.user) : 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/aiplatform.user"

    Si la stratégie IAM de votre projet contient déjà des liaisons de rôle conditionnelles, ajoutez --condition=None à cette commande.

  3. Autorisez l'agent de service Apigee à générer des jetons pour le compte de service en lui attribuant le rôle Créateur de jetons du compte de service (roles/iam.serviceAccountTokenCreator) sur le compte de service : 
    gcloud iam service-accounts add-iam-policy-binding \
    SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
    --project=PROJECT_ID \
    --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-apigee.iam.gserviceaccount.com" \
    --role="roles/iam.serviceAccountTokenCreator"

    Pour trouver PROJECT_NUMBER, exécutez gcloud projects describe PROJECT_ID --format='value(projectNumber)'.

Étape 4 : Importer le proxy

Importez le modèle pour créer une révision de proxy d'API :

gcloud beta apigee apis import ai-gateway \
    --from-template=ai-gateway.yaml \
    --organization=ORG

Notez le numéro de révision dans le résultat de la commande, car vous en aurez besoin à l'étape 5. Pour n'imprimer que le numéro de révision, ajoutez --format="value(revision)" à la commande d'importation.

Étape 5 : Déployez le proxy avec le compte de service

Le déploiement de la passerelle d'IA diffère du proxy simple de la partie 1 de deux manières :

  • Vous devez fournir le compte de service que vous avez créé à l'étape 3. Si vous effectuez un déploiement sans fichier, il échoue et génère une erreur MISSING_SERVICE_ACCOUNT.
  • Vous devez effectuer le déploiement dans un environnement intermédiaire ou complet. Ce proxy utilise une règle extensible, qu'un environnement Base ne prend pas en charge. Le déploiement dans un tel environnement échoue et génère l'erreur Extensible proxy can not be deployed to a base environment (Le proxy extensible ne peut pas être déployé dans un environnement de base). Consultez la section Types d'environnement Apigee.

Interface utilisateur Apigee : déployez le proxy et, lorsque vous êtes invité à saisir un compte de service, saisissez SA_NAME@PROJECT_ID.iam.gserviceaccount.com. Pour connaître la procédure, consultez Déployer un proxy d'API.

API Deployments : appelez l'API Deployments en transmettant le compte de service en tant que paramètre de requête serviceAccount. Remplacez REVISION par le numéro de révision de l'étape 4 :

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -X POST \
"https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/ai-gateway/revisions/REVISION/deployments?serviceAccount=SA_NAME@PROJECT_ID.iam.gserviceaccount.com"

La requête de déploiement est renvoyée immédiatement. Le déploiement est asynchrone. Interrogez l'état de déploiement de la révision, qui indique PROGRESSING jusqu'à ce qu'il devienne READY :

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/ai-gateway/revisions/REVISION/deployments"

Lorsque le proxy est compilé, les fonctionnalités spike-arrest et verify-api-key ajoutent leurs règles au PreFlow de la requête (limitation du débit en premier, puis vérification de la clé API), et la fonctionnalité gemini-target ajoute le backend Vertex AI. Une fois le déploiement terminé, le proxy s'authentifie auprès de Vertex AI en tant que compte de service.

Étape 6 : Obtenir une clé API

La fonctionnalité verify-api-key rejette toute requête qui ne comporte pas de clé API valide. Vous avez donc besoin d'une clé avant de pouvoir appeler le proxy. Une clé API est un identifiant d'une application de développeur associée à un produit d'API contenant ce proxy. Effectuez les tâches suivantes, décrites dans Présentation de la publication :

  1. Créez un produit d'API qui inclut le proxy ai-gateway et l'environnement dans lequel vous l'avez déployé.
  2. Enregistrez un développeur d'applications.
  3. Enregistrez une application de développeur associée à ce produit d'API.

L'enregistrement de l'application génère la clé. Pour la récupérer, consultez Afficher une clé API et un code secret.

Étape 7 : Appeler le proxy

Recherchez le nom d'hôte de votre groupe d'environnements, comme décrit dans la partie 1, étape 5, puis appelez le proxy au chemin de base /v1/gemini. Transmettez la clé API dans l'en-tête x-api-key et envoyez un corps de requête Gemini generateContent :

curl -X POST https://HOSTNAME/v1/gemini \
    -H "x-api-key: API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"contents":[{"role":"user","parts":[{"text":"Say hello in one sentence."}]}]}'

Remplacez HOSTNAME par le nom d'hôte de votre groupe d'environnements et API_KEY par la clé de l'étape 6. Une réponse réussie correspond à la sortie JSON du modèle. Si vous omettez la clé, une erreur d'autorisation est renvoyée par la règle VerifyAPIKey, ce qui confirme que la fonctionnalité verify-api-key est en vigueur. Pour découvrir d'autres façons de transmettre une clé, consultez Envoyer une requête avec une clé API valide.

Étapes suivantes