配置应用程序

App Engine 应用程序在其根目录中有名为 app.yaml 的配置文件。该文件介绍了应用程序所使用的 App Engine 运行时环境、源代码的版本，以及哪些处理程序脚本应处理哪些网址。app.yaml 和应用程序源代码一起上传到 App Engine。

• 必需的元素
• 脚本处理程序
• 静态文件的处理程序
• 需要登录或管理员身份
• 跳过文件
• 参考 Python 库目录
• 保留的网址

以下是 app.yaml 文件的示例：

application: myapp
version: 1
runtime: python
api_version: 1

handlers:
- url: /
  script: home.py

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

- url: /stylesheets
  static_dir: stylesheets

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

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

- url: /.*
  script: not_found.py

app.yaml 的语法为 YAML 格式。有关该语法的详细信息，请参阅 YAML 网站。

提示：YAML 格式支持注释。以井号 (#) 字符开头的行会被忽略：
# This is a comment.

网址和文件路径样式使用 POSIX 扩展的正则表达式语法，对照元素和对照类除外。支持分组匹配项的反向引用（例如 \1），正如支持以下 Perl 扩展一样：\w \W \s \S \d \D（这类似于 Codesite 搜索，增加了反向引用支持）。

必需的元素

app.yaml 文件必须包括以下各元素中的一个：

application

应用程序标识符。这是当您在管理控制台中创建应用程序时选定的标识符。

application: myapp

version

应用程序代码的版本分类符。App Engine 为使用的每个 version 保留一份应用程序副本。管理员可以使用管理控制台更改应用程序的哪个主版本是公共的，并可以先测试非公共版本，再将非公共版本变为公共版本。

应用程序的每个版本都会保留其自身的 app.yaml 副本。当上传应用程序时，将通过上传创建或替换正在上传的 app.yaml 文件中提到的版本。

在管理控制台上，版本号显示为主版本 (version) 以及与此主版本上传次数相对应的次版本。只有最新的主版本才会保留下来。

version: 1

runtime

该应用程序使用的 App Engine 运行时环境的名称。此时，App Engine 有一个运行时环境：python

runtime: python

api_version

该应用程序在指定运行时环境中使用的 API 的版本。当 Google 发布运行时环境 API 的新版本时，您的应用程序会继续使用针对该应用程序编写的 API。要将您的应用程序升级到新 API，请更改该值并上传已升级的代码。

此时，App Engine 有一个 python 运行时环境的版本：1。

api_version: 1

handlers

网址样式及其处理方式说明的列表。App Engine 可以通过执行应用程序代码，或通过提供与代码一起上传的静态文件（例如图像、CSS 或 JavaScript）来处理网址。

根据样式在 app.yaml 中的显示顺序从上到下对其进行评估。样式与网址匹配的第一个映射将用于处理请求。

有两种处理程序：脚本处理程序和静态文件处理程序。脚本处理程序在应用程序中运行 Python 脚本以确定指定网址的响应。静态文件处理程序返回文件的内容（例如图像）作为响应。

有关该值的详细信息，请参阅下面的脚本处理程序以及静态文件的处理程序。

handlers:
- url: /images
  static_dir: static/images

- url: /.*
  script: myapp.py

脚本处理程序

脚本处理程序执行 Python 脚本以处理与网址样式匹配的请求。映射定义要匹配的网址样式和要执行的脚本。

url

网址样式，作为正则表达式。表达式可以通过正则表达式反向引用包含可在脚本的文件路径中参考的分组。

例如，/profile/(.*?)/(.*) 可能与网址 /profile/edit/manager 匹配，并使用 edit 和 manager 作为第一个和第二个分组。

handlers:
- url: /profile/(.*?)/(.*)
  script: /employee/\2/\1.py

script

脚本的路径，从应用程序根目录开始。

如以上示例所示，对于 edit 和 manager 分组，脚本路径 /employee/\2/\1.py 使用完整路径 /employee/manager/edit.py。

以下示例将网址映射到脚本：

handlers:

# The root URL (/) is handled by the index.py script.  No other URLs match this pattern.
- url: /
  script: index.py

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

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

# All other URLs use the not_found.py script.
- url: /.*
  script: not_found.py

静态文件的处理程序

静态文件是直接向指定网址的用户提供的文件，例如图像、CSS 样式表或 JavaScript 源文件。静态文件处理程序说明了应用程序目录中的哪些文件为静态文件，以及为哪些网址提供静态文件。

为了提高效率，App Engine 将应用程序文件与静态文件单独存储和提供。静态文件在应用程序的文件系统中不可用。如果您有需要由应用程序代码读取的数据文件，数据文件必须为应用程序文件，且必须和静态文件样式不匹配。

除非另有通知，否则网络浏览器会将从网站上加载的文件保留有限的一段时间。您可以通过包括 default_expiration 元素（顶级元素），来定义应用程序的所有静态文件处理程序的全局默认缓存周期。您还可以为特定静态文件处理程序配置缓存持续时间。（脚本处理程序可以通过向浏览器返回相应的 HTTP 标头来设置缓存持续时间。）

default_expiration

如果处理程序没有指定自己的 expiration，则静态文件处理程序提供的静态文件的时间长度应缓存在用户的浏览器中。值是一串数字和单位，由空格分隔，其中单位可以用 d 代表天、h 代表小时、m 代表分钟、s 代表秒。例如，"4d 5h" 将缓存期设置为从浏览器首次加载文件开始算起的 4 天 5 小时。

default_expiration 为可选项。如果被忽略，默认行为是允许浏览器确定其自身的缓存持续时间。

例如：

application: myapp
version: 1
runtime: python
api_version: 1

default_expiration: "4d 5h"

handlers:
  # ...

可以用两种方式定义静态文件处理程序：作为映射到网址路径的静态文件目录结构，或作为将网址映射到特定文件的样式。

静态目录处理程序

使用静态目录处理程序可以轻松将目录的全部内容作为静态文件来提供。除非被目录的 mime_type 设置覆盖，否则每个文件都使用与其文件扩展名对应的 MIME 类型提供。指定目录中的所有文件会作为静态文件上传，其中没有文件可以作为脚本运行。

url

网址前缀。该值使用正则表达式语法（因此必须对 regexp 特殊字符进行转义），但它不应该包含分组。所有以该前缀开头的网址都由该处理程序处理，将前缀后面的部分网址用作文件路径的一部分。

static_dir

包括静态文件的目录的路径，从应用程序根目录开始。匹配的 url 样式末尾的所有内容附加到 static_dir 以形成到请求的文件的完整路径。

该目录中的所有文件都作为静态文件由应用程序上传。

mime_type

可选。如果指定，将使用指定的 MIME 类型提供该处理程序提供的所有文件。如果未指定，文件的 MIME 类型将取自该文件的文件扩展名。

有关可以使用的 MIME 媒体类型的详细信息，请参阅 IANA MIME 媒体类型网站。

expiration

该处理程序提供静态文件的时间长度应在用户的浏览器中进行缓存。值是一串数字和单位，由空格分隔，其中单位可以用 d 代表天、h 代表小时、m 代表分钟、s 代表秒。例如，"4d 5h" 将缓存期设置为从浏览器首次加载文件开始算起的 4 天 5 小时。

expiration 为可选项。如果被忽略，将使用应用程序的 default_expiration。

例如：

handlers:

# All URLs beginning with /stylesheets are treated as paths to static files in
# the stylesheets/ directory.  Note that static_dir handlers do not use a
# regular expression for the URL pattern, only a prefix.
- url: /stylesheets
  static_dir: stylesheets

静态文件样式处理程序

静态文件处理程序将网址样式与使用应用程序上传的静态文件的路径相关联。网址样式正则表达式可以定义在文件路径的结构中使用的正则表达式分组。您可以使用它而非 static_dir 来映射到目录结构中的特定文件，而不是映射整个目录。

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

以下 static_dir 和 static_files 处理程序对等：

- url: /images
  static_dir: static/images

- url: /images/(.*)
  static_files: static/images/\1
  upload: static/images/(.*)

url

网址样式，作为正则表达式。表达式可以通过正则表达式反向引用包含可在脚本的文件路径中参考的分组。

例如，/item-(.*?)/category-(.*) 可能与网址 /item-127/category-fruit 匹配，并使用 127 和 fruit 作为第一个和第二个分组。

handlers:
- url: /item-(.*?)/category-(.*)
  static_files: archives/\2/items/\1

static_files

与网址样式匹配的静态文件的路径，从应用程序根目录开始。路径可以参考网址样式的分组中匹配的文本。

如以上示例所示，archives/\2/items/\1 分别在 \2 和 \1 位置插入匹配的第二个和第一个分组。采用以上示例中的样式，文件路径应当为 archives/fruit/items/127。

upload

与该处理程序将引用的所有文件的文件路径匹配的正则表达式。该表达式是必需的，因为处理程序无法确定您的应用程序目录中哪些文件与指定 url 和 static_files 样式相对应。静态文件的上传和处理与应用程序文件相独立。

以上示例可能使用以下 upload 样式：archives/(.*?)/items/(.*)

mime_type

可选。如果指定，将使用指定的 MIME 类型提供该处理程序提供的所有文件。如果未指定，文件的 MIME 类型将取自该文件的文件扩展名。

有关可以使用的 MIME 媒体类型的详细信息，请参阅 IANA MIME 媒体类型网站。

expiration

该处理程序提供静态文件的时间长度应在用户的浏览器中进行缓存。值是一串数字和单位，由空格分隔，其中单位可以用 d 代表天、h 代表小时、m 代表分钟、s 代表秒。例如，"4d 5h" 将缓存期设置为从浏览器首次加载文件开始算起的 4 天 5 小时。

expiration 为可选项。如果被忽略，将使用应用程序的 default_expiration。

例如：

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 regexp, 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))

需要登录或管理员身份

任何网址处理程序都可以使用 login 设置将访问者限制为仅登录了的用户，或是应用程序管理员的用户。当具有 login 设置的网址处理程序与网址匹配时，该处理程序会先检查用户是否用 Google 帐户登录了应用程序。如果没有，用户将被重定向到 Google 登录页面，并在登录或创建帐户后重定向回该应用程序网址。

如果设置为 login: required，用户登录后，处理程序将正常运行。

如果设置为 login: admin，用户登录后，处理程序将检查用户是否是应用程序的管理员。如果不是，将向用户显示错误消息。如果用户是管理员，处理程序将继续运行。

如果应用程序需要其他行为，应用程序可以自行执行用户处理。有关详细信息，请参阅用户 API。

示例：

handlers:

- url: /profile/.*
  script: user_profile.py
  login: required

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

- url: /.*
  script: welcome.py

跳过文件

应用程序目录中路径与 static_dir 路径或 static_files upload 路径匹配的文件被视为静态文件。应用程序目录中的所有其他文件均被视为应用程序和数据文件。

skip_files 元素指定应用程序目录中的哪些文件不上传到 App Engine。值为正则表达式。当上传应用程序时，将从要上传的文件列表中忽略与正则表达式匹配的任何文件名。

skip_files 具有以下默认值：

skip_files: |
 ^(.*/)?(
 (app\.yaml)|
 (app\.yml)|
 (index\.yaml)|
 (index\.yml)|
 (#.*#)|
 (.*~)|
 (.*\.py[co])|
 (.*/RCS/.*)|
 (\..*)|
 )$

默认样式不包括配置文件 app.yaml、app.yml、index.yaml、index.yml（配置单独发送至服务器），具有 #...# 和 ...~、.pyc 和 .pyo 命名格式的 Emacs 备份文件，RCS 版本控制目录中的文件，以及名称以点 (.) 开头的 Unix 隐藏文件。

如果在 app.yaml 中指定新值，它将覆盖该值。要扩展该样式，请将它和扩展名一起复制并粘贴到您的配置。

参考 Python 库目录

您可以使用 $PYTHON_LIB 参考 app.yaml 脚本路径中的 Python 库目录。仅当设置脚本包含在 App Engine 库中的处理程序时，这才有用。

例如，$PYTHON_LIB/google/appengine/ext/admin 是与开发网络服务器的开发人员控制台功能相似的管理应用程序，开发网络服务器自身可以在 App Engine 上作为应用程序的一部分运行。要对其进行设置，请加入使用其路径的脚本处理程序的配置：

handlers:

- url: /admin/.*
  script: $PYTHON_LIB/google/appengine/ext/admin
  login: admin

保留的网址

出于提供功能或管理目的，App Engine 保留了一些网址路径。脚本处理程序和静态文件处理程序路径绝不会与这些路径匹配。

保留了以下网址路径：

• /_ah/
• /form