App Engine app.yaml 参考文档

区域 ID

REGION_ID 是 Google 根据您在创建应用时选择的区域分配的缩写代码。此代码不对应于国家/地区或省，尽管某些区域 ID 可能类似于常用国家/地区代码和省代码。对于 2020 年 2 月以后创建的应用，REGION_ID.r 包含在 App Engine 网址中。对于在此日期之前创建的现有应用，网址中的区域 ID 是可选的。

详细了解区域 ID。

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

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

目录结构

如需详细了解如何在应用中设计多项服务的结构，请参阅在 App Engine 中设计 Web 服务的结构。

示例

以下是 Python 2 应用的 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]

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

应用 ID 是您在 Google Cloud 控制台中创建应用时指定的 Google Cloud 控制台项目 ID。
api_version

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

此字段在较新的 App Engine 运行时环境中已弃用。

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

目前，App Engine 有一个版本的 python27 运行时环境：1

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

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

此字段在 Python 3 运行时环境中已弃用。

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

appstats
启用 /_ah/stats/ 的 Appstats，您可将其用于衡量应用性能。为使用 Appstats，您还需要安装事件记录器。
deferred
启用 /_ah/queue/deferred 的 deferred 处理程序。此内置功能让开发者可以利用 deferred.defer() 来简化“任务队列”任务的创建。
remote_api
启用 /_ah/remote_api/ 的 remote_api 内置功能。此内置功能允许具有适当凭据的远程应用对数据存储区进行远程访问。
示例： 
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 文件中定义的处理程序。但是，如果您包含随后使用 builtins 或 includes 的文件，这些处理程序将按照 include 层次结构的顺序添加。换句话说，“父级”include 的处理程序会先添加，然后再添加“子级”include 的 builtin 等等。

例如，请考虑使用内置 appstats 处理程序的下列 app.yaml。 

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

处理程序的结果列表是：

[/_ah/stats, /.*]

如果 app.yaml 使用 includes 指令：

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 文件中定义环境变量供您的应用使用。请确保环境变量中的键与表达式“[a-zA-Z_][a-zA-Z0-9_]*”（以字母或“_”开头，后跟任何字母数字或“_”）匹配。

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

这些变量可在 os.environ 字典中找到： 
env_variables:
  DJANGO_SETTINGS_MODULE: "myapp.settings"
error_handlers

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

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

error_code
可选。error_code 可以是下列选项之一：
over_quota
表示应用已超出资源配额
timeout
如果截止时间已到而应用未响应，则提供此错误代码。

error_code 是可选的；如果省略，则指定文件便会成为应用的默认错误响应。

file
每个 file 条目都表示一个用于代替一般错误响应而传送的静态文件。如果指定不带相应 error_code 元素的 file 元素，则静态文件将作为应用的默认错误页面。自定义错误数据不得超过 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 按以下顺序解析所含路径：

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

如果 include 指令指定一个目录，则 App Engine 将在该目录中查找名为 include.yaml 的文件。如果 include 指令是一个文件，则会包含该特定文件。仅使用 includes 从目标文件（如有）中检索以下类型的指令：

包含的 skip_files 模式将添加到上一层级 app.yaml 中的模式，或者在 app.yaml 中没有显式列表的情况下添加到默认列表中。请注意，skip_files 会比较绝对路径。
inbound_services

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

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

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

可选。此服务的实例类。

根据服务的扩缩设置，可用的值如下：

自动扩缩
F1、F2、F4、F4_1G
默认值：F1

（可选）使用 automatic_scaling 元素更改自动扩缩的默认设置，例如最小和最大实例数、延迟时间和并发连接数。

注意：如果 instance_class 设置为 F2 或更高级别，您可以将 max_concurrent_requests 设置为大于 10（默认值）的值来优化实例。要确定最佳值，请逐渐增加值，同时监控应用的性能。

基本扩缩和手动扩缩
B1、B2、B4、B4_1G、B8
默认值：B2

基本实例类和手动实例类要求您指定 basic_scaling 元素或 manual_scaling 元素。
libraries

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

此字段在 Python 3 运行时环境中已弃用。

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

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

如果您正在开发尚未有任何用户的应用，则不需要跟踪新版本。但是，如果您的应用用户活跃度非常高，请注意：您可能会感到意外，因为您的应用开始使用不能向后兼容的新的库版本。

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

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

module

注意：模块现在已更名为服务。

如需使用 gcloud CLI 管理应用，请改用 service 元素。
runtime

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

runtime: python27
service

服务以前称为模块。

仅受 gcloud CLI 或基于 gcloud CLI 的插件（例如 gcloud app deploy）支持。

如果创建服务，此元素是必需的。 对于 default 服务，此元素为可选元素。每项服务和每个版本都必须有自己的名称。名称可以包含数字、字母和连字符。在柔性环境中，VERSION-dot-SERVICE-dot-PROJECT_ID 的组合长度（其中 VERSION 是版本名称，SERVICE 是服务名称） PROJECT_ID 是项目 ID）不得超过 63 个字符，且首尾不能使用连字符。请为每项服务和每个版本选择唯一的名称。服务名称和版本名称不得重复。

例如： 
service: service-name

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

module: service-name
service_account

可选。借助 service_account 元素，您可以将用户管理的服务账号指定为版本的身份。访问其他 Google Cloud 服务和执行任务时会使用指定的服务账号。

例如： 
service_account: [SERVICE_ACCOUNT_NAME]@[PROJECT_ID].iam.gserviceaccount.com
skip_files

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

skip_files 具有以下默认值：

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

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

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

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

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

skip_files:
- logs/
threadsafe

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

此字段在 Python 3 运行时环境中已弃用。

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]

如需详细了解如何使用此命令，请参阅部署您的应用。

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

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

注意：版本名称应以字母开头，以便与始终由数字指定的数字实例区分开来。这可以避免产生歧义，比如 123-dot-my-service.uc.r.appspot.com 网址就有两种解读方式：如果存在版本“123”，则目标将是给定服务的版本“123”；如果该版本不存在，则目标将是服务的默认版本的实例编号 123。

应用的每个版本都保留自己的 app.yaml 副本。上传应用时，要上传的 app.yaml 文件中提及的版本即为通过该上传创建或替换的版本。管理员可以使用 Google Cloud 控制台更改由哪个版本的应用处理流量，还可以在配置其他版本接收流量前先测试相应版本。
vpc_access_connector

可选。将应用配置为使用无服务器 VPC 访问通道连接器，使应用能够将请求发送到 VPC 网络中的内部资源。如需了解详情，请参阅连接到 VPC 网络。

name
字符串字面量。在引号内指定无服务器 VPC 访问通道连接器的完全限定名称：
"projects/PROJECT_ID/locations/REGION/connectors/CONNECTOR_NAME"
egress_setting
可选。默认值为 private-ranges-only。egress_setting 可以是下列选项之一：
private-ranges-only
默认值。对内部 IP 地址的请求会通过无服务器 VPC 访问通道连接器发送到连接的 VPC 网络。对外部 IP 地址的请求会发送到公共互联网。
all-traffic
所有请求都通过无服务器 VPC 访问通道连接器发送到连接的 VPC 网络。
示例 
vpc_access_connector:
  name: "projects/PROJECT_ID/locations/REGION/connectors/CONNECTOR_NAME"
  egress_setting: all-traffic

处理程序元素

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

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

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

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

此字段在较新的 App Engine 运行时环境中已弃用。
expiration 可选。Web 代理和浏览器应缓存由此处理程序传送的静态文件的时长。该值是一个用空格分隔的数字和单位字符串，其中，单位可以是 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
    vary: Accept-Encoding
  # ...

CORS 支持

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

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

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

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

注意：如果要让所有人都能访问您的资源，可以使用通配符 '*' 来代替 https://mygame.uc.r.appspot.com。
mime_type

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

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

可选。redirect_http_response_code 与 secure 设置搭配使用，用于设置按照 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 的文件。

在较新的 App Engine 运行时环境中，此字段的行为已更改。
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

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

如需使用 REGION_ID.r.appspot.com 网域来定位应用的特定版本，请将英文句点（通常用来分隔网址的子网域组成部分）替换为字符串“-dot-”，例如：
https://VERSION_ID-dot-default-dot-PROJECT_ID.REGION_ID.r.appspot.com

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

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

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

静态目录中的每个文件都使用与其文件扩展名对应的 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

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

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

与以下元素一起使用时，网址格式在行为上有一些差异：

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

扩缩元素

下表中的元素用于配置应用的扩缩方式。如需详细了解 App Engine 应用的扩缩方式，请参阅扩缩类型。

元素 说明
automatic_scaling

可选。仅适用于使用 F1 或更高级别的实例类的应用。

指定此元素可以更改自动扩缩的默认设置，例如设置最小和最大实例数、延迟时间和服务的并发连接数。

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

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

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

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

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

max_idle_instances

可选。App Engine 应为此版本保留的最大空闲实例数。指定一个介于 1 到 1000 之间的值。如果未指定，则默认值为 automatic，这意味着 App Engine 将管理空闲实例数。请谨记以下内容：

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

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

min_idle_instances

可选：需要保持运行并准备好为此版本处理流量的其他实例数。

App Engine 根据 target_cpu_utilization 和 target_throughput_utilization 等扩缩设置计算处理当前应用流量所需的实例数。设置 min_idle_instances 指定除此计算数量之外要运行的实例数。例如，如果 App Engine 计算出将 5 个实例用于处理流量，并且 min_idle_instances 设置为 2，则 App Engine 将运行 7 个实例（根据流量计算得出 5 个实例，以及每 min_idle_instances 额外 2 个实例）。

请注意，您需要为指定数量的实例支付费用，无论这些实例是否正在接收流量。请谨记以下内容：

  • 较低的最小值有助于在空闲期间降低您的运行费用，但也意味着突然发生负载峰值时可立即使用的实例会更少。

  • 设置较高的最小值有助于应用自如应对突然出现的请求负载峰值。App Engine 会保持运行该最小数量的实例来处理传入请求。您需要为指定数量的实例支付费用，无论这些实例是否正在处理请求。

    如果您设置了最小空闲实例数，则等待延迟时间对应用性能的影响会更小。

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

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

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

与 max_concurrent_requests 搭配使用，用于指定何时因并发请求而启动新实例。当并发请求数达到 max_concurrent_requests 乘以 target_throughput_utilization 的值时，调度器会尝试启动一个新实例。

max_concurrent_requests

可选。在调度器生成新实例之前，自动扩缩实例可以接受的并发请求数（默认值：10，最大值：1,000）。

与 target_throughput_utilization 搭配使用，用于指定何时因并发请求而启动新实例。当并发请求数达到 max_concurrent_requests 乘以 target_throughput_utilization 的值时，调度器会尝试启动一个新实例。

除非您需要单线程，否则我们建议您不要将 max_concurrent_requests 设置为小于 10 的值。小于 10 的值可能会导致创建的实例数多于线程安全应用所需的数量，从而产生不必要的费用。

如果此设置过高，则 API 延迟时间可能会增加。请注意，调度程序可能会在达到实际最大请求数之前生成新实例。

max_pending_latency

在启动额外的实例处理请求以缩短等待延迟时间之前，App Engine 允许请求在待处理队列中等待的最长时间。当达到此阈值时，即表示需要纵向扩容，这会导致实例数增加。 如果未指定，则默认值为 automatic。这意味着请求可在待处理队列中最长保留 10 秒（即待处理请求时间上限），超过此时间才会触发新实例启动。

设置较低的最大值意味着，App Engine 将更早地为待处理请求启动新实例，这有助于提高性能，但会增加运行费用。

设置较高的最大值意味着，用户可能需要花费更长时间来等待其请求得到处理（如果有待处理请求且没有空闲实例来处理这些请求），不过，这有助于降低应用的运行费用。

min_pending_latency

您可以设置一个可选元素，以指定在启动新实例来处理请求之前，App Engine 应允许请求在待处理队列中等待的最短时间。指定值可降低运行费用，但会增加用户必须等待处理请求的时间。

对于免费应用，默认值为 500ms。对于付费应用，默认值为 0。

此元素可以与 max_pending_latency 元素搭配使用，以确定 App Engine 何时创建新实例。如果待处理请求在队列中的时间：

  • 短于您指定的 min_pending_latency，App Engine 将不会创建新实例。
  • 长于 max_pending_latency，App Engine 将会尝试创建新实例。
  • 介于 min_pending_latency 和 max_pending_latency 指定的时间之间，则 App Engine 将尝试重复使用现有的实例。如果没有实例能够在 max_pending_latency 之前处理请求，则 App Engine 将创建新实例。
示例
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

使用 B1 或更高级别的实例类的应用必须指定此元素或 manual_scaling。

此元素用于启用实例类 B1 及更高级别的基本扩缩，并且可以包含以下元素：

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

使用 B1 或更高级别的实例类的应用必须指定此元素或 basic_scaling。

此元素用于启用实例类 B1 及更高级别的手动扩缩，并且可以包含以下元素：

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