Eventarc Standard は、at-least-once のイベント配信をサポートしています。つまり、宛先がイベントを確認応答できない場合、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 が再試行を処理する方法の詳細については、 メッセージ エラーの処理と リクエストの再試行をご覧ください。
再試行を処理するためのベスト プラクティス
デッドレター トピックが構成されていない限り、イベント メッセージがメッセージ保持期間内に正常に配信されない場合は破棄されます。デッドレター トピックを使用すると、永続的な障害を保存して分析できます。この ドキュメントのデッドレター トピックをご覧ください。
at-least-once 配信のため、イベント ハンドラが重複するイベントを受信する可能性があります。ハンドラをべき等にするように設計することが効果的な手法です。この ドキュメントのべき等イベント ハンドラをご覧ください。
再試行を構成する
デフォルトの再試行動作をカスタマイズできます。すべての再試行と保持の設定は、Eventarc トリガーに関連付けられた Pub/Sub サブスクリプション再試行ポリシーを使用して構成されます。
サブスクリプション再試行ポリシーを変更するには、まず Eventarc トリガーに関連付けられた Pub/Sub サブスクリプションを特定します。次に、サブスクリプション自体を更新します。
サブスクリプション プロパティの詳細については、 サブスクリプション プロパティをご覧ください。サブスクリプションの上限については、 Pub/Sub リソースの上限をご覧ください。
サブスクリプションを特定する
Eventarc トリガーに関連付けられた Pub/Sub サブスクリプションを特定する手順は次のとおりです。
コンソール
コンソールで [Eventarc] の [**トリガー**] ページに移動します。 Google Cloud
トリガーのリストから、詳細を確認するトリガーをクリックします。
トピック名をクリックします。
サブスクリプション 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 の使用方法の詳細については、 Terraform のドキュメントをご覧ください。 Google Cloud
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 サブスクリプション再試行ポリシーを更新する手順は次のとおりです。
コンソール
コンソールで [Eventarc] の [**トリガー**] ページに移動します。 Google Cloud
トリガーのリストから、詳細を確認するトリガーをクリックします。
トピック名をクリックします。
サブスクリプション ID を表示するには、[サブスクリプション] タブをクリックします。
サブスクリプション ID をクリックし、 [Edit] をクリックします。
[再試行ポリシー] セクションで、[すぐに再試行] を選択します。
または、指数バックオフ期間の経過後に再試行するには、次の値を秒単位で入力します。
最小バックオフ: 特定のメッセージが連続して 配信される間の最小遅延時間（秒）。デフォルトは 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 が状態ファイル内のリソース
を追跡できるようになります。インポートしたリソースは、他のリソースと同様に管理できます。
リソースの更新時に Terraform が無視する属性を指定するには、
ignore_changes
を使用します。
次に例を示します。
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 バックオフ
push サブスクライバーが送信する否定確認応答が多すぎる場合、Pub/Sub は push バックオフを使用してメッセージ配信を開始する可能性があります。 Pub/Sub が push バックオフを使用すると、事前に設定された期間、メッセージの配信を停止します。この期間は 100 ミリ秒から 60 秒までです。時間が経過すると、Pub/Sub はメッセージの配信を再開します。詳細については、push バックオフをご覧ください。
デッドレター トピック
宛先がメッセージを受信しない場合は、配信不能メッセージをデッドレター トピック（デッドレター キュー）に転送できます。デッドレター トピックには、宛先が認識できないメッセージを格納できます。デッドレター トピックは、Pub/Sub トピックの作成時や Eventarc による Pub/Sub トピックの作成時ではなく、Pub/Sub サブスクリプションを作成または更新するときに設定する必要があります。詳細については、 デッドレター トピックを構成するをご覧ください。
再試行が保証されないエラー
アプリケーションがイベントソースとして Pub/Sub を使用し、イベントが配信されない場合、イベントは自動的に再試行されます。ただし、再試行を保証しないエラーの場合は再試行されません。ワークフローが実行されなければ、任意のソースから Workflows の宛先へのイベントは再試行されません。ワークフロー実行が開始するとすぐに、Workflows はイベントの確認応答を行います。ワークフロー実行が開始して、その後失敗した場合、実行は再試行されません。このようなサービスの問題を解決するには、ワークフロー内で エラーや 再試行に対処する必要があります。
重複するイベント
重複するイベントがイベント ハンドラに配信される場合があります。CloudEvents 仕様により、source 属性と id 属性の組み合わせは一意と見なされるため、同じ組み合わせを持つイベントは重複と見なされます。一般的な効果的な手法として、べき等イベント ハンドラを実装する必要があります。
べき等イベント ハンドラ
再試行可能なイベント ハンドラは、次の一般的なガイドラインに沿ってべき等にする必要があります。
- 多くの外部 API では、べき等のキーをパラメータとして指定できます。このような API を使用している場合は、イベント ID をべき等のキーとして使用します。
- べき等では再試行が安全に行われるため、at-least-once 配信でうまく機能します。したがって、信頼性の高いコードを書くための一般的なベスト プラクティスは、べき等と再試行を組み合わせることです。
- コードが内部でべき等であることを確認します。次に例を示します。
- 結果が変わらずにミューテーションが 2 回以上起こることを確認する。
- 状態を変更する前にトランザクション内のデータベース状態を照会する。
- すべての副作用がそれ自体べき等であることを確認する。
- コードとは関係なく、トランザクション チェックをサービスの外側に置きます。たとえば、指定されたイベント ID がすでに処理されたことを記録している場所の状態を保持します。
- 重複した呼び出しを帯域外で処理するたとえば、重複した呼び出しの後にクリーンアップする別のクリーンアップ プロセスを用意します。