Referência do appengine-web.xml do App Engine

ID da região

O REGION_ID é um código abreviado que a Google atribui com base na região que seleciona quando cria a sua app. O código não corresponde a um país ou uma província, embora alguns IDs de regiões possam parecer semelhantes aos códigos de países e províncias usados frequentemente. Para apps criadas após fevereiro de 2020, REGION_ID.r está incluído nos URLs do App Engine. Para apps existentes criadas antes desta data, o ID da região é opcional no URL.

Saiba mais acerca dos IDs de regiões.

Além do web.xml descritor de implementação, as aplicações Java do App Engine usam um ficheiro de configuração denominado appengine-web.xml para especificar informações sobre a sua app e identificar que ficheiros no ficheiro WAR da app são ficheiros estáticos (como imagens) e quais são ficheiros de recursos usados pela aplicação.

Exemplo

O exemplo seguinte é um ficheiro mínimo que especifica o tempo de execução do Java 8 sem ficheiros estáticos nem ficheiros de recursos:

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

Sintaxe

Uma app Java do App Engine tem de ter um ficheiro denominado appengine-web.xml no respetivo WAR, no diretório WEB-INF/. Este é um ficheiro XML cujo elemento raíz é <appengine-web-app>.

Pode encontrar a definição do tipo de documento e as especificações do esquema para o appengine-web.xml no diretório docs/ do SDK.

Elemento Descrição
<async-session-persistence>

Opcional. É possível reduzir a latência dos pedidos configurando a sua aplicação para escrever dados de sessão HTTP de forma assíncrona no arquivo de dados: 

<?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 envia uma tarefa da fila de tarefas para escrever dados de sessão no armazenamento de dados antes de escrever os dados na cache de memória. Por predefinição, a tarefa é enviada para a fila "default". Se quiser usar uma fila diferente, 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 de sessão são sempre escritos de forma síncrona na memcache. Se um pedido tentar ler os dados da sessão quando o memcache não estiver disponível (ou os dados da sessão tiverem sido esvaziados), vai falhar para o Datastore, que pode ainda não ter os dados da sessão mais recentes. Isto significa que a persistência de sessões assíncrona pode fazer com que a sua aplicação veja dados de sessões desatualizados. No entanto, para a maioria das aplicações, a vantagem da latência supera largamente o risco.

<auto-id-policy> Opcional. Se estiver a definir identificadores de entidades automaticamente, pode alterar o método usado definindo a política de ID automático. Seguem-se as opções válidas:
default
Predefinição. Usa IDs automáticos dispersos que são números inteiros bem distribuídos suficientemente pequenos para serem representados por números de ponto flutuante de 64 bits.
legacy
A opção antiga vai ser descontinuada num lançamento futuro e vai acabar por ser removida. Para mais informações, consulte a publicação no blogue que anuncia esta alteração.
<automatic-scaling>

Opcional. Para uma explicação completa, consulte a secção Dimensionamento automático.

<basic-scaling>

Opcional. Para uma explicação completa, consulte a secção Dimensionamento básico.

<env-variables>

Opcional. O ficheiro appengine-web.xml pode definir variáveis de ambiente que são definidas quando a aplicação está em execução. 

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

Para evitar conflitos com o seu ambiente local, o servidor de desenvolvimento não define variáveis de ambiente com base neste ficheiro e requer que o ambiente local já tenha estas variáveis definidas com valores correspondentes. 

export DEFAULT_ENCODING="UTF-8"
dev_appserver war

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

<inbound-services>

Opcional. Antes de uma aplicação poder receber emails, tem de ser configurada para ativar o serviço. Ativa o serviço para uma app Java 8 incluindo uma secção <inbound-services> no ficheiro appengine-web.xml.

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

mail
Permite que a sua aplicação receba correio.
<instance-class>

Opcional. O tamanho da classe de instância para este módulo.

As seguintes classes de instâncias estão disponíveis quando especifica diferentes opções de escalabilidade:

automatic_scaling
Quando usa o dimensionamento automático, as classes de instâncias F1, F2, F4 e F4_1G estão disponíveis.
Predefinição: o F1 é atribuído se não especificar uma classe de instância juntamente com o elemento automatic_scaling.
basic_scaling
Quando usa o dimensionamento básico, as classes de instâncias B1, B2, B4, B4_1G e B8 estão disponíveis.
Predefinição: B2 é atribuído se não especificar uma classe de instância juntamente com o elemento basic_scaling.
manual_scaling
Quando usa o dimensionamento manual, as classes de instâncias B1, B2, B4, B4_1G e B8 estão disponíveis.
Predefinição: B2 é atribuído se não especificar uma classe de instância juntamente com o elemento manual_scaling.

Nota: se instance-class estiver definido como F2 ou superior, pode otimizar as suas instâncias definindo max-concurrent-requests para um valor superior a 10, que é o predefinido. Para encontrar o valor ideal, aumente-o gradualmente e monitorize o desempenho da sua aplicação.

<manual-scaling>

Opcional. Para uma explicação completa, consulte a secção Dimensionamento manual.

<precompilation-enabled>

Opcional. O App Engine usa um processo de "pré-compilação" com o bytecode Java de uma app para melhorar o desempenho da app no ambiente de tempo de execução Java. O código pré-compilado funciona de forma idêntica ao bytecode original.

Se, por algum motivo, preferir que a sua app não use a pré-compilação, pode desativá-la adicionando o seguinte ao ficheiro 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

Nota: os módulos são agora denominados serviços e os serviços continuam a ser declarados em ficheiros appengine-web.xml como módulos, por exemplo: <module>service_name</module>.

Obrigatório se estiver a criar um serviço. Opcional para o serviço predefinido. Cada serviço e cada versão têm de ter um nome. Um nome pode conter números, letras e hífenes. Não pode ter mais de 63 carateres, começar nem terminar com um hífen e conter a string `-dot`. Escolha um nome exclusivo para cada serviço e cada versão. Não reutilize nomes entre serviços e versões.

Veja também serviço.

<public-root>

Opcional. O <public-root> é um diretório na sua aplicação que contém os ficheiros estáticos da sua aplicação. Quando é feito um pedido de um ficheiro estático, o <public-root> da sua aplicação é adicionado ao caminho do pedido. Indica o caminho de um ficheiro de aplicação que contém o conteúdo pedido.

O valor predefinido de <public-root> é /.

Por exemplo, o seguinte mapearia o caminho do URL /index.html para o caminho do ficheiro da aplicação /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 ficheiros listados no elemento <resource-files> são acessíveis pelo código da aplicação através do sistema de ficheiros. Estes ficheiros são armazenados nos servidores de aplicações com a app, ao contrário da forma como os ficheiros estáticos são armazenados e disponibilizados.

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

<include>
Um elemento <include> designa os ficheiros como ficheiros de recursos e disponíveis para o código da sua aplicação. Estes ficheiros só estão disponíveis para o seu código numa base só de leitura e não para publicação de tráfego. Incluir e excluir ficheiros.
<exclude>

Os ficheiros e os diretórios que correspondem aos padrões <exclude> não são carregados nem estão disponíveis para o código da sua aplicação. No entanto, estes ficheiros e diretórios continuam a estar acessíveis à sua aplicação quando executada no servidor de desenvolvimento local. Para mais informações, consulte o artigo Incluir e excluir ficheiros.

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

Este exemplo demonstra como designar todos os ficheiros .xml como ficheiros de recursos, exceto os que se encontram no diretório feeds/ e todos os respetivos subdiretórios.

Os ficheiros de recursos do App Engine são lidos através de java.io.File ou javax.servlet.ServletContext.getResource/getResourceAsStream. Não estão acessíveis através do Class.getResourceAsStream().

runtime

Para usar o tempo de execução do Java 8, tem de especificar esta entrada com o valor java8.

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.

Atualmente, a definição de um serviço como: <service>service_name</service > só é suportada por comandos gcloud app.
service-account

Opcional. O elemento service-account permite-lhe especificar uma conta de serviço gerida pelo utilizador como a identidade da versão. A conta de serviço especificada é usada quando acede a outros Google Cloud serviços e executa tarefas.

Exemplo: 
<?xml version="1.0" encoding="utf-8"?>
 <appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
   <!-- ... -->
   <service-account>[SERVICE_ACCOUNT_NAME]@[PROJECT_ID].iam.gserviceaccount.com</service-account>
   <!-- ... -->
 </appengine-web-app>
<sessions-enabled>

Opcional. O App Engine inclui uma implementação de sessões, através da interface de sessão de servlet. A implementação armazena dados de sessão no Datastore para persistência e também usa a cache de memória para velocidade. Tal como acontece com a maioria dos outros contentores de servlets, os atributos de sessão definidos com `session.setAttribute()` durante o pedido são mantidos no final do pedido.

Esta funcionalidade está desativada por predefinição. Para a ativar, adicione o seguinte a appengine-web.xml:

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 do Datastore do tipo _ah_SESSION e entradas da cache de memória com chaves com um prefixo de _ahs. Pode eliminar estas entidades através do modelo de fluxo de dados.

Nota: uma vez que o App Engine armazena dados de sessões no armazenamento de dados e na cache de memória, todos os valores armazenados na sessão têm de implementar a interface java.io.Serializable.

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

<ssl-enabled>

Opcional. Por predefinição, qualquer utilizador pode aceder a qualquer URL através de HTTP ou HTTPS. Pode configurar uma app para exigir HTTPS para determinados URLs no descritor de implementação. Consulte o descritor de implementação: URLs seguros.

Se quiser proibir a utilização de HTTPS para a aplicação, coloque o seguinte no ficheiro 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 existe forma de não permitir HTTPS para alguns caminhos de URL e permitir para outros no ambiente de tempo de execução do Java.

<static-error-handlers>

Opcional. Quando ocorrem determinados erros, o App Engine apresenta uma página de erro genérica. Pode configurar a sua app para publicar um ficheiro estático personalizado em vez destas páginas de erro genéricas, desde que os dados de erro personalizados tenham menos de 10 kilobytes. Pode configurar diferentes ficheiros estáticos para publicação para cada código de erro suportado, especificando os ficheiros no ficheiro appengine-web.xml da sua app. Para publicar páginas de erro personalizadas, adicione uma secção <static-error-handlers> ao seu appengine-web.xml, como neste 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 ficheiro de resposta de erro não se sobrepõe aos caminhos do controlador de ficheiros estáticos.

Cada entrada file indica um ficheiro estático que deve ser publicado em vez da resposta de erro genérica. O elemento error-code indica que código de erro deve fazer com que o ficheiro associado seja publicado. Os códigos de erro suportados são os seguintes:

over_quota
Indica que a app excedeu uma quota de recursos.
timeout
Publicado se for atingido um prazo antes de haver uma resposta da sua app.

O elemento error-code é opcional. Se não for especificado, o ficheiro indicado é a resposta de erro predefinida para a sua app.

Opcionalmente, pode especificar um mime-type a usar quando publicar 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 ficheiros a incluir e excluir da lista de ficheiros estáticos, substituindo ou alterando o comportamento predefinido. Os ficheiros estáticos são publicados a partir de servidores e caches dedicados separados dos servidores de aplicações e são úteis para publicar conteúdo estático, como imagens, folhas de estilo CSS ou ficheiros JavaScript.

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

<include>

Um elemento <include> substitui o comportamento predefinido de incluir todos os ficheiros que não sejam JSP. O elemento <include> pode especificar cabeçalhos HTTP a usar quando responder a pedidos dos recursos especificados. Para mais informações, consulte o artigo Incluir e excluir ficheiros.

Pode substituir a expiração da cache estática predefinida 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 da cache para 4 dias e 5 horas após o ficheiro ser pedido pela primeira vez. Para mais informações, consulte o artigo Validade da cache.

<exclude>
Os ficheiros e os diretórios que correspondem aos padrões <exclude> não são carregados quando implementa a sua app no App Engine. No entanto, estes ficheiros e diretórios continuam a estar acessíveis à sua aplicação quando executada no servidor de desenvolvimento local. Para mais informações, consulte o artigo Incluir e excluir ficheiros.
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 ficheiro appengine-web.xml pode definir propriedades do sistema e variáveis de ambiente que são definidas quando a aplicação 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 pedidos em série para um determinado servidor Web. Quando o valor é true, o App Engine pode enviar vários pedidos 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 quiser usar pedidos simultâneos, o código da sua aplicação tem de usar a sincronização adequada de threads antes de ativar threadsafe.

Este elemento não é suportado nos tempos de execução do Java 11 ou superior.

<url-stream-handler>

Opcional. Valores possíveis: native ou urlfetch.

O valor predefinido é native, o que significa que as classes de rede Java padrão usam o transporte HTTP(S) Java padrão. Para usar esta definição, tem de ativar a faturação para a sua app ou recebe exceções, que estão documentadas em Pedidos de emissão.

Se definir url-stream-handler como urlfetch, URL.openConnection e os métodos relacionados usam a obtenção de URLs para o transporte de http e https.

<?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 da versão mais recente do código da app. O identificador de versão pode conter letras minúsculas, dígitos e hífens. Não pode começar com o prefixo "ah-" e os nomes "default" e "latest" estão reservados e não podem ser usados.

Os nomes das versões devem começar com uma letra para os distinguir das instâncias numéricas, que são sempre especificadas por um número. Isto evita a ambiguidade com URLs como 123.my-module.uc.r.appspot.com, que podem ser interpretados de duas formas: se a versão "123" existir, a segmentação será a versão "123" do módulo especificado. Se essa versão não existir, o destino é o número de instância 123 da versão predefinida do módulo.

O App Engine usa este identificador de versão para determinar se deve criar uma nova versão da app com o identificador fornecido (ou substituir a versão da app com o identificador fornecido, se já existir). Pode testar novas versões da sua app com um URL usando "-dot-" como um separador de subdomínio no URL, como, https://VERSION_ID-dot-default-dot-PROJECT_ID.REGION_ID.r.appspot.com. Usando o Google Cloud console, pode selecionar a versão predefinida da sua app. A versão predefinida é carregada quando não é especificada nenhuma versão ou é especificada uma versão inválida.

<warmup-requests-enabled>

Opcional. Predefinição: true. Os pedidos de preparação estão ativados por predefinição para aplicações Java 8.

Com os pedidos de preparação ativados, a infraestrutura do App Engine envia pedidos `GET` para /_ah/warmup, inicializando os servlets <load-on-startup>, ServletContextListeners e servlets de preparação personalizados, o que lhe permite inicializar o código da sua aplicação conforme necessário. Pode ter de implementar o seu próprio controlador para /_ah/warmup, consoante o método que escolher.

Para desativar os pedidos de preparação, 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 a sua aplicação para usar um conetor do Acesso a VPC sem servidor, o que permite à aplicação enviar pedidos a recursos internos na sua rede VPC. Para mais informações, consulte o artigo Estabelecer ligação a uma rede VPC.

name
Especifique o nome totalmente qualificado do seu conetor do Acesso a VPC sem servidor: 
projects/PROJECT_ID/locations/REGION/connectors/CONNECTOR_NAME
egress-setting
Opcional. A predefinição é private-ranges-only. O elemento egress-setting pode ser um dos seguintes:
private-ranges-only
Predefinição. Os pedidos a endereços IP internos são enviados através do conetor de acesso a VPC sem servidor para a rede VPC associada. Os pedidos para endereços IP externos são enviados para a Internet pública.
all-traffic
Todos os pedidos são enviados através do conetor de acesso a VPC sem servidor para a rede VPC ligada.
Exemplo 
<vpc-access-connector>
  <name>projects/PROJECT_ID/locations/REGION/connectors/CONNECTOR_NAME</name>
  <egress-setting>all-traffic</egress-setting>
</vpc-access-connector>

Dimensionar elementos

A tabela seguinte lista as opções para definir como pode especificar que a sua aplicação deve ser dimensionada.

Para uma comparação das funcionalidades de desempenho dos tipos de escalabilidade, consulte o artigo Escalar instâncias dinâmicas.

Elemento Descrição
<automatic-scaling>

Opcional. Por predefinição, a escalabilidade automática é assumida com uma classe de instância predefinida de F1, salvo especificação em contrário.

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 ligações simultâneas de um módulo.

Este elemento pode conter os seguintes elementos:

<target-cpu-utilization>
Opcional. Especifique um valor entre 0,5 e 0,95.

Este parâmetro especifica o limite de utilização da CPU no qual são iniciadas novas instâncias para processar o tráfego, o que lhe permite equilibrar o desempenho e o custo. Os valores mais baixos aumentam o desempenho e o custo, enquanto os valores mais elevados diminuem o desempenho e o custo. Por exemplo, um valor de 0,7 significa que são iniciadas novas instâncias depois de a utilização da CPU atingir 70%.

<target-throughput-utilization>
Opcional. Especifique um valor entre 0,5 e 0,95.

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

<max-instances>
Opcional. O número máximo de instâncias que o App Engine pode criar para esta versão da aplicação. Isto é útil para limitar os custos de um módulo. Especifique um valor entre 0 e 2147483647.
<min-instances>
Opcional. O número mínimo de instâncias que o App Engine deve criar para esta versão do módulo. Estas instâncias publicam tráfego quando chegam pedidos e continuam a publicar tráfego mesmo quando são iniciadas instâncias adicionais, conforme necessário, para processar o tráfego.

Especifique um valor de 0 a 1000. Pode definir o parâmetro para o valor 0 para permitir o dimensionamento para 0 instâncias de modo a reduzir os custos quando não estiverem a ser processados pedidos. Tenha em atenção que lhe é cobrado o número de instâncias especificado, quer estejam a receber tráfego ou não.

<max-concurrent-requests>

Opcional. O número de pedidos simultâneos que uma instância de escalamento automático pode aceitar antes de o programador gerar uma nova instância (predefinição: 10, máximo: 80).

Pode observar um aumento da latência da API se esta definição for demasiado elevada. Tenha em atenção que o agendador pode gerar uma nova instância antes de atingir o número máximo real de pedidos.

Nota: se instance-class estiver definido como F2 ou superior, pode otimizar as suas instâncias definindo max-concurrent-requests para um valor superior a 10, que é o predefinido. Para encontrar o valor ideal, aumente-o gradualmente e monitorize o desempenho da sua aplicação.

<max-idle-instances>

O número máximo de instâncias inativas que o App Engine deve manter para esta versão. O valor predefinido é "automático". Tenha em atenção o seguinte:

  • Um valor máximo elevado reduz o número de instâncias inativas de forma mais gradual quando os níveis de carga voltam ao normal após um pico. Isto ajuda a sua aplicação a manter um desempenho estável através das flutuações na carga de pedidos, mas também aumenta o número de instâncias inativas (e os custos de execução consequentes) durante esses períodos de carga elevada.
  • Um valor máximo baixo mantém os custos de funcionamento mais baixos, mas pode degradar o desempenho perante níveis de carga voláteis.

Nota: quando regressa aos níveis normais após um aumento repentino da carga, o número de instâncias inativas pode exceder temporariamente o máximo especificado. No entanto, não lhe são cobradas mais instâncias do que o número máximo especificado.

<max-pending-latency>

O período máximo durante o qual o App Engine deve permitir que um pedido aguarde na fila pendente antes de iniciar instâncias adicionais para processar pedidos, de modo a reduzir a latência pendente.

  • Um valor máximo baixo significa que o App Engine inicia novas instâncias mais cedo para pedidos pendentes, o que melhora o desempenho, mas aumenta os custos de execução.
  • Um valor máximo elevado significa que os utilizadores podem esperar mais tempo pela publicação dos respetivos pedidos, se existirem pedidos pendentes e nenhuma instância inativa para os publicar, mas a execução da sua aplicação vai custar menos.
<min-idle-instances>

O número de instâncias a manter em execução e prontas para publicar tráfego.Esta definição aplica-se apenas à versão que recebe a maior parte do tráfego. Tenha em atenção o seguinte:

  • Um mínimo baixo ajuda a manter os custos de funcionamento baixos durante os períodos de inatividade, mas significa que podem estar imediatamente disponíveis menos instâncias para responder a um pico de carga súbito.

  • Um mínimo elevado permite preparar a aplicação para picos rápidos na carga de pedidos. O App Engine mantém o número mínimo de instâncias em execução para atender a pedidos recebidos. As instâncias são cobradas, quer estejam ou não a processar pedidos. Para que esta funcionalidade funcione corretamente, tem de se certificar de que os pedidos de preparação estão ativados e que a sua aplicação processa os pedidos de preparação.

    Se definir um número mínimo de instâncias inativas, a latência pendente terá menos efeito no desempenho da sua aplicação. Uma vez que o App Engine mantém instâncias inativas na reserva, é improvável que os pedidos entrem na fila pendente, exceto em picos de carga excecionalmente elevados. Tem de testar a sua aplicação e o volume de tráfego esperado para determinar o número ideal de instâncias a manter em reserva.

<min-pending-latency>

O período mínimo, em segundos, que o App Engine deve permitir que um pedido aguarde na fila pendente antes de iniciar uma nova instância para o processar. Especifique um valor de 0,01 a 15.

  • Um mínimo baixo significa que os pedidos têm de passar menos tempo na fila pendente quando todas as instâncias existentes estão ativas. Isto melhora o desempenho, mas aumenta o custo de execução da sua aplicação.
  • Um mínimo elevado significa que os pedidos vão permanecer pendentes durante mais tempo se todas as instâncias existentes estiverem ativas. Isto reduz os custos de execução, mas aumenta o tempo que os utilizadores têm de esperar que os respetivos pedidos sejam servidos.
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 é encerrada após este período desde que recebeu o último pedido. A predefinição é de 5 minutos.
<max-instances>
Obrigatório. O número máximo de instâncias que o App Engine pode criar para esta versão do módulo. Isto é ú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> permite o dimensionamento 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>
O número de instâncias a atribuir 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 preparação

Grande parte do trabalho realizado durante uma implementação ocorre localmente num passo de preparação denominado preparação, onde os ficheiros JAR são montados, os JSPs são compilados, etc. Opcionalmente, pode configurar determinadas partes do comportamento de preparação usando elementos de preparação no ficheiro de configuração da aplicação. A maioria das aplicações é implementada com êxito sem configurar manualmente o comportamento de preparação. Se a sua app não for implementada, pode ter de configurar a preparação através das opções apresentadas abaixo.

Elemento Descrição
<staging>

Opcional. A maioria das aplicações não precisa de alterar o comportamento predefinido.

O elemento de preparação permite-lhe especificar uma configuração de preparação específica, se necessário para a implementação.

Este elemento pode conter os seguintes elementos:

<enable-jar-splitting>

Opcional. Divida ficheiros JAR grandes (> 10 megabytes) em fragmentos mais pequenos. (Predefinição: true).

<jar-splitting-excludes>

Especifica uma lista de sufixos de ficheiros separados por vírgulas. Se a opção enable-jar-splitting estiver ativada, todos os ficheiros que correspondam aos sufixos serão excluídos de todos os JARs.

<disable_jar_jsps>

Não crie ficheiros JAR de classes geradas a partir de JSPs. (Predefinição: false).

<enable-jar-classes>

Crie um ficheiro JAR com o conteúdo de WEB-INF/classes. (Predefinição: false).

<delete-jsps>

Elimine os ficheiros de origem JSP após a compilação. (Predefinição: true).

<compile-encoding>

Codificação de entrada dos ficheiros de origem para compilação. (Predefinição: utf-8).

Por exemplo:

        <staging>
          <delete-jsps>false</delete-jsps>
        </staging>

Predefinições da opção de preparação

As predefinições das opções de preparação são as seguintes:

Elemento de preparação Valor predefinido
enable-jar-splitting true
jar-splitting-excludes NA
disable-jar-jsps false
enable-jar-classes true. Isto pode afetar a ordem de carregamento das classes. Por isso, se a sua app depender de uma determinada ordem, defina esta opção como false.
delete-jsps true
compile-encoding utf-8

Sintaxe de inclusão e exclusão

Os padrões de caminho são especificados com zero ou mais elementos <include> e <exclude>. Num padrão, '*' representa zero ou mais de qualquer caráter num nome de ficheiro ou diretório, e ** representa zero ou mais diretórios num caminho. Os ficheiros e os diretórios que correspondem aos padrões <exclude> não são carregados quando implementa a sua app no App Engine. No entanto, estes ficheiros e diretórios continuam acessíveis à sua aplicação quando esta é executada no servidor de desenvolvimento local.

Um elemento <include> substitui o comportamento predefinido de incluir todos os ficheiros. Um elemento <exclude> aplica-se após todos os padrões <include> (bem como o padrão se não for fornecido nenhum <include> explícito).

O exemplo seguinte demonstra como designar todos os ficheiros .png como ficheiros estáticos (exceto os que se encontram no diretório data/ e em todos os respetivos subdiretórios):

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

Também pode definir cabeçalhos HTTP para usar quando responde a pedidos a estes 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 ficheiros estáticos

Por predefinição, os ficheiros estáticos são publicados com um tipo MIME selecionado com base na extensão do nome de ficheiro. Pode associar tipos MIME personalizados a extensões de nomes de ficheiros para ficheiros estáticos através de elementos <mime-mapping> em web.xml.

Tempo limite do URLFetch

Pode definir um prazo para cada pedido de URLFetch. Por predefinição, o prazo para uma obtenção é de 5 segundos. Pode alterar esta predefinição incluindo a seguinte definição no ficheiro de configuração appengine-web.xml. Especifique o limite de tempo em segundos:

<system-properties>
    <property name="appengine.api.urlfetch.defaultDeadline" value="10"/>
</system-properties>