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 :
- un projet Google Cloud ;
- une connaissance de base d'OpenAPI ;
- un document OpenAPI au format décrit dans Structure de base Swagger dans la documentation Google Cloud.
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 domainescloud.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
Points de terminaison > la page Services de la console Google Cloud affiche
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 exemple1.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.