Como migrar e dividir o tráfego com a API Admin

ID da região

O REGION_ID é um código abreviado que o Google atribui com base na região que você selecionou ao criar o aplicativo. O código não corresponde a um país ou estado, ainda que alguns IDs de região sejam semelhantes aos códigos de país e estado geralmente usados. Para apps criados após fevereiro de 2020, o REGION_ID.r está incluído nos URLs do App Engine. Para apps existentes criados antes dessa data, o ID da região é opcional no URL.

Saiba mais sobre IDs de região.

Migre ou divida o tráfego para gerenciar o volume que cada versão do aplicativo recebe.

A migração de tráfego altera com facilidade o encaminhamento de solicitações, transferindo gradualmente o tráfego para uma ou mais versões especificadas por você.

A divisão de tráfego distribui um percentual do tráfego para diferentes versões do seu aplicativo. É possível dividir o tráfego movendo-o integralmente para uma única versão ou direcionar partes dele para várias versões. A divisão do tráfego em duas ou mais versões permite a realização de testes A/B entre elas e fornece controle sobre o ritmo do lançamento de recursos.

Lembre-se: a divisão de tráfego é aplicada a URLs que não segmentam uma versão explicitamente. Por exemplo, os seguintes URLs dividem o tráfego porque segmentam todas as versões disponíveis no serviço especificado:

[MY_PROJECT_ID].[REGION_ID].r.appspot.com: distribui o tráfego para as versões do serviço default.
[MY_SERVICE]-dot-[MY_PROJECT_ID].[REGION_ID].r.appspot.com: distribui o tráfego para as versões do serviço MY_SERVICE.

Para mais informações, consulte Como as solicitações são encaminhadas.

Para realizar a migração e a divisão manualmente a partir do Console do Google Cloud, consulte Como migrar tráfego e Como dividir o tráfego.

Antes de começar

A migração de tráfego com a API Admin se comporta de maneira diferente do Console do Google Cloud. Para migrar o tráfego com a API Admin, é preciso autorizar as solicitações HTTP, e as versões precisam atender aos requisitos de migração de tráfego:

Requisitos de migração de tráfego (migrateTraffic=true):

Sua conta de usuário precisa incluir os privilégios exigidos para que você possa configurar o tráfego.
A migração gradual do tráfego não é compatível com o ambiente flexível do App Engine.
Para executar uma migração gradual do tráfego, as versões de destino precisam estar localizadas em instâncias configuradas para:
- Solicitações de aquecimento
- Escalonamento automático
  
  Para informações sobre configuração, consulte a Referência do app.yaml.

Como migrar ou dividir o tráfego

Para migrar ou dividir o tráfego entre as versões do aplicativo, siga estas etapas:

Autorize suas solicitações HTTP, por exemplo, receba um token de acesso.

É possível autorizar o acesso à API Admin usando diferentes fluxos do OAuth, dependendo das necessidades do aplicativo de API. Para mais informações, consulte Como acessar a API.

Dica: se quiser usar tokens de acesso, receba-os imediatamente no OAuth 2.0 Playground.
Use o método patch da coleção apps.services para atualizar a configuração da sua versão para migrar o tráfego ou configurar a divisão de tráfego. A amostra seguinte de solicitação HTTP PATCH foi encapsulada intencionalmente para facilitar a leitura:
```
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] }
    }
  }
```
Parâmetros e campos da solicitação de HTTP:
- updateMask: especifica os campos da configuração a serem atualizados.
- migrateTraffic=true (opcional): especifica a migração gradual do tráfego.
  Importante: para poder migrar o tráfego, as versões precisam atender aos requisitos de migração de tráfego.
- split: define a configuração do tráfego para as versões.
  - shardBy (opcional): define o método usado para dividir o tráfego. Necessário para migração gradual de tráfego (migrateTraffic=true). Os valores válidos são COOKIE ou IP.
  - allocations: define uma ou mais versões e a porcentagem de tráfego distribuída para cada versão. A versão e o percentual de tráfego são especificados como um par key:value. A porcentagem de tráfego é especificada como frações decimais que devem totalizar 1. Exemplo: "allocations": { "v1": 0.8, "v2": 0.2 }
Consulte a coleção apps.services para mais detalhes e a lista completa de parâmetros e campos.

Exemplo de solicitações HTTP:
- Mover todo o tráfego para uma versão:
```
PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split {"split": { "allocations": { "v1": 1 } } }
```
- Migrar todo o tráfego para v2:
```
PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split&migrateTraffic=true {"split": { "shardBy": "IP", "allocations": { "v2": 1 } } }
```
- Divida 80% do tráfego para a versão v1 e 20% para 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 } } }
```

Exemplo: como mover o tráfego para outra versão

Este exemplo demonstra como mover todo o tráfego para a nova versão que você acabou de implantar. Por exemplo, o servidor está retornando erros, então você corrigiu o bug, implantou a nova versão v2 e agora quer redirecionar todo o tráfego.

Para mover todo o tráfego de v1 para v2:

Verifique se 100% do tráfego está sendo enviado para a versão v1 com o método GET da coleção apps.services.

Exemplo de solicitação HTTP GET:

GET https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default

Exemplo de comando cURL:

 curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default

Exemplo de resposta:

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

Atualize a configuração de divisão de tráfego para que todo o tráfego seja movido para a nova versão usando o método PATCH da coleção apps.services.

Na solicitação HTTP PATCH, especifique o serviço no aplicativo em que ambas as versões estão em execução, por exemplo, default. Inclua também o campo updateMask com o valor split para especificar que você está atualizando a configuração de divisão de tráfego.

Exemplo de solicitação HTTP PATCH:

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

Exemplo de comando 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

Exemplo de resposta:

{
  "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" } } }

Assegure-se de que a atualização da configuração esteja concluída:
1. Visualize o status da operação de atualização com uma solicitação HTTP GET:
  
  Para visualizar o status da operação que está executando a atualização, use o método GET da coleção apps.operations com a operação name retornada na resposta HTTP da etapa anterior:
  
  Exemplo de solicitação HTTP GET:
```
GET https://appengine.googleapis.com/v1/[OPERATION_NAME]
```
  Em que [OPERATION_NAME] é o valor do campo name na resposta da solicitação HTTP PATCH enviada na etapa anterior.
  
  Se a resposta HTTP da etapa anterior incluir:
```
"name": "apps/[MY_PROJECT_ID]/operations/bdda402c-77a9-4c6d-b022-f2f69ba78420"
```
  envie a seguinte solicitação HTTP para visualizar o status da operação:
```
GET https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/operations/bdda402c-77a9-4c6d-b022-f2f69ba78420
```
  Exemplo de comando cURL:
```
curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/operations/bdda402c-77a9-4c6d-b022-f2f69ba78420
```
2. Após a conclusão da operação, é possível visualizar os detalhes do serviço em que a versão está com outra solicitação GET HTTP:
  
  Exemplo de solicitação HTTP GET:
```
GET https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default
```
  Exemplo de comando cURL:
```
curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default
```
Opcional: agora é possível remover a versão v1 com falha do seu aplicativo do App Engine com uma solicitação HTTP DELETE.

Exemplo de solicitação HTTP DELETE:
```
DELETE https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions/v1
```
Exemplo de comando cURL:
```
curl -X DELETE -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions/v1
```
Dica: é possível executar solicitações HTTP GET para verificar se a operação foi bem-sucedida, verificar se a operação de exclusão foi concluída e verificar se a versão foi excluída.

Exemplo: como dividir o tráfego entre as versões

Neste exemplo demonstramos como configurar a divisão de tráfego em várias versões do aplicativo. Por exemplo, você acabou de criar as versões v2 e v3, que incluem novos recursos, mas quer distribuir esses recursos lentamente para que cada um receba apenas 20% do tráfego.

Depois de implantar as versões v2 e v3 do aplicativo do App Engine, use a solicitação HTTP PATCH para configurar as três versões para que o tráfego seja dividido em 60% v1 e 20% cada para v2 e v3:

Exemplo de solicitação 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" } } }

Exemplo de comando 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

Depois de confirmar que a operação foi concluída, envie a solicitação HTTP GET para verificar se o tráfego foi dividido entre as versões, por exemplo:

Exemplo de solicitação HTTP PATCH:

GET https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default

Exemplo de comando cURL:

curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default

Exemplo de resposta:

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