Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Extensions OpenAPI 3.x dans API Gateway

API Gateway accepte un ensemble d'extensions spécifiques à Google pour la spécification OpenAPI qui configurent les comportements de la passerelle. Ces extensions vous permettent de spécifier les paramètres de gestion d'API, les méthodes d'authentification, les limites de quota et les intégrations de backend directement dans votre document OpenAPI. Comprendre ces extensions vous aide à adapter le comportement de votre service et à l'intégrer aux fonctionnalités d'API Gateway.

Cette page décrit les extensions spécifiques à Google de la spécification OpenAPI 3.x.

Bien que les exemples fournis soient au format YAML, le format JSON est également accepté.

`x-google-api-management`

Obligatoire.

L'extension x-google-api-management définit les paramètres de gestion d'API de premier niveau pour votre service. Placez cette extension à la racine de votre document OpenAPI.

Le tableau suivant décrit les champs de x-google-api-management :

Champ	Type	Obligatoire	Par défaut	Description
`metrics`	`map[string]Metric`	Non	Vide	Définissez des métriques pour appliquer des limites de quota.
`quota`	`map[string]Quota`	Non	Vide	Spécifiez des limites de quota pour votre service.
`backends`	`map[string]Backend`	Oui	Vide	Configurer les services de backend
`apiName`	`string`	Non	Vide	Associez un nom aux opérations définies dans le document OpenAPI.
`ai`	`AI`	Non	Vide	Configurez les fonctionnalités d'intelligence artificielle, y compris le routage vers les modèles.
`mcp`	`MCP` ou `bool`	Non	Vide	Activez ou configurez les fonctionnalités du protocole MCP (Model Context Protocol).

Objet `Metric`

L'objet Metric définit une métrique utilisée pour l'application des quotas.

Le tableau suivant décrit les champs de Metric :

Champ	Type	Obligatoire	Par défaut	Description
`displayName`	`string`	Non	Vide	Nom à afficher de la métrique.

Objet `Quota`

L'objet Quota définit les limites de quota.

Le tableau suivant décrit les champs de Quota :

Champ	Type	Obligatoire	Par défaut	Description
`limits`	`map[string]QuotaLimit`	Non	Vide	Spécifiez des limites de quota.

Objet `QuotaLimit`

L'objet QuotaLimit définit une limite de quota spécifique.

Le tableau suivant décrit les champs de QuotaLimit :

Champ	Type	Obligatoire	Description
`metric`	`string`	Oui	Référencez une métrique déclarée dans ce document OpenAPI.
`values`	`int64`	Oui	Définissez la valeur maximale que la métrique peut atteindre avant que les requêtes des clients ne soient refusées.

Objet `Backends`

Obligatoire.

L'objet Backends configure un service de backend. Vous devez définir jwtAudience ou disableAuth.

Le tableau suivant décrit les champs de Backends :

Champ	Type	Obligatoire	Par défaut	Description
`address`	`string`	Oui	Vide	Spécifiez l'URL du backend.
`jwtAudience`	`string`	Non	Vide	Par défaut, API Gateway crée le jeton d'ID d'instance avec une audience JWT qui correspond au champ d'adresse. La spécification manuelle de `jwt_audience` n'est requise que lorsque le backend cible utilise l'authentification basée sur JWT et que l'audience attendue est différente de la valeur spécifiée dans le champ d'adresse. Pour les backends distants déployés sur App Engine ou avec IAP, vous devez remplacer l'audience du jeton JWT. App Engine et IAP utilisent leur ID client OAuth comme audience attendue.
`disableAuth`	`bool`	Non	`False`	Empêchez le proxy du plan de données d'obtenir un jeton d'ID d'instance et de l'associer à la requête.
`pathTranslation`	`string`	Non	`APPEND_PATH_TO_ADDRESS` ou `CONSTANT_ADDRESS`	Définissez la stratégie de traduction de chemin d'accès lors de la transmission des requêtes au backend cible. Lorsque `x-google-backend` est défini au niveau supérieur et qu'aucun `path_translation` n'est spécifié, la valeur par défaut de `pathTranslation` est `APPEND_PATH_TO_ADDRESS`. Lorsque `x-google-backend` est défini au niveau de l'opération et qu'aucun `path_translation` n'est spécifié, la valeur par défaut est `CONSTANT_ADDRESS`.
`deadline`	`double`	Non	`15.0`	Spécifiez le nombre de secondes d'attente avant d'obtenir une réponse complète à une requête. Les réponses qui dépassent ce délai expirent. Sur un point de terminaison SSE ou de transfert fragmenté, le délai limite toujours la durée de l'intégralité du flux. Sur un point de terminaison gRPC ou WebSocket, il limite l'intervalle entre les messages. Consultez la section Définir le délai de diffusion pour connaître les délais avant expiration qui s'appliquent à chaque type de requête. Omettez le champ ou définissez-le sur `0` pour utiliser la valeur par défaut. Une valeur négative est rejetée. Le délai avant expiration est configurable jusqu'à 3 600 secondes. Une passerelle sans streaming applique un maximum inférieur de 600 secondes, en rejetant un délai plus élevé lors de la création ou de la mise à jour de la passerelle, plutôt que lors de la création de la configuration de l'API.
`protocol`	`string`	Non	`http/1.1`	Définissez le protocole d'envoi d'une requête au backend. Les valeurs acceptées incluent `http/1.1` et `h2`. Les exigences de protocole dépendent du type de streaming : - gRPC : vous devez définir le protocole sur `h2`. - WebSockets : vous devez utiliser `http/1.1`. - Événements envoyés par le serveur (SSE) et diffusion incrémentielle des réponses : vous pouvez utiliser `http/1.1` ou `h2`. Nous vous recommandons d'utiliser `h2` pour améliorer les performances.

Objet `AI`

L'objet AI configure les fonctionnalités d'intelligence artificielle de votre service, telles que le routage vers les modèles.

Le tableau suivant décrit les champs de AI :

Champ	Type	Obligatoire	Par défaut	Description
`models`	`Models`	Non	Vide	Configurer les intégrations de modèles d'IA.

Objet `Models`

L'objet Models définit des configurations spécifiques au modèle.

Le tableau suivant décrit les champs de Models :

Champ	Type	Obligatoire	Par défaut	Description
`routing`	`Routing`	Non	Vide	Configurez les paramètres de routage vers les modèles.

Objet `Routing`

L'objet Routing définit les règles de routage vers les modèles et les routeurs.

Le tableau suivant décrit les champs de Routing :

Champ	Type	Obligatoire	Par défaut	Description
`routers`	`map[string]Router`	Non	Vide	Définissez des routeurs de modèles nommés.

Objet `Router`

L'objet Router définit un routeur de modèle nommé.

Le tableau suivant décrit les champs de Router :

Champ	Type	Obligatoire	Par défaut	Description
`defaultModel`	`DefaultModel`	Oui	Vide	Destination du modèle de remplacement requise, utilisée lorsqu'une requête entrante ne correspond à aucune règle explicite.
`rules`	`[Rule]`	Non	Vide	Liste des règles de routage explicites vers les modèles.

Objet `DefaultModel`

L'objet DefaultModel spécifie la destination de remplacement.

Le tableau suivant décrit les champs de DefaultModel :

Champ	Type	Obligatoire	Par défaut	Description
`backend`	`string`	Oui	Vide	Référencez un backend déclaré dans `x-google-api-management.backends`.
`targetModel`	`string`	Oui	Vide	Spécifiez l'identifiant du modèle cible au format `<provider>/<model-id>`. Pour les routes compatibles avec OpenAI, cette valeur est transmise en tant qu'attribut `model` sortant dans le corps de la requête lorsque le remplacement se produit.

Objet `Rule`

L'objet Rule définit une règle de routage vers les modèles explicite.

Le tableau suivant décrit les champs de Rule :

Champ	Type	Obligatoire	Par défaut	Description
`model`	`string`	Oui	Vide	La chaîne entrante correspond à l'attribut `model` dans la charge utile JSON du client. Pour les routes compatibles avec OpenAI, cette chaîne est transmise en tant qu'attribut `model` sortant dans le corps de la requête et doit être une chaîne `<provider>/<model-id>` valide.
`backend`	`string`	Oui	Vide	Référencez un backend déclaré dans `x-google-api-management.backends`.
`targetModel`	`string`	Oui	Vide	Spécifiez l'identifiant du modèle cible au format `<provider>/<model-id>`. Cette valeur sélectionne la traduction du fournisseur et est renvoyée dans le champ `model` de la réponse.

Objet `MCP`

L'objet MCP configure les fonctionnalités du protocole MCP (Model Context Protocol) pour votre service. Vous pouvez définir mcp sur une valeur booléenne ou un objet. Définissez cette option sur true pour activer le PCM de manière globale pour toutes les opérations éligibles avec les paramètres par défaut.

Le tableau suivant décrit les champs de l'objet MCP :

Champ	Type	Obligatoire	Par défaut	Description
`tools-list`	`ToolsList`	Non	Vide	Configurez les paramètres de la méthode MCP `tools/list`.

Objet `ToolsList`

L'objet ToolsList configure les paramètres de la méthode MCP tools/list.

Le tableau suivant décrit les champs de ToolsList :

Champ	Type	Obligatoire	Par défaut	Description
`security`	`map`	Non	Vide	Active l'authentification sur `tools/list`. Pour des raisons de sécurité, nous vous recommandons vivement de configurer cette option. Doit nommer exactement un schéma de sécurité de jeton JWT ou de clé API défini sous `components.securitySchemes`.

`x-google-auth`

Facultatif.

L'extension x-google-auth définit les paramètres d'authentification dans un objet de schéma de sécurité.

Le tableau suivant décrit les champs de x-google-auth :

Champ	Type	Obligatoire	Par défaut	Description
`issuer`	`string`	Non	Vide	Spécifiez l'émetteur d'un identifiant. Les valeurs peuvent être un nom d'hôte ou une adresse e-mail.
`jwksUri`	`string`	Non	Vide	Indiquez l'URI de l'ensemble de clés publiques du fournisseur pour valider la signature du jeton Web JSON. API Gateway accepte deux formats de clé publique asymétrique définis par cette extension OpenAPI : Le format prédéterminé JWK Par exemple : `jwksUri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"` X509. Par exemple : `jwksUri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"` Si vous utilisez un format de clé symétrique, définissez `jwksUri` sur l'URI d'un fichier contenant la chaîne de clé encodée en base64url.
`audiences`	`[string]`	Non	Vide	Répertoriez les audiences auxquelles le champ JWT `aud` doit correspondre lors de l'authentification JWT.
`jwtLocations`	`[JwtLocations]`	Non	Vide	Personnalisez les emplacements du jeton JWT. Par défaut, un jeton JWT est transmis dans l'en-tête `Authorization` (préfixé par "Bearer "), l'en-tête `X-Goog-Iap-Jwt-Assertion` ou le paramètre de requête `access_token`.

Objet `JwtLocations`

L'objet JwtLocations fournit des emplacements personnalisés pour le jeton JWT.

Le tableau suivant décrit les champs de JwtLocations :

Champ	Type	Obligatoire	Par défaut	Description
`header` \| `query`	`string`	Oui	N/A	Spécifiez le nom de l'en-tête contenant le jeton JWT ou le nom du paramètre de requête contenant le jeton JWT.
`valuePrefix`	`string`	Non	Vide	Pour l'en-tête uniquement. Lorsqu'elle est définie, sa valeur doit correspondre au préfixe de la valeur d'en-tête contenant le jeton JWT.

`x-google-quota`

Facultatif.

L'extension x-google-quota est utilisée sur des opérations individuelles pour spécifier les métriques définies dans x-google-api-management.metrics qui sont affectées par les requêtes adressées à cette opération.

x-google-quota est un objet contenant des paires clé/valeur, où chaque clé est un nom de métrique et la valeur est le coût entier de chaque requête adressée à l'opération. Exemple :

x-google-api-management:
  metrics:
    read-requests:
      displayName: "Greeter requests"
    write-requests:
      displayName: "Greeter requests by name"
  quota:
    limits:
      read-requests-limit:
        metric: read-requests
        values: 1
# Set at the top-level so this applies to all operations (unless overridden)
x-google-quota:
    read-requests: 1
paths:
  /v1/projects/projectId/pets:
    get:
      # Set at the path level, so it overrides the top level quota
      x-google-quota:
          write-requests: 1

`x-google-backend`

Obligatoire.

L'extension x-google-backend fait référence à un backend défini dans x-google-api-management.backends. Lorsqu'elle est utilisée, sa valeur doit être une chaîne correspondant au nom d'un backend défini dans x-google-api-management.backends. Vous devez définir cette extension pour API Gateway. Vous pouvez définir cette extension au niveau supérieur de votre document OpenAPI ou pour une opération individuelle afin de remplacer le backend de niveau supérieur.

Exemple :

x-google-api-management:
  backends:
    my-backend:
      address: myapp.run.app
x-google-backend: my-backend

`x-google-model-router`

Facultatif.

L'extension x-google-model-router fait référence à un routeur de modèle défini dans x-google-api-management.ai.models.routing.routers. Lorsqu'elle est utilisée, sa valeur doit être une chaîne correspondant au nom d'un routeur défini dans x-google-api-management.ai.models.routing.routers.

Cette extension n'est compatible qu'avec les spécifications OpenAPI 3.x. Elle ne peut pas être utilisée avec les spécifications OpenAPI 2.0 (Swagger). Vous ne pouvez définir cette extension qu'au niveau de l'opération individuelle pour les opérations utilisant la méthode HTTP POST. Vous ne pouvez pas spécifier à la fois x-google-model-router et x-google-backend pour la même opération, ni combiner des opérations de routage vers les modèles et de routage non vers les modèles sur différents chemins d'accès dans la même spécification d'API. De plus, vous ne pouvez pas utiliser le routage vers les modèles avec le protocole MCP (Model Context Protocol). L'activation de x-google-api-management.mcp rend cette extension indisponible.

Exemple :

x-google-api-management:
  backends:
    gemini-backend:
      address: https://aiplatform.googleapis.com/v1/...
  ai:
    models:
      routing:
        routers:
          my-router:
            defaultModel:
              backend: gemini-backend
              targetModel: google/gemini-3.5-flash-lite
paths:
  /v1/chat:
    post:
      x-google-model-router: my-router

`x-google-mcp-tool`

Facultatif.

L'extension x-google-mcp-tool est utilisée sur des opérations individuelles pour les exposer en tant qu'outils MCP et, éventuellement, remplacer le nom et la description de l'outil généré.

Accepte une valeur booléenne ou un objet.

Forme booléenne : définissez sur true pour activer cette opération. Définissez cette option sur false pour la désactiver, ce qui remplace l'activation globale.
Formulaire d'objet : activez et remplacez les paramètres d'outil générés.

Le tableau suivant décrit les champs de x-google-mcp-tool lorsqu'il est utilisé en tant qu'objet :

Champ	Type	Obligatoire	Par défaut	Description
`name`	`string`	Non	`operationId` de l'opération	Nom de l'outil MCP. Doit correspondre à `[A-Za-z0-9_.-]{1,128}` et être unique dans la spécification.
`description`	`string`	Non	Description de l'opération, avec retour au résumé	Description de l'outil MCP. Il s'agit du principal signal utilisé par un LLM pour sélectionner un outil.

Exemple :

paths:
  /v1/shelves/{shelf}:
    delete:
      operationId: deleteShelf
      summary: Delete a shelf.
      x-google-backend: bookstore-backend
      x-google-mcp-tool:
        name: delete_shelf
        description: "Permanently delete a shelf and every book on it."

`x-google-endpoint`

Facultatif.

L'extension x-google-endpoint permet de configurer les propriétés d'un serveur défini dans le tableau servers d'un document OpenAPI 3.x. Une seule entrée de serveur dans votre document OpenAPI peut utiliser l'extension x-google-endpoint.

L'extension définit également d'autres fonctionnalités de backend, y compris :

CORS : vous pouvez activer le partage de ressources interorigines (CORS) en définissant la propriété allowCors sur true.
Chemin de base : le chemin de base défini sur le serveur avec x-google-endpoint est utilisé pour votre API. Par exemple, la configuration suivante définit v1 comme chemin d'accès de base :

servers:
  - url: https://API_NAME.apigateway.PROJECT_ID.cloud.goog/v1
    x-google-endpoint: {}

Le tableau suivant décrit les champs de x-google-endpoint :

Champ	Type	Obligatoire	Par défaut	Description
`allowCors`	`bool`	Non	`false`	Autorisez les requêtes CORS.

`x-google-parameter`

Facultatif.

L'extension x-google-parameter est définie sur un élément parameter. Cela peut être utilisé lorsque le chemin d'accès utilise la modélisation de chemin d'accès pour spécifier que le comportement de correspondance avec double caractère générique doit être utilisé.

Le tableau suivant décrit les champs de x-google-parameter :

Champ	Type	Obligatoire	Description
`pattern`	`string`	Oui	Cette valeur doit être définie sur `**`.

Comprendre les limites des extensions OpenAPI

Ces extensions OpenAPI sont soumises à des limites spécifiques. Pour en savoir plus, consultez Limites des fonctionnalités OpenAPI 3.x.

Étapes suivantes

Explorez la spécification OpenAPI.
Modifiez une passerelle pour utiliser OpenAPI 3.0.

Extensions OpenAPI 3.x dans API Gateway

x-google-api-management

Objet Metric

Objet Quota

Objet QuotaLimit

Objet Backends

Objet AI

Objet Models

Objet Routing

Objet Router

Objet DefaultModel

Objet Rule

Objet MCP

Objet ToolsList

x-google-auth

Objet JwtLocations

x-google-quota

x-google-backend

x-google-model-router

x-google-mcp-tool

x-google-endpoint

x-google-parameter

Comprendre les limites des extensions OpenAPI

Étapes suivantes

`x-google-api-management`

Objet `Metric`

Objet `Quota`

Objet `QuotaLimit`

Objet `Backends`

Objet `AI`

Objet `Models`

Objet `Routing`

Objet `Router`

Objet `DefaultModel`

Objet `Rule`

Objet `MCP`

Objet `ToolsList`

`x-google-auth`

Objet `JwtLocations`

`x-google-quota`

`x-google-backend`

`x-google-model-router`

`x-google-mcp-tool`

`x-google-endpoint`

`x-google-parameter`