Google App Engine 2.1

Google App Engine 2.1
2011年01月31日
　　
App Engine Python 概述欢迎使用 Google App Engine for Python！通过 App Engine，您可以使用 Python 编程语言构建网络应用程序，并利用专业开发人员构建世界级网络应用程序所用的多种针对 Python 的库、工具和框架。您的 Python 应用程序将在 Google 的可扩展基础结构上运行，并使用大型持久性存储和服务。
　　如果您尚未做好准备，请参阅 Python 使用入门指南以获得关于使用 Python 和 Google App Engine 来开发网络应用程序的交互性介绍。
　　Python 运行时环境Python 网络应用程序使用 CGI 协议与 App Engine 网络服务器交互。应用程序可以通过 CGI 适配器使用 WSGI 兼容的网络应用程序框架。App Engine 包含一个称为 webapp 的简单网络应用程序框架，使您易于上手。对于较大的应用程序，诸如 Django 的成熟第三方框架可很好地与 App Engine 配合使用。
　　App Engine 支持 Python 2.5。Python 解释器在一个安全的“沙盒”环境下运行，以便隔离针对服务和安全的应用程序。解释器可运行任何 Python 代码，包括您的应用程序中附带的 Python 模块以及 Python 标准库。解释器不能载入具有 C 代码的 Python 模块，它是一个“纯”Python 环境。
　　沙盒确保了应用程序仅执行不影响其他应用程序的性能和可伸缩性的操作。例如，应用程序不能将数据写入本地文件系统中，也不能建立任意网络连接。应用程序使用 App Engine 提供的可扩展服务来存储数据并通过互联网进行通信。当应用程序尝试从已知不受沙盒限制的标准库中导入模块时，Python 解释器引发异常。
　　有关详细信息，请参阅 CGI 环境。
　　数据存储区和服务应用程序可以使用 App Engine 数据存储区来实现可靠、可扩展的持久数据存储。针对 App Engine 数据存储区的 Python API 包括用于管理数据架构的丰富的数据建模工具。API 支持两种用于执行数据存储区查询的接口，包括也用于管理控制台的类似于 SQL 的查询语言 GQL。
　　App Engine Memcache 提供快速、暂时的分布式存储来缓存数据存储区查询和计算的结果。针对 App Engine Memcache 的 Python 接口与 Python Memcached API 兼容。
　　应用程序使用网址抓取服务来访问网络资源，并且使用 HTTP 和 HTTPS 协议来与其他主机通信。Python 应用程序可以使用来自 Python 标准库的 urllib、urllib2 或 httplib 模块访问此服务，或者可以使用 App Engine 网址抓取服务 API。
　　应用程序可以使用邮件服务，以应用程序管理员或当前登录用户的身份发送电子邮件。
　　应用程序通过图像服务能够转换并处理一些格式的图像数据，包括修剪、旋转、调整大小和照片色彩增强。
　　应用程序可以使用 Google 帐户进行用户验证。Google 帐户处理用户帐户的创建和登录，已拥有 Google 帐户（如 GMail 帐户）的用户可以将该帐户与应用程序结合使用。应用程序可以检测到当前用户的登录时间，并且可以访问该用户的电子邮件地址。Python API 可以在能直接存储在数据存储区中的对象中返回用户数据。
　　计划任务应用程序可以配置将以指定间隔时间调用应用程序网址的计划任务。有关这一点的详细信息，请参阅Cron Job。
　　Python 工具App Engine Python SDK 包括的工具可用于测试应用程序、上传应用程序文件、管理数据存储区索引、下载日志数据以及上传大量数据到数据存储区。
　　开发服务器在您的本地计算机上运行应用程序，以测试您的应用程序。服务器模拟 App Engine 数据存储区、服务和沙盒限制。开发服务器还可以根据应用程序在测试期间执行的查询生成数据存储区索引的配置。
　　称为 appcfg.py 的多用途工具可处理与 App Engine 上所运行的应用程序之间的所有命令行交互。appcfg.py 可将您的应用程序上传到 App Engine，或者只是更新数据存储区索引配置，这样您可以在更新代码之前构建新的索引。AppCfg 还可以下载应用程序的日志数据，这样您可以使用自己的工具来分析应用程序的性能。
　　Python SDK 包括了一个数据上传工具，可将数据从您的本地数据文件添加到应用程序的数据存储区。该工具可从 CSV 文件提取数据，CSV 是一种由大多数电子表格软件（如 Google 文档或 Microsoft Excel）所支持的电子表格格式。您可以使用 Python 代码来自定义如何将 CSV 文件转换为数据存储区实体。
　　Python 运行时环境App Engine 使用预先载入的 Python 解释器在安全的“沙盒”环境中执行 Python 应用程序代码。应用程序收到网络请求、执行操作并通过与此环境交互来发送响应。
　　选择 Python 运行时请求和 CGI响应请求计时器沙盒纯 Python应用程序缓存日志环境配额和限制选择 Python 运行时使用 Python SDK 中名为 appcfg.py 的工具（其配置文件名为 app.yaml）时，App Engine 知道为应用程序代码使用 Python 运行时环境。使用以下配置元素来选择 Python 运行时环境：
　　runtime: pythonapi_version: 1
　　第一个元素 runtime 选择 Python 运行时环境。就本文而言，App Engine 仅支持 python 这一种运行时环境。
　　第二个元素 api_version 选择要使用的 Python 运行时环境的版本。就本文而言，App Engine 仅有1 这一个 Python 环境的版本。如果 App Engine 团队需要发布对可能与现有代码不兼容的环境的更改，他们将使用新版本的标识符来发布。应用程序将继续使用所选择的版本，直到您更改api_version 设置并上传应用程序。
　　有关 app.yaml 和 appcfg.py 的详细信息，请参阅 Python 应用程序配置和上传应用程序。
　　请求和 CGIApp Engine 在收到您的应用程序的网络请求时，会调用与此网址相对应的处理程序脚本（如应用程序的 app.yaml 配置文件中所述）。App Engine 会使用 CGI 标准将请求数据传递到处理程序，并接收响应。
　　App Engine 使用多个网络服务器运行您的应用程序，并自动调整它所使用的服务器数量以便可靠地处理请求。指定的请求可能会传送到任何服务器，而且可能不是处理先前来自同一用户的请求的服务器。
　　服务器通过将请求网址与应用程序配置文件中的网址模式进行比较来确定要运行的 Python 处理程序脚本。然后，它将在填充了请求数据的 CGI 环境中运行处理程序。正如 CGI 标准中所述，服务器会把请求数据置于环境变量和标准输入流中。脚本会执行请求所需的操作，然后准备响应并将响应置于标准输出流上。
　　大多数应用程序会使用一个库来解析 CGI 请求以及返回 CGI 响应，例如，来自 Python 标准库的 cgi 模块或了解 CGI 协议的网络框架（例如 webapp）。要了解有关环境变量和输入流数据格式的详细信息，可以参考 CGI 文档。
　　以下示例处理程序脚本显示了用户浏览器上的消息。它会把标识消息类型和消息内容的 HTTP 标头打印到标准输出流中。
　　print "Content-Type: text/plain"
　　print ""
　　print "Hello, world!"
　　响应App Engine 会收集请求处理程序脚本写入标准输出流的所有数据，然后等待该脚本退出。脚本退出后，所有输出数据均会发送至用户。
　　App Engine 不支持在退出处理程序前将数据发送至用户的浏览器。有些网络服务器将在一段时间内使用该技术将数据“流式处理”到用户的浏览器，以对单个请求做出响应。App Engine 不支持这种流式处理技术。
　　如果客户端发送带有指明该客户端可接受压缩（通过 gzip）内容的请求的 HTTP 标头，则 App Engine 会自动压缩该响应数据并附加相应的响应标头。它同时使用 Accept-Encoding 和 User-Agent 请求标头来确定客户端是否可以可靠地接收压缩响应。自定义客户端可通过指定 Accept-Encoding 和 User-Agent 标头（带有“gzip”值）强行压缩内容。
　　请求计时器请求处理程序对请求生成和返回响应的时间是有限的，通常约为 30 秒。达到限制时间后，请求处理程序将中断。
　　Python 运行时环境通过从包 google.appengine.runtime 中引发 DeadlineExceededError 来中断请求处理程序。如果请求处理程序不捕获此异常，那么和所有未捕获的异常一样，运行时环境将向客户端返回 HTTP 500 服务器错误。
　　请求处理程序可以捕获此错误来自定义响应。运行时环境在引发异常以便准备自定义响应之后，将为请求处理程序提供更多一点的时间（少于一秒）。
　　from google.appengine.runtime import DeadlineExceededError
　　class MainPage(webapp.RequestHandler):
　　def get(self):
　　try:
　　# Do stuff...
　　except DeadlineExceededError:
　　self.response.clear()
　　self.response.set_status(500)
　　self.response.out.write("This operation could not be completed in time...")    
　　如果处理程序在第二个截止时间之前仍未返回响应或引发异常，处理程序将终止，并返回默认错误响应。
　　虽然请求有 30 秒的时间来响应，但 App Engine 针对应用程序进行过优化，请求时间很短，通常只需要几百毫秒。高效的应用程序对大多数的请求都能够很快作出响应。响应不快的应用程序将不能根据 App Engine 基础结构而进行灵活的调整。
　　沙盒为了使得 App Engine 能够跨多个网络服务器分配对于应用程序的请求，并且防止应用程序彼此干扰，请在受限制的“沙盒”环境中运行应用程序。在这种环境中，该应用程序可执行代码；可存储和查询 App Engine 数据存储区中的数据；可使用 App Engine 邮件、网址抓取和用户服务；可检查用户的网络请求以及准备响应。
　　App Engine 应用程序无法：
　　向文件系统写入。应用程序必须使用 App Engine 数据存储区存储永久数据。允许从文件系统中读取，并且可使用与该应用程序一起上传的所有应用程序文件。打开套接字或直接访问另一主机。应用程序可使用 App Engine 网址抓取服务分别向端口 80 和 443 上的其他主机发出 HTTP 和 HTTPS 请求。产生子进程或线程。必须在几秒钟内于单个进程中处理对应用程序的网络请求。响应时间很长的进程会被终止，以避免使网络服务器负载过重。进行其他类型的系统调用。纯 PythonPython 运行时环境使用 Python 2.5.2。
　　适用于 Python 运行时环境的所有代码必须是纯 Python，且不包括任何 C 扩展程序或其他必须编译的代码。
　　该环境包括 Python 标准库。有些模块已被禁用，因为 App Engine 不支持其核心函数（例如，联网或写入到文件系统）。此外，os 模块可用，但其不支持的功能被禁用。尝试导入不支持的模块或使用不支持的功能会引发异常。
　　标准库中的几个模块已替换掉，或已经过自定义，可以与 App Engine 配合使用。例如：
　　cPickle 又名 pickle。不支持 cPickle 特定的功能。列集为空。可以成功导入，但会无法使用。同样，以下模块也为空：imp、ftplib、select、sockettempfile 被禁用，但对 TemporaryFile（又名 StringIO）除外。logging 可用，且强烈建议用户使用！请查看以下信息。除了 Python 标准库和 App Engine 库之外，运行时环境还包括以下第三方库：
　　Django 0.96.1WebOb 0.9PyYAML 3.05您可以通过将代码置于您的应用程序目录中以将其他纯 Python 库添加到该应用程序中。如果您在应用程序目录中创建指向模块目录的符号链接，则 appcfg.py 会跟随此链接，并且将该模块添加到您的应用程序中。
　　Python 模块包括包含您的应用程序根目录（包含 app.yaml 文件的目录）的路径。可通过利用根目录中的路径来使用您在应用程序根目录中创建的模块。请务必在子目录中创建 __init__.py 文件，这样，Python 会把这些子目录识别为数据包。
　　应用程序缓存Python 运行时环境会在单个网络服务器上的请求之间对导入的模块进行缓存，类似于独立 Python 应用程序仅加载一次模块的方式（即使模块由多个文件导入）。如果处理程序脚本提供 main() 例行程序，则运行时环境也会缓存脚本。否则，就会对每个请求加载处理程序脚本。
　　应用程序缓存在响应时间方面有明显的优势。我们建议所有的应用程序都使用 main() 例行程序，如下所述。
　　缓存导入的内容为了提高效率，网络服务器会将导入的模块保存在内存中，并且对于同一服务器上的相同应用程序的后续请求，就不再重新加载或重新评估这些模块。大多数模块不会初始化任何全局数据，或在导入时没有其他副作用，所以缓存它们不会更改应用程序的行为。
　　如果您的应用程序导入的模块取决于针对每个请求进行评估的模块，则应用程序必须调整该缓存行为。
　　以下示例演示了缓存导入的模块的方式。由于 mymodule 只对一个网络服务器导入一次，所以全局mymodule.counter 只会对服务器提出的第一次请求初始化为 0。后续请求则使用来自前一个请求的值。
　　### mymodule.py
　　counter = 0
　　def increment():
　　global counter
　　counter += 1
　　return counter
　　### myhandler.py
　　import mymodule
　　print "Content-Type: text/plain"
　　print ""
　　print "My number: " + str(mymodule.increment())
　　这会输出 My number: #，其中 # 是处理请求的网络服务器调用该处理程序的次数。
　　处理程序脚本也可以进行缓存您可以让 App Engine 除缓存导入模块之外，还对处理程序脚本本身进行缓存。如果处理程序脚本定义了一个名为 main() 的函数，则会缓存脚本及其全局环境，就像缓存导入的模块一样。指定网络服务器上脚本的第一个请求会正常评估脚本。对于后续请求，App Engine 则会调用缓存的环境中的main() 函数。
　　要缓存处理程序脚本，App Engine 必须能够调用不带参数的 main()。如果处理程序脚本没有定义main() 函数，或 main() 函数需要参数（没有默认值），则 App Engine 将针对每个请求加载和评估整个脚本。
　　将解析的 Python 代码保留在内存中可节省时间并加快响应的速度。缓存全局环境也有其他潜在作用：
　　编译的正则表达式。所有正则表达式都以编译的形式进行解析和存储。您可以在全局变量中存储编译的正则表达式，然后使用应用程序缓存以在请求之间重复使用编译的对象。GqlQuery 对象。创建 GqlQuery 对象时，会解析 GQL 查询字符串。重复使用具有参数绑定和bind() 方法的 GqlQuery 对象要比每次都重新构建对象更快。您可为全局变量中的值存储具有参数绑定的 GqlQuery 对象，然后通过对每个请求绑定新参数值来重复使用该对象。配置和数据文件。如果您的应用程序加载和解析来自文件的配置数据，它可以在内存中保留解析的数据，以免对每个请求都重新加载文件。处理程序脚本应在导入时调用 main()。App Engine 希望导入脚本将调用 main()，所以 App Engine 首次在服务器上载入请求处理程序时不调用它。
　　以下示例使用处理程序脚本的全局环境的缓存，可实现与前面的示例相同的操作：
　　### myhandler.py
　　# A global variable, cached between requests on this web server.
　　counter = 0
　　def main():
　　global counter
　　counter += 1
　　print "Content-Type: text/plain"
　　print ""
　　print "My number: " + str(counter)
　　if __name__ == "__main__":
　　main()
　　注意：请勿在请求之间“泄漏”用户特定的信息。除非需要缓存，否则请避免使用全局变量，且一律在 main() 例行程序内初始化请求特定的数据。
　　具有 main() 的应用程序缓存在应用程序的响应时间方面有明显改善。我们建议将其用于所有应用程序。
　　日志App Engine 网络服务器会捕捉处理程序脚本写入标准输出流，以响应网络请求的所有内容。它还会捕捉处理程序脚本写入标准错误流的所有内容，并将其存储为日志数据。您可以使用管理控制台查看和分析您的应用程序的日志数据，或使用 appcfg.py request_logs 下载日志数据。
　　App Engine Python 运行时环境包括对日志模块的特殊支持，请从 Python 标准库了解日志概念，例如日志级别（“调试”、“信息”、“警告”、“错误”、“严重”）。
　　import logging
　　from google.appengine.api import users
　　from google.appengine.ext import db
　　user = users.get_current_user()
　　if user:
　　q = db.GqlQuery("SELECT * FROM UserPrefs WHERE user = :1", user)
　　results = q.fetch(2)
　　if len(results) > 1:
　　logging.error("more than one UserPrefs object for user %s", str(user))
　　if len(results) == 0:
　　logging.debug("creating UserPrefs object for user %s", str(user))
　　userprefs = UserPrefs(user=user)
　　userprefs.put()
　　else:
　　userprefs = results[0]
　　else:
　　logging.debug("creating dummy UserPrefs for anonymous user")
　　环境执行环境包含多个对应用程序有用的环境变量。这些环境变量中有一些是 App Engine 特有的，而其他的则是 CGI 标准的一部分。Python 代码可使用 os.environ 参照表访问这些变量。
　　以下环境变量是 App Engine 特有的：
　　APPLICATION_ID：当前运行的应用程序的 ID。CURRENT_VERSION_ID：当前运行的应用程序的主要版本和次要版本，表示为“X.Y”。在应用程序的 app.yaml 文件中指定了主要版本号（“X”）。将应用程序的每个版本上传到 App Engine 时，都会自动设置次要版本号（“Y”）。在开发网络服务器上，次要版本号一律为“1”。AUTH_DOMAIN：用于通过用户 API 验证用户的域。在 appspot.com 上托管的应用程序具有gmail.com 的 AUTH_DOMAIN，并且可以接受任何 Google 帐户。通过使用 Google 企业应用套件在自定义域上托管的应用程序具有 AUTH_DOMAIN（相当于该自定义域）。以下环境变量属于 CGI 标准的一部分，且在 App Engine 中具有特殊的行为：
　　SERVER_SOFTWARE：在开发网络服务器中，该值为“Development/X.Y”，其中“X.Y”为此运行时的版本。其他环境变量则根据 CGI 标准进行设置。有关这些变量的详细信息，请参阅 CGI 标准。
　　提示：以下 webapp 请求处理程序将在浏览器中显示对应用程序可见的每个环境变量。
　　from google.appengine.ext import webapp
　　import os
　　class PrintEnvironmentHandler(webapp.RequestHandler):
　　def get(self):
　　for name in os.environ.keys():
　　self.response.out.write("%s = %s
\n" % (name, os.environ[name]))
　　配额和限制对应用程序的每个传入请求都会计算在请求配额内。
　　作为请求的一部分所接收的数据会计算在传入带宽（计费）配额内。作为对请求的响应所发送的数据会计算在传出带宽（计费）配额内。
　　HTTP 和 HTTPS（安全）请求都会计算在请求、传入带宽（计费）和传出带宽（计费）配额内。管理控制台的“配额详细信息”页也出于信息方面的考虑，将安全请求、安全传入带宽和安全传出带宽报告为单独的值。只有 HTTPS 请求计算在这些值内。
　　执行请求处理程序所花费的 CPU 处理时间会计算在 CPU 时间（计费）配额内。
　　有关配额的详细信息，请参阅配额，以及管理控制台的“配额详细信息”部分。
　　除了配额以外，请求处理程序还遵循以下限制i：
　　限制值请求大小10 兆字节响应大小10 兆字节请求持续时间30 秒同时动态请求30 *应用程序文件的最大数目1,000静态文件的最大数目1,000应用程序文件的最大大小10 兆字节静态文件的最大大小10 兆字节所有应用程序和静态文件的最大总大小150 兆字节* 应用程序可以同时处理约 30 个活动的动态请求。这表示平均服务器端请求处理时间为 75 毫秒的应用程序可以达到最高为（1000 毫秒/秒 / 75 毫秒/请求）* 30 = 400 请求/秒的效率，且没有任何额外滞后时间。很大程度上受 CPU 制约的应用程序在长时间请求中可能会出现一些额外滞后时间，以便为分享相同服务器的其他应用程序腾出空间。对于静态文件的请求不受此限制的影响。