创建 Cloud Tasks 任务

您可以使用 Cloud Tasks 创建称为任务的异步工作项。本文档演示了如何创建 HTTP 目标任务和 App Engine 任务。

HTTP 目标任务是指转发给位于任何具有外部 IP 地址的通用 HTTP 端点(例如 Cloud Run、Google Kubernetes Engine、Compute Engine 或本地 Web 服务器)的工作器的请求。

对于 App Engine 目标,Cloud Tasks 会将任务请求转发给 App Engine 中的处理程序。定位 App Engine 处理程序的所有队列都必须具有 App Engine 应用。处理程序必须在 App Engine 应用运行的区域中运行。此区域还用作 Cloud Tasks 请求的 REGION 参数。

您可以通过以下方式创建 HTTP 目标任务:

  • 在 Google Cloud 控制台中
  • 在终端或 Cloud Shell 中使用 Google Cloud CLI
  • 通过向 Cloud Tasks API 发送直接请求

如需了解如何以编程方式将 HTTP 目标任务添加到 Cloud Tasks 队列,请参阅以编程方式创建 HTTP 目标任务

您可以通过以下方式创建 App Engine 任务:

  • 在终端或 Cloud Shell 中使用 Google Cloud CLI
  • 通过向 Cloud Tasks API 发送直接请求

如需了解如何以编程方式将 App Engine 任务添加到 Cloud Tasks 队列,请参阅以编程方式创建 App Engine 任务

准备工作

确保您已创建 Cloud Tasks 队列。如需了解详情,请参阅创建 Cloud Tasks 队列

创建 HTTP 目标任务

创建任务时,您可以指定任务名称。如果该名称与现有任务或最近删除或完成的任务的名称相同,则调用将失败。如果您未指定任务名称,系统会生成一个随机的唯一任务 ID。

由于需要额外的查找成本来识别重复的任务名称,因此使用用户指定的 ID 创建的任务的延迟时间会显著增加。建议使用哈希字符串作为任务 ID 或任务 ID 的前缀。如需了解详情,请参阅任务去重

控制台

  1. 在 Google Cloud 控制台中,前往 Cloud Tasks > 队列页面。

    前往“队列”

  2. 点击要向其添加任务的队列的名称。

  3. 点击 创建 HTTP 任务

  4. (可选)指定任务名称

  5. 对于 网址,请指定请求将发送到的完全限定网址。路径必须以 http://https:// 开头,例如:https://www.example.com

  6. (可选)指定要用于请求的 HTTP 方法。默认值为 POST

  7. 对于请求正文,您可以选择性地提供要发送给处理任务的工作器的 HTTP 正文数据。

  8. (可选)点击 添加标头,指定一个或多个 HTTP 请求标头。

  9. 对于身份验证标头,请选择以下授权选项之一,以指定在执行任务时如何对发送到目标的请求进行身份验证:

    • - 无标头,适用于无需授权的公共端点
    • 添加 OAuth 令牌 - 通常用于 *.googleapis.com 上托管的 Google API
    • 添加 OIDC 令牌 - 用于 Google Cloud 和第三方端点调用,但 *.googleapis.com 上托管的 Google API 除外
  10. 如果适用,请为服务账号提供服务账号电子邮件地址,该地址将用于生成授权令牌,该令牌包含在执行任务时发送给目标的请求中。服务账号必须与队列位于同一项目中。调用者必须具有服务账号的 iam.serviceAccounts.actAs 权限。

  11. (可选)如果适用,请指定受众群体,以限制授权令牌的操作类型或接收者。

  12. 点击创建

您的任务应列在队列详情页面上。

gcloud

如需创建 HTTP 目标任务并将其添加到现有队列,请使用 gcloud tasks create-http-task 命令。

gcloud tasks create-http-task \
    --queue=QUEUE_ID \
    --url=URL \
    --location=REGION \
    --project=PROJECT_ID \
    --oidc-service-account-email=SERVICE_ACCOUNT_EMAIL

替换以下内容:

  • QUEUE_ID:要将任务添加到的队列的名称。
  • URL:请求将发送到的完全限定网址。路径必须以 http://https:// 开头,例如:https://www.example.com

  • REGION:可选。部署队列的区域,例如 us-central1

  • PROJECT_ID:可选。将创建任务的Google Cloud 项目的项目 ID。

  • SERVICE_ACCOUNT_EMAIL:可选。用于生成授权令牌的服务账号电子邮件地址,该令牌包含在执行任务时发送到目标的请求中。服务账号必须与队列位于同一项目中。调用者必须具有服务账号的 iam.serviceAccounts.actAs 权限。

    如需生成 OAuth2 访问令牌而非 OpenID Connect 令牌,请将 --oidc-service-account-email 标志替换为 --oauth-service-account-email 以指定服务账号电子邮件地址。

创建任务后,您应该会看到一条确认消息,其中包含所创建任务的完整资源名称。

REST

如需创建 HTTP 目标任务并将其添加到现有队列,请使用 projects.locations.queues.tasks.create 方法。

在使用任何请求数据之前,请先进行以下替换:

  • PROJECT_ID:必填。将创建任务的 Google Cloud 项目的项目 ID。
  • REGION:必填。部署队列的区域,例如 us-central1
  • QUEUE_ID:必填。任务将添加到的队列的 ID。
  • URL:必填。请求将发送到的完全限定网址。此字符串必须以 http://https:// 开头,例如:https://www.example.com
  • SERVICE_ACCOUNT_EMAIL:可选。用于生成授权令牌的服务账号电子邮件地址,该令牌包含在执行任务时发送给目标的请求中。服务账号必须与队列位于同一项目中。调用者必须具有服务账号的 iam.serviceAccounts.actAs 权限。

    如需生成 OAuth2 访问令牌而非 OpenID Connect 令牌,请将 oidcToken 字段替换为 oauthToken 以指定服务账号电子邮件地址。

  • SCHEDULE_TIME:可选。 任务计划尝试的时间,采用 RFC 3339 格式,例如 2026-10-02T15:01:23Z。如果未设置时间或时间为过去的时间,Cloud Tasks 会将其设置为当前时间。

请求 JSON 正文:

{
  "task": {
    "httpRequest": {
      "url": "URL",
      "httpMethod": "POST",
      "oidcToken": {
        "serviceAccountEmail": "SERVICE_ACCOUNT_EMAIL"
      }
    },
    "scheduleTime": "SCHEDULE_TIME"
  }
}

如需发送您的请求,请展开以下选项之一:

如果成功,响应正文将包含新创建的 Task 资源实例。

{
  "name": "projects/PROJECT_ID/locations/REGION/queues/QUEUE_ID/tasks/TASK_ID",
  "httpRequest": {
    "url": "URL",
    "httpMethod": "POST",
    "headers": {
      "User-Agent": "Google-Cloud-Tasks"
    },
    "oidcToken": {
      "serviceAccountEmail": "SERVICE_ACCOUNT_EMAIL",
      "audience": "URL"
    }
  },
  "scheduleTime": "SCHEDULE_TIME",
  "createTime": "2026-04-30T19:11:50Z",
  "dispatchDeadline": "600s",
  "view": "BASIC"
}

创建 App Engine 任务

创建任务时,您可以指定任务名称。如果该名称与现有任务或最近删除或完成的任务的名称相同,则调用将失败。如果您未指定任务名称,系统会生成一个随机的唯一任务 ID。

由于需要额外的查找成本来识别重复的任务名称,因此使用用户指定的 ID 创建的任务的延迟时间会显著增加。建议使用哈希字符串作为任务 ID 或任务 ID 的前缀。如需了解详情,请参阅任务去重

gcloud

如需创建 App Engine 任务并将其添加到现有队列,请使用 gcloud tasks create-app-engine-task 命令。

gcloud tasks create-app-engine-task \
    --queue=QUEUE_ID \
    --relative-uri=RELATIVE_URI \
    --location=REGION \
    --project=PROJECT_ID \
    --routing=KEY:VALUE

替换以下内容:

  • QUEUE_ID:要将任务添加到的队列的名称。
  • RELATIVE_URI:请求的相关 URI。路径必须以正斜杠 (/) 开头。如果未指定,则使用根路径 (/)。
  • REGION:可选。队列部署的区域。如果未指定,则使用当前项目的 App Engine 应用的位置。
  • PROJECT_ID:可选。将创建任务的Google Cloud 项目的项目 ID。
  • KEY:VALUE:可选。此任务要使用的路线,其中 KEY 是以下至少一种:serviceversioninstance。任何缺失的键都将使用默认路由。

创建任务后,您应该会看到一条确认消息,其中包含所创建任务的完整资源名称。

REST

如需创建 App Engine 任务并将其添加到现有队列,请使用 projects.locations.queues.tasks.create 方法。

在使用任何请求数据之前,请先进行以下替换:

  • PROJECT_ID:必填。将创建任务的 Google Cloud 项目的项目 ID。
  • REGION:必填。队列部署的区域
  • QUEUE_ID:必填。任务将添加到的队列的 ID。
  • RELATIVE_URI:必填。请求的相关 URI。路径必须以正斜杠 (/) 开头。如果未指定,则使用根路径 (/)。
  • SERVICE:可选。将处理任务的 App Engine 服务。默认情况下,任务会发送到尝试执行该任务时的默认服务。
  • VERSION:可选。将处理任务的 App Engine 版本。默认情况下,任务会发送到尝试执行该任务时的默认版本。
  • SCHEDULE_TIME:可选。 任务计划尝试的时间,采用 RFC 3339 格式,例如 2026-10-02T15:01:23Z。如果未设置时间或时间为过去的时间,Cloud Tasks 会将其设置为当前时间。

请求 JSON 正文:

{
  "task": {
    "appEngineHttpRequest": {
      "httpMethod": "POST",
      "relativeUri": "RELATIVE_URI",
      "appEngineRouting": {
        "service": "SERVICE",
        "version": "VERSION"
      }
    },
    "scheduleTime": "SCHEDULE_TIME"
  }
}

如需发送您的请求,请展开以下选项之一:

如果成功,响应正文将包含新创建的 Task 资源实例。

{
  "name": "projects/PROJECT_ID/locations/REGION/queues/QUEUE_ID/tasks/TASK_ID",
  "appEngineHttpRequest": {
    "httpMethod": "POST",
    "relativeUri": "RELATIVE_URI",
    "appEngineRouting": {
      "service": "SERVICE",
      "version": "VERSION",
      "host": "VERSION.SERVICE.PROJECT_ID.appspot.com"
    }
  },
  "scheduleTime": "SCHEDULE_TIME",
  "createTime": "2026-04-30T19:11:50Z",
  "dispatchDeadline": "600s",
  "view": "BASIC"
}

创建一批任务

您可以使用 projects.locations.queues.tasks.batchCreate 方法创建请求列表,从而创建一批目标任务并将该批任务添加到现有队列中。

请注意以下几点:

  • 所有任务都必须添加到同一队列中。

  • 单个批次中可创建的任务数量有限制。如需了解详情,请参阅配额和限制

  • 将单个操作汇总到单个请求中的批量请求不是原子操作,因为批量请求中包含的一些操作可能会失败,而其他操作可能会成功。

  • 您还可以批量删除任务。如需了解详情,请参阅从队列中批量删除任务

HTTP 任务

在使用任何请求数据之前,请先进行以下替换:

  • PROJECT_ID:必填。将创建任务的 Google Cloud 项目的项目 ID。
  • REGION:必填。部署队列的区域,例如 us-central1
  • QUEUE_ID:必填。要向其添加任务的队列的 ID。
  • URL:必填。请求将发送到的完全限定网址。此字符串必须以 http://https:// 开头,例如:https://www.example.com
  • SERVICE_ACCOUNT_EMAIL:可选。用于生成授权令牌的服务账号电子邮件地址,该令牌包含在执行任务时发送给目标的请求中。服务账号必须与队列位于同一项目中。调用者必须具有服务账号的 iam.serviceAccounts.actAs 权限。

    如需生成 OAuth2 访问令牌而非 OpenID Connect 令牌,请将 oidcToken 字段替换为 oauthToken 以指定服务账号电子邮件地址。

请求正文包含一个请求列表。

请求 JSON 正文:

{
  "requests": [
    {
      "task": {
        "httpRequest": {
          "url": "URL",
          "httpMethod": "POST",
          "oidcToken": {
            "serviceAccountEmail": "SERVICE_ACCOUNT_EMAIL"
          }
        },
        "scheduleTime": "SCHEDULE_TIME"
      }
    }
  ]
}

如需发送您的请求,请展开以下选项之一:

如果成功,响应正文将包含一个 Operation 资源实例。

{
  "name": "projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.tasks.v2beta3.BatchCreateTasksMetadata"
  },
  "done": false
}

App Engine 任务

在使用任何请求数据之前,请先进行以下替换:

  • PROJECT_ID:必填。将创建任务的 Google Cloud 项目的项目 ID。
  • REGION:必填。队列部署的区域
  • QUEUE_ID:必填。要向其添加任务的队列的 ID。
  • RELATIVE_URI:必填。请求的相关 URI。路径必须以正斜杠 (/) 开头。如果未指定,则使用根路径 (/)。
  • SERVICE:可选。将处理任务的 App Engine 服务。默认情况下,任务会发送到尝试执行该任务时的默认服务。
  • VERSION:可选。将处理任务的 App Engine 版本。默认情况下,任务会发送到尝试执行该任务时的默认版本。
  • SCHEDULE_TIME:可选。 任务计划尝试的时间,采用 RFC 3339 格式,例如 2026-10-02T15:01:23Z。如果未设置时间或时间为过去的时间,Cloud Tasks 会将其设置为当前时间。

请求正文包含一个请求列表。

请求 JSON 正文:

{
  "requests": [
    {
      "task": {
        "appEngineHttpRequest": {
          "httpMethod": "POST",
          "relativeUri": "RELATIVE_URI",
          "appEngineRouting": {
            "service": "SERVICE",
            "version": "VERSION"
          }
        },
        "scheduleTime": "SCHEDULE_TIME"
      }
    }
  ]
}

如需发送您的请求,请展开以下选项之一:

如果成功,响应正文将包含一个 Operation 资源实例。

{
  "name": "projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.tasks.v2beta3.BatchCreateTasksMetadata"
  },
  "done": false
}

后续步骤