Premiers pas avec l'environnement standard Endpoints pour App Engine

Vous trouverez sur cette page la procédure à suivre afin de configurer Cloud Endpoints pour App Engine. Endpoints utilise le proxy Extensible Service Proxy (ESP) en tant que passerelle API. Afin d'assurer la gestion des API pour App Engine, vous devez déployer le conteneur ESP prédéfini sur Cloud Run. Vous sécurisez ensuite votre application à l'aide du proxy Identity-Aware Proxy (IAP) afin qu'ESP puisse les appeler. Une fois la configuration finalisée, ESP intercepte toutes les requêtes adressées à votre application et effectue les vérifications nécessaires, telles que l'authentification, avant d'appeler l'application. Lorsque l'application répond, ESP rassemble et consigne les données de télémétrie. Vous pouvez afficher les métriques de votre application sur la page Endpoints > Services de Google Cloud Console.

Pour obtenir une présentation de Cloud Endpoints, consultez les pages À propos de Cloud Endpoints et Architecture Cloud Endpoints.

Liste de tâches

Tout au long du tutoriel, reportez-vous à la liste de tâches présentée ci-dessous. Toutes les tâches sont requises pour permettre à Endpoints de gérer votre application.

  1. Créez un projet Google Cloud et, si vous n'avez pas déployé votre propre instance App Engine, déployez un exemple d'application. Consultez la section Avant de commencer.
  2. Configurez IAP pour sécuriser votre application. Consultez la section Configurer IAP.
  3. Déployez le conteneur ESP sur Cloud Run. Consultez la section Déployer ESP.
  4. Créez un document OpenAPI décrivant votre API et configurez les routes vers votre instance App Engine. Consultez la section Configurer Endpoints.
  5. Déployez le document OpenAPI pour créer un service géré. Consultez la section Déployer la configuration Endpoints.
  6. Configurez ESP pour qu'il puisse trouver la configuration de votre service. Consultez la section Configurer ESP.
  7. Appelez une application. Consultez la section Envoyer une requête à l'API.
  8. Suivez l'activité de vos applications. Consultez la section Suivre l'activité de l'API.
  9. Faites le nécessaire pour éviter que des frais ne soient facturés sur votre compte Google Cloud. Consultez la section Effectuer un nettoyage.

Avant de commencer

Étant donné qu'Endpoints pour App Engine est en version alpha, nous formulons les recommandations suivantes :

  • Créez un projet Google Cloud à utiliser lorsque vous déployez le conteneur ESP vers Cloud Run.

  • Créez un projet ou sélectionnez-en un existant pour votre instance App Engine.

Avant de vous lancer, procédez comme suit :

  1. Dans Cloud Console, accédez à la page Gérer les ressources et créez un projet.

    Accéder à la page "Gérer les ressources"

  2. Assurez-vous que la facturation est activée pour votre projet.

    Découvrir comment activer la facturation

  3. Notez l'ID du projet, car vous en aurez besoin ultérieurement. Sur le reste de cette page, cet ID est appelé ESP_PROJECT_ID.

  4. Notez le numéro de projet, car vous en aurez besoin ultérieurement. Sur le reste de cette page, ce numéro est appelé ESP_PROJECT_NUMBER.

  5. Téléchargez et installez le SDK Cloud.

    Télécharger le SDK Cloud

  6. Si vous n'avez pas déployé votre propre instance App Engine, suivez les étapes décrites sur la page Guide de démarrage rapide d'App Engine correspondant à votre langage pour sélectionner ou créer un projet Google Cloud et déployer un exemple d'application avec l'outil de ligne de commande gcloud. Notez la région et l'ID de projet correspondant à l'emplacement de déploiement de vos applications. Sur le reste de cette page, cet ID est appelé APP_PROJECT_ID.

Configurer IAP pour sécuriser votre application

Pour sécuriser votre application App Engine, vous devez utiliser Identity-Aware Proxy (IAP) afin d'assurer l'authentification des requêtes.

Suivez les étapes de la section Activer IAP et assurez-vous que vous pouvez vous connecter à votre application.

En outre, lors de la configuration du client OAuth, notez l'ID client_id OAuth, qui sera appelé IAP_CLIENT_ID dans ce guide de démarrage rapide.

Déployer ESP

Pour déployer le conteneur ESP sur Cloud Run, procédez comme suit :

  1. Assurez-vous que le SDK Cloud est autorisé à accéder à vos données et services.
    1. Connectez-vous.
      gcloud auth login
    2. Dans le nouvel onglet de navigateur qui s'ouvre, choisissez un compte auquel a été attribué le rôle Éditeur ou Propriétaire dans le projet Google Cloud que vous avez créé pour déployer ESP dans Cloud Run.
  2. Définissez la région. Actuellement, seule la région us-central1 est disponible dans Cloud Run.
    gcloud config set run/region us-central1
  3. Déployez ESP pour Cloud Run. Remplacez CLOUD_RUN_SERVICE_NAME par le nom que vous souhaitez utiliser pour le service.
        gcloud beta run deploy CLOUD_RUN_SERVICE_NAME \
            --image="gcr.io/endpoints-release/endpoints-runtime-serverless:1.30.0" \
            --allow-unauthenticated \
            --project=ESP_PROJECT_ID
        

    Si elle aboutit, la commande affiche un message semblable à celui-ci :

        Service [gateway] revision [gateway-00001] has been deployed and is serving
        traffic at https://gateway-12345-uc.a.run.app

    Dans l'exemple ci-dessus, gateway correspond au nom du service Cloud Run.

  4. Notez le nom d'hôte dans l'URL. Spécifiez le nom d'hôte dans le champ host de votre document OpenAPI.
  5. Votre service Cloud Run est public sur Internet. Si vous souhaitez ajouter des fonctionnalités d'authentification, nous vous recommandons d'utiliser l'une des méthodes d'authentification compatibles avec Endpoints.

Configurer Endpoints

Vous devez disposer d'un document OpenAPI basé sur la version 2.0 de la spécification OpenAPI décrivant la surface de vos applications, ainsi que les conditions requises pour l'authentification. Vous devez également ajouter un champ spécifique à Google contenant l'URL de chaque application afin qu'ESP dispose des informations nécessaires pour l'appeler. Si vous débutez avec OpenAPI, consultez la page Présentation d'OpenAPI pour en savoir plus.

  1. Créez un fichier texte intitulé openapi-appengine.yaml. (Pour des raisons de commodité, cette page utilise ce nom de fichier pour désigner le document OpenAPI, mais vous pouvez le nommer autrement si vous préférez.)
  2. Chacune de vos applications doit être répertoriée dans la section paths du fichier openapi-appengine.yaml. Exemple :
          swagger: '2.0'
          info:
            title: Cloud Endpoints + App Engine
            description: Sample API on Cloud Endpoints with an App Engine backend
            version: 1.0.0
          host: HOST
          schemes:
            - https
          produces:
            - application/json
          x-google-backend:
            address: https://APP_PROJECT_ID.REGION.r.appspot.com
            jwt_audience: IAP_CLIENT_ID
          paths:
            /hello:
              get:
                summary: Greet a user
                operationId: hello
                responses:
                  '200':
                    description: A successful response
                    schema:
                      type: string
        
  3. Dans le champ address de la section x-google-backend, remplacez APP_PROJECT_ID par l'ID de votre projet Google Cloud, REGION par la région GCP où vous avez déployé App Engine et IAP_CLIENT_ID par l'ID client OAuth que vous avez créé lors de la configuration d'IAP.
  4. Dans le champ host, ajoutez le nom d'hôte de l'URL de diffusion créée par Cloud Run pour ESP. N'incluez pas l'identifiant du protocole https://. Exemple :
        swagger: '2.0'
          info:
            title: Cloud Endpoints + App Engine
            description: Sample API on Cloud Endpoints with an App Engine backend
            version: 1.0.0
          host: gateway-12345-uc.a.run.app
        

    Endpoints utilise le nom que vous configurez dans le champ host comme nom de service.

  5. Enregistrez votre document OpenAPI.

Pour en savoir plus sur les champs du document OpenAPI requis par Endpoints, consultez la page Configurer Endpoints.

Déployer la configuration Endpoints

Pour déployer la configuration Endpoints, exécutez la commande gcloud endpoints services deploy. Cette commande crée un service géré à l'aide de Service Management.

Pour déployer la configuration Endpoints :

  1. Assurez-vous que vous vous trouvez dans le répertoire contenant votre document OpenAPI.

  2. Téléchargez la configuration et créez un service géré.

        gcloud endpoints services deploy openapi-appengine.yaml \
          --project ESP_PROJECT_ID
        

    Vous créez ainsi un service Endpoints avec le nom spécifié dans le champ host du fichier openapi-appengine.yaml. Le service est configuré conformément à votre document OpenAPI.

Lors de la création et de la configuration du service, Service Management envoie des informations au terminal. Une fois le déploiement terminé, un message semblable au suivant s'affiche :

    Service Configuration [2019-02-01-r0] uploaded for service [gateway-12345-uc.a.run.app]
    

Dans l'exemple ci-dessus, 2019-02-01-r0 correspond à l'ID de configuration de service et gateway-12345-uc.a.run.app au nom du service Endpoints. L'ID de configuration de service se compose d'un horodatage, suivi d'un numéro de révision. Si vous déployez à nouveau openapi-appengine.yaml le même jour, le numéro de révision est incrémenté dans l'ID de configuration de service. Vous pouvez afficher la configuration de service et l'historique de déploiement en accédant à la page Endpoints > Services de Cloud Console.

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

Vérifier les services requis

Endpoints et ESP nécessitent au minimum l'activation des services Google suivants :
Nom Titre
servicemanagement.googleapis.com API Service Management
servicecontrol.googleapis.com API Service Control
endpoints.googleapis.com Google Cloud Endpoints

Dans la plupart des cas, la commande gcloud endpoints services deploy permet d'activer ces services requis. Toutefois, la commande gcloud peut aboutir sans pour autant activer les services requis dans les cas suivants :

  • Vous avez utilisé une application tierce telle que Terraform et vous n'incluez pas ces services.

  • Vous avez déployé la configuration Endpoints dans un projet Google Cloud existant dans lequel ces services étaient explicitement désactivés.

Utilisez la commande suivante pour vérifier que les services requis sont activés :

gcloud services list
    

Si les services requis ne s'affichent pas, activez-les :

gcloud services enable servicemanagement.googleapis.com
    gcloud services enable servicecontrol.googleapis.com
    gcloud services enable endpoints.googleapis.com

Activez également votre service Endpoints :

gcloud services enable ENDPOINTS_SERVICE_NAME

Pour déterminer le nom ENDPOINTS_SERVICE_NAME, vous pouvez procéder comme suit :

  • Après avoir déployé la configuration Endpoints, accédez à la page Endpoints de Cloud Console. La liste des noms ENDPOINTS_SERVICE_NAME possibles s'affiche dans la colonne Nom du service.

  • Pour OpenAPI, le nom ENDPOINTS_SERVICE_NAME correspond à ce que vous avez spécifié dans le champ host de votre spécification OpenAPI. Pour gRPC, le nom ENDPOINTS_SERVICE_NAME correspond à ce que vous avez spécifié dans le champ name de votre configuration Endpoints gRPC.

Pour en savoir plus sur les commandes gcloud, consultez la page Services gcloud.

Configurer ESP

Configurez ESP pour qu'il puisse trouver la configuration de votre service Endpoints. Attribuez ensuite à ESP l'autorisation Cloud IAM permettant d'appeler votre application protégée par IAP.

Pour configurer ESP, procédez comme suit :

  1. Définissez le nom du service Endpoints afin qu'ESP puisse localiser et charger votre configuration Endpoints. Dans cette commande :

    • Remplacez YOUR_SERVICE_NAME par le nom de votre service Endpoints. Il s'agit du nom que vous avez spécifié dans le champ host du document OpenAPI.
    • Remplacez CLOUD_RUN_SERVICE_NAME par le nom de votre service Cloud Run.
        gcloud beta run services update CLOUD_RUN_SERVICE_NAME \
           --set-env-vars ENDPOINTS_SERVICE_NAME=YOUR_SERVICE_NAME \
           --project ESP_PROJECT_ID
        
  2. Si vous souhaitez configurer d'autres options de démarrage ESP pour Endpoints, telles que l'activation de CORS, vous pouvez transmettre les arguments dans la variable d'environnement ESP_ARGS :

        gcloud beta run services update CLOUD_RUN_SERVICE_NAME \
           --set-env-vars="^|^ENDPOINTS_SERVICE_NAME=YOUR_SERVICE_NAME|ESP_ARGS=--rollout_strategy=managed,--cors_preset=basic" \
           --project ESP_PROJECT_ID
        

    Vous devez indiquer le nom du service (ENDPOINTS_SERVICE_NAME) ainsi qu'une stratégie de déploiement (--rollout_strategy).

  3. Attribuez à ESP l'autorisation permettant d'appeler votre application sécurisée par IAP. Exécutez la commande suivante. Dans la commande :

    • Remplacez APP_PROJECT_ID par l'ID de votre projet App Engine.
    • Remplacez ESP_PROJECT_NUMBER par le numéro du projet que vous avez créé pour ESP. Pour ce faire, vous pouvez accéder à la console IAM, puis rechercher le compte de service Compute par défaut, qui correspond au compte de service utilisé dans l'option member.
        gcloud projects add-iam-policy-binding APP_PROJECT_ID \
            --member "serviceAccount:ESP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
            --role "roles/iap.httpsResourceAccessor"
        

Envoyer des requêtes à l'API

Cette section montre comment envoyer des requêtes à votre API.

  1. Créez une variable d'environnement pour le nom de votre service Endpoints. Il s'agit du nom que vous avez spécifié dans le champ host du document OpenAPI. Exemple :
    • Linux ou macOS:

      export ENDPOINTS_HOST=gateway-12345-uc.a.run.app

    • Windows PowerShell:

      $Env: ENDPOINTS_HOST="gateway-12345-uc.a.run.app"

Linux ou macOS

Utilisez curl pour envoyer une requête HTTP à l'aide de la variable d'environnement ENDPOINTS_HOST que vous avez définie à l'étape précédente.

    curl --request GET \
       --header "content-type:application/json" \
       "https://${ENDPOINTS_HOST}/hello"

PowerShell

Utilisez Invoke-WebRequest pour envoyer une requête HTTP à l'aide de la variable d'environnement ENDPOINTS_HOST que vous avez définie à l'étape précédente.

    (Invoke-WebRequest -Method GET `
        -Headers @{"content-type"="application/json"} `
        -URI "https://$Env:ENDPOINTS_HOST/hello").Content
    

Dans l'exemple ci-dessus, les deux premières lignes se terminent par un accent grave. Lorsque vous collez l'exemple dans PowerShell, assurez-vous qu'il n'y a pas d'espace après les accents graves. Pour plus d'informations sur les options utilisées dans l'exemple de requête, consultez la page Invoke-WebRequest dans la documentation Microsoft.

Application tierce

Vous pouvez utiliser une application tierce, par exemple une requête Postman de l'extension du navigateur Chrome.

  • Sélectionnez GET comme verbe HTTP.
  • Pour l'en-tête, sélectionnez la clé content-type et la valeur application/json.
  • Utilisez l'URL réelle au lieu de la variable d'environnement, par exemple :

    https://gateway-12345-uc.a.run.app/hello
        

Si vous ne recevez pas de réponse positive, consultez la section Résoudre des problèmes concernant les erreurs de réponse.

Vous venez de déployer et de tester une API dans Endpoints.

Suivre l'activité de l'API

  1. Consultez les graphiques d'activité de votre API sur la page Endpoints > Services de Cloud Console.

    Afficher les graphiques d'activité Endpoints

    Il peut s'écouler quelques instants avant que la requête ne soit reflétée dans les graphiques.

  2. Consultez les journaux de requêtes de votre API sur la page de la visionneuse de journaux.

    Afficher les journaux de requête Endpoints

Créer un portail des développeurs pour l'API

Vous pouvez utiliser le portail Cloud Endpoints pour créer un portail des développeurs, c'est-à-dire un site Web qui vous permet d'interagir avec l'exemple d'API. Pour en savoir plus, consultez la page Présentation du portail Cloud Endpoints.

Nettoyer

Pour éviter que les ressources utilisées dans ce guide de démarrage rapide soient facturées sur votre compte Google Cloud, procédez comme suit :

Pour plus d'informations sur l'arrêt des services utilisés par ce tutoriel, consultez la page Supprimer une API et des instances d'API.

Étape suivante