Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

為工作設定重試參數

建立工作時，您可以使用 projects.locations.queues.tasks.create 方法指定失敗工作的重試次數上限、設定重試的時間限制，以及控制每次重試的時間間隔。工作執行成功後，就會從佇列中移除。在所有情況下，工作保留期限上限也適用。

這項工作層級的重試設定會覆寫工作佇列層級的重試設定。

建立工作時設定重試次數

下列範例說明如何直接向 Cloud Tasks API 傳送要求，在建立 HTTP 目標工作時設定重試參數。建立 App Engine 工作時，您可以使用相同的重試參數。如要進一步瞭解參數，請參閱 Task 資源的 RetryConfig 設定。

使用任何要求資料之前，請先修改下列項目的值：

PROJECT_ID：必填。要建立工作的 Google Cloud 專案的專案 ID。
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

API 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"
}