Arquivos de configuração

Cada versão de um serviço é definida em um arquivo .yaml, que fornece o nome do serviço e a versão. Geralmente, o arquivo YAML recebe o mesmo nome do serviço que define, mas isso não é obrigatório. Se você implantar várias versões de um serviço, poderá criar diversos arquivos yaml no mesmo diretório, um para cada versão.

Normalmente, cria-se um diretório por serviço contendo os arquivos YAML e o código-fonte associado de cada um dos serviços. Os arquivos de configuração opcionais no nível do aplicativo (dispatch.yaml, cron.yaml, index.yaml e queue.yaml) estão incluídos no diretório do aplicativo de nível superior. O exemplo abaixo mostra três serviços. Em service1 e service2, os arquivos de origem estão no mesmo nível do arquivo YAML. Em service3, há arquivos YAML para duas versões.

Gráfico hierárquico de serviços YAML

No caso de projetos pequenos e simples, você pode colocar todos os arquivos do app em um único diretório:

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

Cada arquivo YAML precisa incluir um parâmetro de versão. Para definir o serviço padrão, possível é incluir explicitamente o parâmetro service: default ou deixar o parâmetro de serviço fora do arquivo.

O arquivo de configuração de cada serviço define o tipo de escalonamento e a classe da instância para um determinado serviço/versão. Dependendo do tipo de escalonamento a ser especificado, os parâmetros usados variam. Quando o escalonamento não é especificado, adota-se o padrão. As configurações de escalonamento e classe de instância estão descritas na seção de referência de appengine-web.xml.

Para cada serviço, também é possível especificar configurações que associem solicitações de URL a scripts específicos e identifiquem arquivos estáticos para melhor eficiência do servidor. Essas configurações também estão incluídas no arquivo yaml e estão descritas na seção de referência de appengine-web.xml.

O serviço padrão

Todos os aplicativos têm um serviço padrão único. É possível definir o serviço padrão no appengine-web.xml com a configuração service: default, mas não é necessário. Todos os parâmetros de configuração relevantes aos serviços podem ser aplicados ao serviço padrão.

Arquivos de configuração opcionais

Estes arquivos de configuração controlam os recursos opcionais que se aplicam a todos os serviços de um app:

  • 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.
  • queue.yaml configura filas push e pull.
  • 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.

Para implantar atualizações desses arquivos de configuração no App Engine, execute o seguinte comando no diretório em que estiverem localizados:

    gcloud app deploy [CONFIG_FILE]

Um exemplo

Veja aqui um exemplo de como configurar os diversos arquivos em uma estrutura de diretórios WAR para um aplicativo que tem dois serviços: um serviço padrão que lida com solicitações da Web e outro serviço (denominado my-service) para processamento de back-end.

Supondo que o diretório EAR de nível superior seja "my-application", defina o arquivo my-application/META-INF/appengine-application.xml:

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<appengine-application xmlns="http://appengine.google.com/ns/1.0">
  <application>my-application</application>
</appengine-application>

Crie diretórios WAR para os dois serviços: my-application/default e my-application/my-service.

Agora, crie um arquivo appengine-web.xml em cada WAR que especifique os parâmetros do serviço. O arquivo precisa incluir um nome de versão para o serviço. Para definir o serviço padrão, é possível incluir explicitamente o parâmetro <service>default</service> ou deixá-lo fora do arquivo. Este é o arquivo my-application/default/WEB-INF/appengine-web.xml que define o serviço padrão:

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>my-application</application>
  <module>default</module>
  <version>uno</version>
  <threadsafe>true</threadsafe>
</appengine-web-app>

O arquivo my-application/my-service/WEB-INF/appengine-web.xml define o serviço que processará as solicitações em segundo plano:

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>my-application</application>
  <module>my-service</module>
  <version>uno</version>
  <threadsafe>true</threadsafe>
  <manual-scaling>
    <instances>5</instances>
  </manual-scaling>
</appengine-web-app>

Por fim, defina o arquivo my-application/META-INF/application.xml que enumera os serviços. Observe que o serviço padrão precisa ser o primeiro listado.

<?xml version="1.0"
encoding="UTF-8"?>

<application
  xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
                      http://java.sun.com/xml/ns/javaee/application_5.xsd"
  version="5">

  <description>GAE Java SuperFun app</description>
  <display-name>SuperFun</display-name>

  <!-- Services -->
  <!-- The default service should be listed first -->
  <module>
    <web>
      <web-uri>default</web-uri>
      <context-root>default</context-root>
    </web>
  </module>
  <module>
    <web>
      <web-uri>my-service</web-uri>
      <context-root>my-service</context-root>
    </web>
  </module>

</application>

O App Engine ignorará os elementos <context-root>. Portanto, os clientes HTTP não precisam incluí-lo no caminho do URL ao abordar um serviço.