使用 Eventarc 建立觸發條件

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

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

如要建立 Eventarc 觸發條件，請指定觸發條件的篩選器，並設定事件轉送，包括事件來源和目標 Cloud Run 服務。當指定事件或一組事件符合篩選條件時，Cloud Run 服務會自動叫用，因應事件。使用 Eventarc 觸發條件的服務稱為事件導向服務。傳送至 Cloud Run 服務的事件會以 HTTP 要求的形式接收。

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

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

觸發位置

建立 Eventarc 觸發條件時，您必須指定位置。這應與您要監控事件的 Google Cloud 資源位置相符。在多數情況下，您也應在相同區域部署事件導向的 Cloud Run 服務。詳情請參閱「瞭解 Eventarc 位置」。

觸發條件身分

建立 Eventarc 觸發條件時，您必須為其指定 Identity and Access Management (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 trigger」(Eventarc 觸發條件) 窗格中，按照下列方式修改觸發條件詳細資料：

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

   2. 從清單中選取「Trigger type」(觸發條件類型)，指定下列其中一種觸發條件類型：

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

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

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

   4. 從「Event type」(事件類型) 清單中選取事件類型。觸發條件設定會因支援的事件類型而異。詳情請參閱「事件類型」。

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

   6. 在「Service account」(服務帳戶) 欄位中，選取服務帳戶。Eventarc 觸發條件會連結至服務帳戶，在叫用服務時做為身分識別。Eventarc 觸發條件的服務帳戶必須具備叫用服務的權限。根據預設，Cloud Run 會使用 Compute Engine 預設服務帳戶。

   7. (選用) 指定要將傳入要求傳送至哪個「Service URL path」(服務網址路徑)。這是目的地服務上的相對路徑，觸發條件的事件應傳送至該路徑。例如：/、/route、route 和 route/subroute。

   8. 如要在傳送失敗時啟用重試功能，請勾選「Enable retry on failure」(啟用失敗時重試) 核取方塊。如未勾選，預設行為是只傳送一次，不重試。詳情請參閱「重試事件」。

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

7. 建立觸發條件後，請確認「Triggers」(觸發條件) 分頁中是否有勾號 ，藉此驗證其健康狀態。

   注意：雖然觸發條件會立即建立，但最多可能需要兩分鐘才會生效並篩選事件。

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.
   

   更改下列內容：

   • 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 trigger」(Eventarc 觸發條件) 窗格中，按照下列方式修改觸發條件詳細資料：

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

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

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

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

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

   4. 從「Event type」(事件類型) 清單中選取事件類型。觸發條件設定會因支援的事件類型而異。詳情請參閱「事件類型」。

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

   6. 在「Service account」(服務帳戶) 欄位中，選取服務帳戶。Eventarc 觸發條件會連結至服務帳戶，在叫用函式時做為身分識別。Eventarc 觸發條件的服務帳戶必須具備叫用函式的權限。根據預設，Cloud Run 會使用 Compute Engine 預設服務帳戶。

   7. (選用) 指定要將傳入要求傳送至哪個「Service URL path」(服務網址路徑)。這是目的地服務上的相對路徑，觸發條件的事件應傳送至該路徑。例如：/、/route、route 和 route/subroute。

   8. 如要在傳送失敗時啟用重試功能，請勾選「Enable retry on failure」(啟用失敗時重試) 核取方塊。如未勾選，預設行為是只傳送一次，不重試。詳情請參閱「重試事件」。

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.
   

   更改下列內容：

   • 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 秒。這項設定不適用於許多函式，而且可能會導致不必要的重複執行。

如果您不使用 Eventarc，而是直接透過 Pub/Sub 推送訂閱項目觸發服務或函式，則直接推送訂閱項目會共用相同的 10 秒預設值和 600 秒 (10 分鐘) 的確認期限上限，這會限制有效的要求逾時。

建議您將服務或函式的 ack 期限設為最大值 600 秒，如下所示：

控制台

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

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

   前往 Cloud Run

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

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

4. 按一下觸發條件名稱，開啟「觸發條件詳細資料」。

5. 按一下「主題」連結，開啟主題編輯窗格。

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

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

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 定價