이 페이지는 Cloud Translation API를 통해 번역되었습니다.

재시도 이벤트

표준

Eventarc Standard는 최소 1회 이상 이벤트 전송을 지원합니다. 즉, 대상이 이벤트를 확인하지 못하면 Eventarc에서 자동으로 다시 전송을 시도합니다.

Eventarc Standard의 재시도 특성은 구독 재시도 정책을 사용하여 처리 실패를 처리하는 전송 계층인 Cloud Pub/Sub의 재시도 특성과 일치합니다.

재시도 작동 방식

Eventarc 트리거를 만들면 Pub/Sub 전송 주제와 구독이 자동으로 생성됩니다. (Pub/Sub 소스의 이벤트는 기존 Pub/Sub 주제를 사용할 수 있습니다.) Eventarc에서 자동으로 생성된 모든 구독 ID는 eventarc-REGION-로 시작하는 형식을 취합니다.

기본적으로 대상에서 메시지를 확인할 수 없는 경우 Pub/Sub는 지수 백오프 지연을 사용하여 메시지를 다시 전송합니다. 지수 백오프를 사용하면 재시도 사이에 점진적으로 좀 더 긴 지연 시간을 추가할 수 있습니다. 기본 지연 시간은 최소 10초로 시작하며 후속 실패가 발생할 때마다 최대 600초까지 증가합니다. Eventarc는 기본 메시지 보관 기간을 24시간으로 설정합니다.

Pub/Sub에서 재시도를 처리하는 방법에 대한 자세한 내용은 메시지 오류 처리 및 요청 재시도를 참고하세요.

재시도 처리 권장사항

이벤트 메시지가 메시지 보관 기간 내에 성공적으로 전송되지 않으면 데드 레터 주제가 구성되지 않는 한 삭제됩니다. 데드 레터 주제를 사용하면 지속적인 실패를 저장하고 분석할 수 있습니다. 이 문서에서 데드 레터 주제를 참고하세요.

최소 1회 전송으로 인해 이벤트 핸들러가 중복 이벤트를 수신할 수 있습니다. 핸들러가 멱등성이 되도록 설계하는 것이 좋습니다. 이 문서에서 멱등 이벤트 핸들러를 참고하세요.

재시도 구성

기본 재시도 동작을 맞춤설정할 수 있습니다. 모든 재시도 및 보관 설정은 Eventarc 트리거와 연결된 Pub/Sub 구독 재시도 정책을 통해 구성됩니다.

구독 재시도 정책을 수정하려면 먼저 Eventarc 트리거와 연결된 Pub/Sub 구독을 식별합니다. 그런 다음 구독 자체를 업데이트합니다.

구독 속성에 관한 자세한 내용은 구독 속성을 참고하세요. 구독 한도에 관한 자세한 내용은 Pub/Sub 리소스 한도를 참고하세요.

구독 확인

Eventarc 트리거와 연결된 Pub/Sub 정기 결제를 확인하려면 다음 단계를 따르세요.

콘솔

Google Cloud 콘솔에서 Eventarc 트리거 페이지로 이동합니다.

트리거로 이동
트리거 목록에서 세부정보를 확인하려는 트리거를 클릭합니다.
주제 이름을 클릭합니다.
구독 ID를 표시하려면 구독 탭을 클릭합니다.

gcloud

gcloud eventarc triggers describe 명령어를 사용하여 정기 결제 ID를 검색할 수 있습니다.

gcloud eventarc triggers describe TRIGGER_NAME \
    --location=LOCATION

다음을 바꿉니다.

TRIGGER_NAME: 트리거의 이름 또는 정규화된 식별자입니다.
LOCATION: Eventarc 트리거 위치입니다.

이 명령어는 다음과 유사하고 구독 ID가 포함된 트리거에 대한 정보를 반환합니다.

  createTime: '2023-03-16T13:40:44.889670204Z'
  destination:
    cloudRun:
      path: /
      region: us-central1
      service: hello
  eventDataContentType: application/protobuf
  eventFilters:
  ...
  transport:
    pubsub:
      subscription: projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID
      topic: projects/PROJECT_ID/topics/TOPIC_ID

Terraform

google_eventarc_trigger Terraform 리소스를 설명하려면 state show 명령어를 사용하면 됩니다.

terraform state show google_eventarc_trigger.default

state show 명령어는 정기 결제 ID를 포함한 트리거에 대한 정보를 반환합니다. 예를 들면 다음과 같습니다.

# google_eventarc_trigger.default:
resource "google_eventarc_trigger" "default" {
    conditions              = {}
    create_time             = "2025-07-14T17:29:22.575033822Z"
    effective_labels        = {
        "goog-terraform-provisioned" = "true"
    }
    ...
    transport {
        pubsub {
            subscription = "projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID"
            topic        = "projects/PROJECT_ID/topics/TOPIC_ID"
        }
    }
}

Terraform 사용에 대한 자세한 내용은 Google Cloud 의 Terraform 문서를 참고하세요.

REST

특정 프로젝트 및 위치의 트리거를 설명하려면 projects.locations.triggers.get 메서드를 사용하세요.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

TRIGGER_NAME: 설명하려는 트리거의 이름
PROJECT_ID: Google Cloud프로젝트 ID
LOCATION: 트리거가 생성되는 리전(예: us-central1)

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

cURL(Linux, macOS, Cloud Shell)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

다음 명령어를 실행합니다.

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://eventarc.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/triggers/TRIGGER_NAME"

PowerShell(Windows)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

다음 명령어를 실행합니다.

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

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://eventarc.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/triggers/TRIGGER_NAME" | Select-Object -Expand Content

성공한 경우 응답 본문에는 다음과 유사한 Trigger 인스턴스가 포함됩니다.

{
  "name": "projects/PROJECT_ID/locations/LOCATION/triggers/TRIGGER_NAME",
  "uid": "d700773a-698b-47b2-a712-2ee10b690062",
  "createTime": "2022-12-06T22:44:04.744001514Z",
  "updateTime": "2022-12-06T22:44:09.116459550Z",
  "eventFilters": [
    {
      "attribute": "type",
      "value": "google.cloud.pubsub.topic.v1.messagePublished"
    }
  ],
  "serviceAccount": "SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com",
  "destination": {
    "workflow": "projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_NAME"
  },
  "transport": {
    "pubsub": {
      "topic": "projects/PROJECT_ID/topics/TOPIC_ID",
      "subscription": "projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID"
    }
  }
}

구독 업데이트

Eventarc 트리거와 연결된 Pub/Sub 구독 재시도 정책을 업데이트하려면 다음 단계를 따르세요.

콘솔

Google Cloud 콘솔에서 Eventarc 트리거 페이지로 이동합니다.

트리거로 이동
트리거 목록에서 세부정보를 확인하려는 트리거를 클릭합니다.
주제 이름을 클릭합니다.
구독 ID를 표시하려면 구독 탭을 클릭합니다.
구독 ID를 클릭한 다음 수정을 클릭합니다.
재시도 정책 섹션에서 즉시 재시도를 선택합니다.

또는 지수 백오프 지연 후 다시 시도하려면 다음 값을 초 단위로 입력합니다.
- 최소 백오프: 지정된 메시지의 연속 전송 간 최소 지연 시간(초)입니다. 기본값은 10초이며 0~600 사이여야 합니다.
- 최대 백오프: 지정된 메시지의 연속 전송 사이의 최대 지연 시간(초)입니다. 기본값은 600초이며 0~600 사이여야 합니다.
자세한 내용은 재시도 정책을 참고하세요.
업데이트를 클릭합니다.

gcloud

gcloud pubsub subscriptions update 명령어를 사용하여 정기 결제 재시도 정책을 업데이트할 수 있습니다.

gcloud pubsub subscriptions update SUBSCRIPTION_ID \
    --min-retry-delay=MIN_RETRY_DELAY \
    --max-retry-delay=MAX_RETRY_DELAY

다음을 바꿉니다.

SUBSCRIPTION_ID: 정기 결제의 ID 또는 정규화된 식별자입니다.
지수 백오프 지연 후 재시도하려면 다음 플래그를 모두 지정해야 합니다. 그렇지 않으면 생략된 플래그가 기본값으로 되돌아갑니다.
- MIN_RETRY_DELAY: 지정된 메시지의 연속 전송 간 최소 지연 시간(초)입니다. 기본값은 10초이며 0~600 사이여야 합니다.
- MAX_RETRY_DELAY: 지정된 메시지의 연속 전송 간 최대 지연 시간(초)입니다. 기본값은 600초이며 0~600 사이여야 합니다.

원하는 경우 --clear-retry-policy 플래그를 사용하여 재시도 정책을 지우고 정기 결제를 즉시 재시도하도록 설정할 수 있습니다.

Terraform

google_pubsub_subscription Terraform 리소스를 구성하여 Pub/Sub 구독 재시도 정책을 업데이트할 수 있습니다. import 블록을 사용하여 기존 구독을 가져오면 Terraform이 상태 파일에서 리소스를 추적할 수 있습니다. 그런 다음 ignore_changes를 사용하여 리소스를 업데이트할 때 Terraform에서 무시해야 하는 속성을 지정하여 가져온 리소스를 다른 리소스와 마찬가지로 관리할 수 있습니다.

예를 들면 다음과 같습니다.

import {
  to = google_pubsub_subscription.default
  id = "SUBSCRIPTION_ID"
}

resource "google_pubsub_subscription" "default" {
  name  = "SUBSCRIPTION_ID"
  topic = "TOPIC_ID"
  retry_policy {
    minimum_backoff = "MIN_RETRY_DELAYs"
    maximum_backoff = "MAX_RETRY_DELAYs"
  }
  lifecycle {
    # Ignore push delivery configuration which is managed by Eventarc
    ignore_changes = [push_config]
  }
}

다음을 바꿉니다.

SUBSCRIPTION_ID: 구독의 ID
TOPIC_ID: 주제의 ID
MIN_RETRY_DELAY: 지정된 메시지의 연속 전송 간 최소 지연 시간(초)입니다. 기본값은 10초이며 0~600 사이여야 합니다.
MAX_RETRY_DELAY: 지정된 메시지의 연속 전송 간 최대 지연 시간(초)입니다. 기본값은 600초이며 0~600 사이여야 합니다.

REST

지정된 프로젝트에서 구독의 재시도 정책을 업데이트하려면 projects.subscriptions.patch 메서드를 사용합니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

MIN_RETRY_DELAY: 지정된 메시지의 연속 전송 간 최소 지연 시간(초)입니다. 기본값은 10초이며 0~600초여야 합니다.
MAX_RETRY_DELAY: 지정된 메시지의 연속 전송 간 최대 지연 시간(초)입니다. 기본값은 600초이며 0~600 사이여야 합니다.
PROJECT_ID: Google Cloud프로젝트 ID
SUBSCRIPTION_ID: 업데이트할 Pub/Sub 구독의 ID입니다.

JSON 요청 본문:

{
  "subscription": {
    "retryPolicy": {
      "minimumBackoff": "MIN_RETRY_DELAYs",
      "maximumBackoff": "MAX_RETRY_DELAYs"
    }
  },
  "updateMask": "retry_policy.maximum_backoff,retry_policy.minimum_backoff"
}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

cURL(Linux, macOS, Cloud Shell)

요청 본문을 request.json 파일에 저장합니다. 터미널에서 다음 명령어를 실행하여 현재 디렉터리에 이 파일을 만들거나 덮어씁니다.

cat > request.json << 'EOF'
{
  "subscription": {
    "retryPolicy": {
      "minimumBackoff": "MIN_RETRY_DELAYs",
      "maximumBackoff": "MAX_RETRY_DELAYs"
    }
  },
  "updateMask": "retry_policy.maximum_backoff,retry_policy.minimum_backoff"
}
EOF

그런 후 다음 명령어를 실행하여 REST 요청을 전송합니다.

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID"

PowerShell(Windows)

요청 본문을 request.json 파일에 저장합니다. 터미널에서 다음 명령어를 실행하여 현재 디렉터리에 이 파일을 만들거나 덮어씁니다.

@'
{
  "subscription": {
    "retryPolicy": {
      "minimumBackoff": "MIN_RETRY_DELAYs",
      "maximumBackoff": "MAX_RETRY_DELAYs"
    }
  },
  "updateMask": "retry_policy.maximum_backoff,retry_policy.minimum_backoff"
}
'@  | Out-File -FilePath request.json -Encoding utf8

그런 후 다음 명령어를 실행하여 REST 요청을 전송합니다.

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

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID" | Select-Object -Expand Content

성공한 경우 응답 본문에는 다음과 유사한 Subscription 인스턴스가 포함됩니다.

{
  "name": "projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID",
  "topic": "projects/PROJECT_ID/topics/TOPIC_ID",
  ...
  "retryPolicy": {
    "minimumBackoff": "MIN_RETRY_DELAYs",
    "maximumBackoff": "MAX_RETRY_DELAYs"
  },
  "state": "ACTIVE"
}

기타 재시도 고려사항

처리 실패를 처리하거나 전송되지 않은 메시지를 전달할 때는 다음 고려사항에 유의해야 합니다.

푸시 백오프

push 구독자가 부정 확인을 너무 많이 전송하면 Pub/Sub에서 push 백오프를 사용해 메시지를 전송하기 시작할 수 있습니다. Pub/Sub는 push 백오프를 사용할 때 미리 정해진 시간 동안 메시지 전송을 중지합니다. 이 시간 범위는 100밀리초~60초입니다. 이 시간이 지나면 Pub/Sub에서 메시지를 다시 전송하기 시작합니다. 자세한 내용은 푸시 백오프를 참고하세요.

데드 레터 주제

대상이 메시지를 수신하지 않으면 전달되지 않은 메시지를 데드 레터 주제(데드 레터 큐라고도 함)로 전달할 수 있습니다. 데드 레터 주제는 대상이 확인하지 못한 메시지를 저장할 수 있습니다. Pub/Sub 주제를 만들거나 Eventarc에서 Pub/Sub 주제를 만드는 경우가 아니라 Pub/Sub 구독을 만들거나 업데이트할 때 데드 레터 주제를 설정해야 합니다. 자세한 내용은 데드 레터 주제 구성을 참고하세요.

재시도를 보증할 수 없는 오류

애플리케이션에서 Pub/Sub를 이벤트 소스로 사용하고 이벤트가 전달되지 않으면 재시도를 보증할 수 없는 오류를 제외하고 이벤트가 자동으로 재시도됩니다. 모든 소스에서 Workflows 대상에 대한 이벤트는 워크플로가 실행되지 않으면 재시도되지 않습니다. Workflows는 워크플로 실행이 시작되는 즉시 이벤트를 확인합니다. 워크플로 실행이 시작되었지만 나중에 실패하면 실행은 재시도되지 않습니다. 이러한 서비스 문제를 해결하려면 워크플로 내에서 오류와 재시도를 처리해야 합니다.

중복 이벤트

중복 이벤트가 이벤트 핸들러에 전달될 수 있습니다. CloudEvents 사양에 따라 source 속성과 id 속성의 조합은 고유한 것으로 간주되므로 동일한 조합을 갖는 모든 이벤트는 중복으로 간주됩니다. 일반적인 권장사항에 따라 멱등성 이벤트 핸들러를 구현해야 합니다.

멱등성 이벤트 핸들러

재시도할 수 있는 이벤트 핸들러는 다음 일반 가이드라인을 사용하여 멱등성을 가져야 합니다.

다양한 외부 API를 사용하면 매개변수로 멱등 키를 제공할 수 있습니다. 이러한 API를 사용한다면 이벤트 ID를 멱등 키로 사용해야 합니다.
멱등성이 있으면 재시도해도 안전하므로 최소 1회 전송 시 잘 작동합니다. 따라서 안정적인 코드를 작성하기 위한 일반적인 권장사항은 재시도와 멱등성을 결합하는 것입니다.
코드에 내부적으로 멱등성이 있어야 합니다. 예를 들면 다음과 같습니다.
- 결과에 변화 없이 변형이 2번 이상 발생할 수 있는지 확인합니다.
- 상태가 변형되기 전에 트랜잭션에서 데이터베이스 상태를 쿼리합니다.
- 모든 부가적인 결과에 자체적으로 멱등성이 있는지 확인합니다.
코드에 관계없이 서비스 외부에서 트랜잭션 검사를 시행합니다. 예를 들어 특정 이벤트 ID가 이미 처리되었음을 어딘가에 기록하는 상태를 유지합니다.
중복 호출을 대역 외로 처리합니다. 예를 들어 중복 호출 후 삭제하는 별도의 삭제 프로세스를 둡니다.

재시도 이벤트 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

재시도 작동 방식

재시도 처리 권장사항

재시도 구성

구독 확인

콘솔

gcloud

Terraform

REST

cURL(Linux, macOS, Cloud Shell)

PowerShell(Windows)

구독 업데이트

콘솔

gcloud

Terraform

REST

cURL(Linux, macOS, Cloud Shell)

PowerShell(Windows)

기타 재시도 고려사항

푸시 백오프

데드 레터 주제

재시도를 보증할 수 없는 오류

중복 이벤트

멱등성 이벤트 핸들러

재시도 이벤트