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_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)。例如：

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 天才能重新创建同名队列。