Premiers pas avec Cloud Endpoints Frameworks pour Python

Cette page vous explique comment configurer, déployer et envoyer des requêtes à un exemple d'API à l'aide de Cloud Endpoints Frameworks pour Python. Endpoints Frameworks pour Python est intégré à l'environnement d'exécution standard Python 2.7 d'App Engine. Endpoints Frameworks comprend des outils, des bibliothèques et des fonctionnalités vous permettant de générer des API et des bibliothèques clientes à partir d'une application App Engine.

Objectifs

Tout au long du tutoriel, reportez-vous au récapitulatif des étapes présenté ci-dessous. Toutes les tâches sont nécessaires pour envoyer des requêtes à l'API.

  1. Configurez un projet Google Cloud. Consultez la section Avant de commencer.
  2. Installez les logiciels nécessaires et créez une application App Engine. Consultez la section Installer et configurer les logiciels requis.
  3. Téléchargez l'exemple de code. Consultez la section Obtenir l'exemple de code.
  4. Générez un document OpenAPI. Consultez la section Configurer Endpoints.
  5. Déployez la configuration Endpoints pour créer un service Endpoints. Consultez la section Déployer la configuration Endpoints.
  6. Exécutez l'exemple sur votre ordinateur. Consultez la section Exécuter l'exemple en local.
  7. Créez un backend pour publier et déployer l'API. Consultez la section Déployer le backend de l'API.
  8. Envoyez une requête à l'API. Consultez la section Envoyer une requête à l'API.
  9. Suivez l'activité de l'API. Consultez la section Suivre l'activité de l'API.
  10. Faites le nécessaire pour éviter que des frais ne soient facturés sur votre compte Google Cloud. Consultez la section Nettoyer.

Coûts

Ce tutoriel utilise 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é ce tutoriel, vous pouvez éviter de continuer à payer des frais en supprimant les ressources que vous avez créées. Consultez la page Effectuer un nettoyage pour en savoir plus.

Avant de commencer

  1. Connectez-vous à votre compte Google.

    Si vous n'en possédez pas déjà un, vous devez en créer un.

  2. Dans Google Cloud Console, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.

    Accéder à la page de sélection du projet

  3. Assurez-vous que la facturation est activée pour votre projet Cloud. Découvrez comment vérifier que la facturation est activée pour votre projet.

  4. Notez l'ID du projet Google Cloud, car vous en aurez besoin ultérieurement.

Installer et configurer le logiciel requis

  1. Suivez les instructions de la section Installer le SDK Cloud pour Python pour configurer votre environnement de développement App Engine standard. Veillez à installer les composants gcloud app-engine-python et app-engine-python-extras.
  2. Exécutez les commandes suivantes :
    1. Mettez à jour le SDK Cloud.
      gcloud components update
    2. Assurez-vous que le SDK Cloud (gcloud) est autorisé à accéder à vos données et services sur Google Cloud :
      gcloud auth login
    3. Dans le nouvel onglet de navigateur, choisissez un compte.
    4. Définissez le projet par défaut sur votre ID de projet.
      gcloud config set project [YOUR_PROJECT_ID]

      Remplacez [YOUR_PROJECT_ID] par l'ID de votre projet Google Cloud. Si vous avez d'autres projets Google Cloud et que vous souhaitez les gérer à l'aide de gcloud, consultez la page Gérer les configurations du SDK Cloud.

  3. Vous aurez besoin d'une application pour envoyer des requêtes à l'exemple d'API.

    • Utilisateurs Linux et macOS : ce tutoriel fournit un exemple utilisant curl, qui est généralement préinstallé sur votre système d'exploitation. Si vous ne disposez pas de curl, vous pouvez le télécharger sur la page Releases and Downloads de curl.
    • Utilisateurs Windows : ce tutoriel fournit un exemple d'utilisation de Invoke-WebRequest, compatible avec PowerShell 3.0 et versions ultérieures.
  4. Assurez-vous que votre environnement de développement Python contient la fonction pip.
  5. Assurez-vous de pouvoir compiler des extensions C pour Python.
    • Windows : le compilateur Microsoft Visual C++ 9.0 (ou version ultérieure) est requis. Vous pouvez télécharger Microsoft Visual C++ pour Python 2.7 depuis le centre de téléchargement Microsoft.
    • Autres systèmes d'exploitation : en fonction de votre système d'exploitation, vous devrez peut-être installer des outils de compilation (parfois dans un package appelé build-essential) ou les en-têtes de développement Python (parfois dans un package appelé python-dev).
  6. Pour Linux, définissez la variable d'environnement ENDPOINTS_GAE_SDK sur le chemin d'accès au dossier de votre SDK App Engine : [Path-to-Google-Cloud-SDK]/platform/google_appengine.

    Remplacez [Path-to-Google-Cloud-SDK] par le résultat de la commande suivante :

    gcloud info --format="value(installation.sdk_root)"

  7. Créez une application App Engine :
    1. Sélectionnez la région dans laquelle vous souhaitez créer votre application App Engine. Exécutez la commande suivante pour obtenir la liste des régions :
      gcloud app regions list
    2. Créez une application App Engine à l'aide de la commande suivante. Remplacez [YOUR_PROJECT_ID] par l'ID de votre projet Google Cloud et [YOUR_REGION] par la région dans laquelle vous souhaitez créer l'application App Engine.
      gcloud app create \
      --project=[YOUR_PROJECT_ID] \
      --region=[YOUR_REGION]

      Exemple :

      gcloud app create --project=example-project-12345 --region=us-central

Obtenir l'exemple de code

Pour cloner l'exemple d'API de GitHub :

  1. Clonez le dépôt de l'exemple sur votre ordinateur local :

    git clone https://github.com/GoogleCloudPlatform/python-docs-samples
    
  2. Accédez au répertoire contenant l'exemple de code :

    cd python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
    

Configurer Endpoints

Pour configurer Endpoints, vous devez d'abord installer la bibliothèque Python Cloud Endpoints. Vous allez ensuite générer un document OpenAPI pour l'exemple d'API à l'aide d'un outil de la bibliothèque Endpoints Frameworks. Vous aurez besoin de la bibliothèque Endpoints Frameworks et de ce document OpenAPI pour qu'Endpoints puisse gérer l'API. Pour plus d'informations, consultez la page Ajouter la gestion des API.

Installer la bibliothèque Endpoints Frameworks

Cette section décrit comment utiliser la fonction pip de Python pour ajouter la bibliothèque Endpoints Frameworks au répertoire de projet de l'exemple d'API.

Pour ajouter la bibliothèque Endpoints Frameworks à l'exemple d'API, procédez comme suit :

  1. Assurez-vous que vous êtes bien dans le répertoire principal de l'exemple d'API, python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo.

  2. Créez un sous-répertoire /lib dans le projet :

    mkdir lib
    
  3. Dans le répertoire principal de l'exemple (python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo), exécutez la commande d'installation :

    pip install --target lib --requirement requirements.txt --ignore-installed
    

    Veuillez noter les points suivants :

    • Cette commande pip peut utiliser GCC (GNU Compiler Collection) pour compiler des modules d'extension. Si vous utilisez MacOS et si vous exécutez GCC pour la première fois sur votre système, vous devrez peut-être accepter la licence XCode d'Apple. Pour ce faire, exécutez la commande sudo xcodebuild -license.

    • Si plusieurs versions de Python sont installées sur votre ordinateur, assurez-vous que la version de pip correspond à la version de Python que vous utilisez dans le cadre de ce tutoriel. Les versions discordantes (entre pip issu de Python 3.4 et python issu de Python 2.7, par exemple) peuvent provoquer des erreurs difficiles à comprendre. Si nécessaire, vous pouvez exécuter pip en tant que module Python. Pour ce faire, remplacez pip dans la commande ci-dessus par python -m pip.

    • Si pip ne parvient pas à trouver un package approprié lors de l'exécution de la commande, mettez-le à niveau en exécutant la commande pip install --upgrade pip. Une fois la mise à niveau terminée, relancez la commande d'installation.

    • Sur certaines versions de Debian et d'Ubuntu, l'installation avec pip pourrait échouer avec indication de l'erreur DistutilsOptionError. Si vous voyez cette erreur, ajoutez l'indicateur --system.

En cas de succès, le répertoire lib contient les fichiers requis pour créer l'application Endpoints Frameworks.

Générer le document OpenAPI

Vous allez utiliser un outil de la bibliothèque Endpoints Frameworks pour générer un document décrivant l'API REST de l'exemple de code.

Pour générer le document OpenAPI, procédez comme suit :

  1. Vérifiez que vous êtes bien dans le répertoire principal de l'exemple :

    python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
    
  2. Générez le document OpenAPI :

    python lib/endpoints/endpointscfg.py get_openapi_spec main.EchoApi --hostname [YOUR_PROJECT_ID].appspot.com
    

    Remplacez [YOUR_PROJECT_ID] par l'ID de votre projet Google Cloud. Ignorez les avertissements qui s'affichent. L'outil Endpoints génère un document OpenAPI nommé echov1openapi.json dans le répertoire actuel. Il nomme le fichier en fonction du nom et de la version du service spécifié dans le décorateur @endpoints.api. Pour en savoir plus, consultez la page Créer l'API.

    Endpoints utilise le texte spécifié dans l'argument hostname en tant que nom de service. Le format du nom YOUR_PROJECT_ID.appspot.com correspond à l'entrée DNS créée automatiquement lorsque vous déployez l'API sur le backend App Engine. Ainsi, le nom du service Endpoints et le nom de domaine complet sont identiques.

Si l'opération réussit, le message suivant s'affiche : OpenAPI spec written to ./echov1openapi.json

Déployer la configuration Endpoints

Pour déployer la configuration Endpoints, vous allez utiliser Service Infrastructure, la plate-forme de services de base de Google, utilisée par Endpoints et d'autres services pour créer et gérer des API et des services.

Pour déployer le fichier de configuration :

  1. Vérifiez que vous êtes bien dans le répertoire principal de l'exemple :
    python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
    
  2. Déployez le document OpenAPI généré dans la section précédente en exécutant la commande suivante :
    gcloud endpoints services deploy echov1openapi.json
    

    Cela crée un service Endpoints portant le nom que vous avez spécifié dans l'argument hostname lors de la génération du document OpenAPI à l'aide de l'outil Endpoints. Quel que soit le nom du service Endpoints, lorsque vous déployez l'API sur App Engine, un enregistrement DNS est créé avec le nom au format YOUR_PROJECT_ID.appspot.com, qui est le nom de domaine complet que vous utilisez pour envoyer des requêtes à l'API.

    Lors de la création et de la configuration du service, Service Management envoie de nombreuses informations au terminal. Vous pouvez ignorer en toute sécurité les avertissements indiquant que les chemins dans echov1openapi.json ne nécessitent pas de clé API. Une fois le déploiement terminé, un message semblable à celui-ci s'affiche :

    Service Configuration [2017-02-13r2] uploaded for service [example-project-12345.appspot.com]
    

    Dans l'exemple ci-dessus, 2017-02-13-r2 correspond à l'ID de configuration du service et example-project-12345.appspot.com au nom du service.

    Pour en savoir plus, consultez la page gcloud endpoints services deploy dans la documentation de référence gcloud.

Vérifier les services requis

Pour assurer la gestion des API, Endpoints Frameworks a besoin des services 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.

Exécuter l'exemple en local

Après avoir déployé la configuration Endpoints, vous pouvez exécuter l'exemple en local à l'aide du serveur de développement local.

  1. Vérifiez que vous êtes bien dans le répertoire principal de l'exemple :

    python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
    
  2. Démarrez le serveur de développement local :

    dev_appserver.py ./app.yaml
    

    Par défaut, le serveur de développement utilise le port d'écoute http://localhost:8080, comme indiqué dans les journaux de Google Cloud Console affichés par dev_appserver.py :

    INFO 2018-01-01 [...] Starting module "default" running at: http://localhost:8080
    
  3. Envoyez une requête au serveur de développement local :

Linux ou macOS

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --data '{"message":"hello world"}' \
    http://localhost:8080/_ah/api/echo/v1/echo

Dans la commande curl ci-dessus :

  • L'option --data indique les données à publier sur l'API.
  • L'option --header indique que les données sont au format JSON.

PowerShell

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://localhost:8080/_ah/api/echo/v1/echo").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.

L'API renvoie le message que vous lui avez envoyé et répond avec les éléments suivants :

{
 "message": "hello world"
}

Déployer le backend de l'API

Vous avez déployé le document OpenAPI sur Service Management, mais vous n'avez pas encore déployé le code qui diffuse le backend de l'API. Cette section vous guide tout au long du déploiement de l'exemple d'API dans App Engine.

Pour déployer le backend de l'API :

  1. Affichez l'ID de configuration du service en exécutant la commande suivante :

    gcloud endpoints configs list --service=[YOUR_PROJECT_ID].appspot.com
    

    Remplacez [YOUR_PROJECT_ID] par votre ID de projet. Par exemple :

    gcloud endpoints configs list --service=example-project-12345.appspot.com
    

  2. Ouvrez le fichier app.yaml dans le répertoire python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo.
    env_variables:
      # The following values are to be replaced by information from the output of
      # 'gcloud endpoints services deploy swagger.json' command.
      ENDPOINTS_SERVICE_NAME: YOUR-PROJECT-ID.appspot.com
      ENDPOINTS_SERVICE_VERSION: 2016-08-01r0
  3. Apportez les modifications suivantes dans la section env_variables :
    • Dans le champ ENDPOINTS_SERVICE_NAME, remplacez YOUR-PROJECT-ID par votre ID de projet Google Cloud.
    • Dans le champ ENDPOINTS_SERVICE_VERSION, remplacez le texte par l'ID de configuration du service. Par exemple :
      ENDPOINTS_SERVICE_NAME: example-project-12345.appspot.com
      ENDPOINTS_SERVICE_VERSION: 2017-02-13r2
    
  4. Exécutez la commande suivante :
    gcloud app deploy
    
  5. Suivez les instructions qui s'affichent à l'écran. Attendez que le déploiement soit terminé, en ignorant les messages d'avertissement. Une fois le déploiement terminé, un message semblable à celui-ci s'affiche :
    File upload done.
    Updating service [default]...done.
    

    Si vous recevez un message d'erreur, consultez la section Dépannage de la documentation App Engine.

    Nous vous recommandons d'attendre quelques minutes et la fin de l'initialisation complète d'App Engine avant d'envoyer des requêtes à votre API.

Envoyer une requête à l'exemple d'API

Linux ou macOS

Envoyez une requête HTTP à l'aide de curl. Remplacez [YOUR_PROJECT_ID] par l'ID de votre projet Google Cloud :

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --data '{"message":"hello world"}' \
    https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo

Dans la commande curl ci-dessus :

  • L'option --data indique les données à publier sur l'API.
  • L'option --header indique que les données sont au format JSON.

PowerShell

Envoyez une requête HTTP à l'aide de Invoke-WebRequest. Remplacez [YOUR_PROJECT_ID] par l'ID de votre projet Google Cloud :

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} -URI `
     "https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo").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 telle que l'extension Postman du navigateur Chrome pour envoyer la requête :

  • Sélectionnez POST comme verbe HTTP.
  • Pour l'en-tête, sélectionnez la clé content-type et la valeur application/json.
  • Pour le corps, saisissez ce qui suit :
    {"message":"hello world"}
  • Saisissez l'URL de l'exemple d'application. Par exemple :
    https://example-project-12345.appspot.com/_ah/api/echo/v1/echo

L'API renvoie le message que vous avez envoyé et répond avec les éléments suivants :

{
 "message": "hello world"
}

Si vous ne recevez pas de réponse positive, consultez la section Dépanner des erreurs de réponse.

Suivre l'activité de l'API

  1. Affichez les graphiques d'activité de votre API dans Cloud Console, sur la page Endpoints > Service.

    Accédez à la page Services 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.

    Accéder à la page Visionneuse de journaux

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.

Nettoyer

Pour éviter que les ressources utilisées dans ce tutoriel soient facturées sur votre compte Google Cloud Platform :

  1. Dans Cloud Console, accédez à la page Gérer les ressources.

    Accéder à la page Gérer les ressources

  2. Dans la liste des projets, sélectionnez le projet que vous souhaitez supprimer, puis cliquez sur Supprimer .
  3. Dans la boîte de dialogue, saisissez l'ID du projet, puis cliquez sur Arrêter pour supprimer le projet.

Étape suivante