再試行イベント

Eventarc Standard は、少なくとも 1 回のイベント配信をサポートしています。つまり、宛先がイベントの確認応答に失敗した場合、Eventarc は自動的に再配信を試みます。

Eventarc Standard の再試行の特性は、そのトランスポート層である Cloud Pub/Sub の再試行の特性と一致します。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 サブスクリプションを確認する手順は次のとおりです。

gcloud eventarc triggers describe TRIGGER_NAME \
    --location=LOCATION

  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 state show google_eventarc_trigger.default

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

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

$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

{
  "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 サブスクリプションの再試行ポリシーを更新するには、次の操作を行います。

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

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": {
    "retryPolicy": {
      "minimumBackoff": "MIN_RETRY_DELAYs",
      "maximumBackoff": "MAX_RETRY_DELAYs"
    }
  },
  "updateMask": "retry_policy.maximum_backoff,retry_policy.minimum_backoff"
}

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

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"

@'
{
  "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

$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

{
  "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 をべき等のキーとして使用します。
• べき等では再試行が安全に行われるため、at-least-once 配信でうまく機能します。したがって、信頼性の高いコードを書くための一般的なベスト プラクティスは、べき等と再試行を組み合わせることです。
• コードが内部でべき等であることを確認します。次に例を示します。
  • 結果が変わらずにミューテーションが 2 回以上起こることを確認する。
  • 状態を変更する前にトランザクション内のデータベース状態を照会する。
  • すべての副作用がそれ自体べき等であることを確認する。
• コードとは関係なく、トランザクション チェックをサービスの外側に置きます。たとえば、指定されたイベント ID がすでに処理されたことを記録している場所の状態を保持します。
• 重複した呼び出しを帯域外で処理するたとえば、重複した呼び出しの後にクリーンアップする別のクリーンアップ プロセスを用意します。