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 en 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 d'interface à 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.

Avant de commencer

  • Pour la partie 2 uniquement : activez l'API Agent Platform dans le projet Google Cloud qui héberge le modèle :

    gcloud services enable aiplatform.googleapis.com \
        --project=PROJECT_ID

    Remplacez PROJECT_ID par l'ID du projet qui héberge le modèle, par exemple my-apigee-project. Ce tutoriel utilise le projet de votre organisation Apigee. La partie 1 n'a pas besoin de cette API. Vous n'avez pas besoin de choisir une région, car le modèle utilise le point de terminaison global. L'activation de l'API peut prendre un certain temps.

  • Installez et initialisez la Google Cloud CLI.
  • 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 (voir la section Espaces réservés utilisés sur cette page). La passerelle d'IA de la partie 2 nécessite également un environnement intermédiaire ou complet (et non un environnement de base). 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 : Administrateur d'environnement (roles/apigee.environmentAdmin) sur 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 produisent la clé API à l'étape 6 de la partie 2 : Administrateur d'API (roles/apigee.apiAdmin) et Administrateur de développeurs (roles/apigee.developerAdmin). Pour obtenir la liste complète des rôles, consultez Rôles Apigee.

Espaces réservés utilisés sur cette page

Remplacez chaque espace réservé dans les commandes par votre propre valeur. La plupart des valeurs existent déjà et vous les recherchez. Vous choisissez vous-même SA_NAME, et certaines valeurs sont générées au fur et à mesure que vous suivez les étapes.

Espace réservé Source Description
ORG Rechercher Nom de votre organisation Apigee. Il est généralement identique à PROJECT_ID. Pour lister les organisations auxquelles vous avez accès, exécutez gcloud apigee organizations list.
ENV Rechercher Un environnement de votre organisation, par exemple test. La partie 1, étape 4, explique comment les lister.
PROJECT_ID Rechercher ID du projet Google Cloud qui contient votre organisation Apigee, par exemple my-apigee-project. Pour imprimer le projet actif, exécutez gcloud config get project.
HOSTNAME Rechercher Nom d'hôte d'un groupe d'environnements contenant ENV, par exemple api.example.com. L'étape 5 de la partie 1 indique où le trouver.
SA_NAME À vous de choisir Nom du compte de service que vous créez à l'étape 3 de la partie 2, par exemple apigee-ai-gateway.
PROJECT_NUMBER Rechercher Numéro du projet PROJECT_ID, par exemple 123456789012. La partie 2, étape 3, montre la commande qui l'affiche.
REGION À vous de choisir Facultatif. Région qui diffuse votre modèle, par exemple us-central1. Vous n'en avez besoin que si vous basculez la fonctionnalité gemini-target vers un point de terminaison régional.
REVISION Généré Numéro de révision du proxy que la commande d'importation affiche dans la partie 2, étape 4, par exemple 1.
API_KEY Généré Clé API générée par Apigee lorsque vous enregistrez une application de développement à l'étape 6 de la partie 2.

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

Dans cette section, vous allez créer un proxy qui transfère les requêtes au service cible fictif Apigee et applique une limitation du 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 de projet pour vos modèles, avec un sous-répertoire features pour les fonctionnalités qu'ils utilisent :

mkdir -p proxy-templates/features
cd proxy-templates

Une fois cette partie terminée, le répertoire du projet se présente comme suit :

proxy-templates/
  hello-proxy.yaml
  features/
    spike-arrest.yaml

Dans le répertoire proxy-templates, 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:
- ./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 des 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 caractéristique

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. Par conséquent, la règle de limitation du débit se trouve dans une fonctionnalité.

Dans le répertoire features, 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 remplacée par {RATE} lors de la compilation du proxy.

É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 proxy-templates, qui contient le modèle :

gcloud 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 imprime 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

Répertoriez les environnements de votre organisation :

gcloud apigee environments list --organization=ORG

La commande affiche les noms des environnements. Choisissez-en un à utiliser comme ENV, puis déployez-y la révision :

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 en tant que premier argument, par exemple gcloud apigee apis deploy 1 --api=hello-proxy --environment=ENV. Si un autre proxy est déjà déployé sur le 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 doté d'un nom d'hôte routable. Si vous venez de créer votre organisation, vérifiez que cette configuration est bien 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 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 Gemini Enterprise Agent Platform, applique une limitation du 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 (Agent Platform). La fonctionnalité gemini-target utilise auth: GoogleAccessToken. Apigee associe donc un jeton Google OAuth à chaque requête envoyée à la plate-forme de l'agent. 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).

Avant de commencer, assurez-vous que l'API Agent Platform est activée dans le projet qui héberge le modèle, comme décrit dans Avant de commencer. Vous n'avez pas besoin d'avoir déjà utilisé Agent Platform.

Dans la partie 2, PROJECT_ID est l'ID du projet de votre organisation Apigee, par exemple my-apigee-project. La partie 2 utilise ce projet tout au long de la procédure : vous y activez l'API, vous y créez le compte de service et vous le définissez comme valeur MODEL_PROJECT_ID du modèle.

Étape 1 : Créez le modèle

Dans le répertoire proxy-templates de la partie 1, 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:
- ./features/spike-arrest.yaml
- ./features/verify-api-key.yaml
- ./features/gemini-target.yaml
parameters:
- name: MODEL_PROJECT_ID
  default: PROJECT_ID
- name: MODEL
  default: gemini-3.8-flash
endpoints:
- name: gemini
  basePath: /v1/gemini
  routes:
  - name: default
    target: gemini

La liste parameters définit les valeurs des paramètres déclarés par la fonctionnalité gemini-target, que vous allez créer à l'étape suivante. Remplacez PROJECT_ID par l'ID du projet que vous avez utilisé pour activer l'API, par exemple my-apigee-project.

Étape 2 : Créer les caractéristiques

Le modèle utilise trois caractéristiques. Réutilisez la caractéristique spike-arrest.yaml de la partie 1 et créez les deux autres dans le répertoire features. Une fois cette étape terminée, le répertoire du projet se présente comme suit :

proxy-templates/
  hello-proxy.yaml
  ai-gateway.yaml
  features/
    spike-arrest.yaml
    verify-api-key.yaml
    gemini-target.yaml

Créez features/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 features/gemini-target.yaml pour acheminer 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 the Gemini Enterprise Agent Platform, authenticated with a Google access token.
categories:
- llm
parameters:
- name: MODEL_PROJECT_ID
  displayName: Model Project ID
  description: Google Cloud project that hosts the Gemini model. Supplied by the template; no default.
- name: MODEL
  displayName: Model
  description: The Gemini model to route to.
  default: gemini-3.8-flash
  examples:
  - gemini-3.8-flash
  - gemini-4-argon
targets:
- name: gemini
  url: https://aiplatform.googleapis.com/v1/projects/{MODEL_PROJECT_ID}/locations/global/publishers/google/models/{MODEL}:generateContent
  auth: GoogleAccessToken
  scopes:
  - https://www.googleapis.com/auth/cloud-platform

La fonctionnalité gemini-target déclare deux paramètres et les remplace dans l'URL cible :

  • MODEL_PROJECT_ID : projet Google Cloud qui héberge le modèle. Il n'a pas de valeur par défaut. Le modèle doit donc le définir sur l'ID de votre projet.
  • MODEL : modèle Gemini à appeler. La valeur par défaut de la fonctionnalité est gemini-3.8-flash.

Lorsque la CLI compile le modèle, elle résout chaque paramètre comme suit :

  1. Si la liste parameters du modèle comporte une entrée portant le même nom et une valeur default non vide, la CLI utilise cette valeur.
  2. Sinon, la CLI utilise la valeur default de la caractéristique.
  3. Si aucune valeur n'est définie, la CLI remplace {name} par une chaîne vide. L'importation ne signale pas d'erreur. Par conséquent, un MODEL_PROJECT_ID manquant produit une URL cible sans ID de projet.

Il n'existe pas de flag de ligne de commande permettant de définir des valeurs de paramètre lors de l'importation. Pour utiliser un autre projet ou modèle, modifiez sa valeur dans la liste parameters du modèle, puis importez-le à nouveau.

La fonctionnalité gemini-target utilise auth: GoogleAccessToken pour qu'Apigee associe un jeton d'accès Google à chaque requête adressée à Agent Platform.

L'URL utilise le point de terminaison global (hôte aiplatform.googleapis.com et locations/global), qui diffuse gemini-3.8-flash et achemine les requêtes vers la capacité disponible dans toutes les régions. Avec le point de terminaison global, vous n'avez pas besoin de choisir une région.

Pour appeler un autre modèle, définissez MODEL dans la liste parameters du modèle sur l'ID du modèle. Pour lister les modèles Gemini que vous pouvez appeler, exécutez la commande suivante :

gcloud ai model-garden models list --model-filter=gemini

Chaque valeur de la colonne MODEL_ID ressemble à google/gemini-3.8-flash@default. Définissez MODEL sur la partie comprise entre google/ et @, par exemple gemini-4-argon. La fiche du modèle dans Model Garden dans la consoleGoogle Cloud affiche le même ID. Pour vérifier qu'un modèle est compatible avec le point de terminaison global, consultez l'onglet Global dans Emplacements des points de terminaison des modèles Google.

Si vous devez contrôler la région qui traite les requêtes, remplacez la ligne url dans features/gemini-target.yaml par la forme régionale, qui place la région à la fois dans l'hôte et dans le chemin d'accès :

  url: https://REGION-aiplatform.googleapis.com/v1/projects/{MODEL_PROJECT_ID}/locations/REGION/publishers/google/models/{MODEL}:generateContent

Remplacez REGION par une région qui diffuse votre modèle, comme indiqué dans les mêmes tableaux des emplacements des points de terminaison des modèles Google. Pour savoir quand éviter le point de terminaison global, consultez Point de terminaison global.

É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 Agent Platform en tant que compte de service. Créez ce compte de service, accordez-lui l'accès à Agent Platform 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 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"

    Choisissez un nom descriptif pour SA_NAME, par exemple apigee-ai-gateway. La commande crée le compte de service SA_NAME@PROJECT_ID.iam.gserviceaccount.com, par exemple apigee-ai-gateway@my-apigee-project.iam.gserviceaccount.com.

  2. Accordez au compte de service l'accès au backend qu'il appelle. Pour une cible Agent Platform, attribuez le rôle Utilisateur Agent Platform (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 à créer 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 obtenir 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. Exécutez cette commande à partir du répertoire proxy-templates, qui contient le modèle :

gcloud 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'imprimer 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 en spécifier un, le déploiement échoue avec 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, qui n'est pas compatible avec un environnement Base. Le déploiement dans un tel environnement échoue avec l'erreur Impossible de déployer un proxy extensible dans un environnement de base. La commande gcloud apigee environments list n'affiche pas le type d'environnement. Pour le vérifier, dans la console Google Cloud , accédez à Apigee > Gestion > Environnements. Consultez la section Types d'environnement Apigee.

UI d'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 à suivre, 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 (d'abord la limitation du débit, puis la vérification de la clé API), et la fonctionnalité gemini-target ajoute le backend Agent Platform. Une fois le déploiement terminé, le proxy s'authentifie auprès d'Agent Platform 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 devez donc disposer 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 la vue d'ensemble de la publication :

  1. Créez un produit d'API incluant le proxy ai-gateway. Dans le formulaire du produit, saisissez les informations suivantes, puis cliquez sur Enregistrer :
    • Nom et Nom à afficher : n'importe quelle valeur, par exemple ai-gateway-product.
    • Environnement : environnement dans lequel vous avez déployé le proxy (ENV).
    • Accès : Public. Laissez l'option Approuver automatiquement les demandes d'accès sélectionnée afin que la clé API soit approuvée lorsque vous enregistrez l'application.
    • Dans la section Opérations, cliquez sur + AJOUTER UNE OPÉRATION et définissez les champs suivants :
      • Proxy d'API : ai-gateway.
      • Chemin d'accès : /. Les requêtes sont envoyées au chemin de base du proxy, /v1/gemini, sans rien après. Le chemin d'accès / correspond au chemin d'accès de base. /** ne correspond qu'aux chemins d'accès situés en dessous. Par conséquent, une requête adressée à /v1/gemini échoue avec l'erreur oauth.v2.InvalidApiKeyForGivenResource. Consultez la section Configurer des chemins de ressources.
      • Méthodes : POST.
    • Laissez les champs Limite de quota d'API, Limite de quota de jetons LLM, Quota de l'opération et la section Opérations du LLM vides. La fonctionnalité spike-arrest du proxy applique la limitation du débit.
  2. Enregistrez un développeur d'applications.
  3. Enregistrez une application de développeur et sélectionnez le produit d'API lorsque vous créez l'application, afin que la nouvelle clé soit associée au produit dès le départ.

L'enregistrement de l'application génère la clé. Pour le 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 à l'étape 5 de la partie 1, puis appelez le proxy au niveau du 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. L'omission de la clé renvoie un échec d'autorisation de 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