请求标头和响应

地区 ID

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

详细了解区域 ID

此参考页面详细介绍了受支持的 HTTP 标头以及 App Engine 中的请求和响应限制。要了解 App Engine 如何接收请求和发送响应,请参阅请求的处理方式

请求标头

传入 HTTP 请求包含客户端发送的 HTTP 标头。为保证安全,部分标头在到达应用前由中间代理进行清理、修改或移除。

将从传入请求中移除的标头

如果客户端发送了以下标头,则这些标头会从传入请求中移除:

  • 名称采用 X-Google-* 格式的标头。Google 会预留此名称格式。

  • 名称与 App Engine 专属标头匹配的标头。只有完全匹配、不区分大小写的匹配项才会被移除。例如,名为 X-Appengine-CountryX-AppEngine-Country 的标头将被移除,但 名为 X-Appengine-Cntry 的标头不会被移除。

此外,以下标头会从传入请求中移除,因为它们与客户端和服务器之间的 HTTP 数据传输有关:

  • Accept-Encoding
  • Connection
  • Keep-Alive
  • Proxy-Authorization
  • TE
  • Trailer
  • Transfer-Encoding

例如,服务器可能会自动发送使用经过 Gzip 压缩的响应,具体取决于 Accept-Encoding 请求标头的值。应用本身不需要知道客户端可以接受哪些内容编码。

请求和 WSGI

服务器会将请求的网址与应用配置文件中的网址格式进行比较,以此确定要调用的 Python 应用对象。然后,服务器会使用 WSGI 标准中定义的参数来调用应用对象。应用对象会执行请求所需的操作,然后准备响应并将其作为字符串列表返回。

大多数应用使用诸如 webapp2 之类的框架来处理 WSGI 请求。 webapp2 作为 Python 2.7 运行时的一部分包含在内。

请求和 CGI

服务器会将请求的网址与应用配置文件中的网址格式进行比较,以此确定要运行的 Python 处理程序脚本。然后,服务器会运行填充了请求数据的脚本。如 CGI 标准中所述,服务器会将请求数据放入环境变量和标准输入流中。脚本会执行请求所需的操作,然后准备响应并将响应置于标准输出流上。

大多数应用使用库来解析 CGI 请求并返回 CGI 响应,例如 Python 标准库中的 cgi 模块,或知道 CGI 协议的网络框架(如 webapp)。如需详细了解环境变量和输入流数据格式,可以参考 CGI 文档。

App Engine 专属标头

作为应用的一项服务,App Engine 会将以下标头添加到所有请求中:

X-Appengine-Country
从中发起请求的国家/地区,用 ISO 3166-1 二位字母国家/地区代码表示。App Engine 根据客户端的 IP 地址来确定此代码。请注意,国家/地区信息并非来自于 WHOIS 数据库;WHOIS 数据库中带有国家/地区信息的 IP 地址可能不会在 X-Appengine-Country 标头中包含国家/地区信息。您的应用应该处理特殊国家/地区代码 ZZ(未知国家/地区)。
X-Appengine-Region
发起请求的区域的名称。此值仅在 X -Appengine-Country 中的国家/地区的上下文中有意义。例如,如果国家/地区为“US”,地区为“ca”,则“ca”表示“加利福尼亚州”,而不是加拿大。如需查看有效地区值的完整列表,请参阅 ISO-3166-2 标准。
X-Appengine-City
从中发起请求的城市的名称。例如,对于从美国山景城 (Mountain View) 发起的请求,其标头值可能为 mountain view。此标头没有标准的有效值列表。
X-Appengine-CityLatLong
从中发起请求的城市的纬度和经度。对于来自美国山景城的请求,此字符串可能为“37.386051,-122.083851”。
X-Cloud-Trace-Context
用于 Cloud TraceCloud Logging 的请求的唯一标识符。 您无法停用此标头或选择跟踪的采样率,因为系统会自动跟踪所有 App Engine 标准环境应用。
X-Forwarded-For: [CLIENT_IP(s)], [global forwarding rule IP]

以逗号分隔的 IP 地址列表,客户端请求通过这些 IP 地址路由。此列表中的第一个 IP 通常是创建请求的客户端的 IP。后续 IP 提供有关代理服务器的信息,这些代理服务器在请求到达应用服务器之前也会对其进行处理。例如:

X-Forwarded-For: clientIp, proxy1Ip, proxy2Ip
X-Forwarded-Proto [http | https]

根据客户端用于连接到应用的协议,显示 httphttps

Google Cloud Load Balancer 会终结所有 https 连接,然后通过 http 将流量转发到 App Engine 实例。例如,如果用户通过 https://PROJECT_ID.REGION_ID.r.appspot.com 请求访问您的网站,则 X-Forwarded-Proto 标头值为 https

此外,App Engine 可能会设置以下供 App Engine 内部使用的标头:

  • X-Appengine-Https
  • X-Appengine-User-IP
  • X-Appengine-Api-Ticket
  • X-Appengine-Request-Log-Id
  • X-Appengine-Default-Version-Hostname
  • X-Appengine-Timeout-Ms
App Engine 服务可以添加其他请求标头:

  • 对于在 app.yaml 中指定的 login:adminlogin:required 处理程序,App Engine 会添加以下标头集:

    • X-Appengine-User-Email,示例标头:“ange@example.com”
    • X-Appengine-Auth-Domain,示例标头:“example.com”
    • X-Appengine-User-ID,示例标头:“100979712376541954724”
    • X-Appengine-User-Nickname,示例标头:“ange”
    • X-Appengine-User-Organization,示例标头:“example.com”
    • X-Appengine-User-Is-Admin,示例标头:“1”
  • 任务队列服务可向请求添加其他标头,从而提供请求中的任务相关详情以及与该任务关联的队列。

  • 来自 Cron 服务的请求会添加以下标头:

    X-Appengine-Cron: true

    请参阅保护 Cron 的网址了解详情。

  • 其他 App Engine 应用发出的请求将包含用于标识发出请求的应用的标头,前提是发出请求的应用使用的是网址提取服务:

    X-Appengine-Inbound-Appid

    如需了解详情,请参阅 App Identity 文档

请求响应

本 HTTP 标头文档仅适用于针对入站 HTTP 请求的响应。该响应在返回客户端之前可以进行修改。 如需了解与 App Engine 代码发起的出站请求相关的 HTTP 标头,请参阅 URLFetch 标头文档

将被移除的标头

下列标头将被忽略并从响应中移除:

  • Connection
  • Content-Encoding*
  • Content-Length
  • Date
  • Keep-Alive
  • Proxy-Authenticate
  • Server
  • Trailer
  • Transfer-Encoding
  • Upgrade

*如果 App Engine 已压缩响应,则可以重新添加此标头。

名称或值中包含非 ASCII 字符的标头也将被移除。

将添加或被替换的标头

下列标头将在响应中添加或被替换:

Cache-ControlExpiresVary

这些标头可以为中间网络代理(例如 Google Frontend 和互联网服务提供商)和浏览器指定缓存政策。如果您的应用设置了这些响应标头,它们通常不会被修改,除非您的应用还设置了 Set-Cookie 标头或者系统为使用管理员帐号登录的用户生成了响应。

如果您的应用设置了 Set-Cookie 响应标头,则 Cache-Control 标头将被设为 private(如果此标头尚未被设为限制性更强的值),Expires 标头将被设为当前日期(如果此标头尚未过期)。通常情况下,这样即可让浏览器而不是中间代理服务器缓存响应。这样做是为了确保安全,因为如果公开缓存响应,则其他用户随后可能会请求同一资源,并检索第一个用户的 Cookie。

如果您使用基于 Webob 的框架(例如 webapp 或 webapp2),则该框架默认将 Cache-Control 标头设置为 no-cache,因此,若您要将它缓存在脚本处理程序,则必须覆盖它。

如果您的应用未设置 Cache-Control 响应标头,则服务器可将其设置为 private 并添加 Vary: Accept-Encoding 标头。

如需详细了解缓存,包括 Google Frontend 支持的 Vary 值列表,请参阅响应缓存

Content-Encoding

如上文所述,服务器可能会自动压缩响应正文,具体取决于请求标头和响应 Content-Type。在这种情况下,它会添加一个 Content-Encoding: gzip 标头来指明正文经过压缩。请参阅响应压缩相关部分,了解详情。

Content-LengthTransfer-Encoding

服务器会始终忽略应用返回的 Content-Length 标头。它要么将 Content-Length 设置为正文的长度(如果应用了压缩,则为压缩后的长度),要么删除 Content-Length 并使用分块传输编码(添加 Transfer-Encoding: chunked 标头)。

Content-Type

如果应用未指定标头,服务器将设置默认的 Content-Type: text/html 标头。

Date

设为当前日期和时间。

Server

设置为 Google Frontend。开发服务器将其设为 Development/x,其中 x 是版本号。

如果您在使用管理员帐号登录时访问网站上的动态页面,则 App Engine 将根据请求在响应标头中加入统计信息:

X-Appengine-Resource-Usage
请求使用的资源,其中包含以毫秒为单位的服务器端时间。

包含使用情况统计信息的响应将无法缓存。

如果 X-Appengine-BlobKey 标头位于应用的响应中,它和可选的 X-Appengine-BlobRange 标头将用于将正文替换为 blobstore blob 的全部或部分内容。如果应用未指定 Content-Type,则将其设置为 blob 的 MIME 类型。如果请求范围,响应状态将更改为 206 Partial Content,并添加 Content-Range 标头。将从响应中移除 X-Appengine-BlobKeyX-Appengine-BlobRange 标头。您通常不需要自行设置这些标头,因为 blobstore_handlers.BlobstoreDownloadHandler 类会设置它们。如需了解详情,请参阅传送 Blob

应用配置中设置的响应标头

根据应用配置文件中的动态和静态路径网址,您可以设置自定义 HTTP 响应标头。如需了解详情,请参阅配置文档中的 http_headers 部分。