Premiers pas avec l'API Admin

ID de la région

Le REGION_ID est un code abrégé que Google attribue en fonction de la région que vous sélectionnez lors de la création de votre application. Le code ne correspond pas à un pays ou une province, même si certains ID de région peuvent ressembler aux codes de pays et de province couramment utilisés. Pour les applications créées après février 2020, REGION_ID.r est inclus dans les URL App Engine. Pour les applications existantes créées avant cette date, l'ID de région est facultatif dans l'URL.

En savoir plus sur les ID de région

Ce guide est conçu pour vous aider à utiliser l'API App Engine Admin et à déployer un exemple d'application Python sur App Engine. Vous pouvez appliquer le processus global afin d'obtenir des informations sur la création de code pour gérer et déployer vos applications par programmation.

Dans ce guide, l'exemple utilisé est une simple application "Hello World" qui affiche le texte "Hello, World!" et est disponible dans GitHub. Pour l'autorisation auprès de la console Google Cloud, un ID client OAuth et un navigateur Web sont utilisés. Pour illustrer les différentes étapes du processus, des commandes cURL vous sont fournies afin d'envoyer des requêtes HTTP à partir de votre terminal.

Objectifs

Activez les API dans votre projet de la console Google Cloud, puis créez les identifiants d'ID client OAuth.
Obtenir des jetons d'accès pour l'authentification auprès d'App Engine
Utiliser l'API Admin pour déployer l'exemple d'application sur App Engine
Facultatif : Configurer le trafic vers la version sur laquelle vous avez déployé l'exemple d'application

Avant de commencer

Vous devez avoir ou créer un compte Google.
Téléchargez et installez Google Cloud CLI, puis initialisez la CLI gcloud :
Télécharger le SDK

Configurer votre projet Google Cloud

Activez les API App Engine Admin et Cloud Storage dans votre projet Google Cloud, puis configurez les identifiants :

Activez les API dans la console Google Cloud :

Activer les API
Dans l'assistant, sélectionnez un projet existant dans la liste ou cliquez sur Continuer pour créer un projet.
Cliquez sur Continuer pour créer des identifiants client OAuth :
1. Sur l'écran de consentement OAuth, spécifiez au moins votre adresse e-mail et le nom du produit affiché pour les utilisateurs.
2. Enregistrez les paramètres de l'écran de consentement, puis passez à l'onglet Identifiants en cliquant sur Enregistrer.
3. Cliquez sur Créer des identifiants, puis sur ID client OAuth pour créer un ID client.
4. Cliquez sur Application Web, spécifiez un nom, puis utilisez https://www.google.com comme URI de redirection.
  
  Remarque : L'URI de redirection définit la destination d'envoi de la réponse HTTP. L'URI https://www.google.com est utilisé comme exemple dans ce guide mais pour la production, vous devez spécifier le point de terminaison d'authentification de votre application, qui gère les réponses du serveur OAuth 2.0.
5. Cliquez sur Créer pour enregistrer les identifiants.
6. Prenez note de l'ID client affiché, car il sera utilisé lors d'une étape ultérieure pour demander votre jeton d'accès.

Pour plus d'informations sur la création d'identifiants pour l'API Admin, consultez la page Accéder à l'API.

Créer un fichier de configuration

Créez un fichier de configuration qui définit le déploiement de l'application Hello World. Dans un fichier nommé app.json, vous définissez le bucket Cloud Storage de l'application Hello World dans le champ sourceUrl et les informations de configuration de la version (y compris l'ID de version) dans le champ id.

{
  "deployment": {
    "files": {
      "main.py": {
        "sourceUrl": "https://storage.googleapis.com/admin-api-public-samples/hello_world/main.py"
      },
    }
  },
  "handlers": [
    {
      "script": {
        "scriptPath": "main.app"
      },
      "urlRegex": "/.*"
    }
  ],
  "runtime": "python27",
  "threadsafe": true,
  "id": "appengine-helloworld",
  "inboundServices": [
    "INBOUND_SERVICE_WARMUP"
  ]
}

Par exemple : root/python-docs-samples/appengine/standard/hello_world/app.json

Autoriser les requêtes HTTP

Authentifiez-vous auprès d'App Engine pour pouvoir envoyer des requêtes HTTP avec l'API Admin.

Appliquez l’une des options suivantes pour vous lancer rapidement. Les options HTTPS et gcloud impliquent des étapes manuelles simples pour obtenir des jetons d'accès afin de tester l'API Admin.

HTTPS

Pour simuler un flux OAuth 2.0 côté client, ajoutez vos identifiants client OAuth à un URI, puis envoyez la requête HTTPS via votre navigateur Web :

Dans votre navigateur Web, demandez un jeton d'accès à l'aide de l'ID client de vos identifiants d'API. L'exemple suivant utilise client_id=[MY_CLIENT_ID] et redirect_uri=https://www.google.com, où [MY_CLIENT_ID] est l'ID client de l'identifiant créé précédemment :
```
https://accounts.google.com/o/oauth2/v2/auth?response_type=token&client_id=[MY_CLIENT_ID]&scope=https://www.googleapis.com/auth/cloud-platform&redirect_uri=https://www.google.com
```
Récupérez le jeton d'accès dans la réponse à la demande.

Le champ d'adresse de votre navigateur Web doit contenir l'URI de redirection spécifié dans vos identifiants, ainsi que le jeton d'accès ajouté à l'URI, par exemple :
```
https://www.google.com/#access_token=[MY_ACCESS_TOKEN]&token_type=Bearer&expires_in=3600
```
Vous pouvez désormais utiliser le jeton d'accès [MY_ACCESS_TOKEN] fourni dans le champ access_token pour envoyer des requêtes HTTP à votre projet Google Cloud.

gcloud

Pour récupérer simplement un jeton d'accès, exécutez les commandes gcloud suivantes :

Définissez les identifiants par défaut de l'application que vous souhaitez utiliser pour demander un jeton d'accès :
```
gcloud auth application-default login
```

Demandez le jeton d'accès :

gcloud auth application-default print-access-token

Pour en savoir plus sur ces commandes, consultez la page gcloud auth application-default.

N'oubliez pas que votre jeton d'accès expire environ 60 minutes après son émission.

Les options ci-dessus ne sont pas destinées à être utilisées dans votre implémentation programmatique, mais des informations sur la manière d'implémenter un flux d'autorisation OAuth 2.0 sont disponibles sur la page Accéder à l'API Admin.

Déployer l'application Hello World

Une requête HTTP vous permet de déployer l'application Hello World avec l'API Admin :

Envoyez une requête HTTP POST à l'aide de l'API Admin pour déployer une version de l'application Hello World sur votre application App Engine ; par exemple :

POST https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions app.json

Exemple de commande curl :

Exécutez la commande à partir du répertoire dans lequel vous avez créé le fichier de configuration app.json ; par exemple :

cd root/python-docs-samples/appengine/standard/hello_world/

curl -X POST -T "app.json" -H "Content-Type: application/json" -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions

Où :

[MY_ACCESS_TOKEN] est le jeton d'accès obtenu pour autoriser les requêtes HTTP.
[MY_PROJECT_ID] est l'ID du projet sur lequel vous souhaitez déployer la version.

Exemple de réponse :

{
  "name": "apps/[MY_PROJECT_ID]/operations/89729825-ef1f-4ffa-b3e3-e2c25eb66a85",
  "metadata": {
    "@type": "type.googleapis.com/google.appengine.v1.OperationMetadataV1",
    "insertTime": "2016-07-29T17:12:44.679Z",
    "method": "google.appengine.v1.Versions.CreateVersion",
    "target": "apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld",
    "user": "me@example.com"
  }
}

où [MY_PROJECT_ID] correspond à l’ID de votre projet Google Cloud.

Vérifiez que la version de l'application Hello World a bien été déployée sur votre application App Engine :

Affichez l'état de l'opération de déploiement en utilisant le nom de l'opération renvoyé à l'étape précédente dans le champ name dans une méthode HTTP GET ; par exemple :

GET https://appengine.googleapis.com/v1/[OPERATION_NAME]

Exemple de commande curl :

curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/[OPERATION_NAME]

Où :

[OPERATION_NAME] correspond à la valeur du champ name renvoyé à l'étape précédente lors du déploiement de l'application ; par exemple apps/[MY_PROJECT_ID]/operations/89729825-ef1f-4ffa-b3e3-e2c25eb66a85.
[MY_ACCESS_TOKEN] est le jeton d'accès obtenu pour autoriser les requêtes HTTP.
[MY_PROJECT_ID] est l'ID du projet sur lequel vous souhaitez déployer la version.

Exemple de réponse :

{
  "done": true,
  "metadata": {
    "@type": "type.googleapis.com/google.appengine.v1.OperationMetadataV1",
    "endTime": "2016-07-29T17:13:20.424Z",
    "insertTime": "2016-07-29T17:12:44.679Z",
    "method": "google.appengine.v1.Versions.CreateVersion",
    "target": "apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld",
    "user": "me@example.com"
  },
  "name": "apps/[MY_PROJECT_ID]/operations/89729825-ef1f-4ffa-b3e3-e2c25eb66a85",
  "response": {
    "@type": "type.googleapis.com/google.appengine.v1.Version",
    "creationTime": "2016-07-29T17:12:46.000Z",
    "deployer": "me@example.com",
    "id": "appengine-helloworld",
    "name": "apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld",
    "runtime": "python27",
    "servingStatus": "SERVING",
    "threadsafe": true,
  }
}

où [MY_PROJECT_ID] correspond à l’ID de votre projet Google Cloud.

Vérifiez que la version de l'application Hello World a été créée dans votre application App Engine à l'aide d'une requête HTTP GET pour afficher les détails de la version, par exemple :

GET https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld/?view=FULL

Exemple de commande curl :

curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld/?view=FULL

Où :

[MY_ACCESS_TOKEN] est le jeton d'accès obtenu pour autoriser les requêtes HTTP.
[MY_PROJECT_ID] est l'ID du projet sur lequel vous souhaitez déployer la version.

Exemple de réponse :

{
  "creationTime": "2016-07-29T17:12:46.000Z",
  "deployer": "me@example.com",
  "deployment": {
    "files": {
      "main.py": {
        "sha1Sum": "13f7ea1e24f7cd2de5c66660525f2b509da37c14",
        "sourceUrl": "https://storage.googleapis.com/admin-api-public-samples/hello_world/main.py"
      }
    }
  },
  "handlers": [
    {
      "authFailAction": "AUTH_FAIL_ACTION_REDIRECT",
      "login": "LOGIN_OPTIONAL",
      "script": {
        "scriptPath": "main.app",
      },
      "securityLevel": "SECURE_OPTIONAL",
      "urlRegex": "/.*"
    }
  ]
  "id": "appengine-helloworld",
  "name": "apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld",
  "runtime": "python27",
  "servingStatus": "SERVING",
  "threadsafe": true,
  "versionUrl": "https://appengine-helloworld-dot-[MY_PROJECT_ID].[REGION_ID].r.appspot"
}

où [MY_PROJECT_ID] correspond à l’ID de votre projet Google Cloud.

Affichez l'application Hello World dans votre navigateur Web en accédant à l'URL spécifiée dans le champ versionUrl de la réponse HTTP de l'étape précédente ; par exemple :
```
https://appengine-helloworld-dot-[MY_PROJECT_ID].[REGION_ID].r.appspot.com
```
où [MY_PROJECT_ID] correspond à l’ID de votre projet Google Cloud.
Le REGION_ID est un code abrégé que Google attribue en fonction de la région que vous sélectionnez lors de la création de votre application. Le code ne correspond pas à un pays ou une province, même si certains ID de région peuvent ressembler aux codes de pays et de province couramment utilisés. Pour les applications créées après février 2020, REGION_ID.r est inclus dans les URL App Engine. Pour les applications existantes créées avant cette date, l'ID de région est facultatif dans l'URL.

Configurez le trafic vers l'application Hello World.

Par défaut, la version initiale que vous déployez dans une nouvelle application App Engine reçoit automatiquement 100 % du trafic et les versions ultérieures ne reçoivent aucun trafic.

Pour savoir si votre version est configurée pour recevoir du trafic, envoyez une requête HTTP GET ; par exemple :
```
GET https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default
```
Exemple de commande curl :
```
curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default
```
Où :
- [MY_ACCESS_TOKEN] est le jeton d'accès obtenu pour autoriser les requêtes HTTP.
- [MY_PROJECT_ID] est l'ID du projet sur lequel vous souhaitez déployer la version.
Exemple de réponse :
```
{
  "name": "apps/[MY_PROJECT_ID]/services/default/",
  "id": "default",
  "split": {
    "allocations": {
      "appengine-helloworld": 1
    }
  }
}
```
où [MY_PROJECT_ID] correspond à l’ID de votre projet Google Cloud.

Pour déplacer tout le trafic vers une version, envoyez une requête HTTP PATCH ; par exemple :

PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split {"split": { "allocations": { "appengine-helloworld": 1 } } }

Exemple de commande curl :

curl -X PATCH -H "Content-Type: application/json" -d "{ 'split': { 'allocations': { 'appengine-helloworld': '1' } } }" -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split

Où :

[MY_ACCESS_TOKEN] est le jeton d'accès obtenu pour autoriser les requêtes HTTP.
[MY_PROJECT_ID] est l'ID du projet sur lequel vous souhaitez déployer la version.

Exemple de réponse :

{
  "name": "apps/[MY_PROJECT_ID]/operations/bdda402c-77a9-4c6d-b022-f2f69ba78420",
  "metadata": {
    "@type": "type.googleapis.com/google.appengine.v1.OperationMetadataV1",
    "insertTime": "2016-07-29T17:25:30.413Z",
    "method": "com.google.appengine.v1.Services.UpdateService",
    "target": "apps/[MY_PROJECT_ID]/services/default",
    "user": "me@example.com"
  }
}

où [MY_PROJECT_ID] correspond à l’ID de votre projet Google Cloud.

Apprentissage approfondi

Si vous disposez de plusieurs versions d'une application, vous pouvez procéder comme suit pour répartir le trafic entre ces versions :

Pour déployer une deuxième version de l'application Hello World sur la même application App Engine :
1. Dans le fichier de configuration app.json existant de l'application Hello World que vous avez créé précédemment, mettez à jour le champ id pour spécifier une autre version. Par exemple, ajoutez -2 :
```
"id": "appengine-helloworld-2"
```
2. Suivez à nouveau la même procédure pour déployer une version appengine-helloworld-2 ; par exemple :
  1. Authentifiez-vous sur votre projet.
  2. Déployez la nouvelle version appengine-helloworld-2.
  3. Vérifiez que la version appengine-helloworld-2 a bien été déployée.
  4. Affichez l'application en cours d'exécution dans votre navigateur Web.

Suivez les instructions de répartition du trafic de la page Migrer le trafic et le répartir, puis envoyez par exemple une requête HTTP PATCH :

PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split { 'split': { 'shardBy': 'IP', 'allocations': { 'appengine-helloworld': '0.5', 'appengine-helloworld-2': '0.5' } } }

Exemple de commande curl :

curl -X PATCH -H "Content-Type: application/json" -d "{ 'split': { 'shardBy': 'IP', 'allocations': { 'appengine-helloworld': '0.5', 'appengine-helloworld-2': '0.5' } } }" -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split

Où :

[MY_ACCESS_TOKEN] est le jeton d'accès obtenu pour autoriser les requêtes HTTP.
[MY_PROJECT_ID] est l'ID du projet sur lequel vous souhaitez déployer la version.

Étape suivante

Créez, et configurez des identifiants pour vos applications : Accéder à l'API