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: 필수 항목입니다. 요청이 전송될 정규화된 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로 설정합니다. MAX_ATTEMPTS에 도달하거나 -1로 설정된 경우에도 MAX_RETRY_DURATION가 적용됩니다.
MAX_RETRY_DURATION: 선택사항입니다. 실패한 태스크를 재시도할 수 있는 최대 시간으로, 태스크가 처음 시도되었을 때부터 측정됩니다. 값은 5s와 같이 's'로 끝나는 문자열이어야 합니다. 무제한 기간을 지정하려면 0s로 설정합니다. MAX_RETRY_DURATION에 도달하거나 0s로 설정된 경우에도 MAX_ATTEMPTS가 적용됩니다.
참고: 무제한 시도 (MAX_ATTEMPTS이 -1) 및 무제한 기간 (MAX_RETRY_DURATION이 0s)을 지정하면 최대 작업 보관 기간 한도에 도달할 때까지 작업이 다시 시도됩니다. 그렇지 않으면 Cloud Tasks는 두 조건이 모두 충족되거나 작업이 성공한 후에만 재시도를 중지합니다.
MIN_INTERVAL: 선택사항입니다. 재시도 사이에 대기해야 하는 최소 시간입니다. 값은 5s와 같이 's'로 끝나는 문자열이어야 합니다.
MAX_INTERVAL: 선택사항입니다. 재시도 사이에 대기해야 하는 최대 시간입니다. 값은 5s와 같이 's'로 끝나는 문자열이어야 합니다.
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"
}