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.

OK

Neste guia, abordamos como estruturar os serviços e recursos relacionados do App Engine.

Estrutura de diretórios

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.

Observação: no caso do Java, a organização do arquivo depende do ambiente de execução que você está usando. Talvez seja necessário um arquivo WAR ou JAR, um para cada serviço no seu aplicativo. Consulte o guia do desenvolvedor do ambiente de execução do Java apropriado para ver detalhes.

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.

Examples

Um app simples exige apenas que o app.yaml seja adicionado no mesmo local que os arquivos de origem do app. Se houver somente um aplicativo de serviço, ele incluirá defaultdefault e todos os arquivos residirão no mesmo diretório, na raiz desse aplicativo.

No exemplo a seguir, demonstramos como estruturar um app com três serviços se você estiver desenvolvendo o aplicativo localmente. O arquivo 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:

No exemplo a seguir, um único serviço tem o arquivo opcional dispatch.yaml e dois arquivos de configuração que representam versões diferentes desse serviço, service1.yaml e service2.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 a lógica de fallback que usa resultados em cache quando uma instância de escalonamento manual não está 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.

Se você usar o Java e o pacote de serviços legados, poderá especificar o serviço padrão em appengine-web.xml com a configuração <service>default</service>.

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:

• cron.yaml configura tarefas programadas regularmente que operam em horários definidos ou em intervalos regulares.
• 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.

Nomes de arquivos

O App Engine executa aplicativos em um contêiner em uma distribuição atualizada do Ubuntu Linux. Os nomes de arquivo usados no ambiente padrão do App Engine precisam ser compatíveis com UTF-8, seja UTF-8 ou algo que possa ser convertido automaticamente com segurança em UTF-8. Se os nomes dos arquivos usarem codificações diferentes, implante o aplicativo por meio de uma máquina com configurações de linguagem de nome de arquivo compatíveis com UTF-8.

A implantação falhará se os nomes dos arquivos não forem compatíveis com UTF-8. Não há restrição na codificação de caracteres usada em um arquivo.

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.