Configurer Cloud Endpoints OpenAPI pour l'environnement standard avec ESPv2

Vous trouverez sur cette page la procédure à suivre afin de configurer Cloud Endpoints pour App Engine. Cloud Endpoints utilise le proxy Extensible Service Proxy v2 (ESPv2) en tant que passerelle API. Afin d'assurer la gestion des API pour App Engine, vous devez déployer le conteneur ESPv2 prédéfini sur Cloud Run. Vous sécurisez ensuite votre application à l'aide du proxy Identity-Aware Proxy (IAP) afin que seul ESPv2 puisse l'appeler.

Une fois la configuration finalisée, ESPv2 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, ESPv2 collecte et consigne les données de télémétrie, comme illustré dans la figure ci-dessous. Vous pouvez afficher les métriques de votre application sur la page Endpoints > Services de la console Google Cloud.

Architecture Endpoints

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

Migrer vers ESPv2

Les versions précédentes de Cloud Endpoints acceptaient l'utilisation du proxy Extensible Service Proxy (ESP) avec Cloud Functions. Si vous souhaitez migrer des API existantes vers ESPv2, consultez la page Migrer vers Extensible Service Proxy V2 pour en savoir plus.

Liste de tâches

Consultez la liste de tâches suivante au fur et à mesure que vous suivez le tutoriel. Toutes les tâches sont requises pour permettre à Endpoints de gérer votre application.

Créez un projet Google Cloud et, si vous n'avez pas déployé votre propre environnement App Engine, déployez un exemple d'application backend. Consultez la section Avant de commencer.
Configurez IAP pour sécuriser votre application. Consultez la section Configurer IAP.
Réservez un nom d'hôte Cloud Run pour le service ESPv2. Consultez la page Réserver un nom d'hôte Cloud Run.
Créez un document OpenAPI décrivant votre API et configurez les routes vers votre instance App Engine. Consultez la section Configurer Endpoints.
Déployez le document OpenAPI pour créer un service géré. Consultez la section Déployer la configuration Endpoints.
Créez une image ESPv2 pour Docker avec votre configuration de service Endpoints. Consultez la section Créer une nouvelle image ESPv2.
Déployez le conteneur ESPv2 dans Cloud Run. Accordez ensuite à ESPv2 l'autorisation IAM (Identity and Access Management) d'appeler votre service. Consultez la section Déployer le conteneur ESPv2.
Appelez l'application. Consultez la section Envoyer une requête à l'API.
Suivez l'activité de vos applications. Consultez la section Suivre l'activité de l'API.
Faites le nécessaire pour éviter que des frais ne soient facturés sur votre compte Google Cloud. Consultez la section Effectuer un nettoyage.

Coûts

Dans ce document, vous utilisez les composants facturables suivants de Google Cloud :

Obtenez une estimation des coûts en fonction de votre utilisation prévue à l'aide du simulateur de coût. Les nouveaux utilisateurs de Google Cloud peuvent bénéficier d'un essai gratuit.

Une fois que vous avez terminé les tâches décrites dans ce document, vous pouvez éviter de continuer à payer des frais en supprimant les ressources que vous avez créées. Pour en savoir plus, consultez la section Effectuer un nettoyage.

Avant de commencer

Avant de vous lancer, procédez comme suit :

Dans la console Google Cloud, accédez à la page Gérer les ressources et créez un projet.
Accéder à la page Gérer les ressources
Assurez-vous que la facturation est activée pour votre projet.
Découvrir comment activer la facturation
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.
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.
Téléchargez et installez la Google Cloud CLI.
Télécharger la gcloud CLI
Si vous n'avez pas déployé votre propre environnement App Engine backend, suivez les étapes du Guide de démarrage rapide d'App Engine. Notez la région et l'ID de projet correspondant à l'emplacement de déploiement de votre application. 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 le proxy 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 le client_id OAuth, qui est appelé IAP_CLIENT_ID dans ce tutoriel.

Réserver un nom d'hôte Cloud Run

Vous devez réserver un nom d'hôte Cloud Run pour le service ESPv2 afin de configure le document OpenAPI ou la configuration du service gRPC. Pour réserver un nom d'hôte, vous devez déployer un exemple de conteneur dans Cloud Run. Vous deploy par la suite le conteneur ESPv2 sur le même service Cloud Run.

Assurez-vous que gcloud CLI 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 disposant du rôle Éditeur ou Propriétaire dans le projet Google Cloud que vous avez créé pour déployer ESPv2 dans Cloud Run.

Définissez la région.

gcloud config set run/region us-central1

Déployez l'exemple d'image gcr.io/cloudrun/hello dans Cloud Run. Remplacez CLOUD_RUN_SERVICE_NAME par le nom que vous souhaitez utiliser pour le service.

gcloud run deploy CLOUD_RUN_SERVICE_NAME \
    --image="gcr.io/cloudrun/hello" \
    --allow-unauthenticated \
    --platform managed \
    --project=ESP_PROJECT_ID

Si elle réussit, la commande affiche un message semblable à celui-ci :

Service [CLOUD_RUN_SERVICE_NAME] revision [CLOUD_RUN_SERVICE_NAME-REVISION_NUM] has been deployed and is serving traffic at CLOUD_RUN_SERVICE_URL

Par exemple, si vous définissez CLOUD_RUN_SERVICE_NAME sur gateway :

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

Dans cet exemple, https://gateway-12345-uc.a.run.app correspond à CLOUD_RUN_SERVICE_URL et gateway-12345-uc.a.run.app à CLOUD_RUN_HOSTNAME.

Notez CLOUD_RUN_SERVICE_NAME et CLOUD_RUN_HOSTNAME. Vous déploierez par la suite ESPv2 sur le service Cloud Run CLOUD_RUN_SERVICE_NAME. Spécifiez CLOUD_RUN_HOSTNAME dans le champ host du document OpenAPI.

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'ESPv2 dispose des informations nécessaires pour appeler une application. Si vous débutez avec OpenAPI, consultez la page Présentation d'OpenAPI pour en savoir plus.

Créez un fichier texte intitulé openapi-appengine.yaml. Pour des raisons de commodité, cet article utilise ce nom de fichier pour désigner le document OpenAPI, mais vous pouvez le nommer autrement si vous préférez.

Votre application backend App Engine est définie en haut du fichier openapi-appengine.yaml, dans une définition x-google-backend. 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: CLOUD_RUN_HOSTNAME
  schemes:
    - https
  produces:
    - application/json
  x-google-backend:
    address: https://APP_PROJECT_ID.REGION.r.appspot.com
    jwt_audience: IAP_CLIENT_ID
    protocol: h2
  paths:
    /:
      get:
        summary: Greet a user
        operationId: hello
        responses:
          '200':
            description: A successful response
            schema:
              type: string

La mise en retrait est importante pour le format YAML. Par exemple, le champ host doit se trouver au même niveau que info.

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 dans laquelle 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.
Dans le champ host, spécifiez CLOUD_RUN_HOSTNAME, c'est-à-dire la partie nom d'hôte de l'URL réservée, comme indiqué ci-dessus dans la section Réserver un nom d'hôte Cloud Run. 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
```
Notez la valeur de la propriété title dans le fichier openapi-appengine.yaml :
```
title: Cloud Endpoints + App Engine
```
La valeur de la propriété title devient le nom du service Endpoints après le déploiement de la configuration.
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 :

Assurez-vous que vous vous trouvez dans le répertoire contenant votre document OpenAPI.
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 [CONFIG_ID] uploaded for service [CLOUD_RUN_HOSTNAME]
```
CONFIG_ID correspond à l'ID unique de configuration du service Endpoints créé par le déploiement. Exemple :
```
Service Configuration [2019-02-01r0] uploaded for service [gateway-12345-uc.a.run.app]
```
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 du service et l'historique de déploiement sur la page Endpoints > Services de 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.

Vérifier les services requis

Cloud Endpoints et ESP nécessitent au minimum l'activation des services Google suivants:

Nom	Title (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, bien que la commande gcloud ait abouti, elle n'active pas 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 nécessaires sont activés :

gcloud services list

Si les services requis ne sont pas répertoriés, 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 la valeur de ENDPOINTS_SERVICE_NAME, vous pouvez effectuer l'une des opérations suivantes :

Après avoir déployé la configuration des points de terminaison, accédez à la page Points de terminaison de la console Cloud. La liste des valeurs ENDPOINTS_SERVICE_NAME possibles s'affiche dans la colonne Nom du service.
Pour OpenAPI, ENDPOINTS_SERVICE_NAME correspond à ce que vous avez spécifié dans le champ host de votre spécification OpenAPI. Pour gRPC, 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.

Créer une image ESPv2

Créez la configuration du service Endpoints dans une nouvelle image ESPv2 pour Docker. Vous déploierez par la suite cette image sur le service Cloud Run réservé.

Remarque :

Cette étape est obligatoire.

La configuration de service doit être intégrée à une nouvelle image Docker, car Cloud Run est un service avec scaling à zéro instance. Cela signifie qu'en l'absence de trafic, toutes les instances sont supprimées. Lorsque le trafic augmente, des instances sont créées à la demande. Ce type de création d'instances de service est également appelé démarrage à froid. Pour en savoir plus, consultez la documentation concernant la simultanéité de Cloud Run.

Si l'image Docker ne contenait pas la configuration du service, Cloud Run devrait effectuer deux appels d'API à Google Service Management à chaque démarrage à froid. Ces appels seraient alors comptabilisés dans votre quota d'API Google Service Management.

En créant la configuration du service dans l'image ESPv2 pour Docker, vous supprimez les deux appels d'API, ce qui évite d'affecter le quota du service Google Service Management. Cette étape accélère également la création de la nouvelle instance du service et réduit la latence des requêtes qui attendent la nouvelle instance.

Vous devez exécuter à nouveau l'intégralité de cette étape et redéployer le nouveau conteneur :

chaque fois que vous modifiez et redéployez la configuration du service Endpoints. Sans cela, les modifications apportées à la configuration du service ne seront pas appliquées à ESPv2.
Lorsqu'une nouvelle version d'ESPv2 est disponible. Sans cela, l'ancienne version d'ESPv2 restera déployée.

Pour créer la configuration de service dans une nouvelle image ESPv2 pour Docker, procédez comme suit :

Téléchargez ce script sur l'ordinateur local sur lequel la gcloud CLI est installée.

Remarque :
Ce script nécessite bash. Si vous n'utilisez pas macOS/Linux, vous pouvez l'exécuter sur Cloud Shell, Compute Engine ou le sous-système Windows pour Linux.
Exécutez le script à l'aide de la commande suivante:
```
chmod +x gcloud_build_image

./gcloud_build_image -s CLOUD_RUN_HOSTNAME \
    -c CONFIG_ID -p ESP_PROJECT_ID
```
Pour le paramètre CLOUD_RUN_HOSTNAME, spécifiez le nom d'hôte de l'URL que vous avez réservé, comme indiqué ci-dessus dans la section Réserver un nom d'hôte Cloud Run. N'incluez pas l'identifiant du protocole https://.

Exemple :
```
chmod +x gcloud_build_image

./gcloud_build_image -s gateway-12345-uc.a.run.app \
    -c 2019-02-01r0 -p your-project-id
```
Le script utilise la commande gcloud pour télécharger la configuration de service, la compiler dans une nouvelle image ESPv2, puis importer la nouvelle image dans le registre de conteneurs de votre projet. Le script utilise automatiquement la dernière version d'ESPv2, désignée par ESP_VERSION dans le nom de l'image de sortie. L'image de sortie est importée dans l'emplacement suivant :
```
gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID
```
Exemple :
```
gcr.io/your-project-id/endpoints-runtime-serverless:2.14.0-gateway-12345-uc.a.run.app-2019-02-01r0"
```
Remarque :
Transmettez l'option -z au script pour générer l'image dans un emplacement de registre différent.

Par exemple, pour transférer l'image ESPv2 générée vers un centre de données de l'Union européenne, transmettez -z eu au script.

Déployer le conteneur ESPv2

Déployez le service ESPv2 pour Cloud Run avec la nouvelle image créée ci-dessus. Remplacez CLOUD_RUN_SERVICE_NAME par le nom du service Cloud Run utilisé lors de la réservation initiale du nom d'hôte, comme indiqué ci-dessus dans la section Réserver un nom d'hôte Cloud Run :
```
gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --allow-unauthenticated \
  --platform managed \
  --project=ESP_PROJECT_ID
```
Remarque :
Si vous souhaitez qu'ESPv2 gère l'accès, utilisez l'option --allow-unauthenticated pour vous assurer que le jeton JWT est validé par ESPv2. Si l'option n'est pas utilisée, le jeton JWT est intercepté et validé par le serveur IAM de contrôle des accès Cloud Run <a=" docs=""management-access"="" run=""sec="">et non par ESPv2. Comme IAM et ESPv2 utilisent le même en-tête d'autorisation, ils ne fonctionnent pas ensemble. Veillez donc à n'en utiliser qu'un seul. Recommandez d'utiliser IAM au lieu d'ESPv2 pour gérer l'accès.</a=">
Si vous souhaitez configurer Endpoints afin d'utiliser d'autres options de démarrage d'ESPv2, telles que l'activation de CORS, vous pouvez transmettre les arguments dans la variable d'environnement ESPv2_ARGS :
```
gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=--cors_preset=basic \
  --allow-unauthenticated \
  --platform managed \
  --project ESP_PROJECT_ID
```
Pour en savoir plus et obtenir des exemples de définition de la variable d'environnement ESPv2_ARGS, y compris la liste des options disponibles et des informations sur la manière de spécifier plusieurs options, reportez-vous à la page sur les options d'Extensible Service Proxy V2.
Accordez à ESPv2 l'autorisation d'appeler votre application sécurisée par IAP. Exécutez la commande suivante pour chaque service. Dans la commande ci-après :
- Remplacez APP_PROJECT_ID par le nom de l'ID de votre projet App Engine.
- Remplacez ESP_PROJECT_NUMBER par le numéro du projet que vous avez créé pour ESPv2. Pour ce faire, vous pouvez accéder à la console IAM et rechercher le compte de service Compute Engine par défaut, qui correspond à celui utilisé dans l'indicateur "member".
```
  gcloud projects add-iam-policy-binding APP_PROJECT_ID \
      --member "serviceAccount:ESP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
      --role "roles/iap.httpsResourceAccessor"
    
```

Pour en savoir plus, consultez la page Gérer les accès à l'aide d'IAM.

Envoyer des requêtes à l'API

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

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}/"

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/").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/
```

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

Affichez les graphiques d'activité de votre API sur la page Endpoints > Service de la console Google Cloud.

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.
Consultez les journaux de requêtes de votre API sur la page de l'explorateur de journaux.

Afficher les journaux de requête Endpoints

Créer un portail développeur 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.

Effectuer un nettoyage

Pour éviter que les ressources utilisées sur cette page 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.