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 队列的配置。

如需配置推送队列,您可以使用 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_limittask_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)。例如:

total_storage_limit: 1.2G
queue:
  - name: fooqueue

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

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

  • B(字节)
  • K(千字节)
  • M(兆字节)
  • G(千兆字节)
  • T(太字节)

如果 total_storage_limit 超过应用可以使用的总磁盘存储空间,则上限将不会超过可用的存储空间。

部署队列配置文件

queue.yaml 文件应位于根目录或定义了默认服务的目录中。

如需部署队列配置文件,请运行以下命令:

gcloud app deploy queue.yaml

删除队列

如需删除队列,请执行以下操作:

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

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

    gcloud app deploy queue.yaml

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

    转到“任务队列”页面

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