Python 应用程序配置
Python App Engine 应用程序必须具有名为 app.yaml
的配置文件,用来指定网址路径如何与请求处理程序和静态文件对应。它还包含关于应用程序代码的信息(如应用程序 ID 和最新版本的标识符)。
关于 app.yaml
Python 应用程序在名为 app.yaml
的文件中指定运行时配置(包括版本和网址)。以下是 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: myapp
-
应用程序代码的版本分类符。App Engine 为使用的每个
version
保留一份应用程序副本。管理员可以使用管理控制台 更改应用程序的哪个主版本是公共的,并可以先测试非公共版本,再将非公共版本变为公共版本。应用程序的每个版本都会保留其自身的
app.yaml
副本。当上传应用程序时,将通过上传创建或替换正在上传的app.yaml
文件中提到的版本。version: 1
-
该应用程序使用的 App Engine 运行时环境的名称。此时,App Engine 有一个运行时环境:
python
runtime: python
-
该应用程序在指定运行时环境中使用的 API 的版本。当 Google 发布运行时环境 API 的新版本时,您的应用程序会继续使用针对该应用程序编写的 API。要将您的应用程序升级到新 API,请更改该值并上传已升级的代码。
此时,App Engine 有一个
python
运行时环境的版本:1
。api_version: 1
-
网址样式及其处理方式说明的列表。App Engine 可以通过执行应用程序代码,或通过提供与代码一起上传的静态文件(例如图像、CSS 或 JavaScript)来处理网址。
根据样式在
app.yaml
中的显示顺序从上到下对其进行评估。样式与网址匹配的第一个映射将用于处理请求。有两种处理程序:脚本处理程序和静态文件处理程序。脚本处理程序在应用程序中运行 Python 脚本以确定指定网址的响应。静态文件处理程序返回文件的内容(例如图像)作为响应。
有关该值的详细信息,请参阅下面的脚本处理程序 以及静态文件的处理程序 。
handlers:
- url: /images
static_dir: static/images
- url: /.*
script: myapp.py
application
version
runtime
api_version
handlers
脚本处理程序
脚本处理程序执行 Python 脚本以处理与网址样式匹配的请求。映射定义要匹配的网址样式和要执行的脚本。
-
网址样式,作为正则表达式。表达式可以通过正则表达式反向引用包含可在脚本的文件路径中参考的分组。
例如,
/profile/(.*?)/(.*)
可能与网址/profile/edit/manager
匹配,并使用edit
和manager
作为第一个和第二个分组。handlers:
- url: /profile/(.*?)/(.*)
script: /employee//2//1.py
-
脚本的路径,从应用程序根目录开始。
如以上示例所示,对于
edit
和manager
分组,脚本路径/employee//2//1.py
使用完整路径/employee/manager/edit.py
。
url
script
以下示例将网址映射到脚本:
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 标头来设置缓存持续时间。)
-
如果处理程序没有指定自己的
expiration
,则静态文件处理程序提供的静态文件的时间长度应缓存在用户的浏览器中。值是一串数字和单位,由空格分隔,其中单位可以用d
代表天、h
代表小时、m
代表分钟、s
代表秒。例如,"4d 5h"
将缓存期设置为从浏览器首次加载文件开始算起的 4 天 5 小时。default_expiration
为可选项。如果被忽略,默认行为是允许浏览器确定其自身的缓存持续时间。
default_expiration
例如:
application: myapp
version: 1
runtime: python
api_version: 1
default_expiration: "4d 5h"
handlers:
# ...
可以用两种方式定义静态文件处理程序:作为映射到网址路径的静态文件目录结构,或作为将网址映射到特定文件的样式。
静态目录处理程序
使用静态目录处理程序可以轻松将目录的全部内容作为静态文件来提供。除非被目录的 mime_type
设置覆盖,否则每个文件都使用与其文件扩展名对应的 MIME 类型提供。指定目录中的所有文件会作为静态文件上传,其中没有文件可以作为脚本运行。
-
网址前缀。该值使用正则表达式语法(因此必须对 regexp 特殊字符进行转义),但它不应该包含分组。所有以该前缀开头的网址都由该处理程序处理,将前缀后面的部分网址用作文件路径的一部分。
-
包括静态文件的目录的路径,从应用程序根目录开始。匹配的
url
样式末尾的所有内容附加到static_dir
以形成到请求的文件的完整路径。该目录中的所有文件都作为静态文件由应用程序上传。
-
可选。如果指定,将使用指定的 MIME 类型提供该处理程序提供的所有文件。如果未指定,文件的 MIME 类型将取自该文件的文件扩展名。
有关可以使用的 MIME 媒体类型的详细信息,请参阅 IANA MIME 媒体类型网站 。
-
该处理程序提供静态文件的时间长度应在用户的浏览器中进行缓存。值是一串数字和单位,由空格分隔,其中单位可以用
d
代表天、h
代表小时、m
代表分钟、s
代表秒。例如,"4d 5h"
将缓存期设置为从浏览器首次加载文件开始算起的 4 天 5 小时。expiration
为可选项。如果被忽略,将使用应用程序的default_expiration
。
url
static_dir
mime_type
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/(.*)
-
网址样式,作为正则表达式。表达式可以通过正则表达式反向引用包含可在脚本的文件路径中参考的分组。
例如,
/item-(.*?)/category-(.*)
可能与网址/item-127/category-fruit
匹配,并使用127
和fruit
作为第一个和第二个分组。handlers:
- url: /item-(.*?)/category-(.*)
static_files: archives//2/items//1
-
与网址样式匹配的静态文件的路径,从应用程序根目录开始。路径可以参考网址样式的分组中匹配的文本。
如以上示例所示,
archives//2/items//1
分别在/2
和/1
位置插入匹配的第二个和第一个分组。采用以上示例中的样式,文件路径应当为archives/fruit/items/127
。 -
与该处理程序将引用的所有文件的文件路径匹配的正则表达式。该表达式是必需的,因为处理程序无法确定您的应用程序目录中哪些文件与指定
url
和static_files
样式相对应。静态文件的上传和处理与应用程序文件相独立。以上示例可能使用以下
upload
样式:archives/(.*?)/items/(.*)
-
可选。如果指定,将使用指定的 MIME 类型提供该处理程序提供的所有文件。如果未指定,文件的 MIME 类型将取自该文件的文件扩展名。
有关可以使用的 MIME 媒体类型的详细信息,请参阅 IANA MIME 媒体类型网站 。
-
该处理程序提供静态文件的时间长度应在用户的浏览器中进行缓存。值是一串数字和单位,由空格分隔,其中单位可以用
d
代表天、h
代表小时、m
代表分钟、s
代表秒。例如,"4d 5h"
将缓存期设置为从浏览器首次加载文件开始算起的 4 天 5 小时。expiration
为可选项。如果被忽略,将使用应用程序的default_expiration
。
url
static_files
upload
mime_type
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))
安全网址
对于使用 *.appspot.com
域的网址,Google App Engine 支持通过 HTTPS 的安全连接。如果某个请求使用 HTTPS 访问网址,且该网址配置为使用 app.yaml
文件中的 HTTPS,则发件人在发送请求数据和响应数据前需要对其加密,收件人收到后需要将其解密。安全连接有利于保护客户数据,如联系人信息、密码和私人消息。
注意: Google 企业应用套件域目前不支持 HTTPS。HTTPS 支持限于通过 *.appspot.com
域访问的应用程序。在 Google 企业应用套件域上访问 HTTPS 网址将返回“找不到主机”错误,而使用 HTTP 访问其处理程序仅接受 HTTPS 的网址(参见下文)将返回 HTTP 403“禁止访问”错误。您可以为了安全起见而链接到具有 *.appspot.com
域的 HTTPS 网址,而针对网站的其余部分使用企业应用套件域和 HTTP。
要将网址配置为接受安全连接,请为处理程序提供 secure
参数:
handlers:
- url: /youraccount/.*
script: accounts.py
login: required
secure: always
secure
具有 3 个可能的值:
never
。对与该处理程序(使用 HTTPS)匹配的网址的请求将被自动重定向到 HTTP 同义网址。在没有为处理程序提供secure
的情况下,这是默认设置。always
。对与该处理程序(不使用 HTTPS)匹配的网址的请求将被自动重定向到相同路径的 HTTPS 网址。保留查询参数,以便重定向。optional
。对与处理程序匹配的网址的 HTTP 和 HTTPS 请求均将成功,无需重定向。应用程序可检查请求以确定所使用的协议,并相应地作出响应。
如果某个用户的 HTTPS 查询被重定向为 HTTP 查询,则查询参数将从请求中删除。这可防止用户无意中通过本应为安全连接的不安全连接提交查询数据。
安全连接比不安全连接占用更多的 CPU 和带宽,因此更昂贵。安全连接也比非安全连接慢。
所有的网址处理程序(包括脚本处理程序和静态文件处理程序)都可使用 secure
设置。
开发网络服务器不支持 HTTPS 连接。它将忽略 secure
参数,因此可使用指向开发网络服务器的常规 HTTP 连接对预期用于 HTTPS 的路径进行测试。
当使用版本化 appspot.com 网址(例如 https://1.latest.app-id.appspot.com/
)测试您的应用程序的 HTTPS 处理程序时,您的浏览器将警告没有为该特定域路径注册 HTTPS 证书。如果您接受该域的证书,则将成功载入页面。用户在访问 https://app-id.appspot.com/
时不会显示证书警告。
Google 帐户登录和退出将始终使用安全连接执行,和应用程序的网址如何配置无关。
需要登录或管理员身份
任何网址处理程序都可以使用 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
中指定新值,它将覆盖该值。要扩展该样式,请将它和扩展名一起复制并粘贴到您的配置中。例如,要跳过文件名以 .bak
结尾的文件(除默认样式外),可使用 skip_files
的如下列表值:
skip_files:
- ^(.*/)?app/.yaml
- ^(.*/)?app/.yml
- ^(.*/)?index/.yaml
- ^(.*/)?index/.yml
- ^(.*/)?#.*#
- ^(.*/)?.*~
- ^(.*/)?.*/.py[co]
- ^(.*/)?.*/RCS/.*
- ^(.*/)?/..*
- ^(.*/)?.*/.bak$
参考 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