Migrer et répartir le trafic 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

Gérez la quantité de trafic reçue par une version de votre application en effectuant une migration ou une répartition du trafic.

La migration du trafic bascule progressivement le routage des requêtes en déplaçant progressivement le trafic des versions recevant actuellement le trafic vers une ou plusieurs versions que vous spécifiez.

La répartition du trafic répartit un pourcentage du trafic entre les versions de votre application. Vous pouvez répartir le trafic pour transférer 100% du trafic vers une seule version ou pour acheminer des pourcentages de trafic vers plusieurs versions. La répartition du trafic entre plusieurs versions vous permet d'effectuer des tests A/B entre vos versions et de contrôler le rythme de déploiement des fonctionnalités.

N'oubliez pas : elle s'applique aux URL qui ne ciblent pas explicitement une version. Par exemple, les URL suivantes répartissent le trafic, car elles ciblent toutes les versions disponibles du service spécifié :

[MY_PROJECT_ID].[REGION_ID].r.appspot.com - Distribue le trafic vers les versions du service default.
[MY_SERVICE]-dot-[MY_PROJECT_ID].[REGION_ID].r.appspot.com - Distribue le trafic vers les versions du service MY_SERVICE.

Pour en savoir plus, consultez la page Mode de routage des requêtes.

Pour effectuer manuellement la migration et la répartition du trafic à partir de la console Google Cloud, consultez les pages Migrer le trafic et Répartir le trafic.

Avant de commencer

La migration du trafic avec l'API Admin se comporte différemment de la console Google Cloud. Pour migrer le trafic avec l'API Admin, vous devez être en mesure d'autoriser vos requêtes HTTP et vos versions doivent répondre aux exigences de migration du trafic:

Conditions requises pour la migration du trafic (migrateTraffic=true) :

Votre compte utilisateur doit inclure les privilèges requis pour que vous puissiez configurer le trafic.
La migration progressive du trafic n'est pas disponible dans l'environnement flexible App Engine.
Pour effectuer une migration progressive du trafic, les versions cibles doivent être situées dans des instances configurées pour :
- Requêtes de préchauffage
- Scaling automatique
  
  Pour plus d'informations, consultez la app.yaml.

Migrer ou répartir le trafic

Pour migrer ou répartir le trafic entre les versions de votre application, procédez comme suit :

Autorisez les requêtes HTTP, à l'aide d'un jeton d'accès par exemple.

Vous pouvez obtenir l'autorisation d'accéder à l'API Admin à l'aide de différents flux OAuth en fonction des besoins de votre application API. Pour en savoir plus, consultez la page Accéder à l'API.

Conseil : Si vous le souhaitez, vous pouvez obtenir des jetons d'accès directement depuis la page OAuth 2.0 Playground.
Utilisez la méthode patch de la collection apps.services pour mettre à jour la configuration de votre version afin de migrer le trafic ou de configurer la répartition du trafic. L'exemple de requête HTTP PATCH suivant a été encapsulé intentionnellement pour des raisons de lisibilité :
```
PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/
  ?updateMask=split {
    "split": {
      "shardBy": "[MY_SHARDBY_METHOD]",
      "allocations": { "[MY_APP_VERSION]": [MY_TRAFFIC_PERCENT] }
    }
  }
```
Paramètres et champs de la requête HTTP :
- updateMask : spécifie les champs de la configuration à mettre à jour.
- migrateTraffic=true (facultatif) : indique de migrer le trafic de manière progressive.
  Important : Les versions pour lesquelles vous souhaitez migrer le trafic doivent répondre aux exigences de migration du trafic.
- split : définit la configuration du trafic vers vos versions.
  - shardBy (facultatif) : définit la méthode utilisée pour répartir le trafic. Obligatoire pour la migration progressive du trafic (migrateTraffic=true). Les valeurs valides sont COOKIE ou IP.
  - allocations : définit une ou plusieurs versions, ainsi que le pourcentage de trafic distribué à chaque version. La version et le pourcentage du trafic sont spécifiés en tant que paire key:value. Le pourcentage de trafic est spécifié sous forme de fraction décimale et doit être égale à 1. Exemple : "allocations": { "v1": 0.8, "v2": 0.2 }
Pour en savoir plus et obtenir la liste complète des paramètres et des champs, consultez la collection apps.services.

Exemples de requêtes HTTP :
- Déplacer tout le trafic vers une version :
```
PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split {"split": { "allocations": { "v1": 1 } } }
```
- Migrer tout le trafic vers v2 :
```
PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split&migrateTraffic=true {"split": { "shardBy": "IP", "allocations": { "v2": 1 } } }
```
- Répartir 80% du trafic vers la version v1 et 20% vers la version v2 :
```
PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split { "split": { "shardBy": "IP", "allocations": { "v1": 0.8, "v2": 0.2 } } }
```

Exemple : Déplacer le trafic vers une autre version

Cet exemple montre comment déplacer tout le trafic vers une nouvelle version que vous venez de déployer. Par exemple, le serveur renvoie des erreurs, donc vous avez corrigé le bug, déployé la nouvelle version de v2 et vous souhaitez à présent rediriger tout le trafic.

Pour déplacer tout le trafic de v1 vers v2, procédez comme suit :

Vérifiez que 100% du trafic est actuellement envoyé à la version v1 avec la méthode GET de la collection apps.services.

Exemple de requête HTTP GET :

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

Exemple de réponse :

{
  "name": "apps/[MY_PROJECT_ID]/services/default",
  "id": "default",
  "split": {
    "allocations": {
      "v1": 1
    }
  }
}

Mettez à jour la configuration de la répartition du trafic de sorte que tout le trafic soit déplacé vers la nouvelle version à l'aide de la méthode PATCH de la collection apps.services.

Dans la requête HTTP PATCH, vous devez spécifier le service de votre application dans lequel les deux versions sont en cours d'exécution, par exemple default. Vous devez également inclure le champ updateMask avec la valeur split pour spécifier que vous mettez à jour la configuration de la répartition du trafic.

Exemple de requête HTTP PATCH :

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

Exemple de commande curl :

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

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": "2015-05-29T17:25:30.413Z",
    "method": "com.google.appengine.v1.Services.UpdateService",
    "target": "apps/[MY_PROJECT_ID]/services/default",
    "user": "me@example.com"
  }
}

PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split&migrateTraffic=true {"split": { "shardBy": "IP", "allocations": { "v2": "1" } } }

Assurez-vous que la mise à jour de la configuration est terminée :
1. Affichez l'état de l'opération de mise à jour avec une requête HTTP GET :
  
  Pour afficher l'état de l'opération qui effectue la mise à jour, vous utilisez la méthode GET de la collection apps.operations avec l'opération name qui a été renvoyée dans la réponse HTTP de l'étape précédente :
  
  Exemple de requête HTTP GET :
```
GET https://appengine.googleapis.com/v1/[OPERATION_NAME]
```
  Où [OPERATION_NAME] est la valeur du champ name dans la réponse de la requête HTTP PATCH que vous avez envoyée à l'étape précédente.
  
  Si la réponse HTTP de l'étape précédente inclut :
```
"name": "apps/[MY_PROJECT_ID]/operations/bdda402c-77a9-4c6d-b022-f2f69ba78420"
```
  Vous envoyez ensuite la requête HTTP suivante pour afficher l'état de l'opération :
```
GET https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/operations/bdda402c-77a9-4c6d-b022-f2f69ba78420
```
  Exemple de commande curl :
```
curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/operations/bdda402c-77a9-4c6d-b022-f2f69ba78420
```
2. Une fois l'opération terminée, vous pouvez afficher les détails du service où la version se trouve avec une autre requête HTTP GET :
  
  Exemple de requête HTTP GET :
```
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
```
Facultatif : Vous pouvez maintenant supprimer la version v1 défectueuse de votre application App Engine à l'aide d'une requête HTTP DELETE.

Exemple de requête HTTP DELETE :
```
DELETE https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions/v1
```
Exemple de commande curl :
```
curl -X DELETE -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions/v1
```
Conseil : Vous pouvez exécuter des requêtes HTTP GET pour vérifier que l'opération a réussi : une pour vérifier que l'opération de suppression a bien été exécutée, et l'autre pour vérifier que la version a bien été supprimée.

Exemple : répartition du trafic entre les versions

Cet exemple montre comment configurer la répartition du trafic sur plusieurs versions de votre application. Par exemple, vous venez de créer des versions v2 et v3 qui incluent chacune de nouvelles fonctionnalités, mais vous souhaitez déployer ces fonctionnalités lentement afin qu'elles ne reçoivent que 20% du trafic chacune.

Après le déploiement des versions v2 et v3 sur votre application App Engine, vous utilisez la requête HTTP PATCH pour configurer les trois versions afin que le trafic soit réparti à 60% sur v1 et à 20% sur v2 comme sur v3 :

Exemple de requête HTTP PATCH :

PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split { "split": { "shardBy": "IP", "allocations": { "v1": "0.6", "v2": "0.2", "v3": "0.2" } } }

Exemple de commande curl :

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

Après avoir vérifié que l'opération est terminée, vous pouvez envoyer la requête HTTP GET pour vérifier que le trafic a été réparti entre vos versions ; par exemple :

Exemple de requête HTTP PATCH :

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

Exemple de réponse :

{
  "name": "apps/[MY_PROJECT_ID]/services/default",
  "id": "default",
  "split": {
    "allocations": {
      "v1": 0.6,
      "v2": 0.2,
      "v3": 0.2
    }
  }
}