Ficheiros de configuração

Cada versão de um serviço é definida num ficheiro .yaml, que indica o nome do serviço e da versão. Normalmente, o ficheiro YAML tem o mesmo nome que o serviço que define, mas isto não é obrigatório. Se estiver a implementar várias versões de um serviço, pode criar vários ficheiros YAML no mesmo diretório, um para cada versão.

Normalmente, cria um diretório para cada serviço, que contém os ficheiros YAML do serviço e o código fonte associado. Os ficheiros de configuração opcionais ao nível da aplicação (dispatch.yaml, cron.yaml, index.yaml e queue.yaml) estão incluídos no diretório da app de nível superior. O exemplo abaixo mostra três serviços. Em service1 e service2, os ficheiros de origem estão ao mesmo nível que o ficheiro YAML. Em service3, existem ficheiros YAML para duas versões.

Para projetos pequenos e simples, todos os ficheiros da app podem estar num diretório:

Todos os ficheiros YAML têm de incluir um parâmetro de versão. Para definir o serviço predefinido, pode incluir explicitamente o parâmetro service: default ou deixar o parâmetro de serviço fora do ficheiro.

O ficheiro de configuração de cada serviço define o tipo de escalabilidade e a classe de instância para um serviço/versão específico. São usados diferentes parâmetros de dimensionamento consoante o tipo de dimensionamento que especificar. Se não especificar a escala, a escala automática é a predefinição. As definições de classe de instância e escalabilidade são descritas na secção de appengine-web.xml referência.

Para cada serviço, também pode especificar definições que mapeiam pedidos de URL para scripts específicos e identificam ficheiros estáticos para uma melhor eficiência do servidor. Estas definições também estão incluídas no ficheiro YAML e são descritas na secção de appengine-web.xml referência.

O serviço predefinido

Cada aplicação tem um único serviço predefinido. Pode definir o serviço predefinido no appengine-web.xml com a definição service: default, mas não é necessário fazê-lo. Todos os parâmetros de configuração relevantes para os serviços podem aplicar-se ao serviço predefinido.

Ficheiros de configuração opcionais

Estes ficheiros de configuração controlam as funcionalidades opcionais que se aplicam a todos os serviços numa app:

• dispatch.yaml substitui as regras predefinidas de encaminhamento enviando pedidos recebidos para um serviço específico com base no caminho ou no nome de anfitrião no URL.
• queue.yaml configura as filas de push e de pull.
• index.yaml especifica os índices de que a sua app precisa se usar consultas do Datastore.
• cron.yaml configura tarefas agendadas regularmente que operam em horários definidos ou em intervalos regulares.

Para implementar atualizações destes ficheiros de configuração no App Engine, execute o comando seguinte a partir do diretório onde se encontram:

    gcloud app deploy [CONFIG_FILE]

Um exemplo

Segue-se um exemplo de como configuraria os vários ficheiros numa estrutura de diretórios WAR para uma aplicação que tem dois serviços: um serviço predefinido que processa pedidos Web, além de outro serviço (denominado my-service) para processamento de back-end.

Partindo do princípio de que o diretório EAR de nível superior é "my-application", defina o ficheiro 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 ficheiro appengine-web.xml em cada WAR que especifique os parâmetros do serviço. O ficheiro tem de incluir um nome de versão para o serviço. Para definir o serviço predefinido, pode incluir explicitamente o parâmetro <service>default</service> ou deixá-lo de fora do ficheiro. Aqui está o ficheiro my-application/default/WEB-INF/appengine-web.xml que define o serviço predefinido:

<?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 ficheiro my-application/my-service/WEB-INF/appengine-web.xml define o serviço que vai processar os pedidos 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 último, defina o ficheiro my-application/META-INF/application.xml que enumera os serviços. Tenha em atenção que o serviço predefinido deve ser o primeiro serviço apresentado.

<?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 ignora os elementos <context-root>, pelo que os clientes HTTP não precisam de os acrescentar ao caminho do URL quando se dirigem a um serviço.