透過 Cloud Storage 事件建立觸發條件

在 Cloud Run 中，您可以透過 Eventarc，因應 Cloud Storage 的變更來觸發服務。

為服務指定 Cloud Storage 觸發條件時，請選擇事件類型並指定 Cloud Storage bucket。觸發條件設定完成後，每當指定 bucket 中的物件 (檔案) 有異動時，系統就會呼叫您的服務。

如要讓服務在 Cloud Storage bucket 發生事件時觸發，服務和 bucket 必須位於同一個 Google Cloud 專案中。

如需從 Cloud Storage 事件建立觸發條件的詳細操作說明和程式碼範例，請參閱下列教學課程：

• 使用 Eventarc，透過 Cloud Storage 觸發服務

• 使用 Eventarc，透過 Cloud Storage 觸發函式。您也可以在 Google Cloud 控制台中找到程式碼範例，瞭解如何觸發函式來回應 Cloud Storage 事件 (使用 Cloud Storage 觸發條件部署 Cloud Run 函式後)。

支援的 Cloud Storage 事件類型

Cloud Run 支援下列 Cloud Storage 事件類型：

事件	事件類型	說明
物件已完成	google.cloud.storage.object.v1.finalized (透過 Eventarc)	建立新物件或覆寫現有物件，且 Cloud Storage 建立該物件的新一代時，會發生這個事件。
物件已刪除	google.cloud.storage.object.v1.deleted (透過 Eventarc)	物件虛刪除時會發生這個事件。詳情請參閱「軟刪除」。
物件已封存	google.cloud.storage.object.v1.archived (透過 Eventarc)	物件的使用中版本變成非現行版本時，會發生這個事件。詳情請參閱「物件版本管理」。
物件中繼資料已更新	google.cloud.storage.object.v1.metadataUpdated (透過 Eventarc)	現有物件的中繼資料有異動時，會發生這個事件。

Google Events 存放區包含其他資源，可與事件資料搭配使用。

事前準備

1. 請確認您已按照設定頁面的說明，為 Cloud Run 設定新專案。

2. 啟用 Artifact Registry、Cloud Build、Cloud Run Admin API、Eventarc、Cloud Logging、Pub/Sub 和 Cloud Storage API：

   啟用 API

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

部署者帳戶的必要角色

如要取得從 Cloud Storage 事件觸發函式所需的權限，請要求管理員在專案中授予您下列 IAM 角色：

• Cloud Run 來源開發人員 (roles/run.sourceDeveloper)
• 記錄檔檢視存取者 (roles/logging.viewAccessor)
• 專案 IAM 管理員 (roles/resourcemanager.projectIamAdmin)
• 服務帳戶管理員 (roles/iam.serviceAccountAdmin)
• 服務帳戶使用者 (roles/iam.serviceAccountUser)
• 服務使用情形管理員 (roles/serviceusage.serviceUsageAdmin)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

請注意，根據預設，Cloud Build 權限包含上傳及下載 Artifact Registry 構件的權限。

建立服務的觸發條件

部署服務後，您可以使用 Google Cloud 控制台、Google Cloud CLI 或 Terraform 設定觸發條件。

控制台

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

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

   前往 Cloud Run

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

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

5. 按一下「新增觸發條件」，然後選取「Cloud Storage 觸發條件」。

6. 在「Eventarc trigger」(Eventarc 觸發條件) 窗格中，按照下列步驟修改觸發條件詳細資料：

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

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

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

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

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

   4. 從「事件類型」清單中選取「google.cloud.storage.object.v1.finalized」google.cloud.storage.object.v1.finalized。觸發條件設定會因支援的事件類型而異。詳情請參閱「事件類型」。

   5. 在「Bucket」欄位中，按一下「Browse」(瀏覽)，選取觸發條件要監控的 Cloud Storage bucket。變更這個 bucket 內的物件會觸發函式呼叫。

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

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

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

   9. 如要啟用重試功能 (如果傳送嘗試失敗)，請選取「Enable retry on failure」(失敗時啟用重試) 核取方塊；否則，預設行為是嘗試傳送一次，不會重試。詳情請參閱「重試事件」。

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

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" \
       --event-filters="bucket=BUCKET" \
       --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 事件類型」。
   • BUCKET：Cloud Storage bucket 的全域專屬 ID。
   • 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. 選取「Cloud Storage trigger」(Cloud Storage 觸發條件)。

5. 在「Eventarc trigger」(Eventarc 觸發條件) 窗格中，按照下列步驟修改觸發條件詳細資料：

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

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

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

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

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

   4. 從「事件類型」清單中選取「google.cloud.storage.object.v1.finalized」google.cloud.storage.object.v1.finalized。觸發條件設定會因支援的事件類型而異。詳情請參閱「事件類型」。

   5. 保留「事件資料內容類型」欄位。

   6. 在「Bucket」欄位中，按一下「Browse」(瀏覽)，選取觸發條件要監控的 Cloud Storage bucket。變更這個 bucket 內的物件會觸發函式呼叫。

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

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

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

   10. 如要啟用重試功能 (如果傳送嘗試失敗)，請選取「Enable retry on failure」(失敗時啟用重試) 核取方塊；否則，預設行為是嘗試傳送一次，不會重試。詳情請參閱「重試事件」。

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

7. 點選「建立」。

8. 在「來源」分頁中，視需要編輯原始碼，然後選取「儲存並重新部署」。

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" \
       --event-filters="bucket=BUCKET" \
       --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 事件類型」。
   • BUCKET：Cloud Storage bucket 的全域專屬 ID。
   • 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 建立觸發條件」。

活動傳送

Cloud Storage 觸發條件是透過 Cloud Storage 的 Pub/Sub 通知實作。事件須遵守 Pub/Sub 通知傳送保證。

Cloud Storage bucket 最多可設定 10 項通知，在特定事件發生時觸發通知。超出 bucket 的通知限制，會導致後續函式部署作業失敗，並顯示類似下列的錯誤：

Cloud Storage bucket ...: Pub/Sub notification limit reached

如要解決這項限制，可以自行管理 Pub/Sub 主題，並註冊該主題以接收 Cloud Storage 通知，讓函式對您想要的通知類型做出回應。舉例來說，您可以為所選事件 (例如物件建立) 設定單一通知，並傳送至 Pub/Sub 主題。接著，視需要讓多個函式訂閱者處理主題事件，並將事件傳送至多個目的地。例如：

1. 自行建立 Pub/Sub 主題。
2. 在 Cloud Storage bucket 建立單一通知設定，以便在特定事件 (例如 OBJECT_FINALIZE) 發生時觸發，並將事件傳送至單一 Pub/Sub 主題。
3. 建立由 Pub/Sub 主題觸發的一或多個函式。

這樣一來，您就會有一個 Cloud Storage 通知設定、一個 Pub/Sub 主題，以及所需數量的函式 (Pub/Sub 允許的傳送限制非常高)。

如要進一步瞭解 Cloud Storage 限制，請參閱「配額與限制」。

後續步驟

• 瞭解如何透過事件觸發。
• 瞭解如何使用 Eventarc 透過 Cloud Storage 觸發服務。
• 瞭解如何使用 Eventarc，透過 Cloud Storage 觸發函式。