区域 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 |
推荐的方法是从
如需详细了解如何使用这些命令,请参阅部署您的应用。 应用 ID 是您在 Google Cloud 控制台中创建应用时指定的 Google Cloud 控制台项目 ID。 |
api_version |
必需。您的应用使用的给定运行时环境中的 API 版本。
当 Google 宣布支持新版本的运行时环境的 API 时,您部署的应用将继续使用编写此应用时所用的 API。如需将应用升级到新版本的 API,请更改此值,然后将应用重新部署到 App Engine。如果指定值
目前,App Engine 有一个版本的 |
auto_id_policy |
可选。如果您目前采用的是自动设置实体标识符的方式,则可以通过设置自动 ID 政策来更改所使用的方法。以下是有效选项:
|
builtins |
可选。Python 2 SDK 为常见的应用功能提供了许多内置处理程序。 以下内置处理程序可供您使用:
builtins: - deferred: on - appstats: on
builtins: - name: on 等效于: includes: - $PYTHON_LIB/google/appengine/ext/builtins/name/
当您在
例如,请考虑使用内置 handlers: - url: /.* script: main.app builtins: - appstats: on 处理程序的结果列表是: [/_ah/stats, /.*] 如果 includes: - included.yaml 并且 handlers: - url: /.* script: main.app builtins: - appstats: on 现在,处理程序的结果列表是: [/.*, /_ah/stats]
|
default_expiration |
可选。为应用的所有静态文件处理程序设置全局默认缓存期限。您还可以配置特定静态文件处理程序的缓存时长。该值是一个由数字和单位组成并以空格分隔的字符串,其中,单位可以是 d(表示天)、h(表示小时)、m(表示分钟)和 s(表示秒)。例如, runtime: python27 api_version: 1 threadsafe: true default_expiration: "4d 5h" handlers: # ... 如需了解详情,请参阅缓存到期时间。 |
env_variables
|
可选。您可以在 以 os.environ 字典中找到:
env_variables: DJANGO_SETTINGS_MODULE: "myapp.settings" |
error_handlers |
可选。用于配置针对不同错误类型返回的自定义错误页面。 此元素可以包含以下元素:
error_handlers: - file: default_error.html - error_code: over_quota file: over_quota.html |
handlers |
必需。一组网址格式及其处理方式说明。App Engine 可以通过执行应用代码,或通过传送与代码一起上传的静态文件(例如图片、CSS 或 JavaScript)来处理网址。 |
includes
|
可选。 includes: - lib/user_admin.yaml App Engine 按以下顺序解析所含路径:
如果
包含的 |
inbound_services |
可选。应用必须先启用这些服务,然后才能接收入站请求。如需为 Python 2 应用启用该服务,您可以在 您可以使用下列入站服务: 示例:inbound_services: - mail - warmup |
instance_class |
可选。此服务的实例类。 根据服务的扩缩设置,可用的值如下:
|
libraries |
可选。Python 2.7 运行时包含一些第三方库。其中一些库默认可用;另一些只有配置后才可用。您可以通过指定 libraries: - name: PIL version: "1.1.7" - name: webob version: "latest"
请注意,您指定 如果您正在开发尚未有任何用户的应用,则不需要跟踪新版本。但是,如果您的应用用户活跃度非常高,请注意:您可能会感到意外,因为您的应用开始使用不能向后兼容的新的库版本。 如需了解所包含的第三方库的列表,请参阅第三方库。您若要使用其他纯 Python 第三方库,可以通过将其安装到本地目录中来实现。 如果您正在使用柔性环境,请参阅在柔性环境中使用 Python 库。 |
module |
注意:模块现在已更名为服务。 如需使用 gcloud CLI 管理应用,请改用 service 元素。 |
runtime |
必需。应用使用的运行时环境的名称。例如,如需指定 Python 2.7,请使用: runtime: python27 |
service |
服务以前称为模块。
仅受 gcloud CLI 或基于 gcloud CLI 的插件(例如
如果创建服务,此元素是必需的。
对于 service: service-name 注意: module: service-name |
service_account |
可选。借助 service_account: [SERVICE_ACCOUNT_NAME]@[PROJECT_ID].iam.gserviceaccount.com |
skip_files |
可选。
skip_files: - ^(.*/)?#.*#$ - ^(.*/)?.*~$ - ^(.*/)?.*\.py[co]$ - ^(.*/)?.*/RCS/.*$ - ^(.*/)?\..*$ 默认模式排除了名称格式为
如需扩展上述正则表达式列表,请复制上面的列表并将其粘贴到 skip_files: - ^(.*/)?#.*#$ - ^(.*/)?.*~$ - ^(.*/)?.*\.py[co]$ - ^(.*/)?.*/RCS/.*$ - ^(.*/)?\..*$ - ^(.*/)?.*\.bak$
如需跳过整个目录,请将目录名称添加到列表中。例如,要跳过名为 skip_files: - logs/ |
threadsafe |
必需。将您的应用配置为使用并发请求。如果使用 Python 的线程库,每次请求后,都会清除 threadsafe: [true | false]
注意: |
version |
推荐的方法是从
如需详细了解如何使用此命令,请参阅部署您的应用。 您部署到 App Engine 的应用代码版本的标识符。
版本 ID 可以包含小写字母、数字和连字符,不能以前缀
注意:版本名称应以字母开头,以便与始终由数字指定的数字实例区分开来。这可以避免产生歧义,比如
应用的每个版本都保留自己的 |
vpc_access_connector |
可选。将应用配置为使用无服务器 VPC 访问通道连接器,使应用能够将请求发送到 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,则这些文件也会作为代码数据上传,这样您的应用可以读取它们。这两种上传都会消耗您的代码和静态数据存储资源配额。 |
expiration
|
可选。Web 代理和浏览器应缓存由此处理程序传送的静态文件的时长。该值是一个用空格分隔的数字和单位字符串,其中,单位可以是 d (表示天)、h (表示小时)、m (表示分钟)和 s (表示秒)。例如,"4d 5h" 表示将缓存到期时间设置为首次请求文件后的 4 天 5 小时。如果省略此元素,则系统会使用应用的 default_expiration 。如需了解详情,请参阅缓存到期时间。 |
http_headers |
可选。您可以设置静态文件或目录处理程序响应的 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 应用托管的文件。
例如,假设您有一个游戏应用 下面演示了如何让静态文件处理程序返回这个必需的响应标头值: handlers: - url: /images static_dir: static/images http_headers: Access-Control-Allow-Origin: https://mygame.uc.r.appspot.com # ... 注意:如果要让所有人都能访问您的资源,可以使用通配符 |
mime_type |
可选。如果指定此元素,则由此处理程序传送的所有文件均将使用指定的 MIME 类型进行传送。如果未指定,将根据文件的文件扩展名确定文件的 MIME 类型。如果上传多个扩展名不同的同一文件,则生成的扩展名可能由上传的顺序决定。 如需详细了解可能的 MIME 媒体类型,请参阅 IANA MIME 媒体类型网站 |
redirect_http_response_code |
可选。
handlers: - url: /youraccount/.* script: accounts.app login: required secure: always redirect_http_response_code: 301
重定向用户请求时,HTTP 状态代码将设置为 |
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
注意:就像 Python 在较新的 App Engine 运行时环境中,此字段的行为已更改。 |
secure |
可选。任何网址处理程序(包括脚本处理程序和静态文件处理程序)均可使用 secure 设置。secure 元素可用的值如下:
handlers: - url: /youraccount/.* script: accounts.app login: required secure: always
开发 Web 服务器不支持 HTTPS 连接。它会忽略
如需使用 要将自定义网域与 HTTPS 结合使用,您必须先为该网域激活并配置 SSL 证书。 Google 账号的登录和退出始终是通过安全连接执行的,与应用网址配置为何种格式无关。 |
static_dir
|
可选。应用根目录中包含静态文件的目录的路径。所匹配的
静态目录中的每个文件都使用与其文件扩展名对应的 MIME 类型提供,除非被目录的
此目录中的所有文件均作为静态文件随应用一并上传。App Engine 将应用的文件与静态文件分开存储和提供。默认情况下,应用的文件系统中不提供静态文件。您可以通过将 handlers: # All URLs beginning with /stylesheets are treated as paths to # static files in the stylesheets/ directory. - url: /stylesheets static_dir: stylesheets # ... |
static_files
|
可选。静态文件格式处理程序会将网址格式与随应用一并上传的静态文件的路径相关联。网址格式正则表达式可以定义用来构建文件路径的正则表达式分组。您可以使用它而非 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 将应用的文件与静态文件分开存储和提供。默认情况下,应用的文件系统中不提供静态文件。您可以通过将 静态文件不能与应用代码文件相同。 如果静态文件路径与动态处理程序中使用的脚本的路径匹配,则该动态处理程序将无法使用此脚本。 |
upload |
可选。一个正则表达式,它会与将由此处理程序引用的所有文件的文件路径进行匹配。系统必须执行此操作,否则处理程序将无法确定应用目录中的哪些文件与指定的 |
url |
与以下元素一起使用时,网址格式在行为上有一些差异:
|
扩缩元素
下表中的元素用于配置应用的扩缩方式。如需详细了解 App Engine 应用的扩缩方式,请参阅扩缩类型。
元素 | 说明 |
---|---|
automatic_scaling |
可选。仅适用于使用 F1 或更高级别的实例类的应用。 指定此元素可以更改自动扩缩的默认设置,例如设置最小和最大实例数、延迟时间和服务的并发连接数。 此元素可以包含以下元素:
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 或更高级别的实例类的应用必须指定此元素或 此元素用于启用实例类 B1 及更高级别的基本扩缩,并且可以包含以下元素:
basic_scaling: max_instances: 11 idle_timeout: 10m |
manual_scaling |
使用 B1 或更高级别的实例类的应用必须指定此元素或 此元素用于启用实例类 B1 及更高级别的手动扩缩,并且可以包含以下元素:
manual_scaling: instances: 5 |