重試事件

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 訂閱項目,請按照下列步驟操作:

控制台

  1. 在 Google Cloud 控制台中,前往 Eventarc「Triggers」(觸發條件) 頁面。

    前往「Triggers」(觸發條件)

  2. 在觸發條件清單中,按一下要查看詳細資料的觸發條件。

  3. 按一下主題名稱。

  4. 如要顯示訂閱 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 訂閱項目重試政策,請按照下列步驟操作:

控制台

  1. 在 Google Cloud 控制台中,前往 Eventarc「Triggers」(觸發條件) 頁面。

    前往「Triggers」(觸發條件)

  2. 在觸發條件清單中,按一下要查看詳細資料的觸發條件。

  3. 按一下主題名稱。

  4. 如要顯示訂閱 ID,請按一下「Subscriptions」(訂閱項目) 分頁標籤。

  5. 按一下訂閱 ID,然後按一下 「編輯」

  6. 在「Retry policy」(重試政策) 區段中,選取「Retry immediately」(立即重試)

    或者,如要在指數輪詢延遲時間過後重試,請輸入下列以秒為單位的時間值:

    • 輪詢時間下限:連續傳送特定訊息之間的最短延遲時間 (以秒為單位)。預設值為 10 秒,且應介於 0 到 600 之間。

    • 輪詢時間上限:連續傳送特定訊息之間的最大延遲時間 (以秒為單位)。預設值為 600 秒,應介於 0 到 600 之間。

    詳情請參閱「重試政策」。

  7. 按一下「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 規格sourceid 屬性的組合視為不重複,因此任何具有相同組合的事件都會視為重複。一般而言,您應導入等冪事件處理常式,這是最佳做法。

冪等事件處理常式

可重試的事件處理常式應為等冪,並遵循下列一般準則:

  • 許多外部 API 都允許您以參數形式提供冪等金鑰。如果您使用這類 API,應將事件 ID 做為等冪鍵。
  • 冪等性與「至少傳送一次」的傳送方式搭配使用效果良好,因為這樣重試作業會更安全。因此,撰寫可靠程式碼的一般最佳做法,是將等冪性與重試機制結合。
  • 請確保您的程式碼為內部冪等。例如:
    • 請確保異動可發生多次,但結果不會改變。
    • 在變更狀態之前,查詢交易中的資料庫狀態。
    • 確保所有連帶影響本身也是冪等的。
  • 在服務外部強制執行交易檢查,與程式碼無關。 舉例來說,您可以將狀態保留在某個位置,記錄特定事件 ID 是否已處理完畢。
  • 處理頻外重複呼叫。舉例來說,您可以另外建立清除程序,在重複呼叫後進行清除。