Referência do app.yaml 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.

Configura as definições da app do App Engine no ficheiro app.yaml. Este ficheiro especifica como os caminhos dos URLs correspondem aos processadores de pedidos e aos ficheiros estáticos. O ficheiro app.yaml também contém informações sobre o código da sua app, como o tempo de execução e o identificador da versão mais recente.

Cada serviço na sua app tem o seu próprio ficheiro app.yaml, que funciona como um descritor para a respetiva implementação. Primeiro, tem de criar o ficheiro app.yaml para o serviço default antes de poder criar e implementar ficheiros app.yaml para serviços adicionais na sua app.

Estrutura do diretório

Para saber como estruturar vários serviços na sua app, consulte o artigo Estruturar serviços Web no App Engine.

Exemplo

Segue-se um exemplo de um ficheiro app.yaml para uma aplicação Python 2:

runtime: python27
api_version: 1
threadsafe: true

handlers:
- url: /
  script: home.app

- url: /index\.html
  script: home.app

- url: /stylesheets
  static_dir: stylesheets

- url: /(.*\.(gif|png|jpg))$
  static_files: static/\1
  upload: static/.*\.(gif|png|jpg)$

- url: /admin/.*
  script: admin.app
  login: admin

- url: /.*
  script: not_found.app

Uma diretiva script: pode conter um caminho de ficheiro que termina em .py, o que significa que o script usa CGI, ou um caminho de módulo Python, com nomes de pacotes separados por pontos, o que significa que o script usa WSGI.

Sintaxe

A sintaxe de app.yaml é o formato YAML.

O formato YAML suporta comentários. Uma linha que começa com um caráter de cardinal (#) é ignorada:

# This is a comment.

Os padrões de URL e caminho do ficheiro usam a sintaxe de expressão regular estendida POSIX, excluindo elementos de ordenação e classes de ordenação. As referências anteriores a correspondências agrupadas (por exemplo, \1) são suportadas, tal como estas extensões Perl: \w \W \s \S \d \D.

Tempo de execução e elementos da app

Elemento Descrição
application

A abordagem recomendada é remover o elemento application do ficheiro app.yaml e, em alternativa, usar um sinalizador de linha de comandos para especificar o ID da aplicação:

  • Para usar o comando gcloud app deploy, tem de especificar a flag --project: 
    gcloud app deploy --project [YOUR_PROJECT_ID]

Para mais informações sobre a utilização destes comandos, consulte o artigo Implementar a sua app.

O ID da aplicação é o Google Cloud ID do projeto da consola que especificou quando criou a aplicação na Google Cloud console.

api_version

Obrigatório. A versão da API no ambiente de tempo de execução fornecido que é usada pela sua app.

Este campo foi descontinuado em runtimes do App Engine mais recentes.

Quando a Google anuncia suporte para uma nova versão da API de um ambiente de execução, a sua app implementada continua a usar a versão para a qual foi escrita. Para atualizar a sua app para uma nova versão da API, altere este valor e, em seguida, volte a implementar a app no App Engine. Quando especifica o valor 1 , o ambiente de tempo de execução compatível mais recente é usado sempre que implementa essa app (atualmente, ).

Neste momento, o App Engine tem uma versão do ambiente de tempo de execução: 1python27

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.
builtins

Opcional. O SDK Python 2 inclui vários controladores incorporados para funções comuns da aplicação. A diretiva builtins permite-lhe incluir controladores específicos em app.yaml.

Este campo foi descontinuado no tempo de execução do Python 3.

Os seguintes controladores integrados estão disponíveis para utilização:

appstats
Ativa o Appstats em /_ah/stats/, que pode usar para medir o desempenho da sua aplicação. Para usar o Appstats, também tem de instalar o registador de eventos.
deferred
Ativa o controlador diferido em /_ah/queue/deferred. Esta funcionalidade incorporada permite que os programadores usem deferred.defer() para simplificar a criação de tarefas da fila de tarefas.
remote_api
Ativa o remote_api incorporado em /_ah/remote_api/. Este elemento incorporado permite que as aplicações remotas com as credenciais adequadas acedam ao armazenamento de dados remotamente.
Exemplo: 
builtins:
- deferred: on
- appstats: on

A diretiva builtins é uma instância especial da diretiva includes. Cada diretiva builtin é equivalente, em Python, a uma diretiva includes com um caminho expandido. Por exemplo: 

builtins:
- name: on

É equivalente a:

includes:
- $PYTHON_LIB/google/appengine/ext/builtins/name/

Quando usa builtins no seu ficheiro app.yaml, todos os controladores definidos no ficheiro include.yaml incorporado substituem todos os controladores que definir no seu ficheiro app.yaml. No entanto, se incluir um ficheiro que use builtins ou includes, os processadores são adicionados por ordem da hierarquia de inclusão. Por outras palavras, os controladores da inclusão "parent" são adicionados antes dos controladores incorporados das inclusões "child" e assim sucessivamente.

Por exemplo, considere o seguinte app.yaml, que usa os processadores appstats incorporados: 

handlers:
- url: /.*
  script: main.app
builtins:
- appstats: on

A lista de controladores resultante é:

[/_ah/stats, /.*]

Se o elemento app.yaml usar uma diretiva includes: 

includes:
- included.yaml

O ficheiro included.yaml usa builtins: 

handlers:
- url: /.*
  script: main.app
builtins:
- appstats: on

A lista resultante de controladores é agora: 

[/.*, /_ah/stats]

A ordem de colocação da cláusula builtins num ficheiro .yaml não altera o comportamento.

default_expiration

Opcional. Define um período de cache predefinido global para todos os controladores de ficheiros estáticos de uma aplicação. Também pode configurar uma duração da cache para gestores de ficheiros estáticos específicos. 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. Se for omitido, o servidor de produção define a expiração para 10 minutos.

Exemplo: 
runtime: python27
api_version: 1
threadsafe: true

default_expiration: "4d 5h"

handlers:
# ...

Para mais informações, consulte o artigo Validade da cache.

env_variables

Opcional. Pode definir variáveis de ambiente no ficheiro app.yaml para as disponibilizar à sua app. Certifique-se de que a chave em Variáveis de ambiente corresponde à expressão "[a-zA-Z_][a-zA-Z0-9_]*" (começar com um alfabeto ou "_" seguido de qualquer carater alfanumérico ou "_").

As variáveis de ambiente com o prefixo GAE estão reservadas para utilização do sistema e não são permitidas no ficheiro app.yaml.

Estas variáveis vão estar disponíveis no dicionário os.environ: 
env_variables:
  DJANGO_SETTINGS_MODULE: "myapp.settings"
error_handlers

Opcional. Usado para configurar páginas de erro personalizadas que são devolvidas para diferentes tipos de erros.

Este elemento pode conter os seguintes elementos:

error_code
Opcional. O error_code pode ser um dos 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 error_code é opcional. Se não for especificado, o ficheiro indicado é a resposta de erro predefinida para a sua app.

file
Cada entrada de ficheiro indica um ficheiro estático que deve ser publicado em vez da resposta de erro genérica. Se especificar um elemento file sem um elemento error_code correspondente, o ficheiro estático é a página de erro predefinida para a sua app. Os dados de erro personalizados têm de ter menos de 10 kilobytes.
Exemplo 
error_handlers:
  - file: default_error.html

  - error_code: over_quota
    file: over_quota.html
handlers

Obrigatório. Uma lista de padrões de URL e descrições de como devem ser processados. O App Engine pode processar URLs executando código de aplicação ou publicando ficheiros estáticos carregados com o código, como imagens, CSS ou JavaScript.

Veja a sintaxe de controladores e subelementos

includes

Opcional. A diretiva includes permite-lhe incluir o ficheiro de configuração de qualquer biblioteca ou serviço em toda a sua aplicação. Por exemplo, pode incluir uma biblioteca de administração de utilizadores da seguinte forma: 

includes:
- lib/user_admin.yaml

O App Engine resolve o caminho incluído pela seguinte ordem:

  • Caminho absoluto ou relativo para o diretório de trabalho. O caminho especificado resolve-se num ficheiro.
  • Relativo ao diretório da aplicação, que também é conhecido como basepath. O basepath e o caminho resolvem-se num ficheiro.
  • Relativo ao ficheiro que incluiu o ficheiro atual. A localização do ficheiro de referência e o caminho de inclusão resolvem-se no ficheiro incluído.

Se a diretiva include especificar um diretório, o App Engine procura nesse diretório um ficheiro denominado include.yaml. Se a diretiva include for um ficheiro, então esse ficheiro específico é incluído. A utilização de includes obtém apenas os seguintes tipos de diretivas do ficheiro de destino (se estiverem presentes):

Os padrões skip_files incluídos são adicionados aos padrões em app.yaml, incluindo app.yaml, ou à lista predefinida se não existir uma lista explícita em app.yaml. Tenha em atenção que skip_files compara caminhos absolutos.

inbound_services

Opcional. As aplicações têm de ativar esses serviços antes de poderem receber pedidos de entrada. Pode ativar o serviço para uma app Python 2 incluindo uma secção inbound_services no ficheiro app.yaml.

Estão disponíveis os seguintes serviços de entrada:

mail
Permite que a sua aplicação receba correio.
warmup
Ativa os pedidos de preparação. Consulte Configurar pedidos de preparação.
Exemplo: 
inbound_services:
  - mail
  - warmup
instance_class

Opcional. A classe de instância para este serviço.

Os seguintes valores estão disponíveis consoante o dimensionamento do seu serviço:

Escala automática
F1, F2, F4, F4_1G
Predefinição: F1

Opcionalmente, use o elemento automatic_scaling para alterar as predefinições da escalabilidade automática, como o número mínimo e máximo de instâncias, a latência e as ligações simultâneas.

Nota: se instance_class estiver definido como F2 ou superior, pode otimizar as suas instâncias definindo max_concurrent_requests para um valor superior ao valor predefinido de 10. Para determinar o valor ideal, aumente-o gradualmente e monitorize o desempenho da sua aplicação.

Dimensionamento básico e manual
B1, B2, B4, B4_1G, B8
Predefinição: B2

As classes de instâncias básicas e manuais requerem que especifique o elemento basic_scaling ou o elemento manual_scaling.

libraries

Opcional. O tempo de execução do Python 2.7 inclui algumas bibliotecas de terceiros. Algumas destas opções estão disponíveis por predefinição; outras só estão disponíveis se forem configuradas. Pode especificar a versão que quer usar especificando os valores name e version.

Este campo foi descontinuado no tempo de execução do Python 3.

libraries:
- name: PIL
  version: "1.1.7"
- name: webob
  version: "latest"

Tenha em atenção que, quando especifica latest, o SDK determina a versão mais recente da biblioteca no momento da implementação. Depois de implementada, a versão da biblioteca não é alterada. A única forma de obter uma versão diferente da biblioteca é implementá-la novamente.

Se estiver a desenvolver uma aplicação que ainda não tem utilizadores: não precisa de monitorizar novas versões. No entanto, se a sua aplicação estiver a ser usada ativamente, tenha cuidado: pode ficar surpreendido com o facto de a sua aplicação começar a usar uma nova versão da biblioteca não compatível com versões anteriores.

Para ver uma lista das bibliotecas de terceiros incluídas, consulte o artigo Bibliotecas de terceiros. Pode usar bibliotecas de terceiros adicionais de Python puro instalando-as num diretório local.

Se estiver a usar o ambiente flexível, consulte o artigo Usar bibliotecas Python no ambiente flexível.

module

Nota: os módulos chamam-se agora Serviços.

Para gerir a sua app com a CLI gcloud, use o elemento service.

runtime

Obrigatório. O nome do ambiente de tempo de execução usado pela sua app. Por exemplo, para especificar o Python 2.7, use: 

runtime: python27
service

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

Apenas suportado pela CLI gcloud ou por plug-ins baseados na CLI gcloud, por exemplo: gcloud app deploy .

Obrigatório se estiver a criar um serviço. Opcional para o serviço default. Cada serviço e cada versão têm de ter um nome. Um nome pode conter números, letras e hífenes. O comprimento combinado de VERSION-dot-SERVICE-dot-PROJECT_ID, em que VERSION é o nome da sua versão, SERVICE é o nome do seu serviço e PROJECT_ID é o ID do seu projeto, não pode exceder 63 carateres e não pode começar nem terminar com um hífen. Escolha um nome exclusivo para cada serviço e cada versão. Não reutilize nomes entre serviços e versões.

Exemplo: 
service: service-name

Nota: o comando gcloud app deploy é retrocompatível e suporta ficheiros app.yaml existentes que incluem serviços declarados como módulos, por exemplo: 

module: service-name
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: 
service_account: [SERVICE_ACCOUNT_NAME]@[PROJECT_ID].iam.gserviceaccount.com
skip_files

Opcional. O elemento skip_files especifica os ficheiros no diretório da aplicação que não devem ser carregados para o App Engine. O valor é uma expressão regular ou uma lista de expressões regulares. Qualquer nome de ficheiro que corresponda a qualquer uma das expressões regulares é omitido da lista de ficheiros a carregar quando a aplicação é carregada. Os nomes dos ficheiros são relativos ao diretório do projeto.

O skip_files tem a seguinte predefinição: 

skip_files:
- ^(.*/)?#.*#$
- ^(.*/)?.*~$
- ^(.*/)?.*\.py[co]$
- ^(.*/)?.*/RCS/.*$
- ^(.*/)?\..*$

O padrão predefinido exclui ficheiros de cópias de segurança do Emacs com nomes do formulário #...# e ...~, ficheiros .pyc e .pyo, ficheiros num diretório de RCS controlo de revisões e ficheiros ocultos do Unix com nomes que começam por um ponto (.).

Para prolongar a lista de expressões regulares acima, copie e cole a lista acima no seu app.yaml e adicione as suas próprias expressões regulares. Por exemplo, para ignorar ficheiros cujos nomes terminam em .bak, além dos padrões predefinidos, adicione uma entrada como esta para skip_files: 

skip_files:
- ^(.*/)?#.*#$
- ^(.*/)?.*~$
- ^(.*/)?.*\.py[co]$
- ^(.*/)?.*/RCS/.*$
- ^(.*/)?\..*$
- ^(.*/)?.*\.bak$

Para ignorar um diretório completo, adicione o nome do diretório à lista. Por exemplo, para ignorar um diretório denominado logs, adicione a seguinte linha às descritas anteriormente: 

skip_files:
- logs/
threadsafe

Obrigatório. Configura a sua aplicação para usar pedidos simultâneos. Se usar a biblioteca de threading do Python, os dados locais do thread, conforme devolvidos por threading.local(), são limpos após cada pedido.

Este campo foi descontinuado no tempo de execução do Python 3.

threadsafe: [true | false]

Nota: a diretiva threadsafe é necessária para aplicações Python 2.7. threadsafe: true requer que todos os controladores de scripts sejam WSGI. Ou seja, cada script tem de ser especificado numa diretiva script: usando um caminho do módulo Python, com os nomes dos pacotes separados por pontos. O último componente de uma diretiva script: que usa um caminho de módulo Python é o nome de uma variável global no . Essa variável service: tem de ser uma app WSGI e, por convenção, é normalmente denominada app.

version

A abordagem recomendada é remover o elemento version do seu ficheiro app.yaml e, em alternativa, usar um sinalizador de linha de comando para especificar o ID da versão:

  • Para usar o comando gcloud app deploy, especifique a flag -v: 
    gcloud app deploy -v [YOUR_VERSION_ID]

Para mais informações sobre a utilização deste comando, consulte o artigo Implementar a sua app.

Um identificador da versão do código da sua aplicação que implementa no App Engine.

O ID da 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.

Nota: 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-dot-my-service.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 serviço especificado. Se essa versão não existir, o destino será o número de instância 123 da versão predefinida do serviço.

Cada versão de uma aplicação mantém a sua própria cópia de app.yaml. Quando uma aplicação é carregada, a versão mencionada no ficheiro app.yaml que está a ser carregado é a versão que é criada ou substituída pelo carregamento. Um administrador pode alterar a versão da aplicação que está a publicar tráfego através da Google Cloud consolee também pode testar outras versões antes de as configurar para receber tráfego.

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
Literal de string. Especifique o nome totalmente qualificado do seu conetor de acesso à VPC sem servidor entre aspas: 
"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"
  egress_setting: all-traffic

Elemento Handlers

O elemento handlers é um elemento obrigatório no ficheiro de configuração app.yaml. O elemento fornece uma lista de padrões de URL e descrições de como devem ser processados. O App Engine pode processar URLs executando código de aplicação ou publicando ficheiros estáticos carregados com o código, como imagens, CSS ou JavaScript.

Os padrões são avaliados pela ordem em que aparecem no ficheiro app.yaml, de cima para baixo. O primeiro mapeamento cujo padrão corresponde ao URL é o que é usado para processar o pedido.

A tabela seguinte lista os subelementos do elemento handlers que controlam o comportamento dos scripts, ficheiros estáticos, diretórios estáticos e outras definições.

Elemento Descrição
application_readable Opcional. Booleano. Por predefinição, os ficheiros declarados em controladores de ficheiros estáticos são carregados como dados estáticos e só são publicados para utilizadores finais. Não podem ser lidos por uma aplicação. Se este campo estiver definido como verdadeiro, os ficheiros também são carregados como dados de código para que a sua aplicação os possa ler. Ambos os carregamentos são cobrados em função das quotas de recursos de armazenamento de código e dados estáticos.

Este campo foi descontinuado em runtimes do App Engine mais recentes.
expiration Opcional. O período durante o qual um ficheiro estático publicado por este controlador deve ser colocado em cache por proxies Web e navegadores. 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. Se for omitido, é usado o valor default_expiration da aplicação. Consulte Expiração da cache para mais detalhes.
http_headers

Opcional. Pode definir cabeçalhos HTTP para respostas dos processadores de diretórios ou ficheiros estáticos. Se precisar de definir cabeçalhos HTTP nos seus processadores script, deve fazê-lo no código da sua app. Para obter informações sobre os cabeçalhos de resposta que influenciam o armazenamento em cache, consulte o artigo Armazenamento em cache de conteúdo estático.

Exemplo 
handlers:
- url: /images
  static_dir: static/images
  http_headers:
    X-Foo-Header: foo
    X-Bar-Header: bar value
    vary: Accept-Encoding
  # ...

Compatibilidade com CORS

Uma utilização importante desta funcionalidade é suportar a partilha de recursos de origem cruzada (CORS), como aceder a ficheiros alojados por outra app do App Engine.

Por exemplo, pode ter uma app de jogos mygame.uc.r.appspot.com que acede a recursos alojados por myassets.uc.r.appspot.com. No entanto, se mygame tentar fazer um pedido JavaScript XMLHttpRequest para myassets, não vai ter êxito, a menos que o controlador de myassets devolva um cabeçalho de resposta Access-Control-Allow-Origin: que contenha o valor http://mygame.uc.r.appspot.com.

Veja como faria com que o seu controlador de ficheiros estáticos devolvesse esse valor do cabeçalho da resposta obrigatório: 

handlers:
- url: /images
  static_dir: static/images
  http_headers:
    Access-Control-Allow-Origin: https://mygame.uc.r.appspot.com
  # ...

Nota: se quiser permitir que todos acedam aos seus recursos, pode usar o caráter universal '*' em vez de https://mygame.uc.r.appspot.com.

mime_type

Opcional. Se for especificado, todos os ficheiros publicados por este controlador vão ser publicados com o tipo MIME especificado. Se não for especificado, o tipo MIME de um ficheiro é derivado da extensão do nome de ficheiro. Se o mesmo ficheiro for carregado com várias extensões, a extensão resultante pode depender da ordem em que os carregamentos ocorreram.

Para mais informações sobre os tipos de suportes MIME possíveis, consulte o Website de tipos de suportes MIME da IANA

redirect_http_response_code

Opcional. redirect_http_response_code é usado com a definição secure para definir o código de resposta HTTP devolvido quando é feito um redirecionamento exigido pela forma como a definição secure está configurada. O elemento redirect_http_response_code tem os seguintes valores possíveis:

301
Código de resposta
Movido permanentemente.
302
Código de resposta encontrado.
303
Consulte o código de resposta Other.
307
Código de resposta de redirecionamento temporário.
Exemplo 
handlers:
- url: /youraccount/.*
  script: accounts.app
  login: required
  secure: always
  redirect_http_response_code: 301

Quando o pedido de um utilizador é redirecionado, o código de estado HTTP é definido para o valor do parâmetro redirect_http_response_code. Se o parâmetro não estiver presente, é devolvido 302.

script

Opcional. Especifica o caminho para o script a partir do diretório raiz da aplicação: 

handlers:
# The root URL (/) is handled by the WSGI application named
# "app" in home.py. No other URLs match this pattern.
- url: /
  script: home.app

# The URL /index.html is also handled by the home.py script.
- url: /index\.html
  script: home.app

# A regular expression can map parts of the URL to the
# path of the script.
- url: /browse/(books|videos|tools)
  script: \1.catalog.app

# All other URLs use the WSGI application named in "app"
# in not_found.py.
- url: /.*
  script: not_found.app

Uma diretiva script: tem de ser um caminho de importação do Python, por exemplo, package.module.app, que aponta para uma aplicação WSGI. O último componente de uma diretiva script: que usa um caminho de módulo Python é o nome de uma variável global no módulo: essa variável tem de ser uma app WSGI e, por convenção, é normalmente denominada app.

Nota: tal como para uma declaração import do Python, cada subdiretório que seja um pacote tem de conter um ficheiro com o nome __init__.py.

Nos runtimes do App Engine mais recentes, o comportamento deste campo foi alterado.
secure Opcional. Qualquer controlador de URL pode usar a definição secure, incluindo controladores de scripts e controladores de ficheiros estáticos. O elemento secure tem os seguintes valores possíveis:
optional
Os pedidos HTTP e HTTPS com URLs que correspondem ao controlador são bem-sucedidos sem redirecionamentos. A aplicação pode examinar o pedido para determinar que protocolo foi usado e responder em conformidade. Esta é a predefinição quando secure não é fornecido para um controlador.
never
As solicitações de um URL que corresponda a este controlador que use HTTPS são automaticamente redirecionadas para o URL HTTP equivalente. Quando um pedido HTTPS de um utilizador é redirecionado para ser um pedido HTTP, os parâmetros de consulta são removidos do pedido. Isto impede que um utilizador envie acidentalmente dados de consulta através de uma ligação não segura destinada a uma ligação segura.
always
Os pedidos de um URL que corresponda a este controlador e que não usem HTTPS são automaticamente redirecionados para o URL HTTPS com o mesmo caminho. Os parâmetros de consulta são preservados para o redirecionamento.
Exemplo 
handlers:
- url: /youraccount/.*
  script: accounts.app
  login: required
  secure: always

O servidor Web de desenvolvimento não suporta ligações HTTPS. Ignora o parâmetro secure, pelo que os caminhos destinados a utilização com HTTPS podem ser testados através de ligações HTTP normais ao servidor Web de desenvolvimento.

Para segmentar uma versão específica da sua app através do domínio REGION_ID.r.appspot.com, substitui os pontos que normalmente separariam os componentes do subdomínio do URL pela string "-dot-", por exemplo:
https://VERSION_ID-dot-default-dot-PROJECT_ID.REGION_ID.r.appspot.com

Para usar domínios personalizados com HTTPS, tem de ativar e configurar certificados SSL para esse domínio.

O início e o fim de sessão nas Contas Google são sempre realizados através de uma ligação segura, independentemente da forma como os URLs da aplicação estão configurados.

static_dir

Opcional. O caminho para o diretório que contém os ficheiros estáticos, a partir do diretório raiz da aplicação. Tudo o que estiver após o final do padrão url correspondente é anexado a static_dir para formar o caminho completo para o ficheiro pedido.

Cada ficheiro no diretório estático é publicado com o tipo MIME que corresponde à extensão do nome de ficheiro, a menos que seja substituído pela definição mime_type do diretório. Todos os ficheiros no diretório indicado são carregados como ficheiros estáticos e nenhum deles pode ser executado como scripts.

Todos os ficheiros neste diretório são carregados com a sua app como ficheiros estáticos. O App Engine armazena e publica ficheiros estáticos separadamente dos ficheiros da sua app. Por predefinição, os ficheiros estáticos não estão disponíveis no sistema de ficheiros da app. Pode alterar esta opção definindo a opção application_readable como verdadeira.

Exemplo: 
handlers:
# All URLs beginning with /stylesheets are treated as paths to
# static files in the stylesheets/ directory.
- url: /stylesheets
  static_dir: stylesheets
  # ...
static_files

Opcional. Um controlador de padrões de ficheiros estáticos associa um padrão de URL a caminhos para ficheiros estáticos carregados com a aplicação. A expressão regular do padrão de URL pode definir agrupamentos de expressões regulares a usar na construção do caminho do ficheiro. Pode usar isto em vez de static_dir para mapear ficheiros específicos numa estrutura de diretórios sem mapear o diretório completo.

Exemplo: 
handlers:
# All URLs ending in .gif .png or .jpg are treated as paths to
# static files in the static/ directory. The URL pattern is a
# regular expression, with a grouping that is inserted into the
# path to the file.
- url: /(.*\.(gif|png|jpg))$
  static_files: static/\1
  upload: static/.*\.(gif|png|jpg)$
  # ...

O App Engine armazena e publica ficheiros estáticos separadamente dos ficheiros de aplicações. Por predefinição, os ficheiros estáticos não estão disponíveis no sistema de ficheiros da aplicação. Pode alterar esta opção definindo a opção application_readable como verdadeira.

Os ficheiros estáticos não podem ser iguais aos ficheiros de código da aplicação. Se um caminho de ficheiro estático corresponder a um caminho para um script usado num controlador dinâmico, o script não vai estar disponível para o controlador dinâmico.

upload

Opcional. Uma expressão regular que corresponde aos caminhos dos ficheiros de todos os ficheiros que vão ser referenciados por este controlador. Isto é necessário porque o controlador não consegue determinar que ficheiros no diretório da sua aplicação correspondem aos padrões url e static_files indicados. Os ficheiros estáticos são carregados e processados separadamente dos ficheiros da aplicação. O exemplo acima pode usar o seguinte padrão upload: archives/(.*)/items/(.*)

url

Elemento obrigatório em handlers. O padrão de URL, como uma expressão regular. A expressão pode conter agrupamentos que podem ser referidos no caminho do ficheiro para o script com referências anteriores de expressões regulares. Por exemplo, /profile/(.*)/(.*) corresponderia ao URL /profile/edit/manager e usaria edit e manager como o primeiro e o segundo agrupamentos.

O padrão de URL tem algumas diferenças no comportamento quando usado com os seguintes elementos:

static_dir
Usa um prefixo de URL. O padrão de expressão regular não deve conter agrupamentos quando usado com o elemento static_dir. Todos os URLs que começam com este prefixo são processados por este controlador, usando a parte do URL após o prefixo como parte do caminho do ficheiro.
static_files
Um controlador de padrões de ficheiros estáticos associa um padrão de URL a caminhos para ficheiros estáticos carregados com a aplicação. A expressão regular do padrão de URL pode definir agrupamentos de expressões regulares a usar na construção do caminho do ficheiro. Pode usar isto em vez de static_dir para mapear ficheiros específicos numa estrutura de diretórios sem mapear o diretório completo.

Dimensionar elementos

Os elementos na tabela seguinte configuram a forma como a sua aplicação é dimensionada. Para saber mais sobre como as apps do App Engine são dimensionadas, consulte os tipos de dimensionamento.

Elemento Descrição
automatic_scaling

Opcional. Aplicável apenas a aplicações que usam uma instância da classe F1 ou superior.

Especifique este elemento para alterar as predefinições do dimensionamento automático, como a definição dos níveis mínimo e máximo para o número de instâncias, a latência e as ligações simultâneas para um serviço.

Este elemento pode conter os seguintes elementos:

max_instances
Opcional. Especifique um valor entre 0 e 2147483647, em que zero desativa a definição.

Este parâmetro especifica o número máximo de instâncias que o App Engine deve criar para esta versão do módulo. Isto é útil para limitar os custos de um módulo.

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_idle_instances

Opcional. O número máximo de instâncias inativas que o App Engine deve manter para esta versão. Especifique um valor de 1 a 1000. Se não for especificado, o valor predefinido é automatic, o que significa que o App Engine vai gerir o número de instâncias inativas. 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.

min_idle_instances

Opcional: o número de instâncias adicionais a manter em execução e prontas para publicar tráfego para esta versão.

O App Engine calcula o número de instâncias necessárias para servir o tráfego atual da sua aplicação com base nas definições de dimensionamento, como target_cpu_utilization e target_throughput_utilization. A definição de min_idle_instances especifica o número de instâncias a executar além deste número calculado. Por exemplo, se o App Engine calcular que são necessárias 5 instâncias para publicar tráfego e min_idle_instances estiver definido como 2, o App Engine vai executar 7 instâncias (5, calculadas com base no tráfego, mais 2 adicionais por min_idle_instances).

Tenha em atenção que lhe é cobrado o número de instâncias especificado, quer estejam a receber tráfego ou não. 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. O número de instâncias especificado é cobrado, quer estejam ou não a processar pedidos.

    Se definir um número mínimo de instâncias inativas, a latência pendente terá menos efeito no desempenho da sua aplicação.

target_cpu_utilization
Opcional. Especifique um valor entre 0,5 e 0,95. A predefinição é 0.6.

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. A predefinição é 0.6.

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 programador tenta iniciar uma nova instância.

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: 1000).

Usado com target_throughput_utilization 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 tenta iniciar uma nova instância.

Recomendamos que não defina max_concurrent_requests para menos de 10, a menos que precise de processamento de linha única. Um valor inferior a 10 provavelmente vai resultar na criação de mais instâncias do que o necessário para uma app segura para vários processos, o que pode gerar custos desnecessários.

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

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. Quando este limite é atingido, é um sinal para aumentar a escala e resulta num aumento do número de instâncias. Se não for especificado, o valor predefinido é automatic. Isto significa que os pedidos podem permanecer na fila pendente durante um máximo de 10 segundos, o limite de tempo de pedido pendente máximo, antes de serem acionados novos inícios de instâncias.

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 custa menos.

min_pending_latency

Um elemento opcional que pode definir para especificar a quantidade mínima de tempo que o App Engine deve permitir que um pedido aguarde na fila pendente antes de iniciar uma nova instância para o processar. A especificação de um valor pode reduzir os custos de funcionamento, mas aumenta o tempo que os utilizadores têm de esperar que os respetivos pedidos sejam processados.

Para apps gratuitas, o valor predefinido é 500ms. Para apps pagas, o valor predefinido é 0.

Este elemento funciona em conjunto com o elemento max_pending_latency para determinar quando o App Engine cria novas instâncias. Se existirem pedidos pendentes na fila:

  • Inferior ao valor min_pending_latency especificado, o App Engine não cria novas instâncias.
  • Mais de max_pending_latency, o App Engine tenta criar uma nova instância.
  • Entre a hora especificada por min_pending_latency e max_pending_latency, o App Engine tenta reutilizar uma instância existente. Se nenhuma instância conseguir processar o pedido antes de max_pending_latency, o App Engine cria uma nova instância.
Exemplo 
automatic_scaling:
  target_cpu_utilization: 0.65
  min_instances: 5
  max_instances: 100
  min_pending_latency: 30ms
  max_pending_latency: automatic
  max_concurrent_requests: 50
basic_scaling

As aplicações que usam uma instância da classe de B1 ou superior têm de especificar este elemento ou manual_scaling.

Este elemento permite o dimensionamento básico das classes de instâncias B1 e superiores, pode conter os seguintes elementos:

max_instances
Obrigatório. O número máximo de instâncias que o App Engine pode criar para esta versão do serviço. Isto é útil para limitar os custos de um serviço.
idle_timeout
Opcional. A instância é encerrada após este período desde que recebeu o último pedido. O valor predefinido são 5 minutos (5m).
Exemplo 
basic_scaling:
  max_instances: 11
  idle_timeout: 10m
manual_scaling

As aplicações que usam uma instância da classe de B1 ou superior têm de especificar este elemento ou basic_scaling.

Este elemento permite o dimensionamento manual das classes de instâncias B1 e superiores e pode conter o seguinte elemento:

instances
O número de instâncias a atribuir ao serviço no início.
Exemplo 
manual_scaling:
  instances: 5