Configurer Cloud Endpoints

Cloud Endpoints accepte les API décrites dans la version 2.0 de la spécification OpenAPI. Vous décrivez la surface de l'API et configurez les fonctionnalités de Cloud Endpoints, telles que les règles d'authentification ou les quotas, dans un document OpenAPI.

Endpoints utilise les champs obligatoires suivants de manière particulière dans votre document OpenAPI :

  • host
  • info.title
  • info.version
  • operationId

Cette page fournit des informations sur la manière dont Endpoints utilise les champs ci-dessus. Avec ces informations, vous pouvez terminer la préparation de votre document OpenAPI en vue de son déploiement.

Prérequis

Pour commencer, cette page suppose que vous avez :

host

Cloud Endpoints utilise comme nom de service le nom que vous avez configuré dans le champ host de votre document OpenAPI.

Le nom de votre service API doit être unique sur Google Cloud. Endpoints utilise des noms compatibles avec DNS pour identifier les services. Nous vous recommandons donc d'utiliser le nom de domaine ou le nom de sous-domaine de votre API en tant que nom de service. De cette manière, le nom du service qui apparaît sur la page Services Endpoints correspond au nom utilisé dans les requêtes adressées à votre API. De plus, si le nom du service est identique au nom du domaine, vous pouvez créer un portail Cloud Endpoints pour les utilisateurs de l'API. Endpoints doit répondre aux exigences suivantes concernant le nom du service :

  • La longueur maximale du nom de domaine est de 253 caractères.
  • Le nom de domaine doit commencer par une lettre minuscule.
  • Chaque section du nom de domaine, délimitée par des points, doit répondre aux exigences suivantes :
    • Doit commencer par une lettre minuscule.
    • Ne doit pas se terminer par un tiret.
    • Les caractères restants peuvent être des lettres minuscules, des chiffres ou des tirets.
    • La longueur ne doit pas dépasser 63 caractères.

Vous pouvez enregistrer votre propre domaine personnalisé (par exemple, example.com) ou utiliser un domaine géré par Google.

Utiliser un domaine géré par Google

Google possède et gère les domaines cloud.goog et appspot.com. Si vous souhaitez utiliser un domaine géré par Google, vous devez utiliser votre ID de projet Google Cloud dans le nom du service. Étant donné que les projets Google Cloud ont un ID de projet global unique, cette exigence garantit que vous disposez d'un nom de service unique.

Le nom de domaine que vous utilisez dépend du backend qui héberge votre API :

  • Pour les API hébergées dans l'environnement flexible App Engine, vous devez utiliser le domaine appspot.com. Le nom du service doit respecter le format ci-dessous, où YOUR_PROJECT_ID correspond à l'ID de votre projet Google Cloud :

    YOUR_PROJECT_ID.appspot.com

    Lorsque vous déployez votre API sur App Engine, une entrée DNS portant un nom au format YOUR_PROJECT_ID.appspot.com est créée automatiquement.

  • Pour les API hébergées sur Compute Engine, Google Kubernetes Engine ou Kubernetes, vous devez utiliser le domaine cloud.goog. Le nom du service doit respecter le format suivant, où YOUR_API_NAME correspond au nom de l'API :

    YOUR_API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog

    Pour l'utiliser comme nom de domaine de l'API, consultez la page Configurer un DNS sur le domaine cloud.goog.

Utiliser un domaine personnalisé

Si vous ne souhaitez pas utiliser un domaine géré par Google, vous pouvez utiliser un domaine personnalisé (par exemple, myapi.mycompany.com) que vous êtes autorisé à utiliser. Avant de déployer la configuration de l'API, suivez les étapes décrites sur la page Valider la propriété du domaine.

info.title

Le champ info.title correspond au nom convivial de votre API. La page Endpoints > Services de la console Google Cloud affiche le texte que vous configurez dans le champ info.title. Si vous disposez de plusieurs API par projet Google Cloud, le nom de l'API est affiché dans une liste lorsque vous ouvrez la page pour la première fois. Vous pouvez cliquer sur le nom de l'API pour ouvrir une autre page affichant les métriques, l'historique de déploiement et d'autres informations concernant l'API.

info.version

La page Endpoints > Services de la console Google Cloud affiche le numéro de version de votre API. Avant de déployer votre configuration d'API pour la première fois, procédez comme suit :

  • Définissez le numéro de version dans le champ info.version sur la version d'API applicable, par exemple 1.0.

  • Définissez le champ basePath sur le numéro de version majeure, par exemple /v1.

Pour en savoir plus sur la gestion des versions de votre API, consultez la section Gestion du cycle de vie de l'API.

operationId

Bien que le champ operationId soit facultatif dans la spécification OpenAPI, il est requis par Endpoints, car il est utilisé pour l'identification interne de l'opération. La chaîne que vous utilisez pour le champ operationId doit être unique dans l'API. Reportez-vous à la description de operationId dans la spécification OpenAPI pour en savoir plus sur les conventions de dénomination.

Étape suivante