Extensions OpenAPI 2.0 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. Cette page décrit les extensions personnalisées spécifiques à Google de la spécification OpenAPI 2.0 utilisées pour configurer les comportements d'API Gateway, tels que le routage du backend, l'authentification et les fonctionnalités de gestion d'API.

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

Convention d'attribution de noms

Le nom des extensions Google OpenAPI commence par le préfixe x-google-.

x-google-allow

x-google-allow: [configured | all]

Cette extension est utilisée au niveau supérieur d'une spécification OpenAPI pour indiquer les chemins d'URL qui doivent être autorisés via API Gateway.

Les valeurs possibles sont configured et all.

La valeur par défaut est configured, ce qui signifie que seules les méthodes d'API que vous avez listées dans votre spécification OpenAPI sont diffusées via API Gateway.

Lorsque all est utilisé, les appels non configurés (avec ou sans clé API ou authentification utilisateur) transitent par API Gateway vers votre API.

API Gateway traite les appels à votre API en tenant compte de la casse. Par exemple, API Gateway considère /widgets et /Widgets comme des méthodes d'API différentes.

Avec all, vous devez prendre des précautions supplémentaires dans deux domaines :

  • Règles d'authentification ou clés API
  • Routage de chemin d'accès au backend dans votre service

Les bonnes pratiques recommandent de configurer l'API de sorte qu'elle utilise un routage de chemin d'accès sensible à la casse. En utilisant un routage sensible à la casse, votre API affiche un code d'état HTTP de 404 lorsque la méthode demandée dans l'URL ne correspond pas au nom de la méthode API répertorié dans votre spécification OpenAPI. Notez que les frameworks d'application Web tels que Node.js Express comprennent un paramètre permettant d'activer ou de désactiver le routage sensible à la casse. Le comportement par défaut dépend du framework utilisé. Nous vous recommandons de vérifier les paramètres du framework pour vous assurer que le routage sensible à la casse est activé. Cette recommandation est en accord avec la spécification OpenAPI version 2.0, selon laquelle tous les noms de champs dans la spécification sont sensibles à la casse.

Exemple

Nous partons des principes suivants :

  • La propriété x-google-allow est définie sur all.
  • La méthode d'API widgets est répertoriée dans la spécification OpenAPI, mais pas la méthode Widgets.
  • Vous avez configuré la spécification OpenAPI de façon à exiger une clé API.

Comme widgets est listé dans votre spécification OpenAPI, API Gateway bloque la requête suivante, car elle ne comporte pas de clé API :

https://my-project-id.appspot.com/widgets

Comme Widgets n'est pas listé dans votre spécification OpenAPI, API Gateway transmet la requête suivante à votre service sans clé API :

https://my-project-id.appspot.com/Widgets/

Si votre API utilise un routage sensible à la casse (et que vous n'avez pas acheminé d'appels vers des "Widgets" vers un code quelconque), le backend de votre API affiche 404. Toutefois, si vous utilisez un routage non sensible à la casse, le backend de votre API achemine cet appel vers des "widgets".

Différents langages et frameworks appliquent différentes méthodes pour contrôler la sensibilité à la casse et le routage. Consultez la documentation du framework pour obtenir plus de détails.

x-google-backend

L'extension x-google-backend spécifie comment acheminer les requêtes vers des backends distants. L'extension peut être spécifiée au niveau supérieur, au niveau de l'opération ou aux deux niveaux d'une spécification OpenAPI.

L'extension x-google-backend peut également configurer d'autres paramètres pour les backends distants, tels que l'authentification et les délais avant expiration. Toutes ces configurations peuvent être appliquées opération par opération.

L'extension x-google-backend contient les champs suivants :

address

address: URL

Obligatoire. URL du backend cible. Le schéma de l'adresse doit être http ou https.

Lors du routage vers des backends distants (sans serveur), l'adresse doit être définie et la partie schéma doit être https.

jwt_audience | disable_auth

Une seule de ces deux propriétés doit être définie.

Si une opération utilise x-google-backend, mais ne spécifie ni jwt_audience, ni disable_auth, API Gateway utilise automatiquement la valeur par défaut de jwt_audience pour correspondre à address. Si address n'est pas défini, API Gateway définit automatiquement disable_auth sur true.

jwt_audience

jwt_audience: string

Facultatif. Audience JWT spécifiée lorsque API Gateway obtient un jeton d'ID d'instance, qui est ensuite utilisé lors de la requête de backend cible.

Lorsque vous configurez API Gateway pour Serverless, le backend distant doit être sécurisé pour n'autoriser que le trafic provenant d'API Gateway. API Gateway associe un jeton d'ID d'instance à l'en-tête Authorization lors de la transmission des requêtes par proxy. Le jeton d'ID d'instance représente le compte de service d'exécution utilisé pour déployer API Gateway. Le backend distant peut ensuite vérifier que la requête provient d'API Gateway en fonction de ce jeton associé.

Par exemple, un backend distant déployé sur Cloud Run peut utiliser Identity and Access Management (IAM) pour :

  1. Restreindre les appels non authentifiés en révoquant roles/run.invoker du compte principal spécial allUsers.
  2. Autorisez uniquement API Gateway à appeler le backend en attribuant le rôle roles/run.invoker au compte de service d'exécution d'API Gateway.

Par défaut, API Gateway crée le jeton d'ID d'instance avec une audience JWT correspondant au champ address. 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 address. Pour les backends distants déployés sur App Engine ou avec Identity-Aware Proxy (IAP), vous devez remplacer l'audience JWT. App Engine et IAP utilisent leur ID client OAuth comme audience attendue.

Lorsque cette fonctionnalité est activée, API Gateway modifie les en-têtes des requêtes. Si l'en-tête Authorization est déjà défini dans une requête, API Gateway :

  1. Copier la valeur d'origine dans un nouvel en-tête X-Forwarded-Authorization.
  2. Remplacer l'en-tête Authorization par le jeton d'ID d'instance.

Par conséquent, si un client API définit l'en-tête Authorization, un backend exécuté derrière API Gateway doit utiliser l'en-tête X-Forwarded-Authorization pour récupérer l'intégralité du jeton JWT. Le backend doit valider le jeton JWT dans cet en-tête, car API Gateway n'effectue pas de validation lorsque les méthodes d'authentification ne sont pas configurées.

Pour obtenir des exemples de configuration, consultez Créer une configuration d'API.

disable_auth

disable_auth: bool

Facultatif. Cette propriété détermine si API Gateway doit empêcher l'obtention d'un jeton d'ID d'instance et l'empêcher de l'associer à la requête.

Lorsque vous configurez votre backend cible, vous pouvez ne pas vouloir utiliser IAP ou IAM pour authentifier les requêtes provenant d'API Gateway si l'une des conditions suivantes s'applique :

  1. Le backend doit autoriser les appels non authentifiés.
  2. Le backend nécessite l'en-tête Authorization d'origine du client API et ne peut pas utiliser X-Forwarded-Authorization (comme décrit dans la section jwt_audience).

Dans ce cas, définissez ce champ sur true.

path_translation

path_translation: [ APPEND_PATH_TO_ADDRESS | CONSTANT_ADDRESS ]

Facultatif. Définit la stratégie de traduction de chemin d'accès utilisée par API Gateway lors de la transmission des requêtes au backend cible.

Pour en savoir plus sur la traduction de chemin d'accès, consultez la section Comprendre la traduction de chemin d'accès.

Lorsque x-google-backend est utilisé au niveau supérieur de la spécification OpenAPI, path_translation est défini par défaut sur APPEND_PATH_TO_ADDRESS. Lorsque x-google-backend est utilisé au niveau des opérations de la spécification OpenAPI, path_translation est défini par défaut sur CONSTANT_ADDRESS. Si le champ address n'est pas renseigné, path_translation ne sera pas spécifié et ne se produira pas.

deadline

deadline: double

Facultatif. Délai d'attente (en secondes) avant expiration d'une réponse complète d'une requête. Les réponses qui dépassent le délai défini 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. Le délai par défaut est de 15.0 secondes.

Omettez le champ ou définissez-le sur 0 pour utiliser la valeur par défaut. Une valeur négative utilise également la valeur par défaut, mais elle est obsolète : la création d'une configuration d'API avec une valeur négative renvoie un avertissement dans les métadonnées de l'opération, et sera rejetée dans une version ultérieure.

Le délai avant expiration peut être configuré jusqu'à 3600 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

protocol: [ http/1.1 | h2 ]

Facultatif. Protocole utilisé pour envoyer une requête au backend. Les valeurs acceptées sont http/1.1 et h2.

La valeur par défaut est http/1.1 pour les backends HTTP et HTTPS.

Pour les backends HTTP sécurisés (https://) compatibles avec HTTP/2, définissez ce champ sur h2 pour améliorer les performances. Il s'agit de l'option recommandée pour les backends sans serveur Google Cloud .

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.

Comprendre la traduction de chemin d'accès

Lorsqu'API Gateway traite les requêtes, il prend le chemin de la requête d'origine et le traduit avant d'envoyer une requête au backend cible. La façon dont cette traduction se produit exactement dépend de la stratégie de traduction utilisée. Il existe deux stratégies de traduction du chemin d'accès :

  • APPEND_PATH_TO_ADDRESS : le chemin de la requête envoyée au backend cible est calculé en ajoutant le chemin d'origine de la requête à l'URL address de l'extension x-google-backend.
  • CONSTANT_ADDRESS : le chemin de la requête cible est constant, tel que défini par l'URL address de l'extension x-google-backend. Si le chemin d'accès OpenAPI correspondant contient des paramètres, leurs noms et leurs valeurs deviennent des paramètres de requête.

Par exemple :

  • APPEND_PATH_TO_ADDRESS
    • address: https://my-project-id.appspot.com/BASE_PATH
    • Avec les paramètres de chemin d'accès OpenAPI
      • Chemin OpenAPI : /hello/{name}
      • Chemin de la requête : /hello/world
      • URL de la requête cible : https://my-project-id.appspot.com/BASE_PATH/hello/world
    • Sans paramètres de chemin d'accès OpenAPI
      • Chemin OpenAPI : /hello
      • Chemin de la requête : /hello
      • URL de la requête cible : https://my-project-id.appspot.com/BASE_PATH/hello
  • CONSTANT_ADDRESS
    • address : https://us-central1-my-project-id.cloudfunctions.net/helloGET
    • Avec les paramètres de chemin d'accès OpenAPI
      • Chemin OpenAPI : /hello/{name}
      • Chemin de la requête : /hello/world
      • URL de la requête cible : https://us-central1-my-project-id.cloudfunctions.net/helloGET?name=world
    • Sans paramètres de chemin d'accès OpenAPI
      • Chemin OpenAPI : /hello
      • Chemin de la requête : /hello
      • URL de la requête cible : https://us-central1-my-project-id.cloudfunctions.net/helloGET

x-google-endpoints

Cette section décrit les utilisations de l'extension x-google-endpoints.

Configurer API Gateway pour autoriser les requêtes CORS

Si votre API doit pouvoir être appelée depuis une application Web d'origine différente, elle doit être compatible avec le partage de ressources d'origines multiples (CORS). Pour en savoir plus sur la configuration d'API Gateway pour qu'il soit compatible avec CORS, consultez Ajouter la compatibilité CORS à API Gateway.

Si vous devez implémenter une compatibilité CORS personnalisée dans votre code de backend, définissez allowCors: True de sorte qu'API Gateway transmette toutes les requêtes CORS à votre code de backend :

x-google-endpoints:
- name: "API_NAME.endpoints.PROJECT_ID.cloud.goog"
  allowCors: True

Ajoutez l'extension x-google-endpoints au niveau supérieur de votre document OpenAPI (sans retrait ni imbrication), par exemple :

swagger: "2.0"
host: "my-cool-api.endpoints.my-project-id.cloud.goog"
x-google-endpoints:
- name: "my-cool-api.endpoints.my-project-id.cloud.goog"
  allowCors: True

x-google-issuer

x-google-issuer: URI | EMAIL_ADDRESS

Cette extension est utilisée dans la section OpenAPI securityDefinitions pour spécifier l'émetteur d'identifiants. Les valeurs peuvent prendre la forme d'un nom d'hôte ou d'une adresse e-mail.

x-google-jwks_uri

x-google-jwks_uri: URI

URI de la clé publique du fournisseur définie pour valider la signature du jeton Web JSON.

Le champ x-google-jwks_uri (OpenAPI 2.0) ou jwksUri (OpenAPI 3.x) est obligatoire. API Gateway accepte deux formats de clé publique asymétrique définis par cette extension OpenAPI :

  • Le format prédéterminé JWK Exemple :

    OpenAPI 2.0

    x-google-jwks_uri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"

    OpenAPI 3.x

    jwksUri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"
  • X509. Exemple :

    OpenAPI 2.0

    x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

    OpenAPI 3.x

    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 x-google-jwks_uri (OpenAPI 2.0) ou jwksUri (OpenAPI 3.x) sur l'URI d'un fichier contenant la chaîne de clé encodée en base64url.

x-google-jwt-locations

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 dans le paramètre de requête access_token.

Vous pouvez également utiliser l'extension x-google-jwt-locations de la section OpenAPI securityDefinitions pour fournir les emplacements personnalisés à partir desquels extraire le jeton JWT.

L'extension x-google-jwt-locations accepte une liste des adresses JWT. Chaque emplacement JWT contient les champs suivants :

Élément Description
header/query Obligatoire. Nom de l'en-tête contenant le jeton JWT ou nom du paramètre de requête contenant le jeton JWT.
value_prefix Facultatif. Pour l'en-tête uniquement. Lorsque value_prefix est défini, sa valeur doit correspondre au préfixe de la valeur d'en-tête contenant le jeton JWT.

Exemple :

x-google-jwt-locations:
  # Expect header "Authorization": "MyBearerToken <TOKEN>"
  - header: "Authorization"
    value_prefix: "MyBearerToken "
  # expect header "jwt-header-foo": "jwt-prefix-foo<TOKEN>"
  - header: "jwt-header-foo"
    value_prefix: "jwt-prefix-foo"
  # expect header "jwt-header-bar": "<TOKEN>"
  - header: "jwt-header-bar"
  # expect query parameter "jwt_query_bar=<TOKEN>"
  - query: "jwt_query_bar"

Si vous souhaitez n'accepter qu'un sous-ensemble des emplacements JWT par défaut, répertoriez-les explicitement dans l'extension x-google-jwt-locations. Par exemple, pour n'accepter que l'en-tête Authorization avec le préfixe "Bearer " :

  x-google-jwt-locations:
    # Support the default header "Authorization": "Bearer <TOKEN>"
    - header: "Authorization"
      value_prefix: "Bearer "

x-google-audiences

x-google-audiences: STRING

Cette extension est utilisée dans la section OpenAPI securityDefinitions pour fournir une liste d'audiences auxquelles le champ JWT aud doit correspondre lors de l'authentification JWT. Cette extension accepte une seule chaîne avec des valeurs séparées par une virgule. Les espaces ne sont pas autorisés entre les audiences. Lorsqu'il n'est pas spécifié, le champ JWT aud doit correspondre au champ host du document OpenAPI.

securityDefinitions:
  google_id_token:
    type: oauth2
    authorizationUrl: ""
    flow: implicit
    x-google-issuer: "https://accounts.google.com"
    x-google-jwks_uri: "https://www.googleapis.com/oauth2/v1/certs"
    x-google-audiences: "848149964201.apps.googleusercontent.com,841077041629.apps.googleusercontent.com"

x-google-management

L'extension x-google-management contrôle différents aspects de la gestion des API et contient les champs décrits dans cette section.

metrics

Le champ metrics, utilisé conjointement avec quota et x-google-quota, permet de configurer un quota pour l'API. Le quota permet de contrôler le débit auquel les applications peuvent appeler les méthodes dans l'API. Exemple :

x-google-management:
  metrics:
    - name: read-requests
      displayName: Read requests
      valueType: INT64
      metricKind: DELTA

Le champ metrics contient une liste avec les paires clé-valeur suivantes :

Élément Description
nom Obligatoire. Nom de cette métrique. En général, il s'agit du type de requête (par exemple, "read-requests" ou "write-requests") qui identifie de manière unique la métrique.
displayName

Facultatif, mais recommandé. Texte affiché pour identifier la métrique dans l'onglet Quotas de la page Endpoints > Services (Points de terminaison > Services) de la consoleGoogle Cloud . Ce texte est également présenté aux clients de votre API sur les pages Quotas sous IAM et administration et API et services. Le nom à afficher doit comporter 40 caractères au maximum.

Pour des raisons de lisibilité, l'unité de la limite de quota associée est automatiquement ajoutée au nom à afficher dans la consoleGoogle Cloud . Par exemple, si vous spécifiez "Requêtes de lecture" comme nom à afficher, "Requêtes de lecture par minute et par projet" s'affiche dans la consoleGoogle Cloud . Si elle n'est pas spécifiée, la mention"quota sans libellé " s'affiche pour les utilisateurs de votre API sur les pages Quotas sous IAM et administration et API et services.

Pour assurer la cohérence avec les noms à afficher des services Google listés sur la page Quotas que voient les utilisateurs de votre API, nous vous recommandons de suivre les consignes suivantes pour le nom à afficher :

  • Utilisez "Requests" lorsque vous ne disposez que d'une métrique.
  • Lorsque vous disposez de plusieurs métriques, chacune doit décrire le type de requête et contenir le mot "requests" (par exemple "Read requests" ou "Write requests").
  • Utilisez "quota units" au lieu de "requests" lorsque l'un des coûts associés à la métrique est supérieur à 1.
valueType Obligatoire. Doit être INT64.
metricKind Obligatoire. Doit être DELTA.

quota

Vous spécifiez la limite de quota pour une métrique définie dans la section quota. Exemple :

quota:
  limits:
    - name: read-requests-limit
      metric: read-requests
      unit: 1/min/{project}
      values:
        STANDARD: 5000

Le champ quota.limits contient une liste avec les paires clé-valeur suivantes :

Élément Description
nom Obligatoire. Nom de la limite, qui doit être unique au sein du service. Le nom, d'une longueur maximale de 64 caractères, peut contenir des lettres majuscules et minuscules, des chiffres et des tirets ("-").
métrique Obligatoire. Nom de la métrique à laquelle cette limite s'applique. Ce nom doit correspondre au texte spécifié dans le nom d'une métrique. Si le texte spécifié ne correspond pas à un nom de métrique, vous recevez un message d'erreur lorsque vous déployez votre document OpenAPI.
unité Obligatoire. Unité de la limite. Seul "1/min/{project}" est accepté, ce qui signifie que la limite est appliquée par projet et que l'utilisation est réinitialisée toutes les minutes.
valeurs Obligatoire. Limite pour la métrique. Il doit s'agir d'une paire clé-valeur, au format suivant :
STANDARD: YOUR-LIMIT-FOR-THE-METRIC
Remplacez YOUR-LIMIT-FOR-THE-METRIC par une valeur entière correspondant au nombre maximal de requêtes autorisées pour l'unité spécifiée (qui est uniquement par minute et par projet). Exemple :
values:
  STANDARD: 5000

x-google-quota

L'extension x-google-quota est utilisée dans la section OpenAPI paths pour associer une méthode de l'API à une métrique. Les méthodes pour lesquelles x-google-quota n'est pas défini ne sont pas soumises à des limites de quota. Exemple :

x-google-quota:
  metricCosts:
    read-requests: 1

L'extension x-google-quota contient l'élément suivant :

Élément Description
metricCosts Paire clé-valeur définie par l'utilisateur : "YOUR-METRIC-NAME": METRIC-COST.
  • "YOUR-METRIC-NAME": : le texte de "YOUR-METRIC-NAME" doit correspondre à un nom de métrique défini.
  • METRIC-COST: : valeur entière définissant le coût pour chaque requête. Lorsqu'une requête est générée, la métrique associée est incrémentée du coût spécifié. Le coût permet aux méthodes de pratiquer une utilisation à des rythmes différents à partir de la même métrique. Par exemple, si une métrique présente une limite de quota de 1 000 et un coût de 1, l'application appelante peut effectuer 1 000 requêtes par minute avant de dépasser la limite. Avec un coût de 2 pour la même métrique, une application appelante ne peut effectuer que 500 requêtes par minute avant de dépasser la limite.

Exemples de quotas

L'exemple suivant présente l'ajout d'une métrique et d'une limite pour les requêtes de lecture et les requêtes d'écriture.

x-google-management:
  metrics:
    # Define a metric for read requests.
    - name: "read-requests"
      displayName: "Read requests"
      valueType: INT64
      metricKind: DELTA
    # Define a metric for write requests.
    - name: "write-requests"
      displayName: "Write requests"
      valueType: INT64
      metricKind: DELTA
  quota:
    limits:
      # Rate limit for read requests.
      - name: "read-requests-limit"
        metric: "read-requests"
        unit: "1/min/{project}"
        values:
          STANDARD: 5000
      # Rate limit for write requests.
      - name: "write-request-limit"
        metric: "write-requests"
        unit: "1/min/{project}"
        values:
          STANDARD: 5000

paths:
  "/echo":
    post:
      description: "Echo back a given message."
      operationId: "echo"
      produces:
      - "application/json"
      responses:
        200:
          description: "Echo"
          schema:
            $ref: "#/definitions/echoMessage"
      parameters:
      - description: "Message to echo"
        in: body
        name: message
        required: true
        schema:
          $ref: "#/definitions/echoMessage"
      x-google-quota:
        metricCosts:
          read-requests: 1
      security:
      - api_key: []

x-google-api-name

Lorsque votre service ne contient qu'une seule API, le nom de l'API est identique à celui du service API Gateway. (API Gateway utilise le nom que vous spécifiez dans le champ host de votre document OpenAPI comme nom de votre service.) Lorsque votre service contient plus d'une API, vous spécifiez leurs noms en ajoutant l'extension x-google-api-name à votre document OpenAPI. L'extension x-google-api-name vous permet de nommer explicitement des API individuelles et d'établir une gestion des versions indépendante pour chaque API.

Par exemple, vous pouvez configurer un service nommé api.example.com avec deux API, producer et consumer, avec les fragments de document OpenAPI présentés ici :

  • API producer dans producer.yaml : 

    swagger: 2.0
host: api.example.com
x-google-api-name: producer
info:
  version: 1.0.3

  • API consumer dans consumer.yaml :

    swagger: 2.0
host: api.example.com
x-google-api-name: consumer
info:
  version: 1.1.0

Vous pouvez déployer les deux documents OpenAPI conjointement avec :

gcloud api-gateway api-configs create API_CONFIG_ID \
  --api=my-api \
  --openapi-spec="producer.yaml,consumer.yaml" \
  --project=my-project-id