Referência de appengine-web.xml

Além do descritor de implantação web.xml, os aplicativos Java do App Engine usam um arquivo de configuração chamado appengine-web.xml para especificar informações sobre seu aplicativo e identificar quais arquivos no arquivo WAR do aplicativo são estáticos (como imagens) e quais são arquivos de recursos usados pelo aplicativo.

Exemplo

O exemplo a seguir é um arquivo mínimo que especifica o ID do aplicativo, um identificador da versão e nenhum arquivo estático ou de recursos:

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>_your_app_id_</application><!-- unused for Cloud SDK based tooling -->
  <version>alpha-001</version><!-- unused for Cloud SDK based tooling -->
  <threadsafe>true</threadsafe>
  <runtime>java8</runtime>
</appengine-web-app>

Sintaxe

Um aplicativo Java do App Engine precisa ter um arquivo denominado appengine-web.xml no respectivo WAR, no diretório WEB-INF/. Trata-se de um arquivo XML com elemento raiz <appengine-web-app>.

As especificações de esquema e definição de tipo de documento do appengine-web.xml estão no diretório docs/ do SDK.

Elemento Descrição
<application>

Não é necessário se você implantar o aplicativo usando o conjunto de ferramentas baseado no SDK do Cloud, como o comando gcloud app deploy, os plug-ins IntelliJ ou Eclipse, os plug-ins Maven ou Gradle. O conjunto de ferramentas baseado no SDK do Cloud ignoram esse elemento e conseguem o código do projeto da propriedade "config project" da gcloud. Você pode modificar o código do projeto usando a ferramenta de linha de comando gcloud. Porém, como isso define um código de projeto para toda a máquina, pode haver confusão caso você esteja desenvolvendo vários projetos. O elemento <application> contém o ID do projeto do aplicativo. Esse é o ID do projeto que você registra ao criar seu projeto no Console do Google Cloud Platform. Quando você faz upload do aplicativo, o appcfg consegue o código do projeto a partir desse arquivo.

<async-session-persistence>

Opcional. É possível reduzir a latência de solicitação configurando o aplicativo para gravar dados da sessão HTTP no armazenamento de dados de forma assíncrona:


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <async-session-persistence enabled="true" />
  <!-- ... -->
</appengine-web-app>

Com a persistência de sessão assíncrona ativada, o App Engine enviará uma tarefa à fila de tarefas para gravar dados da sessão no armazenamento de dados antes de gravar os dados no Memcache. Por padrão, a tarefa será enviada à fila "padrão". Se você quiser usar uma outra fila, adicione o atributo "queue-name":


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <async-session-persistence enabled="true" queue-name="myqueue"/>
  <!-- ... -->
</appengine-web-app>

Os dados da sessão são sempre gravados de forma síncrona no Memcache. Se uma solicitação tentar ler os dados da sessão quando o Memcache não estiver disponível (ou se os dados da sessão tiverem sido retirados), ela fará failover para o armazenamento de dados, que talvez ainda não tenha os dados de sessão mais recentes. Isso significa que a persistência da sessão assíncrona pode fazer com que o aplicativo veja os dados de sessão desatualizados. No entanto, para a maioria dos aplicativos, o benefício de latência supera em muito o risco.

<auto-id-policy> Opcional. Se você estiver configurando identificadores de entidade automaticamente, poderá alterar o método empregado definindo a política de código automática. As seguintes opções são válidas:
default
Padrão. Usa códigos automáticos dispersos que são grandes, inteiros e bem distribuídos, e ao mesmo tempo, pequenos o suficiente para serem representados por flutuadores de 64 bits.
legacy
A opção legada ficará obsoleta em uma versão futura e em algum momento será removida. Para mais informações consulte a postagem do blog que anuncia essa alteração.
<automatic-scaling>

Opcional. Para uma explicação completa, consulte a seção sobre escalonamento automático.

<basic-scaling>

Opcional. Para uma explicação completa, consulte a seção sobre escalonamento básico.

<env-variables>

Opcional. O arquivo appengine-web.xml pode definir variáveis de ambiente que são configuradas enquanto o aplicativo está em execução.


<env-variables>
  <env-var name="DEFAULT_ENCODING" value="UTF-8" />
</env-variables>

Para evitar conflitos com o ambiente local, o servidor de desenvolvimento não define variáveis de ambiente com base nesse arquivo, ele exige que o ambiente local tenha essas variáveis já definidas com os valores correspondentes.


export DEFAULT_ENCODING="UTF-8"
dev_appserver war

Quando implementado no App Engine, o ambiente é criado com essas variáveis já definidas.

<inbound-services>

Opcional. Antes de poder receber e-mail, o aplicativo precisa ser configurado para ativar o serviço. Para ativar o serviço para um aplicativo Java 8, inclua uma seção <inbound-services> no arquivo appengine-web.xml.

O seguinte serviço de entrada está disponível:

mail
Permite que o aplicativo receba e-mail.
<instance-class>

Opcional. Tamanho da classe da instância deste módulo.

As seguintes classes de instância estão disponíveis durante a especificação de diferentes opções de escalonamento:

automatic_scaling
Quando você usa o escalonamento automático, as classes de instância F1, F2, F4 e F4_1G ficam disponíveis.
Padrão: F1 será atribuído se você não especificar uma classe de instância com o elemento automatic_scaling.
basic_scaling
Quando você usa o dimensionamento básico, as classes de instância B1, B2, B4, B4_1G e B8 ficam disponíveis.
Padrão: B2 será atribuído se você não especificar uma classe de instância com o elemento basic_scaling.
manual_scaling
Quando você usa o dimensionamento manual, as classes de instância B1, B2, B4, B4_1G e B8 ficam disponíveis.
Padrão: B2 será atribuído se você não especificar uma classe de instância com o elemento manual_scaling.

Observação: se instance-class for definido como F2 ou superior, será possível otimizar suas instâncias definindo max-concurrent-requests como um valor maior que 10, que é o padrão. Para encontrar o valor ideal, aumente gradualmente e monitore o desempenho do aplicativo.

<manual-scaling>

Opcional. Para uma explicação completa, consulte a seção sobre escalonamento manual.

<precompilation-enabled>

Opcional. O App Engine usa um processo de "pré-compilação" com o bytecode Java do aplicativo para melhorar o desempenho dele no Java Runtime Environment. O código pré-compilado funciona de maneira idêntica ao bytecode original.

Se, por algum motivo, você preferir que o aplicativo não use a pré-compilação, poderá desativá-la adicionando o seguinte código ao arquivo appengine-web.xml:


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <precompilation-enabled>false</precompilation-enabled>
  <!-- ... -->
</appengine-web-app>
module

Observação: os módulos agora são chamados de Serviços, e os serviços ainda são declarados em arquivos appengine-web.xml como módulos, por exemplo: <module>service_name</module>.

Obrigatório durante a criação de um serviço. Opcional para o serviço padrão. É necessário que todos os serviços e versões tenham um nome. O nome pode conter números, letras e hifens. Ele não pode ter mais de 63 caracteres nem ser iniciado ou terminado por um hífen. Escolha um nome exclusivo para cada serviço e versão. Não reutilize nomes de serviços em versões e vice-versa.

Consulte também serviço.

<public-root>

Opcional. <public-root> é um diretório no aplicativo que contém os arquivos estáticos do aplicativo. Quando uma solicitação de um arquivo estático é feita, o <public-root> do aplicativo é precedido pelo caminho da solicitação. Com isso, tem-se o caminho de um arquivo de aplicativo contendo o conteúdo que está sendo solicitado.

O <public-root> padrão é /.

Por exemplo, o seguinte código associa o caminho do URL /index.html ao caminho do arquivo do aplicativo /static/index.html:


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <public-root>/static</public-root>
  <!-- ... -->
</appengine-web-app>
<resource-files>

Opcional. Os arquivos listados no elemento <resource-files> são acessados pelo código do aplicativo por meio do sistema de arquivos. Esses arquivos são armazenados nos servidores de aplicativos. O modo como os arquivos estáticos são armazenados e disponibilizados é oposto ao do aplicativo.

O elemento <resource-files> pode conter os seguintes elementos:

<include>
Um elemento <include> designa os arquivos como arquivos de recursos e disponíveis para o código do aplicativo. Esses arquivos só estão disponíveis para o código em regime somente leitura e não para veicular tráfego. Veja Como incluir e excluir arquivos.
<exclude>

Arquivos e diretórios que correspondem aos padrões de <exclude> não serão enviados por upload nem disponibilizados para o código do aplicativo. No entanto, esses arquivos e diretórios ainda estarão acessíveis ao aplicativo quando ele for executado no servidor de desenvolvimento local. Para mais informações, consulte Como incluir e excluir arquivos.

Por exemplo:

<resource-files>
  <include path="/**.xml" />
  <exclude path="/feeds/**.xml" />
</resource-files>

Neste exemplo, demonstramos como designar todos os arquivos .xml como arquivos de recursos, exceto aqueles no diretório feeds/ e em todos os respectivos subdiretórios.

Os arquivos de recursos do App Engine são lidos usando java.io.File ou javax.servlet.ServletContext.getResource/getResourceAsStream. Eles não são acessados por Class.getResourceAsStream().

runtime

Para usar o ambiente de execução do Java 8, é preciso especificar essa entrada com o valor java8. Para usar o ambiente de execução do Java 7, omita essa entrada ou especifique o valor java7. Os ambientes de execução de Java do App Engine são baseados em OpenJDK.

Por exemplo:


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <runtime>java8</runtime>
  <!-- ... -->
</appengine-web-app>
service

Os serviços eram anteriormente conhecidos como módulos.

No momento, a definição de um serviço como <service>service_name</service > é compatível apenas com comandos gcloud app.

<sessions-enabled>

Opcional. O App Engine inclui uma implementação das sessões usando a interface de sessão de servlet. A implementação armazena dados da sessão no armazenamento de dados para persistência e também usa Memcache para velocidade. Tal como acontece com a maioria dos outros contêineres de servlet, os atributos de sessão que são definidos com "session.setAttribute()" durante a solicitação persistem no final da solicitação.

Esse recurso é desativado por padrão. Para ativá-lo, adicione o seguinte código a appengine-web.xml:

Por exemplo:

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <sessions-enabled>true</sessions-enabled>
  <!-- ... -->
</appengine-web-app>

A implementação cria entidades de armazenamento de dados do tipo _ah_SESSION e entradas do Memcache usando chaves com um prefixo _ahs. Você pode excluir essas entidades usando o modelo do Dataflow.

Observação: como o App Engine armazena dados de sessão no Datastore e no Memcache, todos os valores armazenados na sessão precisam implementar a interface java.io.Serializable.

Consulte o elemento async-session-persistence para reduzir a latência do armazenamento de dados da sessão.

<ssl-enabled>

Opcional. Por padrão, qualquer usuário pode acessar qualquer URL usando HTTP ou HTTPS. Você pode configurar um aplicativo para exigir HTTPS em relação a determinados URLs no descritor de implantação. Consulte Descritor de implantação: URLs seguros.

Se você quer retirar a permissão de uso de HTTPS do aplicativo, insira o seguinte código no arquivo appengine-web.xml:


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <ssl-enabled>false</ssl-enabled>
  <!-- ... -->
</appengine-web-app>

Não há como proibir HTTPS para alguns caminhos de URL e permitir para outros no Java Runtime Environment.

<static-error-handlers>

Opcional. Quando ocorrem alguns erros, o App Engine veicula uma página de erro genérica. Você pode configurar o aplicativo para disponibilizar um arquivo estático personalizado em vez dessas páginas genéricas de erro, contanto que os dados de erro personalizados sejam menores que 10 KB. Para configurar diferentes arquivos estáticos que serão disponibilizados para cada código de erro compatível, especifique os arquivos no arquivo appengine-web.xml do aplicativo. Para veicular páginas de erro personalizadas, adicione uma seção <static-error-handlers> ao appengine-web.xml, conforme este exemplo:


<static-error-handlers>
  <handler file="default_error.html" />
  <handler file="over_quota.html" error-code="over_quota" />
</static-error-handlers>

Aviso: certifique-se de que o caminho para o arquivo de resposta de erro não se sobrepõe aos caminhos do gerenciador de arquivos estáticos.

Cada entrada de file indica um arquivo estático que deve ser disponibilizado no lugar da resposta de erro genérica. O error-code indica qual código de erro deve fazer com que o arquivo associado seja disponibilizado. Estes são os códigos de erro compatíveis:

over_quota
Indica que o aplicativo excedeu uma cota de recurso.
dos_api_denial
Esta opção veicula a página de erro para qualquer cliente bloqueado pela configuração de proteção contra DoS do aplicativo.
timeout
Veiculado se um prazo é alcançado antes que haja uma resposta do aplicativo.

O error-code é opcional. Se não for especificado, o arquivo em questão será a resposta de erro padrão do aplicativo.

Se quiser, você pode especificar um mime-type a ser usado ao veicular o erro personalizado. Consulte uma lista completa de tipos MIME.

<static-files>

Opcional. O elemento <static-files> especifica padrões que correspondem a caminhos de arquivo a serem incluídos e excluídos da lista de arquivos estáticos, modificando ou reparando o comportamento padrão. O arquivo estático é disponibilizado de servidores dedicados e caches que são separados dos servidores de aplicativos e são úteis para veicular conteúdo estático, como imagens, folhas de estilo CSS ou arquivos JavaScript.

O elemento <static-files> pode conter os seguintes elementos:

<include>

Um elemento <include> modifica o comportamento padrão de inclusão de todos os arquivos não JSP. O elemento <include> pode especificar cabeçalhos HTTP a serem usados ao responder à solicitação dos recursos especificados. Para mais informações, consulte Como incluir e excluir arquivos.

Você pode especificar a expiração do cache estático especificando o atributo expiration no elemento "include". O valor é uma string de números e unidades, separados por espaços, em que as unidades podem ser d para dias, h para horas, m para minutos e s para segundos. Por exemplo, "4d 5h" define a expiração do cache como 4 dias e 5 horas depois que o arquivo é solicitado pela primeira vez. Se o tempo de expiração for omitido, o servidor de produção usará o valor padrão de 10 minutos. Para mais informações, consulte Expiração do cache estático.

<exclude>
Não ocorre o upload de arquivos e diretórios que correspondem aos padrões <exclude> quando você implanta o aplicativo no App Engine. No entanto, esses arquivos e diretórios ainda estarão acessíveis ao aplicativo quando ele for executado no servidor de desenvolvimento local. Para mais informações, consulte Como incluir e excluir arquivos.
Exemplo

<static-files>
  <include path="/my_static-files" >
    <http-header name="Access-Control-Allow-Origin"
                 value="http://example.org" />
  </include>
</static-files>
<system-properties>

Opcional. O arquivo appengine-web.xml define as propriedades do sistema e as variáveis de ambiente que são configuradas quando o aplicativo está em execução.


<system-properties>
  <property name="myapp.maximum-message-length" value="140" />
  <property name="myapp.notify-every-n-signups" value="1000" />
  <property name="myapp.notify-url"
            value="http://www.example.com/signupnotify" />
</system-properties>

<env-variables>
  <env-var name="DEFAULT_ENCODING" value="UTF-8" />
</env-variables>
<threadsafe>

Obrigatório. Quando o elemento threadsafe em appengine-web.xml é false, o App Engine envia solicitações em série para um determinado servidor da Web. Quando o valor é true, o App Engine pode enviar várias solicitações em paralelo:


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <threadsafe>true</threadsafe>
  <!-- ... -->
</appengine-web-app>

Se você quiser usar solicitações simultâneas, o código do aplicativo precisará usar a sincronização de thread adequada antes que você ative threadsafe.

<url-stream-handler>

Opcional. Os valores possíveis são native ou urlfetch. O valor padrão e o que essa configuração faz varia conforme você usa os ambientes de execução do Java 8 ou do Java 7.

No caso do ambiente de execução do Java 8, o valor padrão é native, que significa que as classes de rede Java padrão usam o transporte HTTP(S) Java padrão, conforme descrito no ambiente de execução do Java 8 vs o comportamento do Java 7. Esta configuração exige que o aplicativo esteja com o faturamento ativado, senão os seguintes erros de ambiente de execução resultarão das solicitações:

No ambiente de execução do Java 8, definir o elemento url-stream-handler como urlfetch faz com que o App Engine instale um URLStreamHandlerFactory, que faz com que URL.openConnection (ambos em inglês) e os métodos relacionados usem o transporte de Busca de URL para URLs em http e https.

Para o ambiente de execução do Java 7, o valor padrão é urlfetch, ou seja, as classes de rede Java padrão usam o serviço de Busca de URL, conforme descrito em Ambiente de execução do Java 8 vs comportamento do Java 7.

No ambiente de execução do Java 7, definir o valor como native significa que o App Engine usa a API Sockets para java.net.HttpURLConnection em vez da Busca de URL. Assim como no Java 8, esta configuração requer que o aplicativo esteja com o faturamento ativado, senão os seguintes erros de ambiente de execução resultarão das solicitações:


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <url-stream-handler>urlfetch</url-stream-handler>
  <!-- ... -->
</appengine-web-app>
<version>

O elemento <version> contém o identificador de versão da versão mais recente do código do aplicativo. O identificador da versão pode conter letras minúsculas, dígitos e hifens. Ele não pode começar com o prefixo "ah-" e não pode usar os nomes "default" (padrão) e "latest" (mais recente), porque são reservados.

É necessário que os nomes das versões comecem com uma letra, para distingui-las das instâncias numéricas, que são sempre especificadas por um número. Isso evita a ambiguidade em URLs como 123.my-module.appspot.com, que pode ser interpretado de duas maneiras: se a versão "123" existir, o alvo será a versão "123" do módulo em questão. Se essa versão não existir, o alvo será o número de instância 123 da versão padrão do módulo.

O comando appcfg usa esse identificador de versão ao fazer o upload do aplicativo. Ele instrui o App Engine a criar uma versão nova do aplicativo com o identificador fornecido ou substituir a versão pelo identificador, se já existir. Se quiser testar novas versões do aplicativo com uma URL, use "-dot-" como separador de subdomínio no URL, por exemplo, https://_version_id_-dot-_your_app_id_.appspot.com. No Console do Google Cloud Platform, é possível selecionar a versão padrão do aplicativo. A versão padrão é carregada quando nenhuma versão, ou uma versão inválida, é especificada.

<warmup-requests-enabled>

Opcional. Padrão: verdadeiro. As solicitações de aquecimento são ativadas por padrão nos aplicativos em Java 8.

Com solicitações de aquecimento ativadas, a infraestrutura do App Engine emite solicitações `GET` para /_ah/warmup, inicializando servlets <load-on-startup>, ServletContextListeners e servlets de aquecimento personalizados, que permitem a inicialização do código do aplicativo conforme necessário. Talvez seja preciso implementar o próprio gerenciador de /_ah/warmup, dependendo de qual desses métodos você escolher.

Para desativar solicitações de aquecimento, especifique false para este elemento:


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <warmup-requests-enabled>false</warmup-requests-enabled>
  <!-- ... -->
</appengine-web-app>
<vpc-access-connector>

Opcional. Configura o aplicativo para usar um conector de acesso VPC sem servidor, permitindo o envio de solicitações para recursos internos na rede VPC. Especifique o nome completo de um conector no elemento <name>:


<vpc_access_connector>
  <name>projects/[PROJECT_ID]/locations/[REGION]/connectors/[CONNECTOR_NAME]</name>
</vpc_access_connector>

Para mais informações, consulte Como se conectar a recursos internos em uma rede VPC.

Como escalonar elementos

A tabela a seguir lista as opções para especificar se o aplicativo precisa ser escalonado.

Para uma comparação dos recursos de desempenho dos tipos de escalonamento, consulte Como escalonar instâncias dinâmicas.

Elemento Descrição
<automatic-scaling>

Opcional. O escalonamento automático é adotado por padrão em uma classe de instância F1 padrão, salvo se especificado de outra forma.

O elemento automatic_scaling define os níveis mínimo e máximo para o número de instâncias, a latência e as conexões simultâneas de um módulo.

Este elemento pode conter os seguintes elementos:

<target-cpu-utilization>
Opcional. Especifique um valor de 0,5 a 0,95.

Este parâmetro especifica o limite de uso da CPU em que novas instâncias serão iniciadas para processar o tráfego. Isso oferece um equilíbrio entre desempenho e custo. Valores menores aumentam o desempenho e o custo, e valores maiores os diminuem. Por exemplo, um valor de 0,7 significa que novas instâncias serão iniciadas quando o uso da CPU atingir 70%.

Importante: se você usar o comando appcfg do SDK do App Engine para Java a fim de implantar, não será possível usar esse parâmetro no appengine-web.xml. Em vez disso, defina o parâmetro conforme descrito em Como configurar parâmetros de escalonamento automático na API Explorer ou usando a API Admin do App Engine.

<target-throughput-utilization>
Opcional. Especifique um valor de 0,5 a 0,95.

Usado com max-concurrent-requests para especificar quando uma nova instância é iniciada devido a solicitações simultâneas. Quando o número de solicitações simultâneas atinge um valor igual a max-concurrent-requests vezes target-throughput-utilization, o planejador inicia uma nova instância.

Importante: se você usar o comando appcfg do SDK do App Engine para Java a fim de implantar, não será possível usar esse parâmetro no appengine-web.xml. Em vez disso, defina o parâmetro conforme descrito em Como configurar parâmetros de escalonamento automático na API Explorer ou usando a API Admin do App Engine.

<max-instances>
Opcional. O número máximo de instâncias a serem criadas pelo App Engine para esta versão do serviço. Isso é útil para limitar os custos de um módulo. Especifique um valor entre 0 e 2147483647.

Importante: se você usar appcfg do SDK do App Engine para Java a fim de implantar, não será possível usar esse parâmetro no appengine-web.xml. Em vez disso, defina o parâmetro conforme descrito em Como configurar parâmetros de escalonamento automático na API Explorer ou usando a API Admin do App Engine.

<min-instances>
Opcional. O número mínimo de instâncias a serem criadas pelo App Engine para esta versão do módulo. Essas instâncias disponibilizam o tráfego quando as solicitações chegam e continuam a disponibilizar mesmo quando outras instâncias são iniciadas, conforme necessário, para processar o tráfego.

Especifique um valor de zero a 1000. Defina o parâmetro com o valor 0 para que nenhuma instância seja usada quando não houver solicitações. Isso causará uma diminuição nos custos. Você é cobrado pelo número de instâncias especificadas, independentemente de elas receberem tráfego ou não.

Importante: se você usar appcfg do SDK do App Engine para Java a fim de implantar, não será possível usar esse parâmetro no appengine-web.xml. Em vez disso, defina o parâmetro conforme descrito em Como configurar parâmetros de escalonamento automático na API Explorer ou usando a API Admin do App Engine.

<max-concurrent-requests>

Opcional. O número de solicitações simultâneas que uma instância de escalonamento automático pode aceitar antes do programador gerar uma nova instância (padrão: 10, máximo: 80).

Pode ocorrer aumento da latência da API se esta configuração for muito alta. O programador pode gerar uma nova instância antes que o número máximo real de solicitações seja atingido.

Observação: se instance-class for definido como F2 ou superior, será possível otimizar suas instâncias ao definir max-concurrent-requests como um valor maior que 10, que é o padrão. Para encontrar o valor ideal, aumente gradualmente e monitore o desempenho do aplicativo.

<max-idle-instances>

O número máximo de instâncias ociosas que o App Engine precisa manter para esta versão. O valor padrão é "automático". Tenha o seguinte em mente:

  • Com um valor máximo elevado, o número de instâncias ociosas é reduzido mais gradualmente quando os níveis de carga retornam ao normal após um pico. Isso ajuda o aplicativo a manter um desempenho constante durante as flutuações na carga da solicitação. No entanto, isso também aumenta o número de instâncias ociosas (e os custos de execução consequentes) durante esses períodos de carga intensa.
  • Com um valor máximo reduzido, os custos de execução ficam mais baixos. No entanto, isso pode afetar o desempenho devido aos níveis de carga voláteis.

Observação: ao retornar aos níveis normais após um pico de carga, o número de instâncias ociosas pode exceder temporariamente o máximo especificado. No entanto, você não será cobrado por mais instâncias do que o número máximo especificado.

<max-pending-latency>

O máximo de tempo que o App Engine permite que uma solicitação aguarde na fila pendente antes que outras instâncias sejam iniciadas para processar solicitações a fim de reduzir a latência pendente. O valor padrão é "30 ms".

  • Com um valor máximo baixo, o App Engine inicia novas instâncias mais cedo para solicitações pendentes, o que melhora o desempenho, mas aumenta os custos de execução.
  • Um máximo alto significa que os usuários poderão aguardar mais tempo para que as solicitações sejam veiculadas, se houver solicitações pendentes e nenhuma instância ociosa para veiculá-las, mas a execução do aplicativo custará menos.
<min-idle-instances>

O número de instâncias a serem mantidas em execução e prontas para atender ao tráfego.Essa configuração aplica-se somente à versão que recebe a maior parte do tráfego. Lembre-se:

  • Com um valor mínimo baixo, os custos de execução são reduzidos durante os períodos ociosos. No entanto, talvez menos instâncias fiquem imediatamente disponíveis para responder a um pico de carga inesperado.
  • Com um valor mínimo alto, é possível preparar o aplicativo para picos rápidos na carga de solicitação. O App Engine mantém o número mínimo de instâncias em execução para atender aos pedidos recebidos. Você é cobrado por instâncias, independentemente de estar lidando com solicitações ou não. Para que esse recurso funcione corretamente, verifique se as solicitações de aquecimento estão ativadas e se são processadas pelo seu aplicativo.

    Se você definir um número mínimo de instâncias ociosas, a latência pendente terá menos efeito no desempenho do aplicativo. Como o App Engine mantém as instâncias ociosas em reserva, é improvável que as solicitações entrem na fila pendente, exceto em picos de carga excepcionalmente elevados. Para determinar o número ideal de instâncias a serem mantidas em reserva, você precisará testar o aplicativo e o volume de tráfego esperado.

<min-pending-latency>

A quantidade mínima de tempo que o App Engine permite que uma solicitação aguarde na fila pendente antes que uma nova instância seja iniciada para processá-la. Especifique um valor de 0,01 a 15.

  • Com um valor mínimo baixo, as solicitações precisam passar menos tempo na fila pendente quando todas as instâncias existentes estão ativas. Isso melhora o desempenho, mas aumenta o custo de execução do aplicativo.
  • Com um valor mínimo alto, as solicitações continuarão pendentes por mais tempo se todas as instâncias existentes estiverem ativas. Isso reduz os custos de operação, mas aumenta o tempo que os usuários precisam aguardar para que as solicitações sejam disponibilizadas.
Exemplo

<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>simple-app</application>
  <module>default</module>
  <version>uno</version>
  <threadsafe>true</threadsafe>
  <instance-class>F2</instance-class>
  <automatic-scaling>
    <target-cpu-utilization>0.65</target-cpu-utilization>
    <min-instances>5</min-instances>
    <max-instances>100</max-instances>
    <max-concurrent-requests>50</max-concurrent-requests>
  </automatic-scaling>
</appengine-web-app>
<basic-scaling>

Opcional. O elemento <basic-scaling> define o número de instâncias de um módulo.

Este elemento pode conter os seguintes elementos:

<idle-timeout>
Opcional. A instância encerrará essa quantidade de tempo depois de receber a última solicitação. O padrão é 5 minutos.
<max-instances>
Obrigatório. Número máximo de instâncias que o App Engine cria para esta versão do módulo. Isso é útil para limitar os custos de um módulo.
Exemplo

<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>simple-app</application>
  <module>default</module>
  <version>uno</version>
  <threadsafe>true</threadsafe>
  <instance-class>B8</instance-class>
  <basic-scaling>
    <max-instances>11</max-instances>
    <idle-timeout>10m</idle-timeout>
  </basic-scaling>
</appengine-web-app>
<manual-scaling>

Opcional. O elemento <manual-scaling> ativa o escalonamento manual de um módulo e define o número de instâncias de um módulo.

Este elemento pode conter os seguintes elementos:

<instances>
Número de instâncias a serem atribuídas ao módulo no início.
Exemplo

<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>simple-app</application>
  <module>default</module>
  <version>uno</version>
  <threadsafe>true</threadsafe>
  <instance-class>B8</instance-class>
  <manual-scaling>
    <instances>5</instances>
  </manual-scaling>
</appengine-web-app>

Elementos de teste

Grande parte do trabalho realizado durante uma implantação ocorre localmente em uma etapa de preparação denominada teste, em que arquivos JAR são montados, JSPs são compilados e assim por diante. Se quiser, você pode configurar certas partes do comportamento de teste usando elementos de teste no arquivo de configuração do aplicativo. A maioria dos aplicativos será implementada com sucesso sem a configuração manual do comportamento de teste. Se o aplicativo não for implementado, talvez seja necessário configurar o teste usando as opções mostradas abaixo.

Elemento Descrição
<staging>

Opcional. A maioria dos aplicativos não precisa alterar o comportamento padrão.

O elemento de teste permite que você especifique uma configuração de teste específica, se necessário, para a implantação.

Este elemento pode conter os seguintes elementos:

<enable-jar-splitting>

Opcional. Divida grandes arquivos (> 10 megabytes) em fragmentos menores (padrão: verdadeiro).

<jar-splitting-excludes>

Lista de sufixos a excluir ao usar a divisão de jar.

<disable_jar_jsps>

Não crie classes jar geradas a partir de JSPs (padrão: falso).

<enable-jar-classes>

Crie jar do conteúdo de WEB-INF/classes (padrão: verdadeiro).

<delete-jsps>

Exclua os arquivos de origem JSP após a compilação (padrão: verdadeiro).

<compile-encoding>

Codificação de entrada de arquivos de origem para compilação (padrão: utf-8).

Padrões das opções de teste

Os padrões das opções de preparo variam de acordo com o recurso usado, por exemplo, ferramentas com base no SDK do App Engine, como appcfg, ou ferramentas com base no SDK do Cloud, como a linha de comando gcloud, além dos plug-ins Maven, Gradle, Eclipse ou IntelliJ, que tem o SDK do Cloud como base.

Elemento de teste Padrões baseados no SDK do App Engine Padrões baseados no SDK do Cloud
enable-jar-splitting false true
jar-splitting-excludes N/D N/D
disable-jar-jsps false false
enable-jar-classes false true. Pode afetar a ordem de carregamento da classe, portanto, se o aplicativo depende de uma determinada ordem que usa o padrão false antigo, você pode configurá-lo como false.
delete-jsps false true
compile-encoding utf-8 utf-8

Sintaxe de inclusão e exclusão

Os padrões de caminho são especificados usando-se zero ou mais elementos <include> e <exclude>. Em um padrão, '*' representa zero ou um número maior de qualquer caractere no nome de um arquivo ou diretório e ** representa zero ou um número maior de diretórios em um caminho. Não ocorre o upload dos arquivos e diretórios que correspondem aos padrões <exclude> quando você implanta o aplicativo no App Engine. No entanto, esses arquivos e diretórios continuarão acessíveis ao aplicativo quando executados no servidor de desenvolvimento local.

Um elemento <include> modifica o comportamento padrão de incluir todos os arquivos. Um elemento <exclude> é aplicado depois de todos os padrões <include> (bem como o padrão se não for fornecido nenhum <include> explícito).

O exemplo a seguir demonstra como designar todos os arquivos .png como arquivos estáticos (exceto aqueles no diretório data/ e todos os respectivos subdiretórios):

<static-files>
  <include path="/**.png" />
  <exclude path="/data/**.png" />
</static-files>

Também é possível definir cabeçalhos HTTP para usar quando for responder às solicitações a esses recursos estáticos.

<static-files>
  <include path="/my_static-files" >
    <http-header name="Access-Control-Allow-Origin"
                 value="http://example.org" />
  </include>
</static-files>

Tipos MIME para arquivos estáticos

Por padrão, arquivos estáticos são veiculados com um tipo MIME selecionado com base na extensão do nome do arquivo. Você pode associar tipos MIME personalizados a extensões de nome de arquivo para arquivos estáticos usando elementos <mime-mapping> em web.xml. Para mais informações, consulte o wiki de referência sobre web.xml no Metawerx.

Expiração estática do cache

Salvo instrução contrária, os proxies e navegadores da Web retêm arquivos que são carregados de um site por um período de tempo limitado.

Você pode configurar uma duração de cache para gerenciadores de arquivos estáticos específicos fornecendo um atributo expiration para <static-files><include ... >. O valor é uma string de números e unidades, separados por espaços, em que as unidades podem ser d para dias, h para horas, m para minutos e s para segundos. Por exemplo, "4d 5h" define a expiração do cache como 4 dias e 5 horas depois que o arquivo é solicitado pela primeira vez. Se o tempo de expiração for omitido, o servidor de produção usará o valor 10 minutos como padrão.

Exemplo:

<static-files>
  <include path="/**.png" expiration="4d 5h" />
</static-files>

O tempo de expiração será enviado nos cabeçalhos de resposta HTTP Cache-Control e Expires, portanto, os arquivos provavelmente serão armazenados em cache pelo navegador do usuário, bem como por servidores proxy de cache intermediários, como os provedores de serviços de Internet. Depois que um arquivo é transmitido com um tempo de expiração determinado, geralmente não há como removê-lo de caches intermediários, mesmo que o usuário limpe seu próprio cache do navegador. A reimplantação de uma nova versão do aplicativo não redefinirá nenhum cache. Portanto, se você planeja modificar um arquivo estático, ele tem que ter um tempo de expiração curto (menos de uma hora). Na maioria dos casos, o tempo de expiração padrão de 10 minutos é apropriado.

Tempo limite de URLFetch

Você pode definir um prazo para cada solicitação URLFetch. Por padrão, o prazo de uma busca é 5 segundos. Você pode alterar esse padrão incluindo a seguinte configuração no arquivo de configuração appengine-web.xml. Especifique o tempo limite em segundos:

<system-properties>
    <property name="appengine.api.urlfetch.defaultDeadline" value="10"/>
</system-properties>
Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Ambiente padrão do App Engine para Java