Como estruturar serviços da Web no App Engine

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.

Use este documento para entender como estruturar os serviços e recursos relacionados do seu aplicativo do App Engine.

Estrutura do diretório

Cada versão do serviço do App Engine é definida em um arquivo de configuração app.yaml. Para aplicativos simples, o requisito mínimo para implantação é definir o arquivo app.yaml. O arquivo app.yaml atua como um descritor de implantação e define o tipo de escalonamento e o ambiente de execução, os gerenciadores e outras configurações de recursos para uma versão específica de um serviço. Se você pretende implantar várias versões de um serviço, é possível criar vários arquivos YAML no mesmo diretório para representar a configuração de cada uma.

Quando você está desenvolvendo localmente, é possível criar diretórios separados para cada serviço na raiz do aplicativo. Se você hospedar o aplicativo em um sistema de controle de versão (VCS, na sigla em inglês), como o GitHub, também poderá estruturá-lo para usar diretórios separados em um repositório ou usar repositórios separados para cada serviço. Cada diretório ou repositório precisa representar um único serviço e conter o arquivo app.yaml desse serviço com o código-fonte associado.

Você tem a opção de especificar um nome exclusivo para cada arquivo app.yaml do serviço. Por exemplo, é possível nomear um arquivo de configuração com o mesmo nome do serviço ou usar nomes exclusivos para representar cada versão deste serviço específico, como service1.yaml ou app.standard.yaml.

Os outros arquivos de configuração opcionais devem residir no diretório raiz ou no repositório do serviço default do seu aplicativo. Estes arquivos de configuração opcionais aplicam configurações de todo o aplicativo que não são específicas de um determinado serviço, incluindo os arquivos dispatch.yaml, index.yaml e cron.yaml.

Exemplos

O exemplo a seguir demonstra como fica um aplicativo com três serviços se ele estiver sendo desenvolvido localmente. O dispatch.yaml opcional foi adicionado a esse aplicativo no diretório raiz. Na raiz, também há três diretórios para cada um dos serviços do aplicativo. O subdiretório para service1 inclui os arquivos de origem e configuração para esse serviço. Da mesma forma, ambos service2 e service3 estão em diretórios separados, que contêm os arquivos de cada serviço, ainda que service3 inclua duas versões do arquivo de configuração YAML:

Gráfico hierárquico de serviços YAML

Para um único aplicativo de serviço, este aplicativo incluirá apenas o serviço default, e todos os arquivos poderão residir no mesmo diretório, na raiz deste aplicativo. No exemplo a seguir, a estrutura possível de um único aplicativo de serviço é demonstrada e inclui o arquivo de configuração dispatch.yaml opcional e dois arquivos de configuração que representam versões diferentes deste serviço, service1.yaml e service2.yaml:

Gráfico hierárquico de pequenos serviços YAML

Considerações de design sobre o tempo de atividade da instância

Falhas de hardware ou software que causam o encerramento antecipado ou reinicializações frequentes da instância podem ocorrer sem qualquer aviso e levar muito tempo para serem solucionadas. O aplicativo precisa ser capaz de lidar com essas falhas.

Confira algumas boas estratégias para evitar a inatividade devido a reinicializações da instância:

  • Reduza o tempo necessário para a reinicialização das instâncias ou para que novas instâncias sejam inicializadas.
  • Para cálculos de longa duração, crie checkpoints periodicamente para que seja possível retomar a partir desse estado.
  • O aplicativo precisa ser "sem estado" para que nada seja armazenado na instância.
  • Use filas para executar tarefas assíncronas.
  • Se você configurar as instâncias para escalonamento manual:
    • Use o balanceamento de carga em várias instâncias.
    • configure mais instâncias do que o necessário para processar o tráfego normal;
    • escreva uma lógica de fallback que use resultados em cache quando não houver uma instância de escalonamento manual disponível.

Saiba mais sobre instâncias em Como as instâncias são gerenciadas.

O serviço default

Cada aplicativo do App Engine inclui um serviço default. É preciso implantar a versão inicial do seu aplicativo no serviço default antes de criar e implantar mais serviços no seu aplicativo.

O serviço padrão pode ser especificado opcionalmente em app.yaml com a configuração service: default.

As solicitações enviadas ao app usando o projeto do Google Cloud são enviadas para o serviço default, por exemplo, https://PROJECT_ID.REGION_ID.r.appspot.com. Para saber mais sobre como segmentar outros serviços, consulte Comunicação entre serviços.

Arquivos de configuração opcionais

Os arquivos de configuração a seguir controlam recursos opcionais que se aplicam a todos os serviços em um determinado app. Consulte os tópicos a seguir para mais detalhes sobre cada um dos recursos opcionais:

  • dispatch.yaml modifica as regras padrão de roteamento enviando solicitações recebidas para um serviço específico com base no caminho ou nome do host no URL.
  • index.yaml especifica quais índices são necessários para o aplicativo ao usar consultas do Datastore.
  • cron.yaml configura tarefas programadas regularmente que operam em horários definidos ou em intervalos regulares.

Considerações sobre armazenamento de dados e arquivos

No App Engine, é possível acessar facilmente outros serviços do Google Cloud, como Datastore, Cloud SQL e Cloud Storage.

Também é possível usar um banco de dados externo ou de terceiros caso ele seja compatível com sua linguagem e possa ser acessado na instância do App Engine.

Saiba mais sobre como armazenar arquivos no Google Cloud ou externamente em Noções básicas sobre armazenamento de dados e arquivos.

Também é possível escolher como exibir o conteúdo estático. É possível exibir o conteúdo estático do aplicativo a partir do próprio aplicativo no App Engine, hospedá-lo em uma opção do Google Cloud, como o Cloud Storage, ou usar uma rede de fornecimento de conteúdo (CDN) de terceiros. Para mais informações sobre a exibição de conteúdo estático, consulte este artigo.

A seguir

Se você trabalha com vários serviços e quer implantar todos eles juntos, consulte as etapas para implantar vários serviços.