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 サブスクリプションを確認する手順は次のとおりです。
コンソール
Google Cloud コンソールで、Eventarc の [トリガー] ページに移動します。
トリガーのリストから、詳細を確認するトリガーをクリックします。
トピック名をクリックします。
サブスクリプション ID を表示するには、[サブスクリプション] タブをクリックします。
gcloud
サブスクリプション ID を取得するには、gcloud eventarc triggers describe コマンドを使用します。
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）。
リクエストを送信するには、次のいずれかのオプションを展開します。
成功した場合、レスポンスの本文には次のような 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"
}
リクエストを送信するには、次のいずれかのオプションを展開します。
成功した場合、レスポンスの本文には次のような 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 をべき等のキーとして使用します。
- べき等では再試行が安全に行われるため、at-least-once 配信でうまく機能します。したがって、信頼性の高いコードを書くための一般的なベスト プラクティスは、べき等と再試行を組み合わせることです。
- コードが内部でべき等であることを確認します。次に例を示します。
- 結果が変わらずにミューテーションが 2 回以上起こることを確認する。
- 状態を変更する前にトランザクション内のデータベース状態を照会する。
- すべての副作用がそれ自体べき等であることを確認する。
- コードとは関係なく、トランザクション チェックをサービスの外側に置きます。たとえば、指定されたイベント ID がすでに処理されたことを記録している場所の状態を保持します。
- 重複した呼び出しを帯域外で処理するたとえば、重複した呼び出しの後にクリーンアップする別のクリーンアップ プロセスを用意します。