Eventarc Standard 支援至少傳送一次事件。也就是說,如果目的地無法確認事件,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 如何處理重試,請參閱「處理訊息失敗情形」和「重試要求」。
處理重試的最佳做法
如果事件訊息無法在訊息保留期限內成功傳送,系統會捨棄該訊息 (除非已設定無效信件主題)。您可以透過死信主題儲存及分析持續性失敗。請參閱本文的「無效信件主題」一節。
由於系統會至少傳送一次事件,事件處理常式可能會收到重複事件。最佳做法是將處理常式設計為冪等。請參閱本文中的等冪事件處理常式。
設定重試
您可能想自訂預設的重試行為。所有重試和保留設定都是透過與 Eventarc 觸發條件相關聯的 Pub/Sub 訂閱項目重試政策設定。
如要修改訂閱重試政策,請先找出與 Eventarc 觸發程序相關聯的 Pub/Sub 訂閱項目。然後更新訂閱方案。
如要進一步瞭解訂閱項目屬性,請參閱「訂閱項目屬性」。如要瞭解訂閱項目限制,請參閱 Pub/Sub 資源限制。
找出訂閱項目
如要找出與 Eventarc 觸發條件相關聯的 Pub/Sub 訂閱項目,請按照下列步驟操作:
控制台
在 Google Cloud 控制台中,前往 Eventarc「Triggers」(觸發條件) 頁面。
在觸發條件清單中,按一下要查看詳細資料的觸發條件。
按一下主題名稱。
如要顯示訂閱 ID,請按一下「Subscriptions」(訂閱項目) 分頁標籤。
gcloud
您可以使用 gcloud eventarc triggers describe
指令擷取訂閱 ID。
gcloud eventarc triggers describe TRIGGER_NAME \ --location=LOCATION
更改下列內容:
TRIGGER_NAME
:觸發條件的名稱或完整 ID。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
如要描述 Terraform 資源,可以使用 state show
指令。google_eventarc_trigger
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 on 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 訂閱項目重試政策,請按照下列步驟操作:
控制台
在 Google Cloud 控制台中,前往 Eventarc「Triggers」(觸發條件) 頁面。
在觸發條件清單中,按一下要查看詳細資料的觸發條件。
按一下主題名稱。
如要顯示訂閱 ID,請按一下「Subscriptions」(訂閱項目) 分頁標籤。
按一下訂閱 ID,然後按一下
「編輯」。在「Retry policy」(重試政策) 區段中,選取「Retry immediately」(立即重試)。
或者,如要在指數輪詢延遲時間過後重試,請輸入下列以秒為單位的時間值:
輪詢時間下限:連續傳送特定訊息之間的最短延遲時間 (以秒為單位)。預設值為 10 秒,且應介於 0 到 600 之間。
輪詢時間上限:連續傳送特定訊息之間的最大延遲時間 (以秒為單位)。預設值為 600 秒,應介於 0 到 600 之間。
詳情請參閱「重試政策」。
按一下「Update」。
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 或完整 ID。您必須指定下列兩個標記,才能在指數輪詢延遲後重試;否則,任何省略的標記都會還原為預設值:
MIN_RETRY_DELAY
:連續傳送指定訊息之間的最短延遲時間 (以秒為單位)。預設為 10 秒,且應介於 0 到 600 之間。MAX_RETRY_DELAY
:連續傳送指定訊息時,延遲時間上限 (以秒為單位)。預設值為 600 秒,且應介於 0 到 600 之間。
如有需要,您可以使用 --clear-retry-policy
標記清除重試政策,並將訂閱項目設為立即重試。
Terraform
如要更新 Pub/Sub 訂閱項目的重試政策,請設定 google_pubsub_subscription
Terraform 資源。使用 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" }
其他重試注意事項
處理處理失敗或轉送未送達的訊息時,請注意下列事項。
延遲推送
如果推送訂閱者傳送過多負面確認訊息,Pub/Sub 可能會開始使用推送退避機制傳送訊息。Pub/Sub 採用推送退避策略時,會停止傳送訊息一段預先決定的時間。時間範圍可介於 100 毫秒到 60 秒之間。時間到期後,Pub/Sub 會再次開始傳送訊息。詳情請參閱「推送輪詢」。
無效信件主題
如果目的地未收到訊息,您可以將未傳送的訊息轉寄至無效信件主題 (也稱為無效信件佇列)。如果目的地無法確認訊息,dead-letter 主題就會儲存這些訊息。建立或更新 Pub/Sub 訂閱項目時,您必須設定死信主題,而不是在建立 Pub/Sub 主題時,或 Eventarc 建立 Pub/Sub 主題時。詳情請參閱「設定無法傳送訊息的主題」。
不值得重試的錯誤
如果應用程式使用 Pub/Sub 做為事件來源,但事件未傳送成功,系統會自動重試,但若發生錯誤,則無法保證會重試。如果工作流程未執行,系統不會重試將任何來源的事件傳送至 Workflows 目的地。請注意,工作流程執行作業開始後,Workflows 就會確認收到事件。如果工作流程執行作業開始後失敗,系統不會重試執行作業。如要解決這類服務問題,您應在工作流程中處理錯誤和重試。
重複的活動
系統可能會將重複事件傳送至事件處理常式。根據 CloudEvents 規格,source
和 id
屬性的組合視為不重複,因此任何具有相同組合的事件都會視為重複。一般而言,您應導入等冪事件處理常式,這是最佳做法。
冪等事件處理常式
可重試的事件處理常式應為等冪,並遵循下列一般準則:
- 許多外部 API 都允許您以參數形式提供冪等金鑰。如果您使用這類 API,應將事件 ID 做為等冪鍵。
- 冪等性與「至少傳送一次」的傳送方式搭配使用效果良好,因為這樣重試作業會更安全。因此,撰寫可靠程式碼的一般最佳做法,是將等冪性與重試機制結合。
- 請確保您的程式碼為內部冪等。例如:
- 請確保異動可發生多次,但結果不會改變。
- 在變更狀態之前,查詢交易中的資料庫狀態。
- 確保所有連帶影響本身也是冪等的。
- 在服務外部強制執行交易檢查,與程式碼無關。 舉例來說,您可以將狀態保留在某個位置,記錄特定事件 ID 是否已處理完畢。
- 處理頻外重複呼叫。舉例來說,您可以另外建立清除程序,在重複呼叫後進行清除。