Extensions OpenAPI 3.x dans API Gateway

API Gateway accepte un ensemble d'extensions propres à 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 propres à Google pour la spécification OpenAPI 3.x.

Bien que les exemples donnés soient au format YAML, le format JSON est également pris en charge.

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 les 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	Configurer les fonctionnalités d'intelligence artificielle, y compris le routage des modèles.

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 les limites de quota.

Objet Quota Limit

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. 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 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 lors de la transmission par proxy de 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 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 expiration d'une réponse complète d'une requête. Les réponses qui dépassent ce délai expirent. La limite maximale du délai est de 600 secondes.
protocol	string	Non	http/1.1	Définissez le protocole pour envoyer une requête au backend. Les valeurs acceptées incluent http/1.1 et h2.

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 des modèles.

Objet Routing

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

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