Referência do app.yaml

Defina as configurações do aplicativo App Engine no arquivo app.yaml. Esse arquivo especifica como os caminhos do URL correspondem aos gerenciadores de solicitação e aos arquivos estáticos. O arquivo app.yaml também contém informações sobre o código do aplicativo, como o ambiente de execução e o identificador da versão mais recente.

Cada serviço do aplicativo tem um arquivo app.yaml próprio, que atua como descritor da implantação. Primeiro, é necessário criar o arquivo app.yaml do serviço default antes de criar e implantar arquivos app.yamlde outros serviços do aplicativo.

Estrutura do diretório

Cada serviço precisa ter um arquivo app.yaml no diretório raiz. Para saber mais sobre como estruturar vários serviços no seu aplicativo, consulte Como estruturar serviços da Web no App Engine.

Exemplo

Veja a seguir um exemplo de arquivo app.yaml referente a um aplicativo 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 arquivo terminado em .py, o que significa que o script usa CGI, ou um caminho do 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 (em inglês).

O formato YAML é compatível com comentários. As linhas iniciadas com o caractere de cerquilha (#) são ignoradas:

# This is a comment.

Os padrões de caminho de URL e arquivo usam a sintaxe de expressões regulares estendidas POSIX, excluindo elementos e classes de compilação. São aceitas tanto as referências inversas às correspondências agrupadas (por exemplo, \1) quanto as extensões Perl: \w \W \s \S \d \D.

Elementos do ambiente de execução e do aplicativo

Elemento Descrição
application

A abordagem recomendada consiste em remover o elemento application do arquivo app.yaml e, no lugar dele, usar uma sinalização de linha de comando para especificar o ID do aplicativo:

  • Para usar o comando gcloud app deploy, é preciso especificar a sinalização --project:
    
    gcloud app deploy --project [YOUR_PROJECT_ID]
  • Para usar o comando appcfg.py update, especifique a sinalização -A:
    
    appcfg.py update -A [YOUR_PROJECT_ID]

Para mais informações sobre como usar esses comandos, consulte Como implantar seu app.

O ID do aplicativo é o código do projeto especificado na criação do aplicativo no Console do Google Cloud Platform.

api_version

Obrigatório. A versão da API no ambiente de execução específico usado pelo aplicativo.

Quando o Google anunciar o suporte para uma nova versão da API do ambiente de execução, o aplicativo implantado continuará usando a versão para a qual ele foi escrito. Para atualizar o aplicativo para uma nova versão da API, altere esse valor e implante novamente o aplicativo no App Engine. Quando você especifica o valor 1, o ambiente de execução mais recente aceito é usado sempre que você implanta esse aplicativo (atualmente).

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

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 opções a seguir são válidas:
default
Padrão. Usa códigos automáticos dispersos que são grandes, inteiros e bem distribuídos que são 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.
builtins

Opcional. O SDK do Python 2 inclui vários gerenciadores integrados para funções de aplicativo comuns. A diretiva builtins permite que você inclua gerenciadores específicos em app.yaml.

Os gerenciadores integrados a seguir estão disponíveis para uso:

appstats
Ativa o Appstats em /_ah/stats/, que é útil para medir o desempenho do aplicativo. Para usar o Appstats, também é necessário instalar o gravador de eventos.
deferred
Ativa o gerenciador deferido em /_ah/queue/deferred. Este gerenciador incorporado permite que desenvolvedores usem deferred.defer() para simplificar a criação de tarefas da Fila de tarefas. Consulte também Trabalho em segundo plano com a biblioteca deferida.
remote_api
Ativa o builtin remote_api incorporado em /_ah/remote_api/. Esse builtin permite que aplicativos remotos com as credenciais adequadas acessem o armazenamento de dados remotamente.
Exemplo:

builtins:
- deferred: on
- appstats: on

A diretiva builtins é uma instância especial da diretiva includes. Cada diretiva builtin é equivalente, no 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 você usa builtins no arquivo app.yaml, todos os gerenciadores que são definidos no arquivo include.yaml incorporado substituirão os gerenciadores definidos no arquivo app.yaml. No entanto, se você incluir um arquivo que use builtins ou includes, os gerenciadores serão adicionados por ordem da hierarquia de inclusão. Em outras palavras, os gerenciadores de inclusão do "pai" são adicionados antes dos builtins das inclusões do "filho", e assim por diante.

Por exemplo, considere o app.yaml a seguir, que usa os gerenciadores incorporados appstats:


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

A lista resultante de gerenciadores é:


[/_ah/stats, /.*]

Se app.yaml usar uma diretiva "includes":


includes:
- included.yaml

E o arquivo included.yaml usar builtins:


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

A lista resultante de gerenciadores será:


[/.*, /_ah/stats]

A ordem de colocação da cláusula builtins em um arquivo .yaml não altera o comportamento.

default_expiration

Opcional. Define um período de cache padrão global para todos os gerenciadores de arquivos estáticos de um aplicativo. Você também pode configurar a duração de um cache para gerenciadores de arquivos 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 do cache para quatro dias e cinco horas após o arquivo ser solicitado pela primeira vez. Se omitida, o servidor de produção definirá a expiração em 10 minutos.

Exemplo:

runtime: python27
api_version: 1
threadsafe: true

default_expiration: "4d 5h"

handlers:
# ...

Para mais informações, consulte Expiração do cache estático.

env_variables

Opcional. Defina variáveis de ambiente no arquivo app.yaml para disponibilizá-las no seu aplicativo

As variáveis de ambiente com o prefixo GAE são reservadas para uso do sistema e não são permitidas no arquivo app.yaml.

Essas variáveis estarão 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 retornadas para diferentes tipos de erro.

Este elemento pode conter os seguintes elementos:

error_code
Opcional. O error_code pode ser um dos valores a seguir:
over_quota
Indica que o aplicativo excedeu uma cota de recursos
dos_api_denial
Indica que a solicitação foi bloqueada pela configuração da Proteção do DoS do aplicativo.
timeout
Exibido se um prazo for alcançado antes que haja uma resposta do aplicativo.

O código do erro é opcional. Se ele não for especificado, o arquivo fornecido será a resposta de erro padrão do aplicativo.

file
Cada entrada de arquivo indica um arquivo estático a ser exibido no lugar da resposta de erro genérica. Se você especificar um elemento file sem um error_code correspondente, o arquivo estático será a página de erro padrão do aplicativo. Os dados de erro personalizados precisam 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 de descrições de como eles precisam ser processados. O App Engine pode processar os URLs executando o código do aplicativo ou exibindo arquivos estáticos enviados com o código, como imagens, CSS ou JavaScript.

Consultar a sintaxe de gerenciadores e subelementos

includes

Opcional. A diretiva includes permite a inclusão do arquivo de configuração em qualquer biblioteca ou serviço no aplicativo. Por exemplo, é possível incluir uma biblioteca de administração de usuários da seguinte maneira:


includes:
- lib/user_admin.yaml

O App Engine resolve o caminho incluído na ordem a seguir:

  • Caminho absoluto ou relativo do diretório em uso. O caminho especificado tem resolução em um arquivo.
  • Relativo ao diretório do aplicativo, que também é conhecido como caminho de base. O caminho de base e o caminho têm resolução em um arquivo.
  • Relativo ao arquivo que incluía o arquivo atual. O local do arquivo de referência e o caminho de inclusão têm resolução no arquivo incluído.

Se a diretiva include especificar um diretório, o App Engine buscará no diretório por um arquivo chamado include.yaml. Se a diretiva de inclusão for um arquivo, esse arquivo específico será incluído. O uso de includes recupera apenas os seguintes tipos de diretivas do arquivo de destino (se presente):

Os padrões de skip_files incluídos são adicionados aos que estão no app.yaml ou à lista padrão, se não houver uma lista explícita em app.yaml. Observe que skip_files compara caminhos absolutos.

inbound_services

Opcional. Os aplicativos precisam ativar esses serviços antes de poder receber solicitações de entrada. Para ativar o serviço em um aplicativo Python 2, inclua uma seção inbound_services no arquivo app.yaml.

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

mail
Permite que o aplicativo receba e-mail.
warmup
Ativa solicitações de aquecimento. Consulte Como configurar solicitações de aquecimento.
Exemplo:

inbound_services:
  - mail
  - warmup
instance_class

Opcional. A classe de instância deste serviço.

Os seguintes valores estão disponíveis dependendo do escalonamento do serviço:

Escalonamento automático
F1, F2, F4, F4_1G
Padrão: F1 será atribuído se nenhuma classe de instância for especificada com o elemento automatic_scaling.
Escalonamento básico e manual
B1, B2, B4, B4_1G, B8
Padrão: B2 será atribuído se nenhuma classe de instância for especificada com o elemento basic_scaling ou manual_scaling.

Observação: se instance_class estiver definido como F2 ou superior, será possível otimizar as instâncias configurando max_concurrent_requests com um valor acima de 10, que é o padrão. Para encontrar o valor ideal, aumente gradualmente e monitore o desempenho do aplicativo.

libraries

Opcional. O ambiente de execução do Python 2.7 inclui algumas bibliotecas de terceiros. Algumas estão disponíveis por padrão. Outras estão disponíveis apenas quando configuradas. Indique qual versão você quer usar especificando os valores name e version.


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

Quando você especifica latest, o SDK determina a versão mais recente da biblioteca no momento da implantação. Depois de implantada, a versão da biblioteca não será alterada. A única maneira de receber uma versão diferente da biblioteca é implantar novamente.

Se você está desenvolvendo um aplicativo que ainda não tem usuários: não é necessário rastrear novas versões. Mas se o aplicativo estiver sendo usado ativamente, cuidado. Talvez você se surpreenda ao constatar que ele começou a usar uma nova versão de biblioteca não compatível com versões anteriores.

Para ver uma lista das bibliotecas de terceiros incluídas, consulte Bibliotecas de terceiros. É possível usar bibliotecas de terceiros puramente em Python instalando-as em um diretório local.

Se você estiver usando o ambiente flexível, consulte Como usar bibliotecas do Python no ambiente flexível.

module

Observação: os módulos agora são denominados serviços.

Para gerenciar seu app com a ferramenta gcloud, use oelemento service.

Para usar a ferramenta appcfg, é necessário declarar os elementos service em arquivos app.yaml como módulos, por exemplo:


module: service-name

Obrigatório ao criar um serviço. Opcional para o serviço default. É necessário que todos os serviços e versões tenham um nome. Esse nome pode conter números, letras e hifens. O nome do serviço combinado com a versão não pode ter mais do que 63 caracteres nem iniciar ou terminar com 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.

runtime

Obrigatório. Nome do ambiente de execução usado pelo aplicativo. Para especificar o Python 2.7, use:


runtime: python27
service

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

Compatível apenas com a ferramenta gcloud ou plug-ins baseados no SDK do Cloud, como: gcloud app deploy.

Para usar a ferramenta appcfg, consulte módulo.

Obrigatório ao criar um serviço. Opcional para o serviço default. É necessário que todos os serviços e versões tenham um nome. Esse nome pode conter números, letras e hifens. O nome do serviço combinado com a versão não pode ter mais do que 63 caracteres nem iniciar ou terminar com 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.

Exemplo:

service: service-name

Observação: o comando gcloud app deploy é compatível com versões anteriores e aceita arquivos app.yaml atuais que incluam serviços declarados como módulos, por exemplo:


module: service-name
skip_files

Opcional. O elemento skip_files especifica que arquivos no diretório de aplicativos não serão enviados para o App Engine. O valor é uma expressão regular ou uma lista de expressões regulares. Qualquer nome de arquivo que corresponda a uma das expressões regulares é omitido na lista de arquivos para upload quando é feito o upload do aplicativo. Os nomes dos arquivos são relativos ao diretório do projeto.

O skip_files tem o seguinte padrão:


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

O padrão exclui arquivos de backup Emacs com nomes nos formatos #...# e ...~, arquivos .pyc e .pyo, arquivos em um diretório de controle de revisão RCS e arquivos ocultos Unix com nomes que começam com um ponto (.).

Para ampliar a lista de expressões regulares acima, copie e cole essa lista no app.yaml e adicione suas próprias expressões regulares. Por exemplo, para ignorar arquivos com nomes que terminam em .bak, além dos padrões, 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 linha a seguir às descritas anteriormente:


skip_files:
- logs/
threadsafe

Obrigatório. Configura o aplicativo para usar solicitações simultâneas. Se você estiver usando a biblioteca de linhas de execução do Python, os dados locais da linha de execução, conforme retornados por threading.local(), serão limpos após cada solicitação.


threadsafe: [true | false]

Observação: a diretiva threadsafe é necessária para aplicativos Python 2.7. threadsafe: true requer que todos os gerenciadores de script sejam WSGI. Ou seja, cada script precisa ser especificado em uma diretiva script: usando o caminho do módulo Python, com nomes de pacotes separados por pontos. O último componente de uma diretiva script: usando um caminho do módulo Python é o nome de uma variável global em service:. Essa variável precisa ser um aplicativo WSGI e geralmente é denominada app por convenção.

version

A abordagem recomendada consiste em remover o elemento version do arquivo app.yaml e, no lugar dele, usar uma sinalização de linha de comando para especificar o código da versão:

  • Para usar o comando gcloud app deploy, especifique a sinalização -v:
    
    gcloud app deploy -v [YOUR_VERSION_ID]
  • Para usar o comando appcfg.py update, especifique a sinalização -V:
    
    appcfg.py update -V [YOUR_VERSION_ID]

Para mais informações sobre como usar esses comandos, consulte Como implantar seu app.

Um identificador da versão do código do aplicativo que você implanta no App Engine.

O código da versão pode conter letras minúsculas, dígitos e hifens. Ele não pode começar com o prefixo ah-, e os nomes default e latest são reservados e não podem ser usados.

Observação: os nomes das versões têm que começar com uma letra, para distingui-las de instâncias numéricas que são sempre especificadas por um número. Isso evita a ambiguidade com URLs como 123.my-service.appspot.com, que pode ser interpretado de duas maneiras: se a versão "123" existir, o destino será a versão "123" do serviço fornecido. Se essa versão não existir, o destino será a instância número 123 da versão padrão do serviço.

Cada versão de um aplicativo retém sua própria cópia do app.yaml. Quando um aplicativo é enviado, a versão mencionada no arquivo app.yaml enviado é a versão que foi criada ou substituída durante o envio. Um administrador pode alterar qual versão do aplicativo está exibindo o tráfego usando o Console do Google Cloud Platform. Além disso, ele também pode testar outras versões antes de configurá-las para receber o tráfego.

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 totalmente qualificado de um conector no campo name:


vpc_access_connector:
  name: "projects/[PROJECT_ID]/locations/[REGION]/connectors/[CONNECTOR_NAME]"

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

Elemento handlers

O elemento handlers é obrigatório no arquivo de configuração app.yaml. Ele contém uma lista de padrões de URL e descrições de como eles serão processados. O App Engine pode processar URLs executando o código do aplicativo ou exibindo arquivos estáticos enviados com o código, como imagens, CSS ou JavaScript.

Os padrões são avaliados na ordem em que aparecem no arquivo app.yaml, de cima para baixo. O primeiro mapeamento com padrão que corresponde ao URL é usado para processar a solicitação.

A tabela a seguir lista os subelementos do elemento handlers que controlam o comportamento de scripts, arquivos e diretórios estáticos e outras configurações.

Elemento Descrição
application_readable Opcional. Booleano. Por padrão, os arquivos declarados em gerenciadores de arquivos estáticos são enviados como dados estáticos e são exibidos somente para usuários finais. Eles não podem ser lidos no aplicativo. Se este campo for definido como verdadeiro, os arquivos também serão enviados como dados de código para que possam ser lidos no aplicativo. Ambos os uploads são cobrados de acordo com o código e as cotas de recursos de armazenamento de dados estáticos.
auth_fail_action

Opcional. Descreve a ação realizada quando o elemento login é especificado para um gerenciador e o usuário está desconectado. Ele tem dois valores possíveis:

redirect
Padrão. O usuário é redirecionado para a página de login do Google ou /_ah/login_required se a autenticação OpenID for usada. O usuário é redirecionado novamente para o URL do aplicativo depois de fazer login ou de criar uma conta.
unauthorized
A solicitação é rejeitada com um código de status HTTP 401 e uma mensagem de erro.

Se um aplicativo precisar de um comportamento diferente, o próprio aplicativo poderá implementar o processamento dos logins de usuário. Consulte a API Users para mais informações.

O exemplo a seguir requer um login no diretório /profile/ e um login de administrador no /admin/:


handlers:
- url: /profile/.*
  script: user_profile.app
  login: required

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

- url: /.*
  script: welcome.app

É possível configurar um gerenciador para recusar o acesso a URLs protegidos quando o usuário não tiver feito login, em vez de redirecionar o usuário para a página de login, adicionando auth_fail_action: unauthorized à configuração do gerenciador:


handlers:
- url: /secure_api/.*
  script: api_handler.app
  login: required
  auth_fail_action: unauthorized
expiration Opcional. É recomendável que a duração de um arquivo estático exibido por este gerenciador seja armazenada em cache por proxies e navegadores da Web. O valor é uma sequência 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 para quatro dias e cinco horas após o arquivo ser solicitado pela primeira vez. Se omitido, o default_expiration do aplicativo é usado. Consulte Expiração do cache estático para mais detalhes.
http_headers

Opcional. Defina cabeçalhos HTTP para ver respostas dos gerenciadores de diretório ou arquivo estático. Se você precisar definir cabeçalhos HTTP nos gerenciadores de script, faça isso no código do aplicativo.

Exemplo

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

Suporte ao CORS

Este recurso é importante para permitir o compartilhamento de recursos entre origens (CORS, na sigla em inglês), como o acesso aos arquivos hospedados por outro aplicativo do App Engine.

Por exemplo, um aplicativo de jogo mygame.appspot.com que acesse os recursos hospedados por myassets.appspot.com. No entanto, se mygame tentar fazer uma XMLHttpRequest JavaScript para myassets, ele não terá êxito a menos que o gerenciador de myassets retorne um cabeçalho de resposta Access-Control-Allow-Origin: contendo o valor http://mygame.appspot.com.

Para que o gerenciador de arquivo estático retorne esse valor de cabeçalho de resposta solicitado, realize as ações a seguir:


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

Observação: para permitir que todos acessem os recursos, use o caractere curinga '*' em vez de http://mygame.appspot.com.

login

Opcional. Determina se o gerenciador de URL exige que o usuário faça login. Este elemento tem três valores possíveis:

optional
Padrão. Não requer que o usuário faça login.
required
Se o usuário tiver feito login, o gerenciador prosseguirá normalmente. Caso contrário, a ação determinada em auth_fail_action será executada.
admin
Assim como em required, auth_fail_action será executado se o usuário não tiver feito login. Além disso, se o usuário não for administrador do aplicativo, ele receberá uma mensagem de erro, seja qual for a configuração de auth_fail_action. Se o usuário for um administrador, o gerenciador prosseguirá.

Quando um gerenciador de URL com uma configuração de login diferente de optional corresponde a um URL, o gerenciador inicialmente verifica se o usuário fez login no aplicativo usando a opção de autenticação. Caso contrário, por padrão, o usuário será redirecionado para a página de login. Também é possível usar auth_fail_action a fim de configurar o app para recusar as solicitações de um gerenciador de usuários que não estejam devidamente autenticados, em vez de redirecioná-los à página de login.

Observação: a restrição de login para admin também é atendida em solicitações internas com cabeçalhos especiais X-Appengine apropriados configurados pelo App Engine. Por exemplo, as tarefas programadas do cron atendem à restrição de admin, porque o App Engine define um cabeçalho HTTP X-AppEngine-Cron: true nas respectivas solicitações. No entanto, as solicitações não cumprem a restrição de login required porque as tarefas cron programadas não são executadas para um usuário qualquer.

mime_type

Opcional. Se especificado, todos os arquivos exibidos por este gerenciador serão exibidos usando o tipo MIME especificado. Se não especificado, o tipo MIME de um arquivo será derivado da extensão do nome do arquivo. Se for feito upload do mesmo arquivo com várias extensões, a extensão resultante poderá depender da ordem em que os uploads ocorreram.

Para mais informações sobre os possíveis tipos de mídia MIME, consulte o site sobre os tipos de mídia IANA MIME (em inglês)

redirect_http_response_code

Opcional. redirect_http_response_code é usado com a configuração secure para definir o código de resposta do HTTP retornado na realização de um redirecionamento definido pela configuração de secure. O elemento redirect_http_response_code tem os seguintes valores possíveis:

301
Código de resposta de movido permanentemente.
302
Código de resposta de encontrado.
303
Código de resposta de ver outro.
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 a solicitação de um usuário for redirecionada, o código de status do HTTP será definido como o valor do parâmetro redirect_http_response_code. Se o parâmetro não estiver presente, será retornado 302.

script

Opcional. Especifica o caminho para o script a partir do diretório raiz do aplicativo:


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: precisa ser um caminho de importação do Python. Por exemplo, package.module.app, que aponta para um aplicativo WSGI. O último componente de uma diretiva script: usando um caminho do módulo Python é o nome de uma variável global no módulo. Essa variável precisa ser um aplicativo WSGI e geralmente é denominada app por convenção.

Observação: assim como no caso de uma instrução import do Python, cada subdiretório que seja um pacote precisará conter um arquivo denominado __init__.py.

secure Opcional. Qualquer gerenciador de URL pode usar a configuração secure, incluindo gerenciadores de script e de arquivos estáticos. O elemento secure tem os seguintes valores possíveis:
optional
Tanto solicitações HTTP como HTTPS com URLs que correspondem ao gerenciador são bem-sucedidas sem redirecionamentos. O aplicativo pode examinar a solicitação para determinar qual protocolo foi usado e responder de acordo com essa informação. Este é o padrão quando secure não é fornecido para um gerenciador.
never
As solicitações para um URL que correspondem a este gerenciador e usam HTTPS são redirecionadas automaticamente para o URL equivalente do HTTP. Quando a solicitação HTTPS de um usuário é redirecionada para ser uma solicitação HTTP, os parâmetros da consulta são removidos da solicitação. Isso evita que um usuário envie acidentalmente dados de consulta destinados a uma conexão segura por meio de uma conexão não segura.
always
As solicitações para um URL que correspondem a esse gerenciador e que não usam HTTPS são redirecionadas automaticamente 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 da Web de desenvolvimento não é compatível com conexões HTTPS. Ele ignora o parâmetro secure, então caminhos feitos para uso com HTTPS podem ser testados usando conexões HTTP regulares com o servidor da Web para desenvolvimento.

Para direcionar uma versão específica do aplicativo usando o domínio "appspot.com", substitua os pontos que geralmente separam os componentes do subdomínio do URL pela string "-dot-". Por exemplo:


https://[VERSION_ID]-dot-[YOUR_PROJECT_ID].appspot.com

Para usar domínios personalizados com HTTPS, primeiro é preciso ativar e configurar certificados SSL para esse domínio.

O login e o logout das contas do Google sempre são realizados por meio de uma conexão segura, sem relação com a configuração dos URLs do aplicativo.

static_dir

Opcional. O caminho para o diretório que contém os arquivos estáticos, do diretório raiz do aplicativo. Tudo depois do fim do padrão url correspondente é anexado ao static_dir para formar o caminho completo para o arquivo solicitado.

Cada arquivo no diretório estático é exibido pelo MIME que corresponde à própria extensão de nome de arquivo, a menos que seja modificado pela configuração mime_type do diretório. Todos os arquivos no diretório específico são enviados como arquivos estáticos, e nenhum deles pode ser executado como script.

Todos os arquivos neste diretório são carregados com seu aplicativo como arquivos estáticos. No App Engine, os arquivos estáticos são armazenados e exibidos separadamente dos arquivos do aplicativo. Por padrão, os arquivos estáticos não estão disponíveis no sistema de arquivos do app. Para alterar essa configuração, defina a opção application_readable como "true".

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 gerenciador de padrão de arquivo estático associa um padrão de URL com caminhos para arquivos estáticos enviados com o aplicativo. A expressão regular do padrão de URL pode definir os agrupamentos de expressões regulares a serem usados na construção do caminho do arquivo. Use isso em vez de static_dir para mapear para arquivos específicos em uma estrutura de diretório sem mapear todo o diretório.

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 exibe arquivos estáticos separadamente dos arquivos do aplicativo. Por padrão, os arquivos estáticos não estão disponíveis no sistema de arquivos do aplicativo. Para alterar essa configuração, defina a opção application_readable como "true".

Os arquivos estáticos não podem ser iguais aos arquivos do código do aplicativo. Se um caminho de arquivo estático corresponder ao caminho para um script usado em um gerenciador dinâmico, o script não ficará disponível para o gerenciador dinâmico.

upload

Opcional. Uma expressão regular que corresponde aos caminhos de arquivo para todos os arquivos que serão referenciados por este gerenciador. Isso é necessário porque o gerenciador não pode determinar quais arquivos no diretório do aplicativo correspondem aos padrões de url e static_files específicos. Os arquivos estáticos são enviados e processados separadamente dos arquivos de aplicativos. No exemplo acima, é possível usar o seguinte padrão de upload: archives/(.*)/items/(.*)

url

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

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

static_dir
Usa um prefixo de URL. O padrão expresso regular não pode conter agrupamentos quando usado com o elemento static_dir. Todos os URLs iniciados por esse prefixo são processados por este gerenciador, usando a porção do URL após o prefixo como parte do caminho do arquivo.
static_files
Um gerenciador de padrão de arquivo estático associa um padrão de URL com caminhos para arquivos estáticos enviados com o aplicativo. A expressão regular do padrão de URL pode definir agrupamentos de expressões regulares a serem usados na construção do caminho do arquivo. É possível usar isso em vez de static_dir para mapear para arquivos específicos em uma estrutura de diretório sem mapear todo o diretório.

Como escalonar elementos

Para saber mais sobre o escalonamento de aplicativos do App Engine, consulte Como escalonar instâncias dinâmicas.

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

Elemento Descrição
automatic_scaling

Opcional. O escalonamento automático é esperado por padrão com uma classe de instância padrão de F1, a menos que especificado o contrário.

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

Este elemento pode conter os seguintes elementos:

target_cpu_utilization
Opcional. Especifique um valor entre 0,5 e 0,95. O padrão é 0.6.

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 appcfg do SDK do App Engine para Python 2 na implantação, não será possível usar esse parâmetro no app.yaml. Em vez disso, defina o parâmetro conforme descrito em Como configurar parâmetros de escalonamento automático no API Explorer ou usando a API Admin do App Engine.

target_throughput_utilization
Opcional. Especifique um valor de 0,5 a 0,95. O padrão é 0.6.

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

Importante: se você usar o appcfg do SDK do App Engine para Python 2 na implantação, não será possível usar esse parâmetro no app.yaml. Em vez disso, defina o parâmetro conforme descrito em Como configurar parâmetros de escalonamento automático no API Explorer ou usando a API Admin do App Engine.

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

Este parâmetro especifica o número máximo de instâncias a serem criadas pelo App Engine para esta versão do módulo, Isso é útil para limitar os custos de um módulo.

Importante: se você usar o appcfg do SDK do App Engine para Python 2 na implantação, não será possível usar esse parâmetro no app.yaml. Em vez disso, defina o parâmetro conforme descrito em Como configurar parâmetros de escalonamento automático no 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 exibem o tráfego quando as solicitações chegam e continuam a exibir 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 o appcfg do SDK do App Engine para Python 2 na implantação, não será possível usar esse parâmetro no app.yaml. Em vez disso, defina o parâmetro conforme descrito em Como configurar parâmetros de escalonamento automático no 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 que o programador gere uma nova instância (padrão: 10, máximo: 80).

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

Se esta configuração for muito alta, poderá ocorrer aumento na latência da API. 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 estiver definido como F2 ou superior, será possível otimizar as instâncias configurando max_concurrent_requests com um valor acima de 10, que é o padrão. Para encontrar o valor ideal, aumente gradualmente e monitore o desempenho do aplicativo.

max_idle_instances

Opcional. O número máximo de instâncias ociosas que o App Engine precisa manter para esta versão. Especifique um valor de 1 a 1000 ou automatic. O valor padrão é automatic. Lembre-se:

  • 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 menores. 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. Quando esse limite é atingido, o serviço aumenta o número de instâncias. O valor padrão é 30ms.

O App Engine pode criar uma instância a qualquer momento entre o horário especificado em min_pending_latency e max_pending_latency. Em outras palavras, o App Engine não criará uma instância para exibir uma solicitação pendente antes do horário especificado em min_pending_latency, mas criará uma instância depois que o valor de max_pending_latency for atingido.

  • 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.
  • Com um valor máximo alto, os usuários podem aguardar mais tempo para que as solicitações deles sejam atendidas (se houver solicitações pendentes e sem instâncias ociosas para exibi-las). No entanto, será mais barato executar o aplicativo.
min_idle_instances

O número de instâncias que serão mantidas em execução e ficarão prontas para exibir o tráfego. Você é cobrado pelo número de instâncias especificadas, independentemente de elas receberem tráfego ou não. Essa configuração é aplicável 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 às solicitações recebidas. Você é cobrado pelo número de instâncias especificado, independentemente de elas processarem 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, será preciso testar o aplicativo e o volume de tráfego esperado.

min_pending_latency

O mínimo de tempo que o App Engine permite que uma solicitação aguarde na fila pendente antes de iniciar uma nova instância para processá-la. Quando esse limite é atingido, o serviço diminui o número de instâncias. O valor padrão é 30ms.

  • 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 execução, mas aumenta o tempo de espera dos usuários para que as solicitações sejam exibidas.
Exemplo

service: my-service
runtime: python27
api_version: 1
instance_class: F2
automatic_scaling:
  target_cpu_utilization: 0.65
  min_instances: 5
  max_instances: 100
  min_pending_latency: 30ms  # default value
  max_pending_latency: automatic
  max_concurrent_requests: 50
basic_scaling

Opcional. O elemento basic_scaling define o número de instâncias de um serviço.

Este elemento pode conter os seguintes elementos:

idle_timeout
Opcional. A instância encerrará esse período depois que receber a última solicitação. O padrão é cinco minutos (5m).
max_instances
Obrigatório. O número máximo de instâncias a serem criadas pelo App Engine para esta versão do serviço, que é útil para limitar os custos de um serviço.
Exemplo

service: my-service
runtime: python27
api_version: 1
instance_class: B8
basic_scaling:
  max_instances: 11
  idle_timeout: 10m
manual_scaling

Opcional. O elemento manual_scaling permite o escalonamento manual de um serviço e define o número de instâncias de um serviço.

Este elemento pode conter os seguintes elementos:

instances
O número de instâncias a serem atribuídas ao serviço no início.
Exemplo

service: my-service
runtime: python27
api_version: 1
instance_class: B8
manual_scaling:
  instances: 5

Expiração do cache estático

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

Para definir um período de armazenamento em cache padrão global para todos os gerenciadores de arquivos estáticos de um aplicativo, inclua o elemento de nível superior default_expiration. Também é possível configurar uma duração de cache para gerenciadores de arquivos estáticos específicos.

O prazo de validade 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 prazo de validade 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 prazo de validade padrão de 10 minutos é apropriado.

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Ambiente padrão do App Engine para Python 2