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:
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:
- Na Tela de consentimento OAuth, especifique pelo menos seu Endereço de e-mail e o Nome do produto mostrado aos usuários.
- Salve as configurações da tela de consentimento e alterne para a guia Credenciais, clicando em Salvar.
- Clique em Criar credenciais e em ID do cliente do OAuth para criar um ID do cliente
Clique em Aplicativo da Web, especifique um nome e use
https://www.google.com
como o URI de redirecionamento.Clique em Criar para salvar a credencial.
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]
eredirect_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 campoaccess_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 HTTPGET
, 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 camponame
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, oREGION_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:
No arquivo de configuração
app.json
atual do aplicativo Hello World que você criou anteriormente, atualize o campoid
para especificar uma versão diferente. Por exemplo, anexe um-2
:"id": "appengine-helloworld-2"
Siga todas as mesmas etapas novamente para implantar uma versão do
appengine-helloworld-2
, por exemplo:- Faça sua autenticação no projeto.
- Implante a nova versão
appengine-helloworld-2
. - Verifique se a versão
appengine-helloworld-2
foi implantada. - 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.