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 explique comment définir un proxy d'API en tant que modèle de fonctionnalité Apigee en YAML et le déployer avec Google Cloud CLI. Vous allez d'abord créer un proxy simple, puis un exemple plus complet qui se trouve devant un modèle Gemini.

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

Avant de commencer

  • Activez l'API Vertex AI dans votre projet Google Cloud afin que le proxy puisse communiquer avec les modèles Gemini. 
    gcloud services enable aiplatform.googleapis.com
  • Installez et initialisez le Google Cloud CLI.
  • Pour accéder aux commandes utilisées dans ce tutoriel, installez le composant gcloud beta : 
    gcloud components install beta
  • Disposez 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 en outre un environnement intermédiaire ou complet (et non un environnement de base) ; consultez la section Types d'environnement Apigee.
  • Assurez-vous de disposer des autorisations requises :
    • Pour importer (créer) un proxy d'API : le Administrateur d'API rôle (roles/apigee.apiAdmin), ou un rôle équivalent qui accorde apigee.proxies.create.
    • Pour déployer un proxy d'API : Administrateur d'environnement (roles/apigee.environmentAdmin) dans l'environnement cible et 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 la section 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 simulé Apigee et applique une limite de débit.

Étape 1 : Créer 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 backend de votre proxy, et répertorie 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.
  • Une route qui envoie des requêtes à la cible nommée default.
  • Une cible qui pointe vers l'URL du backend.
  • Une fonctionnalité, spike-arrest.yaml, que vous allez créer ensuite.

Étape 2 : Créer la fonctionnalité

Une fonctionnalité est une unité de configuration réutilisable qui contient des règles. Un modèle ne peut pas contenir directement de règles. 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 demandes.
  • Utilise defaultEndpoint.flows pour ajouter la règle au PreFlow de la requête, afin qu'elle s'exécute sur chaque requête.
  • Déclare un paramètre, RATE, dont la valeur par défaut (30ps) est substituée à {RATE} lors de la compilation du proxy.

Étape 3 : Importer le proxy

Importez le modèle pour créer une révision du 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 que cette configuration est en place avant d'appeler le proxy. 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 Google Cloud console, accédez à Apigee > Gestion > Environnements.
  2. Sélectionnez l'onglet Groupes d'environnements.
  3. Recherchez le groupe d'environnements contenant votre environnement et 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 simulé.

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. Elle 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 joint donc un jeton OAuth Google à chaque requête adressée à Vertex AI. Ce jeton est émis pour un compte de service que vous créez, puis que vous 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éer 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 fonctionnalités

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

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 acheminer les requêtes 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 afin qu'Apigee joigne un jeton d'accès Google à chaque requête adressée à Vertex AI.

Les modèles ne sont pas disponibles dans tous les emplacements, 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. D'autres modèles ne sont diffusés qu'à partir du point de terminaison global, qui utilise un hôte différent et locations/global :

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

Pour connaître les emplacements compatibles avec un modèle, consultez la section IA générative sur les emplacements Vertex AI.

Étape 3 : Créer 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 autorisez 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 la section Utiliser l'authentification Google.

  1. Créez un compte de service géré par l'utilisateur dans le même Google Cloud projet que votre organisation Apigee. (Le compte de service Compute Engine par défaut n'est pas accepté.) Pour savoir comment en créer un, consultez la section 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, attribuez 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 de compte de service (roles/iam.serviceAccountTokenCreator) : 
    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 du 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. Vous en aurez besoin à l'étape 5. Pour n'afficher que le numéro de révision, ajoutez --format="value(revision)" à la commande d'importation.

Étape 5 : Déployer 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 compte de service, le déploiement échoue et une erreur MISSING_SERVICE_ACCOUNT s'affiche.
  • Vous devez effectuer le déploiement dans un environnement intermédiaire ou complet. Ce proxy utilise une règle extensible, qui n'est pas compatible avec un environnement de base. Si vous effectuez un déploiement dans un environnement de base, 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) s'affiche. Consultez la section Types d'environnement Apigee.

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

API de déploiement : appelez l' API de déploiements 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 d'abord, 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 une identité d'une application de développeur associée à un produit d'API contenant ce proxy. Effectuez les tâches suivantes, qui sont décrites dans Vue d'ensemble 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 la section 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é, la règle VerifyAPIKey renvoie un échec d'autorisation, ce qui confirme que la fonctionnalité verify-api-key est en vigueur. Pour savoir comment transmettre une clé, consultez la section Envoyer une requête avec une clé API valide.

Étapes suivantes