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 des 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 des 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 les limites de quota pour votre service.
`backends`	`map[string]Backend`	Oui	Vide	Configurez 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 des 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 du quota.

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 les 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	Faites référence à 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 client 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 correspondant au champ d'adresse. Il n'est nécessaire de spécifier manuellement `jwt_audience` 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 à distance déployés sur App Engine ou avec IAP, vous devez remplacer l'audience 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 du chemin d'accès lorsque vous transmettez 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 `pathTranslation` par défaut 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 pour 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 à transfert segmenté, le délai limite toujours la durée de l'ensemble du flux. Sur un point de terminaison gRPC ou WebSocket, il limite plutôt l'intervalle entre les messages. Consultez Définir le délai du flux pour connaître les délais d'attente qui s'appliquent à chaque type de requête. Le délai est configurable jusqu'à 3 600 secondes. Une passerelle non streaming applique une durée maximale inférieure de 600 secondes, en refusant un délai plus long 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 pour envoyer une requête au backend. Les valeurs acceptées sont `http/1.1` et `h2`. Les exigences concernant le 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 capacités d'intelligence artificielle de votre service, telles que le routage des 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 les 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 du modèle.

Objet `Routing`

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

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èle 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 lorsqu'une requête entrante ne correspond à aucune règle explicite.
`rules`	`[Rule]`	Non	Vide	Liste des règles de routage de modèle explicites.

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 en cas de secours.

Objet `Rule`

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

Le tableau suivant décrit les champs de Rule :

Champ	Type	Obligatoire	Par défaut	Description
`model`	`string`	Oui	Vide	Chaîne entrante correspondant à 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 MCP (Model Context Protocol) pour votre service. Vous pouvez définir mcp sur une valeur booléenne ou un objet. Définissez la valeur sur true pour activer MCP 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é JWT défini sous `components.securitySchemes`. L'authentification par clé API n'est pas disponible dans la version Preview publique.

`x-google-auth`

Facultatif.

L'extension x-google-auth définit les paramètres d'authentification dans un objet Security Scheme.

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	Fournissez l'URI de l'ensemble de clés publiques du fournisseur pour valider la signature du jeton Web JSON. API Gateway est compatible avec 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	Liste des audiences auxquelles le champ `aud` du jeton JWT doit correspondre lors de l'authentification JWT.
`jwtLocations`	`[JwtLocations]`	Non	Vide	Personnalisez les zones géographiques pour le jeton JWT. Par défaut, un jeton JWT est transmis dans l'en-tête `Authorization` (précédé de "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 JWT ou le nom du paramètre de requête contenant le 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 de l'en-tête contenant le 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 à 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'il est utilisé, 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'il est utilisé, 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 x-google-model-router et x-google-backend dans la même opération. Vous ne pouvez pas non plus combiner des opérations de routage de modèle et de routage non basé sur un modèle sur différents chemins d'accès au sein de la même spécification d'API. De plus, vous ne pouvez pas utiliser le routage de modèle avec le protocole MCP (Model Context Protocol). Si vous activez x-google-api-management.mcp, cette extension ne sera pas disponible.

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és.

Accepte une valeur booléenne ou un objet.

Formulaire booléen : définissez la valeur sur true pour activer cette opération. Définissez la valeur sur false pour le désactiver, en remplaçant une activation globale.
Formulaire d'objet : activez et remplacez les paramètres de l'outil générés.

Le tableau suivant décrit les champs de x-google-mcp-tool lorsqu'il est utilisé comme 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 la sélection d'outils.

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 des ressources entre origines multiples (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 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 des modèles de chemin d'accès pour spécifier que le comportement de correspondance à 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 présentent 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`