Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

작업의 재시도 매개변수 설정

태스크를 만들 때 실패한 태스크를 재시도할 최대 횟수를 지정하고 재시도에 대한 시간 제한을 설정하며 시도 사이의 간격을 제어할 수 있습니다.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: 필수 항목입니다. 요청이 전송될 정규화된 URL입니다. 이 문자열은 http:// 또는 https://로 시작해야 합니다(예: https://www.example.com).
참고: Cloud Run 서비스 또는 함수를 타겟팅하려면 기본 run.app URL을 사용하세요.
SERVICE_ACCOUNT_EMAIL: 선택사항입니다. 태스크를 실행할 때 대상에 전송되는 요청에 포함된 승인 토큰을 생성하는 데 사용되는 서비스 계정 이메일입니다. 서비스 계정은 큐와 동일한 프로젝트에 있어야 합니다. 호출자에게 서비스 계정에 대한 iam.serviceAccounts.actAs 권한이 있어야 합니다.
OpenID Connect 토큰 대신 OAuth2 액세스 토큰을 생성하려면 oidcToken 필드를 oauthToken으로 바꿔 서비스 계정 이메일을 지정합니다.
MAX_ATTEMPTS: 선택사항입니다. 첫 번째 시도를 포함하여 태스크의 최대 시도 횟수입니다. 무제한 재시도를 허용하려면 이 값을 -1로 설정합니다. 에 도달하거나 -1로 설정된 경우에도 MAX_RETRY_DURATION이 계속 적용됩니다.MAX_ATTEMPTS
MAX_RETRY_DURATION: 선택사항입니다. 실패한 태스크를 재시도할 수 있는 최대 시간으로, 태스크가 처음 시도되었을 때부터 측정됩니다. 값은 5s와 같이 's'로 끝나는 문자열이어야 합니다. 무제한 기간을 지정하려면 이 값을 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_ATTEMPTS번 시도될 때까지 MAX_INTERVAL 간격으로 재시도됩니다. 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 탐색기(브라우저)

요청 본문을 복사하고 메서드 참조 페이지를 엽니다. 페이지 오른쪽에 API 탐색기 패널이 열립니다. 이 도구를 사용하여 요청을 보낼 수 있습니다. 요청 본문을 이 도구에 붙여넣고 다른 필수 필드를 입력한 후 실행 을 클릭합니다.

성공한 경우 응답 본문에 새로 생성된 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"
}