使用队列管理或 queue.yaml

本页面介绍了使用 Cloud Tasks API 管理队列与通过上传 Cloud Tasks queue.yaml 文件达到相同目的之间的区别。此外，还讨论了混合使用这两种机制的一些误区以及处理常见问题的方法。

简介

Cloud Tasks API 为 App Engine 任务队列服务提供独立于 App Engine 的界面。作为该界面的一部分，它提供了管理队列的功能，包括通过控制台或 gcloud 命令执行此操作。可以从 App Engine SDK 访问 Cloud Tasks API 创建的队列，反之亦然。为了保持兼容性，可以使用 App Engine SDK 使用的配置文件 queue.yaml 来创建和配置要通过 Cloud Tasks API 使用的队列。但是，通过文件将配置与通过 Cloud Tasks API 进行配置混合会产生意想不到的后果。

queue.yaml 与 Cloud Tasks 队列管理方法混合使用的误区

对于底层服务，queue.yaml 文件是决定性的。如果上传省略了项目中现有队列的 queue.yaml，那么无论这些队列是如何创建的，都会导致这些队列停用或暂停。因此，如果您使用 Cloud Tasks API 调用 CreateQueue 或 UpdateQueue，然后上传忽略了它们的 queue.yaml 文件，则在 Cloud Tasks 调用中创建的队列将被停用。

请考虑以下情况：

  1. 调用 CreateQueue 以创建名为“cloud-tasks-queue”的队列。

  2. 上传一个包含以下内容的 queue.yaml 文件：

    queue:
- name: queue-yaml-queue

这个项目中队列的当前状态是什么？名为“cloud-tasks-queue”的队列和之前存在的任何其他队列都处于 DISABLED 状态，名为“queue-yaml-queue”的队列处于 RUNNING 状态。

如果您通过 Cloud Tasks API 创建队列，这种行为可能会令人惊讶。以下说明介绍了如何恢复已停用的队列。

同样，如果一个队列在 Cloud Tasks API 中被停用，但后来出现在上传的 queue.yaml 文件中，则该队列已恢复。

如果使用 DeleteQueue 方法删除的队列稍后显示在 queue.yaml 文件中，则 queue.yaml 上传可能会失败，因为在队列删除后几天内不允许重用队列名称。

最佳实践

如果您刚开始接触 Cloud Tasks 或 App Engine，请仅使用 Cloud Tasks API 来管理队列，并避免同时使用 queue.yaml。Cloud Tasks 队列管理方法为用户提供了更多创建、更新和删除队列的选择。

但是，如果您现在是 queue.yaml 用户，则只有在了解将 queue.yaml 与 Cloud Tasks 队列管理方法混用的误区时，才应考虑切换到队列管理方法。

为了防止用户混用各种任务管理方法，一种方案是创建一个 Web 应用或命令行工具，所有用户都必须使用它来创建、更新和删除队列。该工具是使用 Cloud Tasks 队列管理方法还是 queue.yaml，这属于该工具的实现细节，无需用户关注。如果用户需要使用该工具，您可以保证不会无意中混合使用 Cloud Tasks 队列管理方法和使用 queue.yaml。为帮助强制使用此类工具，您可以向该工具授予队列管理员角色，并要求用户进行身份验证才能使用该工具。如需详细了解访问权限管理，请参阅安全队列配置。

调试

您可以检查项目的管理活动审核日志，以检索队列配置更改的历史记录，包括队列创建、更新和删除：

    gcloud logging read \
      'protoPayload.methodName=
       (com.google.appengine.legacy.queue_created OR
        com.google.appengine.legacy.queue_updated OR
        google.cloud.tasks.v2.CloudTasks.CreateQueue OR
        google.cloud.tasks.v2.CloudTasks.UpdateQueue OR
        google.cloud.tasks.v2.CloudTasks.DeleteQueue)'

例如，如果 queue.yaml 上传操作停用了现有队列，则审核日志中会通过 com.google.appengine.legacy.queue_updated 方法显示“已停用队列‘[QUEUE_NAME]’”消息。

如何恢复因上传的 queue.yaml 而被停用的队列

如果您将 queue.yaml 与 Cloud Tasks 队列管理方法混合使用，则上传 queue.yaml 文件可能会意外停用通过 Cloud Tasks API 创建的队列。

如需恢复队列，您可以对队列调用 ResumeQueue 或将其添加到 queue.yaml 并上传。请注意，如果您之前在队列的 queue.yaml 配置中设置了自定义处理 rate，则 ResumeQueue 会将队列重置为默认 rate。这会反映在对 ResumeQueue 的响应的 maxDispatchesPerSecond 字段中。

配额

如果您使用 queue.yaml 创建队列，则默认最多可以创建 100 个队列。使用 Cloud Tasks API 创建的队列默认包含的队列上限是 1000 个。与在其他情况下一样，混合使用 queue.yaml 和 Cloud Tasks API 方法可能会产生意外结果。例如，假设您使用 queue.yaml 创建一些队列，然后将配额增加到 2000。如果您随后使用 Cloud Tasks API 方法创建更多队列，则会遇到配额错误。如需解决此问题，请在 Google Cloud 控制台的“配额”页面中，使用修改配额来提交请求。

有关 Cloud Tasks 队列管理方法的其他信息

队列配置和队列启动延迟

对队列配置的更改可能需要几分钟才能生效。例如，在调用 CreateQueue 或 UpdateQueue 时，可能会经过几分钟才能成功调用该队列上的 CreateTask。

Cloud Tasks 和 default App Engine 队列

名为 default 的 App Engine 队列在 App Engine SDK 和 Cloud Tasks API 中会进行特殊处理。

如果 default 队列尚不存在，则在以下情况下创建该队列：

  1. 使用 App Engine SDK 首次将任务添加到 default 队列时。
  2. 上传指定 default 队列的 queue.yaml 文件时。
  3. 调用 CreateQueue 或 UpdateQueue 用于创建 default 队列时。

为了保持与 App Engine 的兼容性，Cloud Tasks 强制执行以下限制：

  1. 如果创建名为“default”的队列，则它必须是使用 App Engine 任务的队列。
  2. 创建队列后，用户无法删除 default 队列。

在 Cloud Tasks API 中，以下内容也适用于 default 队列：

  1. Cloud Tasks API 不会自动创建 default 队列或任何其他队列。
  2. 就像任何其他队列一样，如果在创建队列之前调用队列，则在 default 队列上调用 GetQueue 会导致出现“未找到”错误。
  3. 同样，default 队列在创建前不会出现在 ListQueues 的输出中。
  4. 您可以使用 UpdateQueue 调用更改 default 队列的配置。

后续步骤