Premiers pas avec Cloud Endpoints Frameworks pour Python

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

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

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 écoute http://localhost:8080, comme indiqué dans les journaux de la console Google Cloud généré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 :

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

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

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 l'ID du projet. Exemple :

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

2. Open the app.yaml file in the python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo directory.

   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