appengine-web.xml 参考

区域 ID

REGION_ID 是 Google 根据您在创建应用时选择的地区分配的缩写代码。此代码不对应于国家/地区或省,尽管某些地区 ID 可能类似于常用国家/地区代码和省代码。在 App Engine 网址中包含 REGION_ID.r 对于现有应用是可选的,但在不久后将成为对所有新应用的要求。

为了确保顺利过渡,我们正在逐步更新 App Engine 以使用地区 ID。如果我们尚未更新您的 Google Cloud 项目,则您不会看到应用的地区 ID。由于该 ID 对于现有应用是可选的,因此您在现有应用可以使用地区 ID 后无需更新网址或进行其他更改。

详细了解地区 ID

除了 web.xml 部署描述符,App Engine Java 应用使用名为 appengine-web.xml 的配置文件指定有关应用的信息,并确定应用的 WAR 文件中哪些文件是静态文件(如图片),哪些文件是应用使用的资源文件。

示例

以下示例是一个可指定应用 ID、版本标识符以及无静态文件或资源文件的极小文件:

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>_your_app_id_</application><!-- unused for Cloud SDK based tooling -->
  <version>alpha-001</version><!-- unused for Cloud SDK based tooling -->
  <threadsafe>true</threadsafe>
  <runtime>java8</runtime>
</appengine-web-app>

语法

App Engine Java 应用必须在其 WAR 的 WEB-INF/ 目录中包含一个名为 appengine-web.xml 的文件。这是一个根元素为 <appengine-web-app> 的 XML 文件。

您可以在 SDK 的 docs/ 目录中找到 appengine-web.xml 的文档类型定义和架构规范。

元素 说明
<application>

如果您使用基于 Cloud SDK 的工具(如 gcloud app deploy 命令、IntelliJ 或 Eclipse 插件、Maven 或 Gradle 插件)部署应用,则不需要。基于 Cloud SDK 的工具会忽略此元素,并且从 gcloud 配置项目属性中获取项目 ID。请注意,虽然您可以使用 gcloud 命令行工具替换项目 ID,但这会在整个计算机范围内设置项目 ID,因此,如果您正在开发多个项目,这可能会引起混乱。 <application> 元素包含应用的项目 ID。这是您在 Google Cloud Console 中创建项目时注册的项目 ID。当您上传应用时,appcfg 会从此文件中获取项目 ID。

<async-session-persistence>

可选。通过将应用配置为在数据存储区中异步写入 HTTP 会话数据,可以缩短请求延迟时间:


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <async-session-persistence enabled="true" />
  <!-- ... -->
</appengine-web-app>

启用异步会话持久性后,App Engine 将提交任务队列任务,先将会话数据写入数据存储区中,然后再将该数据写入到 memcache 中。 默认情况下,任务会提交到“默认”队列。 如果您想使用其他队列,请添加“queue-name”属性:


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <async-session-persistence enabled="true" queue-name="myqueue"/>
  <!-- ... -->
</appengine-web-app>

会话数据始终同步写入 Memcache 中。 如果请求尝试在 Memcache 不可用(或会话数据已清空)时读取会话数据,则将故障转移到可能尚不具有最新会话数据的数据存储区。这意味着异步会话持久性可能导致应用查看过时的会话数据。不过,对于大多数应用而言,延时优势远远超过风险。

<auto-id-policy> 可选。如果您目前采用的是自动设置实体标识符的方式,则可以通过设置自动 ID 政策来更改所使用的方法。以下是有效选项:
default
默认。使用分散的自动 ID,这些 ID 是分布均匀的大整数,小到可以由 64 位浮点数表示。
legacy
未来版本将弃用旧选项,并最终移除这些选项。如需了解详情,请参阅宣布此变化的博文
<automatic-scaling>

可选。如需了解完整说明,请参阅自动调节部分。

<basic-scaling>

可选。如需了解完整说明,请参阅基本调节部分。

<env-variables>

可选。appengine-web.xml 文件可以定义在应用运行时设置的环境变量。


<env-variables>
  <env-var name="DEFAULT_ENCODING" value="UTF-8" />
</env-variables>

为避免与本地环境发生冲突,开发服务器不会根据此文件设置环境变量,而会要求本地环境已将这些变量设置为匹配值。


export DEFAULT_ENCODING="UTF-8"
dev_appserver war

部署到 App Engine 时,环境是使用已设置的这些变量创建的。

<inbound-services>

可选。应用可以接收电子邮件之前,必须配置成启用该服务。 如要为 Java 8 应用启用该服务,您可以在 appengine-web.xml 文件中添加 <inbound-services> 部分。

以下入站服务可用:

mail
允许您的应用接收邮件
<instance-class>

可选。此模块的实例类大小。

在指定不同的调节选项时,以下实例类可用:

automatic_scaling
使用自动扩缩时,F1、F2、F4 和 F4_1G 实例类别可用。
默认:如果您未将实例类与 automatic_scaling 元素一起指定,则系统会分配 F1。
basic_scaling
使用基本扩缩时,B1、B2、B4、B4_1G 和 B8 实例类别可用。
默认:如果您未将实例类与 basic_scaling 元素一起指定,则系统会分配 B2。
manual_scaling
使用手动扩缩时,B1、B2、B4、B4_1G 和 B8 实例类别可用。
默认:如果您未将实例类与 manual_scaling 元素一起指定,则系统会分配 B2。

注意:如果 instance-class被设置为 F2 或更高级别,您可以将 max-concurrent-requests 设置为大于 10(默认值)的值来优化实例。要找到最佳值,请逐渐增加值,同时监控应用的性能。

<manual-scaling>

可选。如需了解完整说明,请参阅手动调节部分。

<precompilation-enabled>

可选。在 Java 运行时环境中,App Engine 结合使用“预编译”过程与应用的 Java 字节码来提高应用性能。 预编译的代码与原始字节码的功能完全相同。

如果您由于某种原因不希望应用使用预编译,可以在 appengine-web.xml 文件中添加以下内容以将其禁用:


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <precompilation-enabled>false</precompilation-enabled>
  <!-- ... -->
</appengine-web-app>
module

注意 :模块现在命名为 Services,而服务在 appengine-web.xml 文件中仍声明为模块,例如:<module>service_name</module>

在创建服务时是必需的。 对于默认服务是可选的。 每项服务和每个版本都必须有自己的名称。名称可以包含数字、字母和连字符。它不能超过 63 个字符,以连字符开头或结尾,并且包含字符串“-dot”。为每项服务和每个版本选择一个唯一的名称。服务名称和版本名称不得重复。

另请参阅 service

<public-root>

可选。<public-root> 是应用中的目录,其中包含应用的静态文件。向静态文件发出请求时,应用的 <public-root> 会被附加到请求路径。这提供的应用文件路径包含正在请求的内容。

<public-root> 的默认值为 /

例如,以下代码会将网址路径 /index.html 映射到应用文件路径 /static/index.html


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <public-root>/static</public-root>
  <!-- ... -->
</appengine-web-app>
<resource-files>

可选。<resource-files> 元素中列出的文件可通过使用文件系统的应用代码进行访问。这些文件通过应用存储在应用服务器上,与存储和处理静态文件的方式截然相反。

<resource-files> 元素可以包含以下元素:

<include>
<include> 元素将文件指定为资源文件,以供您的应用代码使用。这些文件仅以只读方式提供给您的代码,而不适用于流量处理。 包含和排除文件
<exclude>

<exclude> 模式匹配的文件和目录不会被上传或被应用代码使用。不过,在本地开发服务器上运行时,您的应用仍然可以访问这些文件和目录。如需了解详情,请参阅包含和排除文件

例如:

<resource-files>
  <include path="/**.xml" />
  <exclude path="/feeds/**.xml" />
</resource-files>

此示例演示了如何将所有 .xml 文件指定为资源文件,但 feeds/ 目录及其所有子目录中的文件除外。

使用 java.io.Filejavax.servlet.ServletContext.getResource/getResourceAsStream 读取 App Engine 资源文件。他们无法通过 Class.getResourceAsStream() 访问。

runtime

如要使用 Java 8 运行时,必须使用值 java8 指定此条目。

示例


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <runtime>java8</runtime>
  <!-- ... -->
</appengine-web-app>
service

Service 以前被称为 Module

目前,只有 gcloud app 命令支持将服务定义为 <service>service_name</service >

<sessions-enabled>

可选。App Engine 包含使用 servlet 会话界面的会话实现。 该实现将会话数据存储在数据存储区以实现持久化,并使用 Memcache 来提高速度。 与大多数其他 servlet 容器一样,请求期间使用“session.setAttribute()”设置的会话属性将在请求结束后持续存在。

默认情况下,此功能处于关闭状态。 如要将其启用,请在 appengine-web.xml 中添加以下内容:

示例

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <sessions-enabled>true</sessions-enabled>
  <!-- ... -->
</appengine-web-app>

该实现使用前缀为 _ahs 的键创建 _ah_SESSION 种类的 Datastore 实体和内存缓存条目。您可以使用 Dataflow 模板来删除这些实体。

注意:由于 App Engine 在 Datastore 和 Memcache 中存储会话数据,因此会话中存储的所有值都必须实现 java.io.Serializable 接口。

请参阅 async-session-persistence 元素,了解如何减少会话数据存储的延迟时间。

<ssl-enabled>

可选。默认情况下,任何用户都可以使用 HTTP 或 HTTPS 访问任何网址。 您可以在部署描述符中将应用配置为需要使用 HTTPS 访问某些网址。请参阅部署描述符:安全网址

如果要禁止应用使用 HTTPS,请在 appengine-web.xml 文件中添加以下内容:


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <ssl-enabled>false</ssl-enabled>
  <!-- ... -->
</appengine-web-app>

在 Java 运行时环境中,无法禁止某些网址路径使用 HTTPS,但可以禁止其余路径使用。

<static-error-handlers>

可选。在发生某些错误时,App Engine 将传送一个常规错误页面。 您可以将应用配置为传送自定义静态文件,而不是这些常规错误页面,但前提是自定义错误数据要小于10 KB。可通过在应用的 appengine-web.xml 文件中指定文件,为每种支持的错误代码设置不同的静态文件。如要提供自定义错误页面,请在 appengine-web.xml 中添加 <static-error-handlers> 部分,如下例所示:


<static-error-handlers>
  <handler file="default_error.html" />
  <handler file="over_quota.html" error-code="over_quota" />
</static-error-handlers>

警告:确保错误响应文件的路径不和静态文件处理程序路径重叠。

每个 file 条目表示一个应该用来替代常规错误响应的静态文件。error-code 表示哪个错误代码将导致提供关联文件。支持的错误代码如下所示:

over_quota
表示应用已超出资源配额
dos_api_denial
此选项为您应用的 DoS Protection 配置阻止的所有客户端传送此错误页面。
timeout
如果截止时间已到而应用未响应,则提供此错误代码。

error-code 是可选的;如果未指定,则给定文件是应用的默认错误响应。

您可以选择指定在处理自定义错误时使用的 mime-type。查看 MIME 类型的完整列表

<static-files>

可选。<static-files> 元素指定与文件路径匹配的模式,以包含和排除静态文件列表、替换或修改默认行为。静态文件是由专用服务器和缓存传送的,这些服务器和缓存不会受应用服务器的影响,对提供静态内容(如图片、CSS 样式表或 JavaScript 文件)非常有用。

<static-files> 元素可以包含以下元素:

<include>

<include> 元素将替换包含所有非 JSP 文件的默认行为。<include> 元素可以指定在响应指定资源的请求时使用的 HTTP 标头。如需了解详情,请参阅包含和排除文件

您可以通过在 include 元素上指定 expiration 属性来替换默认静态缓存到期时间。该值是一个用空格分隔的数字和单位字符串,其中,单位可以是 d(表示天)、h(表示小时)、m(表示分钟)和 s(表示秒)。例如,"4d 5h" 将缓存到期时间设置为首次请求文件后的 4 天 5 小时。如需了解详情,请参阅缓存到期时间

<exclude>
在将应用部署到 App Engine 时,系统不会上传与 <exclude> 模式匹配的文件和目录。不过,在本地开发服务器上运行时,您的应用仍然可以访问这些文件和目录。如需了解详情,请参阅包含和排除文件
示例

<static-files>
  <include path="/my_static-files" >
    <http-header name="Access-Control-Allow-Origin"
                 value="http://example.org" />
  </include>
</static-files>
<system-properties>

可选。appengine-web.xml 文件可以定义在应用运行时设置的系统属性和环境变量。


<system-properties>
  <property name="myapp.maximum-message-length" value="140" />
  <property name="myapp.notify-every-n-signups" value="1000" />
  <property name="myapp.notify-url"
            value="http://www.example.com/signupnotify" />
</system-properties>

<env-variables>
  <env-var name="DEFAULT_ENCODING" value="UTF-8" />
</env-variables>
<threadsafe>

必需。当 appengine-web.xml 中的 threadsafe 元素为 false 时,App Engine 会向给定网络服务器连续发送请求。当该值为 true 时,App Engine 可以并行发送多个请求:


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <threadsafe>true</threadsafe>
  <!-- ... -->
</appengine-web-app>

如果您希望使用并发请求,则在您启用 threadsafe 之前,您的应用代码需要使用正确的线程同步。

<url-stream-handler>

可选。可能的值,nativeurlfetch

默认值为 native,这表示标准 Java 网络类使用标准 Java HTTP(S)传输。如要使用此设置,您必须为您的应用启用结算功能,否则系统会在问题请求中记录例外情况。

如果您将 url-stream-handler 设置为 urlfetchURL.openConnection,则相关方法将对 httphttps 传输使用网址提取。


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <url-stream-handler>urlfetch</url-stream-handler>
  <!-- ... -->
</appengine-web-app>
<version>

<version> 元素包含应用代码的最新版本的版本标识符。版本标识符可以包含小写字母、数字和连字符。其开头不能为前缀“ah-”,并且名称“default”和“latest”会被保留,无法使用。

版本名称应以字母开头,以便与始终由数字指定的数字实例区分开来。 这样可以避免网址(如123.my-module.uc.r.appspot.com)的不确定性,它可以通过两种方式来解读:如果存在“123”,则目标将是指定模块的“ 123”。如果该版本不存在,则目标是默认版本模块的实例编号 123。

appcfg 命令会在上传应用时使用此版本标识符,告知 App Engine 使用给定标识符创建新版本的应用,或使用给定标识符替换应用版本(如果已存在)。您可以使用网址中将“-dot-”作为子网域分隔符的网址(例如 https://VERSION_ID-dot-default-dot-PROJECT_ID.REGION_ID.r.appspot.com)来测试应用的新版本。通过 Google Cloud Console,您可以选择应用的默认版本。如果未指定版本或指定了无效版本,则系统会加载默认版本。

<warmup-requests-enabled>

可选。默认值:true。对于 Java 8 应用,默认启用了预热请求。

启用预热请求后,App Engine 基础架构会向 /_ah/warmup 发出“GET”请求,初始化 <load-on-startup> servlet、ServletContextListeners自定义预热 servlet,可让您根据需要初始化应用的代码。您可能需要为 /_ah/warmup 实现自定义处理程序,具体取决于您选择哪些方法。

如要停用预热请求,请为以下元素指定 false


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <warmup-requests-enabled>false</warmup-requests-enabled>
  <!-- ... -->
</appengine-web-app>
<vpc-access-connector>

可选。将应用配置为使用 Serverless VPC Access 连接器,使应用能够将请求发送到 VPC 网络中的内部资源。在 <name> 元素中指定连接器的完全限定名称:


<vpc-access-connector>
  <name>projects/[PROJECT_ID]/locations/[REGION]/connectors/[CONNECTOR_NAME]</name>
</vpc-access-connector>

如需了解详情,请参阅连接到 VPC 网络中的内部资源

扩缩元素

下表列出了可供您用来指定如何扩缩应用的一些选项。

如需了解各类扩缩类型性能功能的比较情况,请参阅扩缩动态实例

元素 说明
<automatic-scaling>

可选。除非另有说明,否则,系统默认采用自动扩缩,并以 F1 作为默认实例类。

automatic_scaling 元素可设置模块的实例数、延迟时间和并发连接数上下限。

该元素可以包含以下元素:

<target-cpu-utilization>
可选。指定 0.5 至 0.95 之间的值。

此参数指定需要启动新实例来处理流量时的 CPU 使用率阈值,使您能够在性能和费用之间取得平衡,较低的值表示性能提升和费用增加,而较高的值表示性能和费用下降。例如,0.7 表示 CPU 使用率达到 70% 后会启动新实例。

重要提示:如果您使用 Java 版 App Engine SDK 中的 appcfg 命令进行部署,则不能在 appengine-web.xml 中使用此参数。而是应按照在 API Explorer 中设置自动扩缩参数中的说明或使用 App Engine Admin API 设置此参数。

<target-throughput-utilization>
可选。指定 0.5 至 0.95 之间的值。

max-concurrent-requests 搭配使用,用于指定何时因并发请求而启动新实例。当并发请求数达到 max-concurrent-requests 乘以 target-throughput-utilization 的值时,调度程序将启动一个新实例。

重要提示:如果您使用 Java 版 App Engine SDK 中的 appcfg 命令进行部署,则不能在 appengine-web.xml 中使用此参数。而是应按照在 API Explorer 中设置自动扩缩参数中的说明或使用 App Engine Admin API 设置此参数。

<max-instances>
可选。App Engine 可为此应用版本创建的最大实例数。这对限制模块费用非常有用。请指定一个介于 0 到 2147483647 之间的值。

重要提示:如果您使用 Java 版 App Engine SDK 中的 appcfg 进行部署,则不能在 appengine-web.xml 中使用此参数。而是应按照在 API Explorer 中设置自动扩缩参数中的说明或使用 App Engine Admin API 设置此参数。

<min-instances>
可选。App Engine 可为此模块版本创建的最小实例数。这些实例在请求到达时处理流量,即便在必要时启动了其他实例来处理流量,这些实例也会继续处理流量。

指定 0 至 1000 之间的值。您可以将此参数的值设置为 0,以允许扩缩到 0 个实例,这样可以在未处理任何请求时降低费用。请注意,您需要为指定的实例数支付费用,无论这些实例是否接收流量。

重要提示:如果您使用 Java 版 App Engine SDK 中的 appcfg 进行部署,则不能在 appengine-web.xml 中使用此参数。而是应按照在 API Explorer 中设置自动扩缩参数中的说明或使用 App Engine Admin API 设置此参数。

<max-concurrent-requests>

可选。在调度程序生成新实例之前,自动调节实例可以接受的并发请求数(默认值:10;最大值:80)。

如果此设置太高,您可能会遇到 API 延迟时间增加的情况。请注意,调度程序可能会在达到实际最大请求数之前生成新实例。

注意:如果 instance-class 设置为 F2 或更高级别,您可以将 max-concurrent-requests 设置为大于 10(默认值)的值来优化实例。要找到最佳值,请逐渐增加值,同时监控应用的性能。

<max-idle-instances>

App Engine 应为此版本保留的最大空闲实例数。 默认值为“automatic”。请谨记以下内容:

  • 如果设置的最大值较高,那么当负载水平在峰值后恢复正常时,空闲实例数会较为平缓地逐渐减少。这有助于您的应用在请求负载发生波动期间保持稳定的性能,但也会增加负载繁重时段的空闲实例数(从而增加运行费用)。
  • 设置较低的最大值有助于保持较低的运行费用,但在负载水平波动期间可能会降低性能。

注意:当负载水平在峰值过后恢复到正常水平时,空闲实例数可能会暂时超出您指定的最大值。不过,对于这些多出的实例,您不需要支付费用。

<max-pending-latency>

在启动其他实例处理请求以缩短等待延迟时间之前,App Engine 允许请求在待处理队列中等待的最长时间。默认值为“30ms”。

  • 较低的最大值意味着 App Engine 将更快为待处理请求启动新实例,从而提高性能,但会增加运行费用。
  • 较高的最大值意味着用户可能需要等待更长时间才能处理其请求(如果有待处理请求且没有空闲实例来处理这些请求),但您的应用运行时费用会降低。
<min-idle-instances>

要保持运行并准备处理流量的实例数。此设置仅适用于接收大部分流量的版本。请记住以下内容:

  • 较低的最小值有助于在空闲期间降低您的运行费用,但也意味着突然发生负载峰值时可立即使用的实例会更少。
  • 设置较高的最小值有助于应用自如应对突然出现的请求负载峰值。App Engine 保持运行最小实例数来处理传入请求。不论实例是否在处理请求,您都需要支付费用。要使此功能正常运行,您必须确保启用预热请求,并让您的应用处理预热请求。

    如果您设置了最小空闲实例数,则等待延迟时间对应用性能的影响会更小。由于 App Engine 保留有空闲实例,因此除非出现特别高的负载峰值,否则请求不可能进入待处理队列。 您需要测试应用和预期流量,以确定理想的保留实例数。

<min-pending-latency>

在启动新实例处理请求之前,App Engine 允许请求在待处理队列中等待的最短时间(以秒为单位)。 指定一个介于 0.01 到 15 之间的值。

  • 较低的最小值意味着,当所有现有实例都处于活跃状态时,请求在待处理队列中需要等待的时间更短。这有助于提高性能,但同时会增加应用的运行费用。
  • 设置较高的最小值意味着,如果所有现有实例都处于活跃状态,请求处于待处理状态的时间会更长。这在降低运行费用的同时,会增加用户必须等待处理请求的时间。
示例

<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>simple-app</application>
  <module>default</module>
  <version>uno</version>
  <threadsafe>true</threadsafe>
  <instance-class>F2</instance-class>
  <automatic-scaling>
    <target-cpu-utilization>0.65</target-cpu-utilization>
    <min-instances>5</min-instances>
    <max-instances>100</max-instances>
    <max-concurrent-requests>50</max-concurrent-requests>
  </automatic-scaling>
</appengine-web-app>
<basic-scaling>

可选。<basic-scaling> 元素用于设置模块的实例数。

该元素可以包含以下元素:

<idle-timeout>
可选。实例在收到最后一个请求后,再经过该值指定的时间即会关停。默认值为 5 分钟。
<max-instances>
必需。App Engine 可为此模块版本创建的最大实例数。这对限制模块费用非常有用。
示例

<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>simple-app</application>
  <module>default</module>
  <version>uno</version>
  <threadsafe>true</threadsafe>
  <instance-class>B8</instance-class>
  <basic-scaling>
    <max-instances>11</max-instances>
    <idle-timeout>10m</idle-timeout>
  </basic-scaling>
</appengine-web-app>
<manual-scaling>

可选。<manual-scaling> 元素可为模块启用手动扩缩,并为模块设置实例数。

该元素可以包含以下元素:

<instances>
在开始时分配给模块的实例数。
示例

<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>simple-app</application>
  <module>default</module>
  <version>uno</version>
  <threadsafe>true</threadsafe>
  <instance-class>B8</instance-class>
  <manual-scaling>
    <instances>5</instances>
  </manual-scaling>
</appengine-web-app>

暂存元素

部署期间本地完成的很多工作都发生在名为暂存的准备步骤,其中包括汇编 JAR 文件、编译 JSP 等等。 您可以使用应用配置文件中的暂存元素,选择性地配置暂存行为的某些部分。 大多数应用不需要手动配置暂存行为,即可成功部署。如果您的应用未部署,您可能需要使用以下选项配置暂存。

元素 说明
<staging>

可选。大多数应用都不需要更改默认行为。

如果部署需要,暂存元素允许您指定一个特定的暂存配置。

该元素可以包含以下元素:

<enable-jar-splitting>

可选。将大型 jar 文件(> 10 兆字节)拆分为较小的片段文件。 (默认值:true)。

<jar-splitting-excludes>

指定以逗号分隔的文件后缀列表。如果启用了 enable-jar-splitting,则从所有 JAR 中排除与后缀匹配的所有文件。

<disable_jar_jsps>

不要将 JSP 生成的类处理为 jar。 (默认值:false)。

<enable-jar-classes>

将 WEB-INF/类的内容处理为 Jar。 (默认值:true)。

<delete-jsps>

编译后删除 JSP 源文件。 (默认值:true)。

<compile-encoding>

输入源文件的编码以进行编译。 (默认值:utf-8)。

例如:


        <staging>
          <delete-jsps>false</delete-jsps>
        </staging>
        

暂存选项默认值

暂存选项的默认值会有所不同,具体取决于您是使用基于 App Engine SDK 的工具(如 appcfg),还是使用基于 Cloud SDK 的工具(例如 gcloud 命令行,或者基于 Cloud SDK 的 MavenGradleEclipseIntelliJ 插件)。

暂存元素 基于 App Engine SDK 的默认值 - 基于 Cloud SDK 的默认值
enable-jar-splitting false true
jar-splitting-excludes NA
disable-jar-jsps false false
enable-jar-classes false true。这会影响类加载顺序,因此,如果您的应用依赖于使用之前的 false 默认值的特定顺序,则可以将此设置为 false
delete-jsps false true
compile-encoding utf-8 utf-8

包含和排除语法

路径模式是使用零个或多个 <include><exclude> 元素指定的。在模式中,'*' 表示文件或目录名称中的零个或多个任意字符,** 表示路径中的零个或多个目录。在将应用部署到 App Engine 时,系统不会上传与 <exclude> 模式匹配的文件和目录。不过,在本地开发服务器上运行时,您的应用仍然可以访问这些文件和目录。

<include> 元素替换将所有文件包含在内的默认行为。<exclude> 元素在所有 <include> 模式之后应用(如果未提供显式 <include>,则应用此默认元素)。

以下示例说明了如何将所有 .png 文件指定为静态文件(data/ 目录及其所有子目录中的文件除外):

<static-files>
  <include path="/**.png" />
  <exclude path="/data/**.png" />
</static-files>

您还可以设置响应对这些静态资源的请求时要使用的 HTTP 标头。

<static-files>
  <include path="/my_static-files" >
    <http-header name="Access-Control-Allow-Origin"
                 value="http://example.org" />
  </include>
</static-files>

静态文件的 MIME 类型

默认情况下,静态文件是使用根据文件扩展名选择的 MIME 类型提供的。您可以在 web.xml 中使用 <mime-mapping> 元素将自定义 MIME 类型与静态文件的文件扩展名相关联。如需了解详情,请参阅 Metawerx web.xml 参考 Wiki

URLFetch 超时

您可以为每个 URLFetch 请求设置截止日期。默认情况下,提取截止时间为 5 秒。 如要更改此默认设置,您可以在 appengine-web.xml 配置文件中添加以下设置。指定超时(以秒为单位):

<system-properties>
    <property name="appengine.api.urlfetch.defaultDeadline" value="10"/>
</system-properties>