queue.yaml 参考文档

区域 ID

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

详细了解区域 ID。

queue.yaml 配置文件用于创建和配置应用使用的几乎所有任务队列（推送或拉取）。所有 App Engine 应用都附带一个名为 default 的自动预配置的推送队列。虽然您无法自行创建 default 队列，但您可以使用 queue.yaml 文件来添加其他队列或更改 default 队列的配置。

对于 Java 应用，此文件存储在源代码目录中的任何位置。

如需配置推送队列，您可以使用 queue.yaml 或 Cloud Tasks 中的队列管理 方法，但不能同时使用两者。将 queue.yaml 上传方法与队列管理方法混合使用可能会产生意外的结果，因此不建议这样做。

如需配置拉取队列，您必须使用 queue.yaml 文件。

示例

以下基本示例定义了一个命名的队列并替换了默认处理速率：

queue:
- name: my-push-queue
  rate: 1/s

下面是更为复杂的 queue.yaml 配置示例，演示了如何设置任务尝试次数以及修改默认处理速率。

queue:
- name: fooqueue
  rate: 1/s
  retry_parameters:
    task_retry_limit: 7
    task_age_limit: 2d
- name: barqueue
  rate: 1/s
  retry_parameters:
    min_backoff_seconds: 10
    max_backoff_seconds: 200
    max_doublings: 0
- name: bazqueue
  rate: 1/s
  retry_parameters:
    min_backoff_seconds: 10
    max_backoff_seconds: 200
    max_doublings: 3

语法

queue.yaml 文件是一个 YAML 文件，其根指令为 queue。此指令包含零个或零个以上命名队列。每个队列定义都可以指定以下元素：

元素 说明
<bucket-size>（推送队列）

可选。任务队列使用令牌存储桶算法来控制任务执行的速率。每个命名队列都有一个用于存储令牌的令牌桶，其最大容量由 bucket_size 值指定。应用每次执行任务时，系统都会从存储桶中移除一个令牌。您可以继续处理队列中的任务，直到队列存储桶中的令牌用完为止。App Engine 会根据您为队列指定的速率不断使用新令牌重新填充存储桶。

如果队列中包含许多任务并且速率很高，则存储桶的大小会限制队列的处理速度。存储桶大小的最大值为 500。这样一来，您可以拥有较高的速率，因此任务在排入队列后很快开始处理，但如果短时间内有很多任务排入队列，则仍会限制资源使用量。

如果您没有为队列指定 bucket_size，则默认值为 5。我们建议您将此值设置为较大的值，因为对于许多用例而言，默认大小可能太小。例如，您可以根据处理速率来确定存储桶大小。

如需详细了解此元素，请参阅 Cloud Tasks API 参考文档中 max_burst_size 的

比较说明。
<max-concurrent-requests>（推送队列）

可选。设置可从指定队列中同时执行的最大任务数。该值为整数。每个队列的上限默认为 1000 个任务。每个队列的建议上限为 5000 个任务。请注意，首次创建队列或在队列处于空闲状态一段时间后，其任务数量可能会缓慢增加。

通过限制并发任务的数量，您可以更好地控制队列的执行速率，并防止一次运行太多任务。该元素还可以防止数据存储区争用，使资源可用于其他队列或在线处理。

如需详细了解此元素，请参阅 Cloud Tasks API 参考文档中 max_concurrent_dispatches 的比较说明。
<mode>

可选。标识队列模式。默认设置为 push，用于将队列标识为推送队列。如果要使用拉取队列，请将模式设置为 pull。
<name>

必需。队列名称。这是在调用 QueueFactory.getQueue() 时指定的名称。

队列名称可以包含大写和小写字母、数字和连字符。队列名称的最大长度为 100 个字符。

所有应用都有一个名为 default 的推送队列。此队列的预设速率为每秒 5 个任务。请注意，首次使用或配置此默认队列之前，Google Cloud 控制台中不会显示该队列。您可以通过在 queue.yaml 文件中定义名为“default”的队列来配置默认队列，包括更改默认速率。
<rate>（推送队列）

必需。相应队列中的任务处理速率。该值是一个数字，后跟一个斜杠和时间单位，其中 s 表示秒、m 表示分钟、h 表示小时、d 表示天。例如，5/m 值表示按每分钟 5 次的速率处理任务。rate 的最大值为 500/s。

如果数字为 0（例如 0/s），则该队列被视为“暂停”，不处理任务。

如需详细了解此元素，请参阅 Cloud Tasks API 参考文档中 max_dispatches_per_second 的比较说明。
<retry-parameters>

可选。配置推送队列中失败任务的重试尝试次数。通过添加相应的值，您可以指定特定队列中失败任务的最大重试次数。您还可以为重试尝试设置时间限制，控制重试之间的时间间隔。

重试参数可以包含以下子元素：

<task-retry-limit>
重试次数。例如，如果指定 0，那么当任务失败时，系统完全不会重试任务。如果指定 1，那么当任务失败时，系统会重试任务一次。如果未指定此参数，则系统将无限次地重试任务。如果同时指定了 task_retry_limit 和 task_age_limit，则系统会重试任务，直到同时达到这两个限制为止。
<task-age-limit>（推送队列）
重试失败任务的时间限制，从首次运行任务开始计算。该值是一个数字，后跟一个时间单位，其中 s 表示秒，m 表示分钟，h 表示小时，d 表示天。例如，值 5d 指定的限制为任务首次执行尝试后的五天。如果未指定此参数，则系统将无限次地重试任务。如果同时还指定了 task_retry_limit，则 App Engine 将重试任务，直至达到这两个限制为止。
<min-backoff-seconds>（推送队列）
任务失败后等待重试的最短时间（以秒为单位）。默认值为 0.1。
<max-backoff-seconds>（推送队列）
任务失败后等待重试的最长时间（以秒为单位）。默认值为 3600。
<max-doublings>（推送队列）
在增加量变为常量之前，失败任务重试之间的时间间隔将加倍的最大次数。该常量为：2**max_doublings * min_backoff_seconds。默认值为 16。
<target>（推送队列）

可选。对于已排入此队列的所有任务，指定执行这些任务所在的服务/版本、前端版本或后端名称的字符串。默认值为空字符串。

为任务构造 HTTP 请求时，该字符串将被添加到应用的域名前面。例如，如果您的应用 ID 是 my-app，而您将目标设置为 my-version-dot-my-service，则网址主机名将设置为 my-version-dot-my-service-dot-my-app.REGION_ID.r.appspot.com。

如果未指定目标，则系统会在将任务排入队列所在的应用版本中调用任务。因此，如果您在默认应用版本将任务排入队列，而没有在该队列上指定目标，则系统会在默认应用版本中调用任务。请注意，如果在任务排入队列到任务执行这期间，默认应用版本发生变化，则任务将在新的默认版本中运行。

如果您将服务与调度文件一起使用，则任务的 HTTP 请求可能会遭到拦截并被重新路由到另一项服务。

您可为应用中的所有队列指定以下元素：

元素 说明
<total-storage-limit>

可选。一个字符串，它会替换任务队列存储中可用的默认配额存储上限 (100M)。例如：

<queue-entries>
  <total-storage-limit>1.2G</total-storage-limit>
  <queue>
    <name>fooqueue</name>
  </queue>
</queue-entries>

此配额是应用的总存储配额（包括数据存储区和 blobstore 配额）的一部分。

如果未指定后缀，则您指定的数字将被解析为字节。系统支持以下后缀：

  • B（字节）
  • K（千字节）
  • M（兆字节）
  • G（千兆字节）
  • T（太字节）

如果 <total-storage-limit> 超过应用可以使用的总磁盘存储空间，则上限将不会超过可用的存储空间。

部署队列配置文件

queue.yaml 文件可以位于源代码目录中的任意位置。

如果要在不以其他方式改变当前服务版本的情况下部署队列配置文件，请根据您的环境，在包含队列文件的目录中使用以下命令之一：

gcloud

gcloud app deploy queue.yaml

Maven

mvn appengine:deployQueue queue.yaml

Gradle

gradle appengineDeployQueue queue.yaml

IDE

如果您使用 IntelliJ 或 Eclipse，则可以使用部署表单来选择要部署的各个配置文件。

删除队列

如需删除队列，请执行以下操作：

  1. 从 queue.yaml 文件中移除队列定义。

  2. 上传对 queue.yaml 文件的更改。

    gcloud app deploy queue.yaml

  3. 在 Google Cloud 控制台中删除队列，选择队列，然后点击删除队列：

    转到“任务队列”页面

如果您从 Google Cloud 控制台中删除某个队列，则必须等待 7 天才能重新创建同名队列。