为任务设置重试参数

预览

此功能受服务专用条款的“通用服务条款”部分中的“非正式版产品条款”的约束。 非正式版功能“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅 发布阶段说明。

创建任务时，您可以使用 projects.locations.queues.tasks.create 方法指定重试 失败任务的最大次数、设置重试尝试的时间限制，以及控制 尝试之间的间隔。任务成功执行后，系统会将其从队列中移除。在 所有情况下，任务保留时间上限也 适用。

此任务级重试配置会替换任务的 队列级重试配置。

在创建任务时配置重试

以下示例展示了如何通过向 Cloud Tasks API 发送直接请求来设置创建 HTTP 目标任务时的重试参数。您可以使用相同的重试参数，在 创建 App Engine 任务时。如需了解 更多参数详细信息，请参阅 RetryConfig 设置，了解 Task 资源。

在使用任何请求数据之前， 请进行以下替换：

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

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

• MAX_ATTEMPTS：可选。任务的最大尝试次数，包括第一次尝试。如需允许无限次重试，请将此值设置为 -1。MAX_RETRY_DURATION 即使达到 MAX_ATTEMPTS 或将其设置为 -1，仍然适用。
• MAX_RETRY_DURATION：可选。 重试失败任务的最长时间，从首次尝试任务时开始计算。该值必须是以“s”结尾的字符串，例如 5s。如需指定 无限时长，请将此值设置为 0s。MAX_ATTEMPTS 仍然适用，即使达到 MAX_RETRY_DURATION 或将其设置为 0s。
  注意：如果您指定无限次尝试（MAX_ATTEMPTS 为 -1）和无限时长（MAX_RETRY_DURATION 为 0s）， 则系统会重试任务，直到达到 任务保留时间上限。否则， Cloud Tasks 仅在满足这两个条件或任务 成功后才会停止重试。
• MIN_INTERVAL：可选。重试尝试之间等待的最短 时间。该值必须是以“s”结尾的字符串，例如 5s。
• MAX_INTERVAL：可选。重试尝试之间等待的最长时间。该值必须是以“s”结尾的字符串，例如 5s。
• MAX_DOUBLINGS：可选。在失败任务重试之间的间隔增加到恒定值之前，间隔将翻倍的最大次数。任务的重试间隔从 MIN_INTERVAL 开始，然后翻倍 MAX_DOUBLINGS 次，然后线性增加，最后以 MAX_INTERVAL 的间隔重试，最多 MAX_ATTEMPTS 次。

  例如，如果 MIN_INTERVAL 为 10s，MAX_INTERVAL 为 300s，MAX_DOUBLINGS 为 3，则重试间隔将翻倍 3 次，线性增加 2^3 * 10 秒，然后以 MAX_INTERVAL 的间隔重试，直到任务尝试了 MAX_ATTEMPTS 次：10 秒、20 秒、40 秒、80 秒、160 秒、240 秒、300 秒、300 秒，依此类推。

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

请求 JSON 正文：

{
  "task": {
    "httpRequest": {
      "url": "URL",
      "httpMethod": "POST",
      "oidcToken": {
        "serviceAccountEmail": "SERVICE_ACCOUNT_EMAIL"
      }
    },
    "retryConfig": {
      "maxAttempts": MAX_ATTEMPTS,
      "maxRetryDuration": "MAX_RETRY_DURATION",
      "minBackoff": "MIN_INTERVAL",
      "maxBackoff": "MAX_INTERVAL",
      "maxDoublings": MAX_DOUBLINGS
    },
    "scheduleTime": "SCHEDULE_TIME"
  }
}

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

curl（Linux、macOS 或 Cloud Shell）

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以通过运行 gcloud auth list 来检查当前的活跃账号。

将请求正文保存在名为 request.json 的文件中。在终端中运行以下命令，在当前目录中创建或覆盖此文件：

cat > request.json << 'EOF'
{
  "task": {
    "httpRequest": {
      "url": "URL",
      "httpMethod": "POST",
      "oidcToken": {
        "serviceAccountEmail": "SERVICE_ACCOUNT_EMAIL"
      }
    },
    "retryConfig": {
      "maxAttempts": MAX_ATTEMPTS,
      "maxRetryDuration": "MAX_RETRY_DURATION",
      "minBackoff": "MIN_INTERVAL",
      "maxBackoff": "MAX_INTERVAL",
      "maxDoublings": MAX_DOUBLINGS
    },
    "scheduleTime": "SCHEDULE_TIME"
  }
}
EOF

然后，执行以下命令以发送 REST 请求：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://cloudtasks.googleapis.com/v2beta3/projects/PROJECT_ID/locations/REGION/queues/QUEUE_ID/tasks"

PowerShell (Windows)

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以通过运行 gcloud auth list 来检查当前的活跃账号。

将请求正文保存在名为 request.json 的文件中。在终端中运行以下命令，在当前目录中创建或覆盖此文件：

@'
{
  "task": {
    "httpRequest": {
      "url": "URL",
      "httpMethod": "POST",
      "oidcToken": {
        "serviceAccountEmail": "SERVICE_ACCOUNT_EMAIL"
      }
    },
    "retryConfig": {
      "maxAttempts": MAX_ATTEMPTS,
      "maxRetryDuration": "MAX_RETRY_DURATION",
      "minBackoff": "MIN_INTERVAL",
      "maxBackoff": "MAX_INTERVAL",
      "maxDoublings": MAX_DOUBLINGS
    },
    "scheduleTime": "SCHEDULE_TIME"
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

然后，执行以下命令以发送 REST 请求：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://cloudtasks.googleapis.com/v2beta3/projects/PROJECT_ID/locations/REGION/queues/QUEUE_ID/tasks" | Select-Object -Expand Content

APIs Explorer（浏览器）

复制请求正文并打开方法参考页面。APIs Explorer 面板会在页面右侧打开。您可以与此工具进行交互以发送请求。 将请求正文粘贴到此工具中，填写任何其他必填字段，然后点击执行 。

如果成功，响应正文将包含新创建的 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"
    }
  },
  "retryConfig": {
    "maxAttempts": MAX_ATTEMPTS,
    "maxRetryDuration": "MAX_RETRY_DURATION",
    "minBackoff": "MIN_INTERVAL",
    "maxBackoff": "MAX_INTERVAL",
    "maxDoublings": MAX_DOUBLINGS
  },
  "scheduleTime": "SCHEDULE_TIME",
  "createTime": "2026-04-30T19:11:50Z",
  "dispatchDeadline": "600s",
  "view": "BASIC"
}

后续步骤

• 创建 Cloud Tasks 队列
• 创建 Cloud Tasks 任务
• 配置队列路由、限制和重试
• 管理队列和任务