Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

為工作設定重試參數

建立工作時，您可以使用 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_ATTEMPTS 或設為 -1，MAX_RETRY_DURATION 仍適用。
MAX_RETRY_DURATION：選用。工作第一次嘗試執行後，重試失敗工作的最長時間。值必須是結尾為「s」的字串，例如 5s。如要指定無限期，請將此值設為 0s。即使達到 MAX_RETRY_DURATION 或設為 0s，MAX_ATTEMPTS 仍適用。
注意：如果您指定無限次嘗試 (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/v2/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/v2/projects/PROJECT_ID/locations/REGION/queues/QUEUE_ID/tasks" | Select-Object -Expand Content

APIs Explorer (瀏覽器)

複製要求主體，然後開啟方法參考頁面。頁面右側會開啟 APIs Explorer 面板。您可以與這項工具互動來傳送要求。將要求主體貼在這項工具中，並完成任何其他必填欄位，然後按一下「Execute」(執行)。

如果成功，回應主體會包含新建立的 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"
}