使用 Eventarc 建立觸發條件

本頁面說明如何建立 Eventarc 觸發條件，讓 Cloud Run 服務接收來自其他 Google Cloud 服務的事件。

Eventarc 是一項 Google Cloud服務，可讓您建構事件導向架構，不必實作、自訂或維護基礎架構。

您可以指定觸發條件的篩選器，並設定事件的轉送方式 (包括事件來源和目標 Cloud Run 服務)，藉此建立 Eventarc 觸發條件。當指定的事件或事件集符合篩選條件時，系統會因應事件自動叫用 Cloud Run 服務。使用 Eventarc 觸發器的服務稱為事件驅動服務。傳送至 Cloud Run 服務的事件以 HTTP 請求的形式接收。

下列事件類型會觸發對服務的要求：

• 符合觸發條件篩選條件的稽核記錄
• 直接事件，例如 Cloud Storage bucket 的更新
• 直接訊息發布到 Pub/Sub 主題

觸發地點

建立 Eventarc 觸發條件時，您需要指定位置。這應與要監控事件的 資源 Google Cloud 位置相符。在大多數情況下，您也應該在同一區域部署事件驅動型 Cloud Run 服務。有關更多信息，請參閱以瞭解 Eventarc 位置。

觸發條件身分

在建立 Eventarc 觸發器時，您需要為其指定身分和存取管理 (IAM) 服務帳戶。 觸發程序會使用這個服務帳戶做為預設身分。我們建議您指定一個由使用者管理的服務帳戶，並授予其所需的最低權限。

注意： 如果在建立觸發程序時未指定服務帳戶，觸發程序會使用 Compute Engine 預設服務帳戶做為身分。根據機構政策設定，系統可能會自動為這個服務帳戶授予權限過於寬鬆的角色。

事前準備

1. 設定 Cloud Run 環境。

2. 啟用 Artifact Registry、Cloud Build、Cloud Run Admin API 和 Eventarc API：

   啟用 API

3. 授予必要的 IAM 角色和權限。

建立服務的觸發條件

部署服務後，您可以使用 Google Cloud 控制台、Google Cloud CLI 或 Terraform 配置觸發器。

控制台

1. 使用容器或來源部署 Cloud Run 服務。

2. 在 Google Cloud 控制台，前往Cloud Run：

   前往 Cloud Run

3. 在服務清單中，點選現有服務。

4. 在「Service details」(服務詳細資料) 頁面中，前往「Triggers」(觸發條件) 分頁標籤。

5. 按一下「新增觸發條件」，然後選取所需選項。

6. 在 Eventarc 觸發器 窗格中，以下列方式修改觸發器詳細資料：

   1. 在「觸發條件名稱」欄位中，輸入觸發條件名稱或使用預設名稱。

   2. 從清單中選擇一個 觸發器類型，以指定下列觸發器類型之一：

      • Google 來源：指定 Pub/Sub、Cloud Storage、Firestore 和其他 Google 事件供應商的觸發條件。

      • 第三方 與提供 Eventarc 來源的非 Google 提供者整合。詳情請參閱「Eventarc 中的第三方事件」。

   3. 從 事件提供者 清單中選擇一個事件提供者，以選擇提供觸發您的服務的事件類型的產品。如需事件提供者清單，請參閱「事件提供者和目的地」。

   4. 從「事件類型」清單中選取事件類型。觸發器配置會根據支援的事件類型而有所不同。 詳情請參閱「事件類型」。

   5. 如果啟用了 Region 字段，請為 Eventarc 觸發器選擇 location。一般來說，Eventarc 觸發條件的位置應與要監控事件的 Google Cloud 資源位置一致。在大多數情況下，您也應在相同區域部署服務。如要進一步瞭解 Eventarc 觸發條件的所在位置，請參閱「瞭解 Eventarc 位置」。

   6. 在「服務帳戶」欄位中，選取服務帳戶。 Eventarc 觸發程序會連結至服務帳戶，在叫用服務時做為身分使用。您的 Eventarc 觸發器的服務帳戶必須具有呼叫您的服務的權限。根據預設，Cloud Run 會使用 Compute Engine 預設服務帳戶。

   7. 如有需要，請指定服務網址路徑，將傳入的要求傳送至該路徑。這是目標服務上的相對路徑，觸發器的事件應該會傳送到該路徑。例如：/、/route、route 和 route/subroute。

   8. 如果投遞嘗試失敗，可以選擇啟用重試功能，選取 失敗時啟用重試​​ 複選框；否則，預設行為是只進行一次投遞嘗試，不進行重試。有關更多信息，請參閱 重試事件。

   9. 填妥必填欄位後，按一下「儲存觸發條件」。

7. 建立觸發程序後，請確認「觸發程序」分頁上顯示勾號 ，驗證觸發程序是否正常運作。

   註： 雖然觸發器會立即創建，但最多可能需要兩分鐘才能傳播並過濾事件。

gcloud

1. 使用容器或來源部署 Cloud Run 服務。

2. 執行以下命令建立用於過濾和路由事件的觸發器：

   gcloud eventarc triggers create TRIGGER_NAME  \
       --location=LOCATION \
       --destination-run-service=DESTINATION_RUN_SERVICE  \
       --destination-run-region=DESTINATION_RUN_REGION \
       --event-filters="type=EVENT_FILTER_TYPE" \
       --max-retry-attempts=1 \
       --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
   

   更改下列內容：

   • TRIGGER_NAME：觸發條件的 ID 或完整 ID。
   • LOCATION: Eventarc 觸發器的位置。或者，您可以設定 eventarc/location 屬性；例如，gcloud config set eventarc/location us-central1。

     為避免任何效能和資料落地問題，位置必須與產生事件的 Google Cloud 服務的位置相符。詳情請參閱「Eventarc 區域」。

   • DESTINATION_RUN_SERVICE: 接收觸發器事件的 Cloud Run 服務的名稱。此服務可以位於 Cloud Run 支援的任何位置，並且不需要與觸發器位於相同位置。不過，服務必須與觸發程序位於同一專案，且每當產生事件時，服務都會收到以 HTTP POST 要求傳送至根網址路徑 (/) 的事件。
   • DESTINATION_RUN_REGION：(選用) 目的地 Cloud Run 服務所在的 Cloud Run 位置。如未指定，系統會假設服務與觸發程序位於相同區域。
   • EVENT_FILTER_TYPE：事件的 ID。 方法的 API 呼叫成功時，系統會產生事件。對於長時間運行的操作，該事件僅在操作結束時生成，並且僅在操作成功執行時才會生成。 如需支援的事件類型清單，請參閱「Eventarc 支援的 Google 事件類型」。
   • SERVICE_ACCOUNT_NAME：使用者管理的服務帳戶名稱。
   • PROJECT_ID：您的 Google Cloud 專案 ID。

   注意：

   • --event-filters="type=EVENT_FILTER_TYPE" 旗標為必要項目。如未設定其他事件篩選器，系統會比對所有資源的事件。
   • EVENT_FILTER_TYPE建立後即無法變更。如要變更 EVENT_FILTER_TYPE，請建立新觸發條件並刪除舊觸發條件。
   • 每個觸發器可以有多個事件過濾器，用逗號分隔成一個 --event-filters=[ATTRIBUTE=VALUE,...] 標誌，或者您可以重複該標誌以添加更多過濾器。只有符合所有篩選條件的事件會傳送至目的地。不支援萬用字元和規則運算式，但使用 --event-filters-path-pattern 旗標時，可以定義資源路徑模式。
   • 如要指定單一事件傳送嘗試，且不重試，請使用 --max-retry-attempts 旗標。唯一有效值為 1。如果省略旗標，系統會套用標準重試行為。詳情請參閱「重試事件」。
   • 其他旗標包括：有關更多信息，請參閱gcloud eventarc triggers create。

Terraform

如要為 Cloud Run 服務建立 Eventarc 觸發條件，請參閱「使用 Terraform 建立觸發條件」。

建立函式的觸發條件

部署函數後，您可以使用 Google Cloud 控制台、Google Cloud CLI 或 Terraform 配置觸發器。

控制台

使用 Google Cloud 控制台建立函式時，也可以為函式新增觸發條件。請按照下列步驟為函式建立觸發條件：

1. 前往 Google Cloud 控制台的 Cloud Run：

   前往 Cloud Run。

2. 點選編寫函數，並輸入函數詳細資料。如要進一步瞭解如何在部署期間設定函式，請參閱「部署函式」。

3. 在 觸發器 部分，按一下 新增觸發器。

4. 選取所需選項。

5. 在 Eventarc 觸發器 窗格中，以下列方式修改觸發器詳細資料：

   1. 在「觸發條件名稱」欄位中輸入觸發條件名稱，或使用預設名稱。

   2. 從清單中選取「觸發條件類型」：

      • Google 來源：指定 Pub/Sub、Cloud Storage、Firestore 和其他 Google 事件供應商的觸發條件。

      • 第三方 與提供 Eventarc 來源的非 Google 提供者整合。詳情請參閱「Eventarc 中的第三方事件」。

   3. 從「Event provider」(事件供應商) 清單中選取事件供應商，以便選取提供事件類型的產品，觸發函式。如需事件提供者清單，請參閱「事件提供者和目的地」。

   4. 從「事件類型」清單中選取事件類型。觸發器配置會根據支援的事件類型而有所不同。 詳情請參閱「事件類型」。

   5. 如果「區域」欄位已啟用，請選取 Eventarc 觸發程序的位置。一般來說，Eventarc 觸發條件的位置應與要監控事件的Google Cloud 資源位置相符。在多數情況下，您也應該在相同區域中部署函式。如要進一步瞭解 Eventarc 觸發條件的所在位置，請參閱「瞭解 Eventarc 位置」。

   6. 在「服務帳戶」欄位中，選取服務帳戶。 Eventarc 觸發程序會連結至服務帳戶，在叫用函式時做為身分。您的 Eventarc 觸發器的服務帳戶必須具有呼叫您的函數的權限。根據預設，Cloud Run 會使用 Compute Engine 預設服務帳戶。

   7. 如有需要，請指定服務網址路徑，將傳入的要求傳送至該路徑。這是目標服務上的相對路徑，觸發器的事件應該會傳送到該路徑。例如：/、/route、route 和 route/subroute。

   8. 如果投遞嘗試失敗，可以選擇啟用重試功能，選取 失敗時啟用重試​​ 複選框；否則，預設行為是只進行一次投遞嘗試，不進行重試。有關更多信息，請參閱 重試事件。

6. 填妥必填欄位後，按一下「儲存觸發條件」。

7. 點選「建立」。

8. 在 Source 標籤中，根據需要編輯原始碼，然後選擇 Save and redeploy。

gcloud

使用 gcloud CLI 建立函數時，必須先執行以下操作。部署在你的函數中，然後建立一個觸發器。請按照下列步驟為函式建立觸發條件：

1. 在包含程式碼範例的目錄中執行下列指令，即可部署函式：

   gcloud run deploy FUNCTION \
       --source . \
       --function FUNCTION_ENTRYPOINT \
       --base-image BASE_IMAGE_ID \
       --region REGION
   

   更改下列內容：

   • FUNCTION：要部署的函式名稱。您可以完全省略此參數，但如果您省略它，系統會提示您輸入名稱。

   • FUNCTION_ENTRYPOINT: 原始碼中函數的入口點。這是 Cloud Run 在您的函數運行時執行的程式碼。此旗標的值必須是原始碼中既有的函式名稱或完整類別名稱。

   • BASE_IMAGE_ID：函式的基礎映像檔環境。如要進一步瞭解基本映像檔，以及每個映像檔中包含的套件，請參閱「執行階段基本映像檔」。

   • REGION: 你要部署函數的 Google Cloud 區域。例如：europe-west1。

2. 執行以下命令建立用於過濾和路由事件的觸發器：

   gcloud eventarc triggers create TRIGGER_NAME \
       --location=LOCATION \
       --destination-run-service=FUNCTION \
       --destination-run-region=DESTINATION_RUN_REGION \
       --event-filters="type=EVENT_FILTER_TYPE" \
       --max-retry-attempts=1 \
       --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
   

   更改下列內容：

   • TRIGGER_NAME：觸發條件的 ID 或完整 ID。
   • LOCATION: Eventarc 觸發器的位置。或者，您可以設定 eventarc/location 屬性；例如，gcloud config set eventarc/location us-central1。

     為避免任何效能和資料落地問題，位置必須與產生事件的 Google Cloud 服務的位置相符。詳情請參閱「Eventarc 區域」。

   • FUNCTION：已部署的 Cloud Run 函式名稱，用於接收觸發條件的事件。
   • DESTINATION_RUN_REGION：(選用) 目的地 Cloud Run 函式所在的Cloud Run 位置。如未指定，系統會假設函式與觸發程序位於相同區域。
   • EVENT_FILTER_TYPE：事件的 ID。 方法的 API 呼叫成功時，系統會產生事件。對於長時間運行的操作，該事件僅在操作結束時生成，並且僅在操作成功執行時才會生成。 如需支援的事件類型清單，請參閱「Eventarc 支援的 Google 事件類型」。
   • SERVICE_ACCOUNT_NAME：使用者管理的服務帳戶名稱。
   • PROJECT_ID：您的 Google Cloud 專案 ID。

   注意：

   • --event-filters="type=EVENT_FILTER_TYPE" 旗標為必要項目。如未設定其他事件篩選器，系統會比對所有資源的事件。
   • EVENT_FILTER_TYPE建立後即無法變更。如要變更 EVENT_FILTER_TYPE，請建立新觸發條件並刪除舊觸發條件。
   • 每個觸發器可以有多個事件過濾器，用逗號分隔成一個 --event-filters=[ATTRIBUTE=VALUE,...] 標誌，或者您可以重複該標誌以添加更多過濾器。只有符合所有篩選條件的事件會傳送至目的地。不支援萬用字元和規則運算式，但使用 --event-filters-path-pattern 旗標時，可以定義資源路徑模式。
   • 如要指定單一事件傳送嘗試，且不重試，請使用 --max-retry-attempts 旗標。唯一有效值為1。如果省略旗標，系統會套用標準重試行為。詳情請參閱「重試事件」。
   • 其他旗標包括：有關更多信息，請參閱gcloud eventarc triggers create。

Terraform

如要為 Cloud Run 函式建立 Eventarc 觸發條件，請參閱「使用 Terraform 建立觸發條件」。

設定 Pub/Sub 應答期限

事件導向的 Cloud Run 函式是透過 Eventarc 和 Pub/Sub 訂閱項目一併實作。預設情況下，此 Pub/Sub 訂閱的 確認 (ack) 截止時間 為 10 秒。這項設定不足以支援許多函式，且可能導致不必要的重複執行。

我們建議您將服務或功能的 ack 截止時間設定為最大值 600 秒，具體如下：

控制台

部署函式後，請按照下列步驟修改函式的 ack 期限：

1. 前往 Google Cloud 控制台的「Cloud Run」：

   前往 Cloud Run

2. 在「Services」(服務) 清單中找出要更新的函式，然後按一下開啟該函式的詳細資料。

3. 開啟「觸發條件」分頁。

4. 按一下觸發器名稱以開啟 觸發器詳細資料。

5. 點選 主題 連結開啟主題編輯窗格。

6. 按一下「訂閱 ID」名稱前往訂閱窗格，然後按一下頁面頂端的「編輯」。

7. 將「確認期限」的值設為 600，然後按一下「更新」儲存變更。

gcloud

將每個觸發器的 ack 截止時間更新為最大值 600 秒。 請注意，下列指令會參照您在上一個步驟中設定值的變數 (TRIGGER_NAME 和 LOCATION)。

## Per Cloud Run function:

# Update Ack Deadline to max (600s)
SUBSCRIPTION_ID=$(gcloud eventarc triggers describe "$TRIGGER_NAME" --location $LOCATION --format json | jq -r '.transport.pubsub.subscription')
gcloud pubsub subscriptions update "$SUBSCRIPTION_ID" --ack-deadline=600

對所有服務和函式觸發器執行大量更新，將其 ack 截止時間設定為 600 秒：

### Match all Cloud Run service triggers and update all deadlines to 600s (max timeout)
### This will change ALL Cloud Run services and Cloud Run functions
TRIGGER_NAMES=($(gcloud eventarc triggers list | awk '/Cloud Run service/ {print $1}'))

if [ ${#TRIGGER_NAMES[@]} -eq 0 ]; then
  echo "No matching triggers found"
fi

for trigger in "${TRIGGER_NAMES[@]}"; do
echo "Updating ack deadline for trigger: $trigger"
SUBSCRIPTION_ID=$(gcloud eventarc triggers describe "$trigger" --location $LOCATION --format json | jq -r '.transport.pubsub.subscription')

if [ -z "$SUBSCRIPTION_ID" ]; then
    echo "Error: Could not retrieve subscription ID for trigger: $trigger"
    continue # Skip to the next trigger
fi
gcloud pubsub subscriptions update "$SUBSCRIPTION_ID" --ack-deadline=600
echo "Ack deadline updated for subscription: $SUBSCRIPTION_ID"
done

查看 CloudEvent ID 和來源

如要查看觸發服務的 CloudEvent ID 和來源，請在 Cloud Run 服務記錄中查看下列資源：

• LogEntry.labels.run.googleapis.com/cloud_event_id
• LogEntry.labels.run.googleapis.com/cloud_event_source

後續步驟

• 事件提供者和目的地
• Eventarc 支援的 Google 事件類型
• Eventarc 中的重試事件
• Eventarc 定價