Extensions OpenAPI

Cloud Endpoints accepte un ensemble d'extensions propres à Google pour la spécification OpenAPI, qui configurent les comportements d'Extensible Service Proxy (ESP), d'Extensible Service Proxy V2 (ESPv2) et de Service Control. Cette page décrit les extensions propres à Google pour la spécification OpenAPI.

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

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 quels chemins d'URL doivent être autorisés via ESP.

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 répertoriées dans la spécification OpenAPI sont diffusées via ESP.

Avec all, les appels non configurés, avec ou sans clé API ou authentification des utilisateurs, passent par ESP vers l'API.

ESP traite les appels vers votre API en tenant compte de la casse. Par exemple, ESP 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.

Étant donné que la méthode widgets est répertoriée dans la spécification OpenAPI, ESP bloque la requête suivante, car elle ne possède pas de clé API :

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

Étant donné que la méthode Widgets n'est pas répertoriée dans la spécification OpenAPI, ESP 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 indique comment acheminer les requêtes vers des backends locaux ou distants. L'extension peut être spécifiée au premier niveau et/ou au niveau de l'opération d'une spécification OpenAPI.

Par défaut, ESP est configuré pour relayer l'ensemble du trafic vers un seul backend local. L'adresse du backend local est spécifiée par l'option --backend (par défaut, http://127.0.0.1:8081). Vous pouvez utiliser l'extension x-google-backend pour remplacer ce comportement par défaut, et spécifier un ou plusieurs backends locaux ou distants pouvant recevoir des requêtes.

L'extension x-google-backend peut également configurer d'autres paramètres pour les backends locaux et 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

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

Si une opération utilise x-google-backend, mais ne spécifie pas address, ESPv2 achemine les requêtes vers le backend local spécifié par l'option --backend.

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 pas jwt_audience ni disable_auth, ESPv2 définit automatiquement par défaut la valeur jwt_audience pour qu'elle corresponde à address. Si address n'est pas défini, ESPv2 définit automatiquement disable_auth sur true.

jwt_audience

jwt_audience: string

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

Lors de la configuration d'Endpoints pour le modèle sans serveur, le backend distant doit être sécurisé de manière à n'autoriser que le trafic provenant d'ESPv2. ESPv2 associe un jeton d'ID d'instance à l'en-tête Authorization lors de la transmission par proxy de requêtes. Le jeton d'ID d'instance représente le compte de service de l'environnement d'exécution utilisé pour déployer ESPv2. Le backend distant peut alors vérifier que la requête provient d'ESPv2 sur la base de ce jeton associé.

Par exemple, un backend distant déployé sur Cloud Run peut utiliser IAM pour :

1. Restreindre les appels non authentifiés en révoquant roles/run.invoker du compte principal spécial allUsers.
2. N'autoriser ESPv2 qu'à appeler le backend en attribuant le rôle roles/run.invoker au compte de service de l'environnement d'exécution ESPv2.

Par défaut, ESPv2 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 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, ESPv2 modifie les en-têtes des requêtes. Si l'en-tête Authorization d'une requête est déjà défini, ESPv2 va :

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 ESPv2 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 ESPv2 n'effectue aucune vérification lorsque les méthodes d'authentification ne sont pas configurées.

disable_auth

disable_auth: bool

Facultatif. Cette propriété détermine si ESPv2 doit empêcher l'obtention d'un jeton d'ID d'instance et son association à la requête.

Lors de la configuration du backend cible, vous ne souhaiterez peut-être pas utiliser IAP ou IAM pour authentifier les requêtes provenant d'ESPv2 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 du chemin d'accès utilisée par ESPv2 lors de la transmission par proxy de requêtes au backend cible.

Pour en savoir plus sur la traduction du chemin d'accès, consultez la section Comprendre la traduction du 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 reste non spécifié et ne se produit 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. Le délai par défaut est de 15.0 secondes.

Les valeurs non positives ne sont pas prises en compte. Dans ce cas, ESPv2 utilise automatiquement la valeur par défaut.

Le délai ne peut pas être désactivé, mais il peut être défini sur une valeur supérieure (par exemple, 3600.0 pendant une heure).

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 Google Cloud sans serveur.

Activer la compatibilité des backends dans ESP

ESPv2 détecte automatiquement le fait que x-google-backend est configuré.

Pour activer cette fonctionnalité, ESP requiert une modification de configuration manuelle. Activez la compatibilité de x-google-backend dans ESP en fournissant l'argument --enable_backend_routing lors de l'exécution du conteneur ESP. (Pour les environnements d'exécution dans lesquels vous ne contrôlez pas les options du conteneur ESP, cette option est déjà indiquée.) Voici un exemple d'activation de la compatibilité de x-google-backend lors du déploiement du conteneur ESP sur GKE (cet exemple repose sur l'exemple Tutoriel concernant Endpoints sur GKE) :

- name: esp
  image: gcr.io/endpoints-release/endpoints-runtime:1
  args: [
    "--http_port", "8081",
    "--service", "SERVICE_NAME",
    "--rollout_strategy", "managed",
    "--enable_backend_routing"
  ]

Comprendre la traduction du chemin d'accès

Lorsque ESP traite une requête, il prend son chemin d'origine et le traduit avant d'envoyer la 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 des paramètres de chemin 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 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 des paramètres de chemin 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 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 un DNS sur le domaine cloud.goog

Si vous avez déployé votre application sur Compute Engine ou Google Kubernetes Engine, vous pouvez créer une entrée DNS pour votre service Endpoints sur le domaine cloud.goog en ajoutant ce qui suit à votre document OpenAPI :

x-google-endpoints:
- name: "API_NAME.endpoints.PROJECT_ID.cloud.goog"
  target: "IP_ADDRESS"

Ajoutez l'extension x-google-endpoints au niveau supérieur de votre document OpenAPI (c'est-à-dire sans retrait ni imbrication). Vous devez configurer le nom de domaine au format : .endpoints.PROJECT_ID.cloud.goog.

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"
  target: "192.0.2.1"

Le domaine .cloud.goog est géré par Google et partagé par les clients Google Cloud. Les ID de projet Google Cloud étant globalement uniques, un nom de domaine au format .endpoints.PROJECT_ID.cloud.goog est un nom de domaine unique pour votre API.

Par souci de simplicité, configurez le champ host et le champ x-google-endpoints.name de sorte qu'ils soient identiques. Lorsque vous déployez votre document OpenAPI, Service Management crée :

• un service géré portant le nom que vous avez spécifié dans le champ host ;
• un enregistrement A DNS utilisant le nom et l'adresse IP que vous avez configurés dans l'extension x-google-endpoints.

Pour les API hébergées dans l'environnement flexible App Engine, vous pouvez utiliser le domaine appspot.com. Pour en savoir plus, consultez la page Configurer Endpoints.

Configurer ESP 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 plus d'informations sur la configuration d'ESP avec la compatibilité CORS, consultez la section Ajouter la compatibilité CORS à ESP.

Si vous avez besoin de mettre en œuvre une compatibilité CORS personnalisée dans votre code backend, définissez allowCors: True de sorte qu'ESP transmette toutes les requêtes CORS vers le code 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.

ESP accepte deux formats de clé publique asymétrique définis par l'extension OpenAPI x-google-jwks_uri :

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

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

• X509. Exemple :

  x-google-jwks_uri: "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 sur l'URI d'un fichier contenant la chaîne de clé encodée en base64url.

Si vous omettez x-google-jwks_uri, ESP suivra le protocole OpenID Connect Discovery pour détecter automatiquement l'URI JWKS pour le fournisseur OpenID indiqué. ESP envoie une requête à x-google-issuer/.well-known/openid-configuration, analyse la réponse JSON et lit l'URI JWKS à partir du champ de premier niveau jwks_uri.

Notez que l'omission de x-google-jwks_uri entraîne des temps de démarrage à froid plus élevés, car ESP doit effectuer un appel distant supplémentaire au démarrage. Par conséquent, il est recommandé d'omettre ce champ si l'URI JWKS change souvent. La plupart des fournisseurs OpenID certifiés (tels que Google, Auth0 et Okta) possèdent des URI JWKS stables.

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. Consultez la section Effectuer un appel authentifié à une API Endpoints pour obtenir des exemples sur la transmission d'un jeton JWT.

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 :

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 la liste des audiences auxquelles le champ aud du jeton JWT 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 aud du jeton JWT doit correspondre au champ host du document OpenAPI, sauf si l'indicateur --disable_jwt_audience_service_name_check est utilisé. Si l'indicateur est utilisé et que x-google-audiences n'est pas spécifié, le champ aud du jeton JWT n'est pas validé.

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 :

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 :

STANDARD: YOUR-LIMIT-FOR-THE-METRIC

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 :

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 au nom du service Endpoints. (Endpoints utilise comme nom de service le nom que vous avez spécifié dans le champ host de votre document OpenAPI.) 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 permet de nommer explicitement des API individuelles et d'établir une gestion des versions indépendante pour chacune d'entre elles.

Par exemple, vous pouvez configurer un service nommé api.example.com avec deux API, producer et consumer, avec les fragments de document OpenAPI ci-dessous :

• 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 endpoints services deploy producer.yaml consumer.yaml