Primeiros passos 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.

Este guia foi criado para ajudar você a saber como usar a API Admin do Google App Engine para implantar um aplicativo Python de amostra no App Engine. Você pode usar o processo geral para descobrir como criar o código que gerencia e implanta seus aplicativos de maneira programática.

Neste guia, a amostra usada é um aplicativo Hello World simples que exibe o texto "Hello, World!" e está disponível no GitHub. Para autorização com o console do Google Cloud, é usado um ID do cliente OAuth e um navegador da Web. Para demonstrar as etapas individuais do processo, os comandos cURL permitem enviar solicitações HTTP do seu terminal.

Objetivos

Ative as APIs no projeto do console do Google Cloud e crie credenciais de ID do cliente OAuth.
Receber tokens de acesso para autenticação no App Engine.
Usar a API Admin para implantar o aplicativo de amostra no App Engine.
Opcional: configurar o tráfego para a versão em que você implementou o aplicativo de amostra.

Antes de começar

É necessário ter ou criar uma Conta do Google.
Faça o download e instale a Google Cloud CLI e, em seguida, inicialize a CLI gcloud:
Faça o download do SDK

Como configurar seu projeto do Google Cloud

Ative a API App Engine Admin do Google e as APIs do Cloud Storage no seu projeto do Google Cloud e configure as credenciais:

Ative as APIs no console do Google Cloud:

Ativar as APIs
No assistente, selecione um dos projetos na lista ou clique em Continuar para criar um projeto novo.
Clique em Continuar para criar uma credencial de ID do cliente do OAuth:
1. Na Tela de consentimento OAuth, especifique pelo menos seu Endereço de e-mail e o Nome do produto mostrado aos usuários.
2. Salve as configurações da tela de consentimento e alterne para a guia Credenciais, clicando em Salvar.
3. Clique em Criar credenciais e em ID do cliente do OAuth para criar um ID do cliente
4. Clique em Aplicativo da Web, especifique um nome e use https://www.google.com como o URI de redirecionamento.
  
  Observação: o URI de redirecionamento define para onde a resposta HTTP é enviada. O URI https://www.google.com é usado neste guia como um exemplo, mas, para produção, especifique o endpoint de autenticação do seu aplicativo, que gerencia as respostas do servidor OAuth 2.0.
5. Clique em Criar para salvar a credencial.
6. Anote o ID do cliente exibido porque ele será usado em uma etapa posterior para solicitar o token de acesso.

Para mais informações sobre como criar credenciais para a API Admin, consulte Como acessar a API.

Como criar um arquivo de configuração

Crie um arquivo de configuração que defina a implantação do aplicativo Hello World. Em um arquivo chamado app.json, você define o bucket do Cloud Storage do aplicativo Hello World no campo sourceUrl e as informações de configuração da versão, incluindo o ID no campo 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"
  ]
}

Por exemplo, root/python-docs-samples/appengine/standard/hello_world/app.json.

Como autorizar solicitações HTTP

Autentique-se com o App Engine para enviar solicitações HTTP com a API Admin.

Use uma das seguintes opções para ajudar você a dar os primeiros passos rapidamente. As opções HTTPS e gcloud fornecem etapas manuais, mas simples, para conseguir tokens de acesso com o objetivo de testar a API Admin.

HTTPS

Para simular um fluxo OAuth 2.0 do lado do cliente, adicione sua credencial de ID do cliente OAuth a um URI e, em seguida, envie a solicitação HTTPS por meio do navegador da Web:

No navegador da Web, solicite um token de acesso usando o ID do cliente de suas credenciais da API. O exemplo a seguir usa client_id=[MY_CLIENT_ID] e redirect_uri=https://www.google.com, em que [MY_CLIENT_ID] é o ID do cliente da credencial criada anteriormente:
```
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
```
Recupere o token de acesso da resposta da solicitação.

O campo de endereço no navegador da Web deve conter o URI de redirecionamento especificado nas suas credenciais junto com o token de acesso anexado ao URI, por exemplo:
```
https://www.google.com/#access_token=[MY_ACCESS_TOKEN]&token_type=Bearer&expires_in=3600
```
Agora é possível usar o token de acesso [MY_ACCESS_TOKEN] fornecido no campo access_token para enviar solicitações HTTP para seu projeto do Google Cloud.

gcloud

Para simplesmente recuperar um token de acesso, execute os seguintes comandos gcloud:

Defina a credencial do Application Default Credentials (ADC) que você quer usar para solicitar um token de acesso.
```
gcloud auth application-default login
```

Solicite o token de acesso:

gcloud auth application-default print-access-token

Para ver detalhes sobre esses comandos, consulte gcloud auth application-default.

Lembre-se: seu token de acesso expira em aproximadamente 60 minutos após a emissão.

As opções acima não se destinam a uso em sua implementação programática, mas as informações sobre como implementar um fluxo de autorização do OAuth 2.0 estão disponíveis em Como acessar a API Admin.

Como implantar o aplicativo Hello World

Use uma solicitação HTTP para implantar o aplicativo Hello World com a API Admin:

Envie uma solicitação HTTP POST usando a API Admin para implantar uma versão do aplicativo Hello World no seu aplicativo do App Engine. Por exemplo:

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

Exemplo de comando cURL:

Execute o comando no diretório em que você criou o arquivo de configuração app.json, por exemplo:

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

Em que:

[MY_ACCESS_TOKEN] é o token de acesso que você recebeu para autorizar suas solicitações HTTP.
[MY_PROJECT_ID] é o código do projeto em que você quer implantar a versão.

Exemplo de resposta:

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

em que [MY_PROJECT_ID] é o ID do projeto no Google Cloud.

Verifique se a versão do aplicativo Hello World foi implantada com sucesso no aplicativo do App Engine:

Visualize o status da operação de implantação real usando o nome da operação retornado na etapa anterior como o campo name em um método HTTP GET, por exemplo:

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

Exemplo de comando cURL:

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

Em que:

[OPERATION_NAME] é o valor do campo name que foi retornado na etapa anterior quando você implantou o aplicativo, por exemplo, apps/[MY_PROJECT_ID]/operations/89729825-ef1f-4ffa-b3e3-e2c25eb66a85.
[MY_ACCESS_TOKEN] é o token de acesso que você recebeu para autorizar suas solicitações HTTP.
[MY_PROJECT_ID] é o código do projeto em que você quer implantar a versão.

Exemplo de resposta:

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

em que [MY_PROJECT_ID] é o ID do projeto no Google Cloud.

Verifique se a versão do aplicativo Hello World foi criada no seu aplicativo do App Engine usando uma solicitação HTTP GET para visualizar os detalhes da versão, por exemplo:

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

Exemplo de comando cURL:

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

Em que:

[MY_ACCESS_TOKEN] é o token de acesso que você recebeu para autorizar suas solicitações HTTP.
[MY_PROJECT_ID] é o código do projeto em que você quer implantar a versão.

Exemplo de resposta:

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

em que [MY_PROJECT_ID] é o ID do projeto no Google Cloud.

Visualize o aplicativo Hello World em seu navegador da Web acessando o URL especificado no campo versionUrl da resposta HTTP da etapa anterior. Por exemplo:
```
https://appengine-helloworld-dot-[MY_PROJECT_ID].[REGION_ID].r.appspot.com
```
Em que [MY_PROJECT_ID] é o ID do projeto do Google Cloud.
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.

Configure o tráfego para o aplicativo Hello World.

Por padrão, a versão inicial que você implanta em um novo aplicativo do App Engine recebe automaticamente 100% do tráfego e as versões subsequentes recebem tráfego zero.

Para ver se a versão está configurada para receber tráfego, envie uma solicitação HTTP GET. Por exemplo:

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

Em que:

[MY_ACCESS_TOKEN] é o token de acesso que você recebeu para autorizar suas solicitações HTTP.
[MY_PROJECT_ID] é o código do projeto em que você quer implantar a versão.

Exemplo de resposta:

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

em que [MY_PROJECT_ID] é o ID do projeto no Google Cloud.

Para mover todo o tráfego para uma versão, envie uma solicitação HTTP PATCH. Por exemplo:

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

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

Em que:

[MY_ACCESS_TOKEN] é o token de acesso que você recebeu para autorizar suas solicitações HTTP.
[MY_PROJECT_ID] é o código do projeto em que você quer implantar a versão.

Exemplo de resposta:

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

em que [MY_PROJECT_ID] é o ID do projeto no Google Cloud.

Aprendizado estendido

Se você tiver mais de uma versão de um aplicativo, poderá executar as etapas a seguir para dividir o tráfego entre essas versões:

Para implantar uma segunda versão do aplicativo Hello World no mesmo aplicativo do App Engine:
1. No arquivo de configuração app.json atual do aplicativo Hello World que você criou anteriormente, atualize o campo id para especificar uma versão diferente. Por exemplo, anexe um -2:
```
"id": "appengine-helloworld-2"
```
2. Siga todas as mesmas etapas novamente para implantar uma versão do appengine-helloworld-2, por exemplo:
  1. Faça sua autenticação no projeto.
  2. Implante a nova versão appengine-helloworld-2.
  3. Verifique se a versão appengine-helloworld-2 foi implantada.
  4. Veja seu app no navegador da Web:

Para dividir o tráfego, siga as instruções em Como migrar e dividir o tráfego. Por exemplo, envie uma solicitação PATCH HTTP:

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' } } }

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

Em que:

[MY_ACCESS_TOKEN] é o token de acesso que você recebeu para autorizar suas solicitações HTTP.
[MY_PROJECT_ID] é o código do projeto em que você quer implantar a versão.

A seguir

Crie, configure e defina credenciais para os aplicativos: Como acessar a API.