Teste e implemente a sua aplicação

ID da região

O REGION_ID é um código abreviado que a Google atribui com base na região que seleciona quando cria a sua app. O código não corresponde a um país ou uma província, embora alguns IDs de regiões possam parecer semelhantes aos códigos de países e províncias usados frequentemente. Para apps criadas após fevereiro de 2020, REGION_ID.r está incluído nos URLs do App Engine. Para apps existentes criadas antes desta data, o ID da região é opcional no URL.

Saiba mais acerca dos IDs de regiões.

OK

Go Java Node.js PHP Python Ruby .NET Personalizado

Saiba como executar a sua aplicação localmente, implementá-la e testá-la no App Engine.

Executar localmente

Para testar a sua aplicação antes da implementação, execute-a no ambiente local com as ferramentas de desenvolvimento que usa habitualmente. Por exemplo, normalmente, pode executar uma aplicação Flask com o servidor de desenvolvimento do Flask através do seguinte comando:

python main.py

Inicie aplicações Django com:

python manage.py runserver

Para simular um ambiente de produção do App Engine, pode executar o servidor da interface de gateway do servidor Web (WSGI) completo localmente. Use o mesmo comando especificado como entrypoint no ficheiro app.yaml, por exemplo:

gunicorn -b :$PORT main:app

Implemente a sua aplicação

Implemente a sua aplicação no App Engine através do comando gcloud app deploy.

O serviço Cloud Build cria automaticamente a sua implementação numa imagem de contentor e implementa a imagem no ambiente flexível do App Engine. O contentor inclui todas as modificações locais que fez à imagem de tempo de execução.

Para implementar as suas apps programaticamente, use a API Admin.

Antes de começar

Antes de poder implementar a sua aplicação:

• O proprietário do projeto tem de configurar o projeto Google Cloud para o App Engine. Google Cloud

• Certifique-se de que a sua conta de utilizador inclui os privilégios necessários.

Garanta uma implementação bem-sucedida

Se ativar as verificações de saúde atualizadas, as implementações são revertidas se a sua aplicação não atingir o estado de funcionamento. Quando implementa a sua primeira aplicação no ambiente flexível, pode haver um atraso enquanto a máquina virtual (VM) e outra infraestrutura são configuradas. Após a configuração inicial, as verificações do estado garantem que a sua instância está em bom estado e pronta para receber tráfego. Se a sua aplicação não atingir o estado de preparação num período especificado, indicado pelo campo initial_delay_sec na secção liveness_check do ficheiro app.yaml, a implementação falha e é revertida.

A sua aplicação pode precisar de mais tempo para ficar pronta. Por exemplo, pode inicializar a sua aplicação transferindo ficheiros grandes ou pré-carregando caches. Se estiver a usar verificações de estado atualizadas, pode aumentar o período modificando a definição de configuração app_start_timeout_sec na secção readiness_check do ficheiro app.yaml.

Se a implementação falhar, certifique-se de que a API Cloud Build está ativada no seu projeto. O App Engine ativa esta API automaticamente na primeira vez que implementa uma app, mas se alguém tiver desativado a API desde então, as implementações falham.

Implemente um serviço

Implementa a sua aplicação no App Engine implementando versões dos serviços da sua aplicação e cada um dos respetivos ficheiros de configuração.

Para implementar o serviço da sua aplicação, execute o seguinte comando a partir do diretório onde se encontra o ficheiro app.yaml do seu serviço:

gcloud app deploy

Por predefinição, o comando gcloud app deploy implementa apenas o ficheiro app.yaml no diretório atual. Sempre que executa este comando, o App Engine gera um ID exclusivo para a versão que implementa, implementa a versão no projeto que configurou para a CLI gcloud usar e encaminha todo o tráfego para a nova versão.Google Cloud A nova versão torna-se a versão predefinida.

Nota: é uma boa prática verificar a página Versões do App Engine na Google Cloud consola ou executar gcloud app versions list após executar o comando gcloud app deploy para verificar a versão que está a receber tráfego.

Pode alterar o comportamento predefinido do comando deploy: segmentando ficheiros específicos, especificando versões ou incluindo parâmetros adicionais:

• Pode implementar os outros ficheiros de configuração do seu serviço segmentando e implementando cada ficheiro em separado, por exemplo:

  gcloud app deploy cron.yaml
  gcloud app deploy dispatch.yaml
  gcloud app deploy index.yaml
  

• Para especificar um ID da versão personalizado, use a flag --version.

• Para impedir que o tráfego seja encaminhado automaticamente para a nova versão, use a flag --no-promote.

• Para implementar num Google Cloud projeto--project específico, use a flag --project.

Por exemplo, para implementar o serviço definido pelo ficheiro app.yaml num projeto específico, atribua ao serviço um ID de versão personalizado e impeça o encaminhamento do tráfego para a nova versão:Google Cloud

gcloud app deploy --project PROJECT_ID --version VERSION_ID --no-promote

Para mais informações, consulte a gcloud app deploy referência.

Pode definir propriedades para a CLI gcloud e criar e gerir configurações do SDK para não ter de especificar flags como --project sempre que implementar.

Quando implementa uma nova versão com o mesmo nome de uma versão existente, o App Engine migra imediatamente o tráfego para a nova versão. Existe um pico de latência quando o App Engine carrega pedidos para a nova versão. A nova versão substitui a anterior e não pode migrar o tráfego para a versão anterior. Quando implementa uma nova versão com o mesmo nome que a versão anterior, o App Engine implementa a nova imagem de contentor nas máquinas virtuais existentes para uma implementação mais rápida e atualiza o contentor da sua aplicação nas máquinas virtuais existentes.

Implemente vários serviços

Usa o mesmo comando de implementação para implementar ou atualizar os vários serviços que compõem a sua aplicação.

Antes de começar:

• Inicialmente, tem de implementar uma versão da sua aplicação no serviço default antes de poder criar e implementar serviços subsequentes.

• O ID de cada um dos seus serviços tem de ser especificado nos respetivos ficheiros de configuração app.yaml. Para especificar o ID do serviço, inclua a definição do elemento service em cada ficheiro de configuração. Por predefinição, a exclusão desta definição de elemento do ficheiro de configuração implementa a versão no serviço default.

Para implementar vários serviços, tem de implementar separadamente o ficheiro app.yaml de cada serviço, por exemplo:

gcloud app deploy service1/app.yaml
gcloud app deploy service2/app.yaml

Pode especificar vários ficheiros com um único comando de implementação:

gcloud app deploy service1/app.yaml service2/app.yaml

Ignore ficheiros

Pode usar um ficheiro .gcloudignore para especificar ficheiros e diretórios que não devem ser carregados para Google Cloud quando implementa os seus serviços. Isto é útil para ignorar artefactos de compilação e outros ficheiros que não precisam de ser carregados com a sua implementação.

Nota: não pode especificar o campo skip_files no ficheiro app.yaml se tiver um ficheiro .gcloudignore.

Saiba mais sobre a sintaxe do ficheiro .gcloudignore na gcloud referência.

Crie manualmente um contentor para implementação

Atenção: o Container Registry foi descontinuado. A partir de 18 de março de 2025, o Container Registry é encerrado e a gravação de imagens no Container Registry fica indisponível. Para ver detalhes sobre a descontinuação e como migrar para o Artifact Registry, consulte Descontinuação do Container Registry.

Para criar as imagens de contentor fora do Google Cloud:

1. Carregue as suas imagens para um repositório do Artifact Registry. Para mais informações, consulte o artigo Envie e receba imagens.
2. Implemente no App Engine com o comando gcloud app deploy.

Por exemplo, se criar as imagens de contentores localmente com o Docker, pode enviar essas imagens para o Artifact Registry e especificar o URL da imagem na flag --image-url do comando:

gcloud app deploy --image-url LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE

Substituição:

• LOCATION com a localização do repositório onde a imagem está armazenada.

• PROJECT-ID com o seu Google Cloud ID do projeto.

• REPOSITORY com o nome do repositório onde a imagem está armazenada.

• IMAGE com o nome da imagem do contentor.

Use pipelines de implementação contínua automatizados

Pode usar o Cloud Build para automatizar implementações em pipelines de implementação contínua. Para mais informações, consulte os artigos Implementação no App Engine e Crie e faça a gestão de acionadores de compilação na documentação do Cloud Build.

Imagens base do Docker

Se quiser criar uma aplicação de tempo de execução personalizada, consulte o artigo Crie um ficheiro Docker.

Veja a sua candidatura

Depois de implementar a aplicação no App Engine, pode executar o seguinte comando para iniciar o navegador e vê-la em https://PROJECT_ID.REGION_ID.r.appspot.com:

gcloud app browse

Teste no App Engine

Antes de configurar uma nova versão para receber tráfego, pode testá-la no App Engine. Por exemplo, para testar uma nova versão do seu serviço default:

1. Implemente a nova versão e inclua a flag --no-promote:

   gcloud app deploy --no-promote

2. Aceda à nova versão navegando para o seguinte URL:

   https://VERSION_ID-dot-default-dot-PROJECT_ID.REGION_ID.r.appspot.com

   Nota: pode encontrar o ID da versão na Google Cloud consola ou especificar um quando fizer a implementação com o parâmetro version.

   Agora, pode testar a nova versão no ambiente de tempo de execução do App Engine. Pode depurar a sua aplicação vendo os respetivos registos noGoogle Cloud Explorador de registosda consola. Para mais informações, consulte o artigo Escrever registos de aplicações.

   Os pedidos enviados para https://PROJECT_ID.REGION_ID.r.appspot.com continuam a ser encaminhados para a versão configurada anteriormente para receber tráfego.

3. Quando quiser enviar tráfego para a nova versão, use a Google Cloud consola para migrar o tráfego:

   Faça a gestão das versões

   Selecione a versão que acabou de implementar e clique em Migrar tráfego.

Pode usar o mesmo processo para testar novas versões de outros serviços substituindo default no URL pelo nome do seu serviço:

https://VERSION-dot-SERVICE-dot-PROJECT_ID.REGION_ID.r.appspot.com

Para mais informações sobre a segmentação de serviços e versões específicos, consulte o artigo Como os pedidos são encaminhados.

Use variáveis de ambiente de compilação

Pode definir variáveis de ambiente de compilação para tempos de execução que suportam buildpacks.

As variáveis de ambiente de compilação são pares de chave-valor que pode especificar para configurar o buildpack que usa para implementar a sua app. Por exemplo, pode querer especificar opções do compilador.

Antes de começar:

• As chaves têm de começar com uma letra ASCII em maiúsculas e podem incluir letras ASCII em maiúsculas, dígitos e sublinhados.
• Deve evitar criar variáveis com um prefixo de chave GOOGLE_*.
• As seguintes chaves estão reservadas para utilização pela Google:
  • GOOGLE_RUNTIME
  • GOOGLE_RUNTIME_VERSION
  • GOOGLE_ENTRYPOINT
  • GOOGLE_DEVMODE
• Pode usar qualquer chave suportada por buildpacks.

Para usar variáveis de ambiente com buildpacks, especifique o campo build_env_variables no ficheiro app.yaml.

Saiba mais acerca dos buildpacks.

Use o Cloud Trace

O Cloud Trace é útil para compreender como os pedidos se propagam através da sua aplicação. Pode inspecionar informações detalhadas de latência para um único pedido ou ver a latência agregada para toda a sua aplicação.

Pode ver os detalhes do rastreio. No Explorador de rastreios, pode filtrar por um serviço e uma versão específicos do App Engine.

Resolver problemas

Seguem-se mensagens de erro comuns que pode encontrar quando implementa apps:

PERMISSION_DENIED: Operation not allowed

The "appengine.applications.create" permission is required.

Se o Google Cloud projeto não incluir a aplicação App Engine necessária, o comando gcloud app deploy pode falhar quando tenta executar o comando gcloud app create. Apenas as contas com a função Proprietário têm as autorizações necessárias para criar aplicações do App Engine.

502 Bad Gateway

O Google Cloud projeto pode não ser iniciado se o app.yaml estiver configurado incorretamente. Verifique os registos da app para ver mensagens de erro mais detalhadas.

[13] An internal error occurred while creating a Cloud Storage bucket.

O App Engine cria um contentor multirregional do Cloud Storage predefinido em seu nome na mesma região onde cria a sua aplicação. Requer que este contentor armazene o conteúdo da sua aplicação. O erro é devolvido quando não é possível criar este contentor, como nos seguintes cenários:

• O agente de serviço do ambiente flexível do App Engine não está presente no seu projeto ou não tem a função App Engine flexible environment Service Agent. Pode adicionar novamente a conta de serviço do agente ao seu projeto concedendo-lhe as autorizações de IAM corretas. Consulte o artigo Restaure um agente de serviço eliminado.

• A conta de serviço predefinida do App Engine não está presente no seu projeto. Se a conta de serviço do App Engine tiver sido removida antes de decorridos 30 dias desde a respetiva eliminação, pode restaurá-la.

• O seu projeto está numa organização que aplica a constraints/gcp.resourceLocations política e a organização não permite a criação de recursos na mesma região onde o App Engine foi criado. Tem de substituir a política constraints/gcp.resourceLocations aplicada para o seu projeto e permitir as localizações de várias regiões na mesma região onde a sua app do App Engine é criada.

Por exemplo, se a sua app do App Engine for criada na região europe-west, mesmo que a região seja mapeada para as localizações europe-west1, tem de modificar a restrição para permitir recursos em in:eu-locations, que inclui todas as regiões EU. Isto é necessário porque os contentores criados pelo App Engine são multirregionais. Se a sua app do App Engine for criada na região US, tem de permitir in:us-locations. Se a sua app for criada nas regiões ASIA, tem de permitir in:asia-locations.

[13] An internal error occurred.

Este erro pode ocorrer se estiver a implementar o seu serviço com uma configuração de rede que usa uma configuração de VPC partilhada. Experimente o seguinte:

1. Certifique-se de que a configuração do app.yaml é válida.
2. Certifique-se de que o ambiente flexível do App Engine cumpre todos os requisitos para uma configuração de VPC partilhada. Consulte o artigo Usar o ambiente flexível do App Engine numa rede VPC partilhada.
3. Certifique-se de que tem contas de serviço configuradas no seu projeto. Caso contrário, tem de restaurar as contas. A região da sub-rede no projeto anfitrião da VPC partilhada tem de corresponder à localização onde o ambiente do App Engine foi criado.

Se o problema persistir, volte a implementar o serviço através do SDK do Google Cloud. Certifique-se de que adiciona a flag --verbosity=debug. Contacte o Google Cloud apoio técnico e faculte o resultado do comando.

IP space of {USER_SUBNETWORK_NAME} is exhausted and needs to be expanded.

Se a implementação falhar com esta mensagem de erro, significa que a rede configurada para o serviço do App Engine não tem endereços disponíveis para alocar às novas instâncias do serviço. Para resolver o problema, expanda os intervalos de VPC na sub-rede configurada para o seu serviço do ambiente flexível do App Engine.