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.

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 Backend

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

Le tableau suivant décrit les champs de Backend :

Champ Type Obligatoire Par défaut Description
address string Non 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êcher 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.
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.

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

Indiquez l'URI de la clé publique du fournisseur définie pour valider la signature du jeton Web JSON. API Gateway accepte deux formats de clé publique asymétrique définis par cette extension OpenAPI :

  1. Le format prédéterminé JWK Par exemple : jwksUri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"
  2. 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 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 définit les limites de quota. Vous pouvez définir cette extension au niveau supérieur de votre document OpenAPI ou pour une opération individuelle.

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

Champ Type Obligatoire Description
self map[string]int64 Oui L'objet quota (self) fait référence à toutes les métriques définies dans l'objet. Dans ce cas, mappez une métrique (telle que read-requests) à un montant pour incrémenter la métrique. Les requêtes sont refusées lorsque la valeur de la métrique atteint la limite de quota.

x-google-backend

Obligatoire.

L'extension x-google-backend fait référence à un backend défini dans x-google-api-management. 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.

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

Champ Type Obligatoire Description
self string Oui Faites référence à l'ID d'un backend défini dans x-google-api-management.

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. Il peut être utilisé lorsque le chemin 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