Cette page a été traduite par l'API Cloud Translation.

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.

Configurez un projet Google Cloud. Consultez la section Avant de commencer.
Installez les logiciels nécessaires et créez une application App Engine. Consultez la section Installer et configurer les logiciels requis.
Téléchargez l'exemple de code. Consultez la section Obtenir l'exemple de code.
Générez un document OpenAPI. Consultez la section Configurer Endpoints.
Déployez la configuration Endpoints pour créer un service Endpoints. Consultez la section Déployer la configuration Endpoints.
Exécutez l'exemple sur votre ordinateur. Consultez la section Exécuter l'exemple en local.
Créez un backend pour diffuser et déployer l'API. Consultez la section Déployer le backend de l'API.
Envoyez une requête à l'API. Consultez la section Envoyer une requête à l'API.
Suivez l'activité de l'API. 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 Nettoyer.

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

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

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

Installer et configurer le logiciel requis

Suivez les instructions de la section Installer la Google Cloud CLI 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.
Exécutez les commandes suivantes :
1. Mettez à jour gcloud CLI.
```
gcloud components update
```
2. Assurez-vous que la Google Cloud CLI (gcloud) est autorisée à 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 de gcloud CLI.
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.
Assurez-vous que votre environnement de développement Python contient la fonction pip.
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).
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)"
```
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 :

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

git clone https://github.com/GoogleCloudPlatform/python-docs-samples

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 :

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.
Créez un sous-répertoire /lib dans le projet :
```
mkdir lib
```
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 :

Vérifiez que vous êtes bien dans le répertoire principal de l'exemple :
```
python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
```
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 :

Vérifiez que vous êtes bien dans le répertoire principal de l'exemple :
```
python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
```
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

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.

Vérifiez que vous êtes bien dans le répertoire principal de l'exemple :
```
python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
```
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
```
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 :

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

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

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

Exécutez la commande suivante :

gcloud app deploy

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

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

Affichez les graphiques d'activité de votre API dans la console Google Cloud, 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.
Consultez les journaux de requêtes de votre API sur la page de l'explorateur de journaux.

Accéder à la page "Explorateur 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.

Effectuer un nettoyage

Pour éviter que les ressources utilisées lors de ce tutoriel soient facturées sur votre compte Google Cloud, supprimez le projet contenant les ressources, ou conservez le projet et supprimez les ressources individuelles.

In the Google Cloud console, go to the Manage resources page.
Go to Manage resources
In the project list, select the project that you want to delete, and then click Delete.
In the dialog, type the project ID, and then click Shut down to delete the project.

Étape suivante

Découvrez l'architecture Endpoints Frameworks.
Découvrez comment créer une API.
Découvrez comment créer un serveur Web pour diffuser votre API.
Découvrez comment diffuser votre API depuis un autre chemin d'accès.
Découvrez comment surveiller votre API.
Découvrez comment restreindre l'accès à l'aide de clés API.
Découvrez comment configurer un nom de domaine personnalisé.
Découvrez comment gérer les versions d'API.
Découvrez les options d'assistance.