Premiers pas avec Cloud Endpoints pour Cloud Functions

Cette page explique comment configurer Cloud Endpoints pour Cloud Functions. Cloud Endpoints utilise le proxy Extensible Service Proxy v2 bêta (ESPv2 bêta) en tant que passerelle API. Afin d'assurer la gestion des API pour Cloud Functions, vous devez déployer le conteneur ESPv2 bêta prédéfini sur Cloud Run. Vous pouvez ensuite sécuriser vos fonctions à l'aide des rôles IAM pour Cloud Functions afin que le proxy ESPv2 bêta puisse les appeler.

Une fois la configuration finalisée, ESPv2 bêta peut intercepter toutes les requêtes adressées à vos fonctions et effectuer les vérifications nécessaires, telles que l'authentification, avant d'appeler ces fonctions. Lorsque la fonction répond, ESPv2 bêta rassemble et consigne les données de télémétrie. Vous pouvez afficher les métriques de votre fonction 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 Présentation de l'architecture Cloud Endpoints.

Migrer vers ESPv2 bêta

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 la version ESPv2 bêta, consultez la page Migrer vers Extensible Service Proxy V2 bêta pour en savoir plus.

Liste de tâches

Tout au long du tutoriel, reportez-vous à la liste de tâches présentée ci-dessous. La finalisation du tutoriel suppose de réaliser l'intégralité de ces tâches.

  1. Créez un projet Google Cloud et, si vous n'avez pas déployé votre propre environnement Cloud Functions, déployez un exemple de fonction. Consultez la section Avant de commencer.
  2. Déployez le conteneur ESPv2 bêta dans Cloud Run. Consultez la section Déployer ESPv2 bêta.
  3. Créez un document OpenAPI décrivant votre API, puis configurez les routes vers votre environnement Cloud Functions. Consultez la section Configurer Cloud Endpoints.
  4. Déployez le document OpenAPI pour créer un service géré. Consultez la section Déployer la configuration Endpoints.
  5. Créez et déployez une image Docker ESPv2 bêta avec votre configuration de service Endpoints. Accordez ensuite à ESPv2 bêta l'autorisation Cloud IAM (Cloud Identity and Access Management) requise pour appeler votre service. Consultez la section Créer une image ESPv2 bêta.
  6. Invoquez une fonction. Consultez la section Envoyer des requêtes à l'API.
  7. Suivez l'activité de vos fonctions. Consultez la section Suivre l'activité de l'API.
  8. 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é que Cloud Endpoints pour Cloud Functions est en version bêta, nous formulons les recommandations suivantes :

  • Créez un projet Google Cloud à utiliser lorsque vous déployez le conteneur ESPv2 bêta dans Cloud Run.

  • Créez un projet ou sélectionnez-en un existant pour votre environnement Cloud Functions.

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 encore déployé votre propre environnement Cloud Functions, suivez la procédure décrite sur la page Guide de démarrage rapide : utiliser l'outil de ligne de commande gcloud pour sélectionner ou créer un projet Google Cloud, et déployer un exemple de fonction. Notez la région et l'ID de projet correspondant à l'emplacement dans lequel vos fonctions sont déployées. Sur le reste de cette page, cet ID est appelé FUNCTIONS_PROJECT_ID.

Déployer ESPv2 bêta

Pour déployer le conteneur ESPv2 bêta dans Cloud Run, procédez comme suit :

  1. Assurez-vous que le SDK Cloud est autorisé à accéder à vos données et services.
  2. Connectez-vous.
    gcloud auth login
  3. 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 ESPv2 bêta dans Cloud Run.
  • Définissez la région.
    gcloud config set run/region us-central1
  • Déployez ESPv2 bêta 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/endpoints-release/endpoints-runtime-serverless:2" \
        --allow-unauthenticated \
        --platform managed \
        --project=ESP_PROJECT_ID
    

    Si elle aboutit, 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 la valeur de CLOUD_RUN_HOSTNAME. Spécifiez CLOUD_RUN_HOSTNAME dans le champ host du document.
  • Vous pouvez vérifier si la version initiale d'ESPv2 bêta est déployée sur Cloud Run en accédant à CLOUD_RUN_SERVICE_URL dans votre navigateur Web. Un message d'avertissement à propos d'une variable d'environnement manquante s'affiche normalement. Ce message d'avertissement est attendu et s'affiche jusqu'à la fin de l'étape Créer une image ESPv2 bêta
  • 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 fonctions, ainsi que les conditions requises pour l'authentification. Vous devez également ajouter un champ spécifique à Google contenant l'URL de chaque fonction afin qu'ESPv2 bêta dispose des informations nécessaires pour appeler une fonction. 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-functions.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.
    2. Chacune de vos fonctions doit être répertoriée dans la section paths du fichier openapi-functions.yaml. Exemple :
      swagger: '2.0'
      info:
        title: Cloud Endpoints + GCF
        description: Sample API on Cloud Endpoints with a Google Cloud Functions backend
        version: 1.0.0
      host: HOST
      schemes:
        - https
      produces:
        - application/json
      paths:
        /hello:
          get:
            summary: Greet a user
            operationId: hello
            x-google-backend:
              address: https://REGION-FUNCTIONS_PROJECT_ID.cloudfunctions.net/FUNCTIONS_NAME
              protocol: h2
            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.
    3. Dans le champ address de la section x-google-backend, remplacez REGION par la région Google Cloud où se trouve votre fonction, FUNCTIONS_PROJECT_ID par l'ID de votre projet Google Cloud et FUNCTIONS_NAME par le nom de votre fonction. Exemple :
      x-google-backend:
        address: https://us-central1-myproject.cloudfunctions.net/helloGET
      
      Si vous souhaitez sécuriser votre fonction Cloud en n'autorisant que ESPv2 Bêta à l'appeler, assurez-vous que le champ address inclut le nom de la fonction si jwt_audience n'est pas spécifié. Exemple :
      x-google-backend:
        address: https://REGION-FUNCTIONS_PROJECT_ID.cloudfunctions.net/FUNCTIONS_NAME
        path_translation: CONSTANT_ADDRESS
      
      Si jwt_audience est spécifié, sa valeur doit également inclure le nom de la fonction. Exemple :
      x-google-backend:
        address: https://REGION-FUNCTIONS_PROJECT_ID.cloudfunctions.net
        jwt_audience: https://REGION-FUNCTIONS_PROJECT_ID.cloudfunctions.net/FUNCTIONS_NAME
        path_translation: APPEND_PATH_TO_ADDRESS
      
      ESPv2 Bêta génère un jeton d'ID lors de l'appel de la fonction Cloud pour l'authentification. Le jeton d'ID doit avoir un élément audience approprié spécifiant l'hôte et le nom de la fonction. ESPv2 bêta définit l'élément audience du jeton d'ID à l'aide de la valeur du champ jwt_audience s'il est spécifié. Sinon, le champ address est utilisé.
    4. Dans le champ host, spécifiez CLOUD_RUN_HOSTNAME, la partie nom d'hôte de l'URL créée par Cloud Run lors du déploiement d'ESPv2 bêta, effectué à la section Déployer ESPv2 bêta. N'incluez pas l'identifiant du protocole https://. Exemple :

      swagger: '2.0'
        info:
          title: Cloud Endpoints + GCF
          description: Sample API on Cloud Endpoints with a Google Cloud Functions backend
          version: 1.0.0
        host: gateway-12345-uc.a.run.app
      
    5. Notez la valeur de la propriété title dans le fichier openapi-functions.yaml :

      title: Cloud Endpoints + GCF

      La valeur de la propriété title devient le nom du service Endpoints après le déploiement de la configuration.

    6. 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-functions.yaml \
          --project ESP_PROJECT_ID

      Vous créez ainsi un service Endpoints avec le nom spécifié dans le champ host du fichier openapi-functions.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 de configuration du service Endpoints unique créé par le déploiement. Exemple :

      Service Configuration [2019-02-01-r0] 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-functions.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 requièrent 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, 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 Endpoints, accédez à la page Endpoints de Cloud Console. 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 bêta

    Créez la configuration de service Endpoints dans une nouvelle image Docker ESPv2 bêta et redéployez le service ESPv2 bêta Cloud Run avec l'image. Accordez ensuite à ESPv2 bêta l'autorisation Cloud IAM d'appeler vos fonctions.

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

    1. Téléchargez ce script sur la machine locale où le SDK gcloud est installé, puis exécutez-le comme suit :

      chmod +x gcloud_build_image
      
      ./gcloud_build_image -s CLOUD_RUN_HOSTNAME \
          -c CONFIG_ID -p ESP_PROJECT_ID

      Dans le champ CLOUD_RUN_HOSTNAME, spécifiez le nom d'hôte de l'URL créée par Cloud Run lors du déploiement d'ESPv2 bêta, effectué à la section Déployer ESPv2 bêta. 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-01-r0 -p ESP_PROJECT_ID

      Le script utilise la commande gcloud pour télécharger la configuration de service, créer cette configuration dans une nouvelle image ESPv2 bêta, et importer la nouvelle image dans le registre de conteneurs de votre projet situé à l'emplacement suivant :

      gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID

      Exemple :

      gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:gateway-12345-uc.a.run.app-2019-02-01-r0"
    2. Redéployez le service Cloud Run ESPv2 bêta avec la nouvelle image. Remplacez CLOUD_RUN_SERVICE_NAME par le nom du service Cloud Run utilisé lors du déploiement initial effectué à la section Déployer ESPv2 bêta :

      gcloud run deploy CLOUD_RUN_SERVICE_NAME \
        --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID" \
        --allow-unauthenticated \
        --platform managed \
        --project=ESP_PROJECT_ID
    3. Si vous souhaitez configurer d'autres options de démarrage ESPv2 bêta pour Cloud Endpoints, 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:CLOUD_RUN_HOSTNAME-CONFIG_ID" \
        --set-env-vars=ESPv2_ARGS=--cors_preset=basic \
        --allow-unauthenticated \
        --platform managed \
        --project ESP_PROJECT_ID

      Pour obtenir des exemples de définition de la variable d'environnement ESPv2_ARGS, consulter la liste des options disponibles et découvrir comment spécifier plusieurs options, reportez-vous à la page sur les options ESPv2 bêta.

    4. Accordez à ESPv2 bêta l'autorisation d'appeler Service Management et Service Control.

      • Dans Cloud Console, accédez à la page "Cloud Run".
      • Accéder à la page Cloud Run

      • Vous pouvez voir l'instance Cloud Run que vous avez déployée et le compte de service qui lui est associé.
      • Accordez des autorisations au compte de service.
      • gcloud projects add-iam-policy-binding PROJECT_NAME --member "serviceAccount:SERVICE_ACCOUNT" --role roles/servicemanagement.serviceController
      Pour en savoir plus, consultez la page Que sont les rôles et les autorisations ?
    5. Accordez à ESPv2 bêta l'autorisation d'appeler vos fonctions. Exécutez la commande suivante pour chaque fonction. Dans cette commande :

      • Remplacez FUNCTION_NAME par le nom de votre fonction. Si vous utilisez la fonction créée depuis la page Guide de démarrage rapide : utiliser l'outil de ligne de commande gcloud, définissez cette valeur sur helloGET.
      • Remplacez ESP_PROJECT_NUMBER par le numéro du projet que vous avez créé pour ESPv2 bêta. 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 functions add-iam-policy-binding FUNCTION_NAME \
         --member "serviceAccount:ESP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
         --role "roles/cloudfunctions.invoker" \
         --project FUNCTIONS_PROJECT_ID

    Pour en savoir plus, consultez la page Gérer l'accès via IAM.

    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.

    Effectuer un nettoyage

    Afin d'éviter que des frais ne soient facturés sur votre compte Google Cloud pour les ressources utilisées dans ce guide de démarrage rapide, 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.

    Étapes suivantes