Déployer la configuration Endpoints

Une fois que vous avez configuré Cloud Endpoints dans un document OpenAPI, vous pouvez le déployer de sorte que Cloud Endpoints dispose des informations nécessaires pour gérer votre API. Pour déployer la configuration Endpoints, exécutez la commande gcloud endpoints services deploy. Cette commande utilise l'infrastructure de service, autrement dit la plate-forme de services de base de Google, utilisée par Cloud Endpoints et d'autres services pour créer et gérer des API et des services. Cette page explique comment déployer un document OpenAPI sur Cloud Endpoints.

Prérequis

Pour commencer, cette page suppose que vous avez :

Préparer la Google Cloud CLI pour le déploiement

Utilisez l'outil de ligne de commande gcloud pour déployer la configuration. Pour en savoir plus sur les commandes, consultez la documentation de référence sur gcloud.

Pour préparer le déploiement, procédez comme suit :

  1. Installez et initialisez gcloud CLI.
  2. Mettez à jour gcloud CLI :
    gcloud components update
  3. Assurez-vous que gcloud CLI est autorisé à accéder à vos données et services :
    gcloud auth login

    Un nouvel onglet de navigateur vous invite à choisir un compte.

  4. Définissez le projet par défaut. Remplacez [YOUR-PROJECT-ID] par l'ID de votre projet GCP :
    gcloud config set project [YOUR-PROJECT-ID]
  5. Si vous déployez le backend de l'API sur Kubernetes ou Kubernetes Engine, exécutez la commande suivante pour obtenir de nouveaux identifiants utilisateur qui serviront d'identifiants par défaut de l'application. Ces identifiants utilisateur sont nécessaires pour autoriser kubectl.
    gcloud auth application-default login
    Un nouvel onglet de navigateur s'ouvre et vous êtes invité à choisir un compte.

Valider la syntaxe openapi.json

Le fichier de document OpenAPI peut être au format YAML ou au format JSON. S'il est au format JSON, nous vous recommandons de vérifier la syntaxe avant de déployer le fichier. Pour vérifier que openapi.json est un fichier JSON bien formaté, vous pouvez l'ouvrir dans un éditeur de texte validant JSON, tel que vim, utiliser un service linter JSON en ligne, ou encore utiliser Python comme illustré ici :

python -m json.tool openapi.json

Pour améliorer la lisibilité, vous pouvez imprimer la version correctement formatée du fichier JSON :

python -m json.tool input.json > output.json

Remplacez input.json par le chemin d'accès à votre fichier openapi.json. output.json correspond au fichier JSON correctement formaté.

Valider votre document OpenAPI

Les constructions OpenAPI ne sont pas toutes actuellement compatibles avec Cloud Endpoints. Avant de déployer, vous pouvez valider votre document OpenAPI.

Pour valider votre document OpenAPI, procédez comme suit :

  1. Remplacez le répertoire par l'emplacement contenant votre document OpenAPI.

  2. Confirmez le projet Google Cloud dans lequel vous souhaitez créer le service. Si vous utilisez un nom de domaine personnalisé (par exemple, myapi.example.com), vous devez valider l'ID de projet renvoyé par la commande suivante, afin que le service soit créé dans le bon projet.

    gcloud config list project
    

    Si vous devez changer le projet par défaut, exécutez la commande suivante et remplacez [YOUR_PROJECT_ID] par l'ID du projet Google Cloud dans lequel vous souhaitez créer le service :

    gcloud config set project [YOUR_PROJECT_ID]
    
  3. Exécutez la commande suivante et remplacez [YOUR_OPENAPI_DOCUMENT] par le nom du document OpenAPI décrivant votre API :

    gcloud endpoints services deploy [YOUR_OPENAPI_DOCUMENT] --validate-only
    

La commande gcloud appelle ensuite l'API Service Management pour créer un service géré avec le nom que vous avez spécifié dans le champ host de votre document OpenAPI. Lorsque vous spécifiez l'indicateur --validate-only, un service est toujours créé, mais la configuration n'est pas déployée. Il n’existe pas de moyen de valider votre document OpenAPI sans créer de service. Bien que vous puissiez supprimer le service, Service Management ne vous permet pas de créer un service du même nom pendant une période d'environ 30 jours.

Déployer le document OpenAPI

Lorsque vous êtes prêt à déployer votre API, exécutez la Google Cloud CLI, qui utilise Service Management pour importer la configuration de votre API et créer (ou mettre à jour) un service géré.

Pour déployer votre document OpenAPI, procédez comme suit :

  1. Remplacez le répertoire par l'emplacement contenant votre document OpenAPI.

  2. Validez l'ID de projet renvoyé par la commande suivante, afin de vous assurer que le service est créé dans le projet correct.

    gcloud config list project
    

    Si vous devez changer le projet par défaut, exécutez la commande suivante et remplacez [YOUR_PROJECT_ID] par l'ID du projet Google Cloud dans lequel vous souhaitez créer le service :

    gcloud config set project [YOUR_PROJECT_ID]
    
  3. Exécutez la commande suivante et remplacez [YOUR_OPENAPI_DOCUMENT] par le nom du document OpenAPI décrivant votre API :

    gcloud endpoints services deploy [YOUR_OPENAPI_DOCUMENT]
    

La première fois que vous exécutez la commande ci-dessus, Service Management crée un nouveau service Cloud Endpoints dans le projet par défaut avec un nom correspondant au texte que vous avez spécifié dans le champ host de votre document OpenAPI, puis transfère la configuration de votre service.

Lors de la création et de la configuration du service, Service Management envoie des informations au terminal. Si l'opération réussit, une ligne semblable à la suivante affiche l'ID de configuration et le nom du service :

Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]

Dans l'exemple ci-dessus, 2017-02-13r0 correspond à l'ID de configuration du service et echo-api.endpoints.example-project-12345.cloud.goog au nom du service.

Une fois le déploiement réussi, vous pouvez consulter l'API sur la page Endpoints > Services dans la console Google Cloud.

Si vous recevez un message d'erreur, consultez la section Résoudre des problèmes de déploiement de la configuration Endpoints.

Redéployer

Lorsque vous modifiez un élément de votre document OpenAPI, veillez à le déployer à nouveau afin que Cloud Endpoints dispose de la version la plus récente de la configuration de service de votre API. Si vous avez déjà déployé ESP en ayant défini l'option rollout sur managed, vous n'avez pas besoin de redéployer ni de redémarrer ESP. Cette option configure ESP pour qu'il utilise la dernière configuration de service déployée. Si cette option est spécifiée, jusqu'à 5 minutes après le déploiement d'une nouvelle configuration de service, ESP détecte la modification et commence à l'utiliser automatiquement. Nous vous recommandons de spécifier cette option plutôt qu'un ID de configuration spécifique à utiliser par ESP.

Une fois le déploiement initial réalisé, vous pouvez attribuer à un utilisateur, un groupe ou un compte de service un rôle qui leur permet de redéployer la configuration Endpoints. Pour en savoir plus, consultez la page Accorder et révoquer les accès à des ressources.

Étapes suivantes