区域 ID
REGION_ID
是 Google 根据您在创建应用时选择的区域分配的缩写代码。此代码不对应于国家/地区或省,尽管某些区域 ID 可能类似于常用国家/地区代码和省代码。对于 2020 年 2 月以后创建的应用,REGION_ID.r
包含在 App Engine 网址中。对于在此日期之前创建的现有应用,网址中的区域 ID 是可选的。
详细了解区域 ID。
除了 web.xml
部署描述符,App Engine Java 应用使用名为 appengine-web.xml
的配置文件指定有关应用的信息,并确定应用的 WAR
文件中哪些文件是静态文件(如图片),哪些文件是应用使用的资源文件。
示例
以下示例是一个可指定无静态文件或资源文件的 Java 8 运行时的极小文件:
<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
<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
的文档类型定义和架构规范。
元素 | 说明 |
---|---|
<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 政策来更改所使用的方法。以下是有效选项:
|
<automatic-scaling> |
可选。如需了解完整说明,请参阅自动调节部分。 |
<basic-scaling> |
可选。如需了解完整说明,请参阅基本调节部分。 |
<env-variables> |
可选。 <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 应用启用该服务,您可以在 以下入站服务可用:
|
<instance-class> |
可选。此模块的实例类大小。 在指定不同的调节选项时,以下实例类可用:
|
<manual-scaling> |
可选。如需了解完整说明,请参阅手动调节部分。 |
<precompilation-enabled> |
可选。在 Java 运行时环境中,App Engine 结合使用“预编译”过程与应用的 Java 字节码来提高应用性能。 预编译的代码与原始字节码的功能完全相同。
如果您由于某种原因不希望应用使用预编译,可以在 <?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,而服务在 在创建服务时是必需的。 对于默认服务是可选的。 每项服务和每个版本都必须有自己的名称。名称可以包含数字、字母和连字符。它不能超过 63 个字符,以连字符开头或结尾,并且包含字符串“-dot”。为每项服务和每个版本选择一个唯一的名称。服务名称和版本名称不得重复。 另请参阅 service。 |
<public-root> |
可选。
例如,以下代码会将网址路径 <?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> |
可选。
使用 |
runtime |
如要使用 Java 8 运行时,必须使用值 示例: <?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-account |
可选。借助 <?xml version="1.0" encoding="utf-8"?> <appengine-web-app xmlns="http://appengine.google.com/ns/1.0"> <!-- ... --> <service-account>[SERVICE_ACCOUNT_NAME]@[PROJECT_ID].iam.gserviceaccount.com</service-account> <!-- ... --> </appengine-web-app> |
<sessions-enabled> |
可选。App Engine 包含使用 servlet 会话界面的会话实现。 该实现将会话数据存储在数据存储区以实现持久化,并使用 Memcache 来提高速度。 与大多数其他 servlet 容器一样,请求期间使用“session.setAttribute()”设置的会话属性将在请求结束后持续存在。
默认情况下,此功能处于关闭状态。 如要将其启用,请在 <?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>
该实现使用前缀为
注意:由于 App Engine 在 Datastore 和 Memcache 中存储会话数据,因此会话中存储的所有值都必须实现
请参阅 |
<ssl-enabled> |
可选。默认情况下,任何用户都可以使用 HTTP 或 HTTPS 访问任何网址。 您可以在部署描述符中将应用配置为需要使用 HTTPS 访问某些网址。请参阅部署描述符:安全网址。 如果要禁止应用使用 HTTPS,请在 <?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。可通过在应用的 <static-error-handlers> <handler file="default_error.html" /> <handler file="over_quota.html" error-code="over_quota" /> </static-error-handlers> 警告:确保错误响应文件的路径不和静态文件处理程序路径重叠。
每个
您可以选择指定在处理自定义错误时使用的 |
<static-files> |
可选。
<static-files> <include path="/my_static-files" > <http-header name="Access-Control-Allow-Origin" value="http://example.org" /> </include> </static-files> |
<system-properties> |
可选。 <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> |
必需。当 <?xml version="1.0" encoding="utf-8"?> <appengine-web-app xmlns="http://appengine.google.com/ns/1.0"> <!-- ... --> <threadsafe>true</threadsafe> <!-- ... --> </appengine-web-app>
如果您希望使用并发请求,则在您启用 Java 11+ 运行时不支持此元素。 |
<url-stream-handler> |
可选。可能的值, 默认值为 如果您将 <?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> |
版本名称应以字母开头,以便与始终由数字指定的数字实例区分开来。 这样可以避免网址(如
App Engine 使用此版本标识符来确定是否使用给定标识符创建新版本的应用(如果给定版本已存在,则使用给定标识符替换应用版本)。您可以使用网址中将“-dot-”作为子网域分隔符的网址(例如 |
<warmup-requests-enabled> |
可选。默认值:true。对于 Java 8 应用,默认启用了预热请求。
启用预热请求后,App Engine 基础架构会向 如要停用预热请求,请为以下元素指定 <?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> |
可选。将应用配置为使用无服务器 VPC 访问通道连接器,使应用能够将请求发送到 VPC 网络中的内部资源。如需了解详情,请参阅连接到 VPC 网络。
<vpc-access-connector> <name>projects/PROJECT_ID/locations/REGION/connectors/CONNECTOR_NAME</name> <egress-setting>all-traffic</egress-setting> </vpc-access-connector> |
扩缩元素
下表列出了可供您用来指定应用如何进行扩缩的一些选项。
如需了解各类扩缩类型性能功能的比较情况,请参阅扩缩动态实例。
元素 | 说明 |
---|---|
<automatic-scaling> |
可选。除非另有说明,否则,系统默认采用自动扩缩,并以
该元素可以包含以下元素:
<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> |
可选。 该元素可以包含以下元素:
<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> |
可选。 该元素可以包含以下元素:
<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> |
可选。大多数应用都不需要更改默认行为。 如果部署需要,暂存元素允许您指定一个特定的暂存配置。 该元素可以包含以下元素:
例如: <staging> <delete-jsps>false</delete-jsps> </staging> |
暂存选项默认值
暂存选项的默认值如下:
暂存元素 | 默认值 |
---|---|
enable-jar-splitting |
true |
jar-splitting-excludes |
NA |
disable-jar-jsps |
false |
enable-jar-classes |
true 这可能会影响类加载顺序,因此,如果您的应用依赖于特定顺序,请将此设置为 false 。 |
delete-jsps |
true |
compile-encoding |
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 类型与静态文件的文件扩展名相关联。
URLFetch 超时
您可以为每个 URLFetch 请求设置截止日期。默认情况下,提取截止时间为 5 秒。
如要更改此默认设置,您可以在 appengine-web.xml
配置文件中添加以下设置。指定超时(以秒为单位):
<system-properties>
<property name="appengine.api.urlfetch.defaultDeadline" value="10"/>
</system-properties>