app.yaml 参考

您可以在 app.yaml 文件中配置 App Engine 应用的设置。此文件指定了网址路径与请求处理程序和静态文件的对应关系。app.yaml 文件还包含与应用代码有关的信息,例如运行时和最新版本标识符。

应用中的每项服务都有专属 app.yaml 文件,该文件充当其部署的描述符。您必须先为 default 服务创建 app.yaml 文件,然后才能为应用中的其他服务创建和部署 app.yaml 文件。

目录结构

每个服务的根目录中必须有一个 app.yaml 文件。如需详细了解如何在应用中构建多个服务,请参阅在 App Engine 中构建网络服务

示例

下面是 Python 应用的 app.yaml 文件示例:

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

script: 指令可以包含以 .py 结尾的文件路径或由点号分隔软件包名称的 Python 模块路径,前者意味着脚本使用 CGI,后者意味着脚本使用 WSGI。

语法

app.yaml 的语法采用 YAML 格式

YAML 格式支持注释。系统会忽略以井号 (#) 字符开头的行:

# This is a comment.

网址和文件路径模式使用 POSIX 扩展正则表达式语法,但整理元素和排序规则类除外。支持对分组匹配项的反向引用(例如 \1),另外还支持以下 Perl 扩展:\w \W \s \S \d \D

运行时和应用元素

元素 说明
application

推荐的方法是从 app.yaml 文件中移除 application 元素,并改用命令行标志来指定您的应用 ID:

  • 如需使用 gcloud app deploy 命令,您必须指定 --project 标志:
    
    gcloud app deploy --project [YOUR_PROJECT_ID]
  • 如需使用 appcfg.py update 命令,请指定 -A 标志:
    
    appcfg.py update -A [YOUR_PROJECT_ID]

如需详细了解如何使用这些命令,请参阅部署您的应用

应用 ID 是您在 Google Cloud Platform Console 中创建应用时指定的 GCP Console 项目 ID。

api_version

必需。您的应用使用的给定运行时环境中的 API 版本。

当 Google 宣布支持新版本的运行时环境的 API 时,您部署的应用将继续使用编写此应用时所用的 API。要将应用升级到新版本的 API,请更改此值,然后将应用重新部署到 App Engine。如果指定值 1,则每次部署该应用时都会使用支持的最新运行时环境(当前为 )。

此时,App Engine 有一个版本的 python27 运行时环境:1

auto_id_policy 可选。如果您正在自动设置实体标识符,则可以通过设置自动 ID 政策来更改所使用的方法。以下是有效选项:
default
默认值。使用分散的自动 ID,这些 ID 是分布均匀的大整数,小到可以由 64 位浮点数表示。
legacy
未来版本将弃用旧选项,并最终移除这些选项。如需了解详情,请参阅宣布此变化的博文
builtins

可选。Python SDK 为常见的应用功能提供了许多内置处理程序。builtins 指令允许您在 app.yaml 中包含特定处理程序。

以下内置处理程序可供您使用:

appstats
使用 /_ah/stats/ 启用您可用于衡量应用性能的 Appstats。要使用 Appstats,您还需要安装事件记录器
deferred
使用 /_ah/queue/deferred 启用延迟处理程序。此内置功能允许开发人员使用 deferred.defer() 来简化任务队列任务的创建。另请参阅使用延迟库的后台工作
remote_api
使用 /_ah/remote_api/ 启用 remote_api builtin。此内置功能允许具有适当凭据的远程应用远程访问数据存储区。
示例:

builtins:
- deferred: on
- appstats: on

builtins 指令是 includes 指令的特殊实例。在 Python 中,每个 builtin 指令都等效于带有扩展路径的 includes 指令。例如:


builtins:
- name: on

等效于:


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

当您使用 app.yaml 文件中的 builtins 时,内置 include.yaml 文件定义的处理程序会替换您在 app.yaml 文件中定义的处理程序。但是,如果包含随后使用 builtinsincludes 的文件,这些处理程序将按照 include 层次结构的顺序添加。换句话说,要先添加“父级”include 的处理程序,再添加“子级”include 的 builtin 等等。

例如,考虑下面采用内置 appstats 处理程序的 app.yaml


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

处理程序的结果列表是:


[/_ah/stats, /.*]

如果 app.yaml 使用 include 指令:


includes:
- included.yaml

并且 included.yaml 文件使用 builtins


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

现在,处理程序的结果列表是:


[/.*, /_ah/stats]

替换 .yaml 文件中 builtins 子句的顺序不会改变行为。

default_expiration

可选。为应用的所有静态文件处理程序设置全局默认缓存期限。您还可以配置特定静态文件处理程序的缓存时长。该值是一个由数字和单位组成并以空格分隔的字符串,其中,单位可以是 d(表示天)、h(表示小时)、m(表示分钟)和 s(表示秒)。例如,"4d 5h" 表示将缓存到期时间设置为首次请求文件后的 4 天 5 小时。如果省略此元素,生产服务器会将到期时间设置为 10 分钟。

示例:

runtime: python27
api_version: 1
threadsafe: true

default_expiration: "4d 5h"

handlers:
# ...

如需了解详情,请参阅静态缓存到期

env_variables

可选。您可以在 app.yaml 文件中定义环境变量,使这些变量可用于您的应用。

GAE 作为前缀的环境变量会保留给系统使用,因此不允许在 app.yaml 文件中使用。

这些变量可在 os.environ 字典中找到:

env_variables:
  DJANGO_SETTINGS_MODULE: 'myapp.settings'
error_handlers

可选。用于配置针对不同错误类型返回的自定义错误页面。

此元素可以包含以下元素:

error_code
可选。error_code 可以为以下其中一项:
over_quota
表示应用已超出资源配额
dos_api_denial
表示请求已被应用的 DoS 防护配置阻止。
timeout
最后期限已到而应用未响应时提供。

error_code 是可选元素;如果省略此元素,则指定文件便会成为应用的默认错误响应。

file
每个 file 条目都表示一个为代替一般错误响应而传送的静态文件。如果指定的 file 元素没有对应的 error_code 元素,则此静态文件将成为应用的默认错误页面。 自定义错误数据不得超过 10 千字节。
示例

error_handlers:
  - file: default_error.html

  - error_code: over_quota
    file: over_quota.html
handlers

必需。网址格式及其处理方式说明的列表。App Engine 可以通过执行应用代码,或通过传送与代码一起上传的静态文件(例如图片、CSS 或 JavaScript)来处理网址。

请参阅处理程序和子元素语法

includes

可选。includes 指令允许您包含应用中所有库或服务的配置文件。例如,您可以包含用户管理库,如下所示:


includes:
- lib/user_admin.yaml

App Engine 按以下顺序解析所含路径:

  • 工作目录的绝对路径或相对路径。指定路径将解析到某个文件。
  • 应用目录的相对路径(也称为基本路径)。基本路径和路径将解析至某个文件。
  • 包含当前文件的文件的相对路径。引用文件的位置以及包含路径将解析到所含的文件。

如果 include 指令指定一个目录,则 App Engine 会在该目录中查找名为 include.yaml的文件。如果 include 指令为文件,则包含该特定文件。使用 includes 只能从目标文件中检索以下类型的指令(如果存在):

如果 app.yaml 中没有明确的列表,包含的 skip_files 模式将添加到那些在包含 app.yaml 中的相关模式或者默认列表中。请注意,skip_files 会比较这些绝对路径。

inbound_services

可选。应用必须先启用这些服务,然后才能接收入站请求。要为 Python 应用启用该服务,您可以在 app.yaml 文件中包含 inbound_services 部分。

您可以使用下列入站服务:

mail
允许您的应用接收邮件
warmup
启用预热请求。请参阅配置预热请求
示例:

inbound_services:
  - mail
  - warmup
instance_class

可选。此服务的实例类别

根据服务的扩缩设置,可用的值如下:

自动扩缩
F1F2F4F4_1G
默认值:如果未指定实例类别,但指定了 automatic_scaling 元素,则分配 F1
基本扩缩和手动扩缩
B1B2B4B4_1GB8
默认值:如果未指定实例类别,但指定了 basic_scaling 元素或 manual_scaling 元素,则分配 B2

注意:如果 instance_class 设置为 F2 或更高级别,您可以将 max_concurrent_requests 设置为大于 10(默认值)的值来优化实例。要找到最佳值,请逐渐增加上述值并监控应用的性能。

libraries

可选。Python 2.7 运行时包含一些第三方库。其中一些库默认可用;另一些只有配置后才可用。您可以通过指定 nameversion 值来指定要使用的哪个版本。


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

请注意,您指定 latest 后,SDK 会在部署时确定最新的库版本。部署后,不能再更改库版本。获取不同库版本的唯一方法是再次部署。

如果您正在开发尚未有任何用户的应用,则不需要跟踪新版本。但是,如果您的应用用户活跃度非常高,注意:您可能非常惊讶,您的应用开始使用新的不能向后兼容的库版本。

如需了解所包含的第三方库的列表,请参阅第三方库。您若要使用其他纯 Python 第三方库,可以通过将其安装到本地目录中来实现。

如果您正在使用柔性环境,请参阅在柔性环境中使用 Python 库

module

注意:模块现在名为服务。

如需使用 gcloud 工具管理应用,请改用 service 元素。

如需使用 appcfg 工具,必须在 app.yaml 文件中将服务声明为模块,例如:


module: service-name

如果创建服务,则是必需的。对于 default 服务为可选。每项服务和每个版本都必须有自己的名称。名称可以包含数字、字母和连字符。服务和版本的总长度不能超过 63 个字符,且首尾不能使用连字符。请为每项服务和每个版本选择唯一的名称。服务名称和版本名称不得重复。

runtime

必需。应用使用的运行时环境的名称。如需指定 Python 2.7,请使用:


runtime: python27
service

服务以前称为模块。

仅受 gcloud 工具或基于 Cloud SDK 的插件(例如 gcloud app deploy)支持。

如需使用 appcfg 工具,请参阅模块

对于服务的创建是必需的。对于 default 服务,此为可选元素。每项服务和每个版本都必须有自己的名称。名称可以包含数字、字母和连字符。服务和版本的总长度不能超过 63 个字符,且首尾不能使用连字符。请为每项服务和每个版本选择唯一的名称。服务名称和版本名称不得重复。

示例:

service: service-name

注意gcloud app deploy 命令向后兼容,并支持现有的 app.yaml 文件,这些文件包含声明为模块的服务,例如:


module: service-name
skip_files

可选。skip_files 元素指定应用目录中的哪些文件不上传到 App Engine。该值可能是正则表达式,也可能是正则表达式的列表。上传应用时,与正则表达式匹配的所有文件名都将从要上传的文件列表中删除。文件名相对于项目目录。

skip_files 具有以下默认值:


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

默认格式排除了名称格式为 #...#...~ 的 Emacs 备份文件、.pyc.pyo 文件、RCS 修订控制目录中的文件以及名称以点 (.) 开头的 Unix 隐藏文件。

要扩展上述正则表达式列表,请复制上面的列表并将其粘贴到 app.yaml,然后添加您自己的正则表达式。例如,要跳过名称以 .bak 结尾的文件以及默认模式,请为 skip_files 添加如下条目:


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

要跳过整个目录,请将目录名称添加到列表中。例如,要跳过名为 logs 的目录,请将以下行添加到上述内容:


skip_files:
- logs/
threadsafe

必需。将您的应用配置为使用并发请求。如果使用 Python 的线程库,每次请求后,都会清除 threading.local() 返回的线程本地数据。


threadsafe: [true | false]

注意:threadsafe 指令是 Python 2.7 应用所必需的。 threadsafe: true 要求所有脚本处理程序都是 WSGI 处理程序。也就是说,必须在使用 Python 模块路径的 script: 指令中指定每个脚本,且此模块路径中的软件包名称要用点号分隔开。使用 Python 模块路径的 script: 指令的最后部分是 service: 中全局变量的名称,该变量必须是 WSGI 应用,按照惯例,通常被称为 app

version

推荐的方法是从 app.yaml 文件中移除 version 元素,并改用命令行标志指定您的版本 ID:

  • 如需使用 gcloud app deploy 命令,请指定 -v 标志:
    
    gcloud app deploy -v [YOUR_VERSION_ID]
  • 如需使用 appcfg.py update 命令,请指定 -V 标志:
    
    appcfg.py update -V [YOUR_VERSION_ID]

如需详细了解如何使用这些命令,请参阅部署您的应用

您部署到 App Engine 的应用代码版本的标识符。

版本 ID 可以包含小写字母、数字和连字符,不能以前缀 ah- 开头;并且名称 defaultlatest 已被保留,不能使用。

注意:版本名称应以字母开头,以便与始终由数字指定的数字实例区分开来。这避免了像 123.my-service.appspot.com 等网址的歧义,因为此网址有两种解读方式:如果存在版本“123”,则目标将是给定服务的版本“123”;如果该版本不存在,则目标将是服务的默认版本的实例编号 123。

每个版本的应用都保留自己的 app.yaml 副本。上传应用后,上传的 app.yaml 文件中提及的版本即是通过上传创建或替换的版本。管理员可以使用 Google Cloud Platform Console 更改由哪个版本的应用传送流量,还可以在配置其他版本接收流量前先测试相应版本

vpc_access_connector

可选。将应用配置为使用 Serverless VPC Access 连接器,使应用能够将请求发送到 VPC 网络中的内部资源。在 name 字段中指定连接器的完全限定名称:


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

如需了解详情,请参阅连接到 VPC 网络中的内部资源

处理程序元素

handlers 元素是 app.yaml 配置文件中的必需元素。该元素提供了网址格式的列表及其处理方式的说明。App Engine 可以通过执行应用代码,或通过提供与代码一起上传的静态文件(例如图片、CSS 或 JavaScript)来处理网址。

格式评估按照格式在 app.yaml 文件中出现的顺序(即从上到下)依次进行。格式与网址匹配的第一个映射将用于处理请求。

下表列出了控制脚本、静态文件、静态目录和其他设置行为的 handlers 元素的子元素。

元素 说明
application_readable 可选。布尔值。默认情况下,静态文件处理程序中声明的文件将作为静态数据上传,并仅提供给最终用户。应用无法读取这些文件。如果此字段设置为 true,则这些文件也会作为代码数据上传,这样您的应用可以读取它们。系统会按照您的代码和静态数据存储资源配额对这两次上传计费。
auth_fail_action

可选。说明为处理程序指定 login 元素且用户未登录时所执行的操作。有两个可能的值:

redirect
默认值。用户会被重定向到 Google 登录页面,或者如果使用 OpenID 身份验证,则被重定向至 /_ah/login_required。用户在登录或创建帐号后,会被重定向回应用的网址。
unauthorized
请求被拒绝,并返回 HTTP 401 状态代码和错误消息。

如果应用需要其他行为,则该应用自身可以实现对用户登录的处理方法。如需了解详情,请参阅用户 API

以下示例需要登录 /profile/ 目录,并以管理员身份登录 /admin/ 目录:


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

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

- url: /.*
  script: welcome.app

您可以在处理程序的配置中加入 auth_fail_action: unauthorized,以便将处理程序配置为拒绝未登录的用户访问受保护的网址,而不是将其重定向到登录页面:


handlers:
- url: /secure_api/.*
  script: api_handler.app
  login: required
  auth_fail_action: unauthorized
expiration 可选。网络代理和浏览器应缓存由此处理程序传送的静态文件的时长。该值是一个由数字和单位组成并以空格分隔的字符串,其中,单位可以是 d(表示天)、h(表示小时)、m(表示分钟)和 s(表示秒)。例如,"4d 5h" 表示将缓存到期时间设置为首次请求文件后的 4 天 5 小时。如果省略此元素,则系统会使用应用的 default_expiration。如需了解详情,请参阅静态缓存到期时间
http_headers

可选。您可以为静态文件或目录处理程序的响应设置 HTTP 标头。如果您需要在 script 处理程序中设置 HTTP 标头,则应该改为在应用的代码中执行此操作。

示例

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

CORS 支持

此功能的一个重要用途是支持跨域资源共享 (CORS),例如,访问由其他 App Engine 应用托管的文件。

例如,假设您有一个游戏应用 mygame.appspot.com 需访问由 myassets.appspot.com 托管的资源。但是,如果 mygame 尝试向 myassets 发出 JavaScript XMLHttpRequest,则除非 myassets 的处理程序返回一个包含 http://mygame.appspot.com 值的 Access-Control-Allow-Origin: 响应标头,否则尝试将失败。

下面演示了如何让静态文件处理程序返回这个必需的响应标头值:


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

注意:如果要让所有人都可访问您的资源,可以使用通配符 '*' 来代替 http://mygame.appspot.com

login

可选。确定网址处理程序是否要求用户登录。该元素有三个可能的值:

optional
默认值。不要求用户已登录。
required
如果用户已登录,则处理程序正常运行。否则,将执行 auth_fail_action 中指定的操作。
admin
required 一样,如果用户未登录,则执行 auth_fail_action。此外,如果用户不是应用的管理员,则无论 auth_fail_action 设置为何值,用户都会收到错误消息。如果用户是管理员,处理程序将继续运行。

如果 login 设置设为非 optional 值的网址处理程序与某个网址匹配,则处理程序首先会使用其身份验证选项检查用户是否已登录应用。如果用户未登录,则默认将其重定向到登录页面。您还可以使用 auth_fail_action 将应用配置为仅拒绝未正确进行身份验证的用户对处理程序的请求,而不是将用户重定向到登录页面。

注意:如果 App Engine 为内部请求设置了合适的 X-Appengine 特殊标头,该内部请求也满足 admin 登录限制。例如,cron 计划任务满足 admin 限制,因为 App Engine 为相应请求设置了 HTTP 标头 X-AppEngine-Cron: true。但是,这些请求并满足 required 登录限制,因为并非任何用户都可以运行 Cron 计划任务。

mime_type

可选。如果指定此元素,则由此处理程序传送的所有文件均将使用指定的 MIME 类型进行传送。如果未指定此元素,则文件的 MIME 类型将根据该文件的文件扩展名确定。如果使用多个扩展名上传相同的文件,则生成的扩展名可能取决于上传的顺序。

如需详细了解可能的 MIME 媒体类型,请参阅 IANA MIME 媒体类型网站

redirect_http_response_code

可选。redirect_http_response_codesecure 设置搭配使用,用于设置按照 secure 设置的配置执行重定向时返回的 HTTP 响应代码。 redirect_http_response_code 元素可用的值如下:

301
Moved Permanently 响应代码。
302
Found 响应代码。
303
See Other 响应代码。
307
Temporary Redirect 响应代码。
示例

handlers:
- url: /youraccount/.*
  script: accounts.app
  login: required
  secure: always
  redirect_http_response_code: 301

在系统将用户请求重定向时,会将 HTTP 状态代码设置为 redirect_http_response_code 参数的值。如果该参数不存在,系统将返回 302。

script

可选。指定从应用根目录到脚本的路径:


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

script: 指令必须是 python 导入路径,例如,指向 WSGI 应用的 package.module.app。使用 Python 模块路径的 script: 指令的最后部分是该模块中全局变量的名称,该变量必须是 WSGI 应用,按照惯例,通常被称为 app

注意:就像 Python import 语句一样,每个子目录都是一个软件包,必须包含名为 __init__.py 的文件。

secure 可选。任何网址处理程序都可以使用 secure 设置,包括脚本处理程序和静态文件处理程序。secure 元素可能有以下值:
optional
与处理程序相匹配的 HTTP 和 HTTPS 网址请求都会成功执行,而不会发生重定向。应用可以检查请求以确定请求使用了哪个协议,并相应地做出响应。如果没有为处理程序提供 secure,默认将使用此值。
never
与处理程序匹配且使用 HTTPS 的网址请求会被自动重定向到等效的 HTTP 网址。如果用户的 HTTPS 请求被重定向为 HTTP 请求,查询参数将会从该请求中移除。这可以防止用户意外地通过非安全连接提交本应通过安全连接传输的查询数据。
always
与此处理程序匹配的非 HTTPS 网址请求会自动重定向到路径相同的 HTTPS 网址。重定向时会保留查询参数。
示例

handlers:
- url: /youraccount/.*
  script: accounts.app
  login: required
  secure: always

开发网络服务器不支持 HTTPS 连接。它忽略 secure 参数,因此可以使用到开发网络服务器的常规 HTTP 连接测试专用于 HTTPS 的路径。

如需使用 appspot.com 网域定位应用的特定版本,请将英文句点(通常用来分隔网址的子网域组成部分)替换为字符串“-dot-”,例如:


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

要将自定义网域与 HTTPS 结合使用,您必须先为该网域激活并配置 SSL 证书

Google 帐号的登录和退出始终是通过安全连接执行的,与应用网址配置为何种格式无关。

static_dir

可选。应用根目录中包含静态文件的目录的路径。所匹配的 url 格式结尾字符后面的所有内容都会附加到 static_dir 中,以构成所请求文件的完整路径。

静态目录中的每个文件均使用与其文件扩展名相对应的 MIME 类型来传送,但此 MIME 类型被目录的 mime_type 设置替换的情况除外。指定目录中的所有文件都会作为静态文件上传,并且它们都不能作为脚本运行。

此目录中的所有文件都随应用一起作为静态文件上传。App Engine 将应用的文件与静态文件分开存储和提供。默认情况下,应用的文件系统中不提供静态文件。可以通过将 application_readable 选项设置为 true 来更改此设置。

示例:

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

可选。静态文件格式处理程序会将网址格式与随应用一并上传的静态文件的路径相关联。网址格式正则表达式可以定义用来构建文件路径的正则表达式分组。您可以使用该元素代替 static_dir,以映射到目录结构中的特定文件,而不是映射整个目录。

示例:

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)$
  # ...

App Engine 将应用的文件与静态文件分开存储和提供。默认情况下,应用的文件系统中不提供静态文件。可以通过将 application_readable 选项设置为 true 来更改此设置。

静态文件不能与应用代码文件相同。如果静态文件路径与动态处理程序中使用的脚本的路径匹配,则该动态处理程序将无法使用此脚本。

upload

可选。一个正则表达式,它会与将由此处理程序引用的所有文件的文件路径进行匹配。系统必须执行此操作,否则处理程序将无法确定应用目录中的哪些文件与指定的 urlstatic_files 格式相对应。静态文件与应用文件的上传和处理是分开进行的。上例可能使用以下 upload 格式:archives/(.*)/items/(.*)

url

handlers 下的必需元素。正则表达式形式的网址格式。表达式可以通过正则表达式反向引用包含可在脚本的文件路径中引用的分组。例如,/profile/(.*)/(.*) 将与网址 /profile/edit/manager 匹配,并将 editmanager 分别用作第一个和第二个分组。

与以下元素搭配使用时,此网址格式在行为上有一些差异:

static_dir
使用网址前缀。与 static_dir 元素搭配使用时,此正则表达式格式不应包含分组方式。以该前缀开头的所有网址都由此处理程序处理,且前缀后面的网址部分用作文件路径的一部分。
static_files
静态文件格式处理程序会将网址格式与随应用一并上传的静态文件的路径相关联。网址格式正则表达式可以定义用来构建文件路径的正则表达式分组。您可以使用该元素代替 static_dir,以映射到目录结构中的特定文件,而不是映射整个目录。

扩缩元素

如需详细了解 App Engine 应用如何扩缩,请参阅扩缩动态实例

下表列出了可供您用来指定如何扩缩应用的一些选项。

元素 说明
automatic_scaling

可选。除非另有说明,否则,系统默认采用自动扩缩,并以 F1 作为默认实例类别。

automatic_scaling 元素可设置服务的实例数、延迟时间和并发连接数上下限。

此元素可以包含以下元素:

target_cpu_utilization
可选。指定 0.5 至 0.95 之间的值。默认值为 0.6

此参数用来指定需要启动新实例来处理流量时的 CPU 使用率阈值。指定该参数有助于您在性能和费用之间取得平衡,较低的值意味着性能提升、费用增加,而较高的值则意味着性能下降、费用减少。例如,0.7 表示 CPU 使用率达到 70% 后会启动新实例。

重要提示:如果您使用 Python 版 App Engine SDK 中的 appcfg 进行部署,则无法在 app.yaml 中使用此参数,而是应按照在 API Explorer 中设置自动扩缩参数中的说明或者使用 App Engine Admin API 来设置此参数。

target_throughput_utilization
可选。指定 0.5 至 0.95 之间的值。默认值为 0.6

max_concurrent_requests 搭配使用,用于指定何时因并发请求而启动新实例。当并发请求数达到 max_concurrent_requeststarget_throughput_utilization 的乘积时,调度程序将启动一个新实例。

重要提示:如果您使用 Python 版 App Engine SDK 中的 appcfg 进行部署,则无法在 app.yaml 中使用此参数,而是应按照在 API Explorer 中设置自动扩缩参数中的说明或者使用 App Engine Admin API 来设置此参数。

max_instances
可选。指定 0 至 2147483647 之间的值,其中 0 表示停用该设置。

此参数用来指定 App Engine 可为此模块版本创建的最大实例数。这对限制模块费用非常有用。

重要提示:如果您使用 Python 版 App Engine SDK 中的 appcfg 进行部署,则无法在 app.yaml 中使用此参数,而是应按照在 API Explorer 中设置自动扩缩参数中的说明或者使用 App Engine Admin API 来设置此参数。

min_instances
可选。App Engine 可为此模块版本创建的最小实例数。这些实例在请求到达时处理流量,即便在必要时启动了其他实例来处理流量,这些实例也会继续处理流量。

指定 0 至 1000 之间的值。您可以将此参数的值设置为 0,以允许扩缩到 0 个实例,这样可以在未处理任何请求时降低费用。请注意,您需要为指定的实例数支付费用,无论这些实例是否接收流量。

重要提示:如果您使用 Python 版 App Engine SDK 中的 appcfg 进行部署,则无法在 app.yaml 中使用此参数,而是应按照在 API Explorer 中设置自动扩缩参数中的说明或者使用 App Engine Admin API 来设置此参数。

max_concurrent_requests

可选。在调度程序生成新实例之前,自动扩缩实例可以接受的并发请求数(默认值:10,最大值:80)。

target_throughput_utilization 一起用来指定何时因并发请求而启动新实例。当并发请求数达到 max_concurrent_requests 乘以 target_throughput_utilization 的值时,调度程序会启动一个新实例。

如果设置的值过高,您可能会遇到 API 延迟时间增加的情况。请注意,调度程序可能会在实际尚未达到最大请求数时就生成新实例。

注意:如果 instance_class 设置为 F2 或更高级别,您可以将 max_concurrent_requests 设置为大于 10(默认值)的值来优化实例。如需找到最佳值,请逐渐增加值,同时监控应用的性能。

max_idle_instances

可选。App Engine 应为此版本保留的最大空闲实例数。指定 1 至 1000 之间的值,或 automatic。默认值为 automatic。请注意以下几点:

  • 如果设置的最大值较高,那么当负载水平在峰值后恢复正常时,空闲实例数会较为平缓地逐渐减少。这有助于您的应用在请求负载发生波动期间保持稳定的性能,但也会增加负载繁重时段的空闲实例数(从而增加运行费用)。
  • 设置较低的最大值有助于保持较低的运行费用,但在负载水平波动期间可能会降低性能。

注意:当负载水平在峰值过后恢复到正常水平时,空闲实例数可能会暂时超出您指定的最大值。不过,对于这些多出的实例,您不需要支付费用。

max_pending_latency

在启动其他实例处理请求以减少等待延迟时间之前,App Engine 允许某请求在待处理队列中等待的最长时间。当达到此阈值时,即表示需要纵向扩容,这会导致实例数增加。默认值为 30ms

App Engine 会在 min_pending_latencymax_pending_latency 中指定的时间之间随时创建实例。换句话说,App Engine 不会在 min_pending_latency 中指定的时间之前创建实例来处理待处理请求,但会在达到 max_pending_latency 之后创建实例。

  • 设置较低的最大值意味着,App Engine 将更早地为待处理请求启动新实例,这有助于提高性能,但会增加运行费用。
  • 设置较高的最大值意味着,用户可能需要花费更长时间来等待其请求得到处理(如果有待处理请求且没有空闲实例来处理这些请求),不过,这有助于降低应用的运行费用。
min_idle_instances

保持运行并可用于处理流量的实例数。请注意,您需要为指定数量的实例支付费用,无论这些实例是否正在接收流量。此设置仅适用于接收最大部分流量的版本。请谨记以下内容:

  • 设置较低的最小值有助于在空闲期间降低您的运行费用,但也意味着在突然出现负载峰值时,可立即使用的实例数较少。
  • 设置较高的最小值有助于应用自如应对突然出现的请求负载峰值。App Engine 会保持运行该最小数量的实例来处理传入请求。您需要为指定的实例数支付费用,无论这些实例是否正在处理请求。要使此功能正常运行,您必须确保启用预热请求,并让您的应用处理预热请求。

    如果您设置了最小空闲实例数,那么等待延迟时间对应用性能的影响会比较小。由于 App Engine 保留有空闲实例,因此除非出现特别高的负载峰值,否则请求不可能进入待处理队列。您需要测试应用和预期流量,以确定要保留的理想实例数。

min_pending_latency

在启动新实例来处理请求之前,App Engine 允许请求在待处理队列中等待的最短时间。当达到此阈值时,即表示需要缩减,这会导致实例数减少。默认值为 30ms

  • 较低的最小值意味着,当所有现有实例都处于活跃状态时,请求在待处理队列中所花费的时间必定会更少。这有助于提高性能,但同时会增加应用的运行费用。
  • 设置较高的最小值意味着,如果所有现有实例都处于活跃状态,那么请求保持待处理状态的时间将会更长。这有助于降低运行费用,但会让用户花费更多时间来等待其请求得到处理。
示例

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

可选。basic_scaling 元素可设置服务的实例数。

此元素可以包含以下元素:

idle_timeout
可选。实例在收到最后一个请求后,在经过该值指定的一段时间后会关停。默认值为 5 分钟 (5m)。
max_instances
必需。App Engine 可为此服务版本创建的最大实例数。这对限制服务费用非常有用。
示例

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

可选。manual_scaling 元素用于为服务启用手动扩缩,以及设置服务的实例数。

此元素可以包含以下元素:

instances
在开始时分配给服务的实例数。
示例

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

静态缓存到期时间

除非另有说明,否则网络代理和网络浏览器会在限定时间内保留它们从网站加载的文件。

您可以通过包含顶级 default_expiration 元素,为应用的所有静态文件处理程序定义全局默认缓存期限。您还可以为特定的静态文件处理程序配置缓存时长

到期时间将在 Cache-ControlExpires HTTP 响应标头中发送,因此,用户的浏览器以及中间缓存代理服务器(如互联网服务提供商)很可能会缓存文件。在传输指定了到期时间的文件后,即使用户清除了自己的浏览器缓存,通常也无法将文件从中间缓存中清除。重新部署新版本的应用将不会重置任何缓存。因此,如果您打算修改静态文件,则应该设置较短的到期时间(不到一个小时)。在大多数情况下,默认的 10 分钟到期时间是合适的。

此页内容是否有用?请给出您的反馈和评价:

发送以下问题的反馈:

此网页
适用于 Python 2 的 App Engine 标准环境