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_IDRemplacez 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 accordeapigee.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.
- Pour importer (créer) un proxy d'API : le rôle Administrateur d'API (
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.flowspour 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=ORGLa 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=ORGPar 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 :
- Dans la console Google Cloud , accédez à Apigee > Gestion > Environnements.
- Sélectionnez l'onglet Groupes d'environnements.
- 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é estgemini-3.8-flash.
Lorsque la CLI compile le modèle, elle résout chaque paramètre comme suit :
- Si la liste
parametersdu modèle comporte une entrée portant le même nom et une valeurdefaultnon vide, la CLI utilise cette valeur. - Sinon, la CLI utilise la valeur
defaultde la caractéristique. - 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, unMODEL_PROJECT_IDmanquant 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.
- 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 serviceSA_NAME@PROJECT_ID.iam.gserviceaccount.com, par exempleapigee-ai-gateway@my-apigee-project.iam.gserviceaccount.com. - 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. - 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=ORGNotez 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 commandegcloud apigee environments listn'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 :
- 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'erreuroauth.v2.InvalidApiKeyForGivenResource. Consultez la section Configurer des chemins de ressources. - Méthodes :
POST.
- Proxy d'API :
- 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-arrestdu proxy applique la limitation du débit.
- Nom et Nom à afficher : n'importe quelle valeur, par exemple
- Enregistrez un développeur d'applications.
- 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
- Documentation de référence sur la configuration YAML des proxys d'API
- Configurer un proxy avec YAML
- Déployer des proxys d'API
- Vue d'ensemble de la publication