將 Cloud Storage 事件轉送至 Cloud Run

Eventarc 觸發條件會宣告您對特定事件或一組事件感興趣。您可以為觸發條件指定篩選器 (包括事件來源) 和目標 Cloud Run 服務，藉此設定事件路由。

Eventarc 會透過 HTTP 要求，以 CloudEvents 格式將事件傳送至事件接收器。

請參閱下列操作說明，瞭解如何設定事件轉送，將直接Cloud Storage 事件觸發的事件轉送至 Cloud Run 服務。詳情請參閱支援的直接事件清單。

準備建立觸發條件

建立觸發條件前，請先完成下列先決條件：

主控台

  1. 在 Google Cloud 控制台的專案選擇器頁面中，選取或建立 Google Cloud 專案。

    前往專案選取器

  2. 啟用 Cloud Logging、Eventarc 和 Eventarc Publishing API。

    啟用 API

  3. 如有需要，請啟用與直接事件相關的 API。舉例來說，如要使用 Cloud Storage 活動，請啟用Cloud Storage API。

  4. 如果沒有，請建立使用者代管的服務帳戶，然後授予必要角色和權限，讓 Eventarc 管理目標服務的事件。

    1. 前往 Google Cloud 控制台的「建立服務帳戶」頁面。

      前往「Create service account」(建立服務帳戶)

    2. 選取專案。

    3. 在「Service account name」(服務帳戶名稱) 欄位中輸入名稱。 Google Cloud 控制台會根據這個名稱填入「服務帳戶 ID」欄位。

      在「服務帳戶說明」欄位中輸入說明。例如：Service account for event trigger。

    4. 按一下「建立並繼續」。

    5. 如要提供適當的存取權，請在「Select a role」(請選擇角色) 清單中，選取要授予服務帳戶的必要 Identity and Access Management (IAM) 角色，以進行已驗證或未驗證的叫用。詳情請參閱「Cloud Run 目標的角色和權限」。

      如要新增其他角色，請按一下「新增其他角色」，然後新增每個其他角色。

    6. 按一下「繼續」。

    7. 按一下「完成」，即可完成帳戶建立程序。

  5. 將 Pub/Sub 發布者角色授予 Cloud Storage 服務代理。通常是 service-PROJECT_NUMBER@gs-project-accounts.iam.gserviceaccount.com。您可以擷取 Cloud Storage 服務代理程式的電子郵件地址。

    1. 前往 Google Cloud 控制台的「IAM」頁面。

      前往「IAM」頁面

    2. 在 Cloud Storage 服務代理的列中，按一下「編輯主體」。(如果未列出服務代理程式，請繼續下一個步驟)。「編輯存取權」窗格隨即開啟。

      1. 按一下「新增其他角色」，然後搜尋「Pub/Sub 發布者」角色。
      2. 選取角色。
      3. 按一下 [儲存]。

    3. 如果服務代理人未列出，請按一下「授予存取權」。「授予存取權」窗格隨即開啟。

      1. 在「New principals」(新增主體) 欄位中，輸入服務代理人的電子郵件地址。
      2. 在「Select a role」(選取角色) 清單中，搜尋「Pub/Sub Publisher」(Pub/Sub 發布者) 角色。
      3. 選取角色。
      4. 按一下「儲存」。

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. 啟用 Cloud Logging、Eventarc 和 Eventarc Publishing API。

    gcloud services enable logging.googleapis.com \
  eventarc.googleapis.com \
  eventarcpublishing.googleapis.com

  3. 如有需要，請啟用與直接事件相關的 API。舉例來說，如要啟用 Cloud Storage 活動，請啟用storage.googleapis.com。

  4. 如果沒有，請建立使用者代管的服務帳戶，然後授予必要角色和權限，讓 Eventarc 管理目標服務的事件。

    1. 建立服務帳戶：

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

      將 SERVICE_ACCOUNT_NAME 替換為服務帳戶名稱。長度必須介於 6 至 30 個字元之間，可以使用小寫英數字元和破折號。建立服務帳戶後，即無法變更名稱。

    2. 針對已驗證或未驗證的呼叫，授予必要的 Identity and Access Management (IAM) 角色或權限。詳情請參閱Cloud Run 目標的角色和權限。

  5. 將 pubsub.publisher 角色授予 Cloud Storage 服務帳戶：

    SERVICE_ACCOUNT="$(gcloud storage service-agent --project=PROJECT_ID)"

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/pubsub.publisher"

建立觸發條件

您可以使用 Google Cloud CLI 建立 Eventarc 觸發條件，或透過 Google Cloud 控制台建立。

主控台

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

    前往「Triggers」(觸發條件)

  2. 按一下「建立觸發條件」。
  3. 輸入觸發條件名稱。

    這是觸發條件的 ID，開頭必須是英文字母。最多可包含 63 個小寫英文字母、數字或連字號。

  4. 在「Trigger type」(觸發條件類型) 中，選取「Google sources」(Google 來源)。
  5. 在「Event provider」(事件提供者) 清單中，選取「Cloud Storage」。

    請注意，相關Google Cloud 文件中使用的事件提供者名稱可能沒有 Cloud 或 Google Cloud 前置字元。舉例來說，在控制台中，「Memorystore for Redis」稱為「Memorystore for Redis」Google Cloud 。

  6. 在「Event type」(事件類型) 清單中，從「Direct」(直接) 事件選取事件類型：
    • google.cloud.storage.object.v1.archived：當物件的使用中版本遭到封存或刪除時，系統會傳送事件。只有版本控制值區才會傳送這項事件。
    • google.cloud.storage.object.v1.delete：物件永久刪除時傳送的事件。視值區的物件版本管理設定而定，這表示：
      • 如果是啟用版本管理的值區，只有在永久刪除版本時才會傳送這個事件 (封存物件時不會傳送)。
      • 如果值區未啟用版本管理功能，則系統在刪除或覆寫物件時，會傳送這個事件。
    • google.cloud.storage.object.v1.finalized：在 bucket 中建立新物件 (或覆寫現有物件，並建立該物件的新產生版本) 時，系統會傳送這個事件。
    • google.cloud.storage.object.v1.metadataUpdated：現有物件的 [中繼資料](/storage/docs/metadata)變更時，系統會傳送這項事件。
  7. 在「事件資料內容類型」清單中，選取事件酬載的編碼。

    如果是來自 Cloud Storage的直接事件，則必須為 application/json。

  8. 指定或瀏覽 Cloud Storage Bucket 的全域不重複 ID。

    Cloud Storage 值區必須與 Eventarc 觸發程序位於相同的Google Cloud 專案和區域或多區域。

  9. 選取「區域」。

    Eventarc 的 Cloud Storage 觸發程序適用於單一區域、雙區域和多區域位置。請注意，Cloud Storage bucket 必須與 Eventarc 觸發程序位於相同 Google Cloud 專案和區域或多區域。

    系統會使用 Cloud Storage 的 Pub/Sub 通知傳送事件。如果為同一個值區註冊過多通知，可能會超出值區的通知上限 (如錯誤 Cloud Storage bucket ...: Pub/Sub notification limit reached 所示)。您最多可以在值區中建立 10 項設定，讓系統在特定事件出現時觸發通知。如要查看更多配額和限制，請參閱 Cloud Storage 配額與限制頁面。

  10. 選取要叫用服務或工作流程的服務帳戶。

    或者，您也可以建立新的服務帳戶。

    這會指定與觸發程序相關聯的 Identity and Access Management (IAM) 服務帳戶電子郵件，您先前已授予該帳戶 Eventarc 所需的特定角色。

  11. 在「Event destination」(事件目的地) 清單中，選取「Cloud Run」。
  12. 選取服務。

    這是接收觸發條件事件的服務名稱。 這項服務必須與觸發條件位於同一專案，且每當產生事件時，都會收到以 HTTP POST 要求傳送至根網址路徑 (/) 的事件。

  13. 您可以視需要指定服務網址路徑，將傳入要求傳送至該路徑。

    這是目的地服務上的相對路徑，觸發條件的事件應傳送至該路徑。例如：/、/route、route、route/subroute。

  14. 如要新增標籤，請按一下 「新增標籤」。標籤是鍵/值組合，可協助您整理Google Cloud 資源。詳情請參閱「什麼是標籤？」
  15. 點選「建立」。

    16. 觸發條件建立後，事件來源篩選器就無法修改。 請改為建立新的觸發條件，並刪除舊的觸發條件。詳情請參閱「管理觸發條件」。

gcloud

您可以執行 gcloud eventarc triggers create 指令，並搭配必要和選用旗標，建立觸發條件。

gcloud eventarc triggers create TRIGGER \
    --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：觸發條件的 ID 或完整 ID。
  • LOCATION：Eventarc 觸發條件的位置。或者，您也可以設定 eventarc/location 屬性，例如 gcloud config set eventarc/location us-central1。

    Cloud Storage 值區必須與 Eventarc 觸發程序位於相同 Google Cloud 專案和區域或多區域。詳情請參閱「Eventarc 區域」。

  • DESTINATION_RUN_SERVICE：接收觸發事件的 Cloud Run 服務名稱。服務可以位於 Cloud Run 支援的任何位置，不一定要與觸發條件位於相同位置。不過，服務必須與觸發程序位於同一專案，且每當產生事件時，都會收到以 HTTP POST 要求形式傳送至根網址路徑 (/) 的事件。
  • DESTINATION_RUN_REGION：(選用) 目的地 Cloud Run 服務所在的區域。如未指定，系統會假設服務與觸發程序位於同一區域。
  • EVENT_FILTER_TYPE：Cloud Storage 事件的 ID，可以是下列其中一項：
    • google.cloud.storage.object.v1.finalized：在值區中建立新物件 (或覆寫現有物件，並建立該物件的新產生版本) 時，系統會傳送這個事件。
    • google.cloud.storage.object.v1.archived：封存或刪除物件的使用中版本時，系統會傳送事件。這個事件只會針對版本管理值區傳送。
    • google.cloud.storage.object.v1.deleted：永久刪除物件時，系統會傳送這個事件。視值區的物件版本管理設定而定，這表示：
      • 如果是啟用版本管理的值區，只有在永久刪除版本時才會傳送這個事件 (封存物件時不會傳送)。
      • 如果值區未啟用版本管理功能，則系統在刪除或覆寫物件時，會傳送這個事件。
    • google.cloud.storage.object.v1.metadataUpdated：當現有物件的中繼資料變更時，系統會傳送這個事件。
  • BUCKET 是 Cloud Storage bucket 的全域專屬 ID。
  • SERVICE_ACCOUNT_NAME：使用者管理的服務帳戶名稱。
  • PROJECT_ID：您的 Google Cloud 專案 ID。

注意：

  • 如果是來自 Cloud Storage的直接事件，事件酬載的編碼為 application/json。
  • 必須使用下列旗標：
    • --event-filters="type=EVENT_FILTER_TYPE"
    • --event-filters="bucket=BUCKET"
  • 每個觸發條件可以有多個事件篩選器，以逗號分隔，放在一個 --event-filters=[ATTRIBUTE=VALUE,...] 標記中，也可以重複標記來新增更多篩選器。只有符合所有篩選條件的事件，才會傳送至目的地。不支援萬用字元和規則運算式。
  • 建立觸發條件後，就無法變更事件篩選器類型。如要使用其他事件類型，請建立新的觸發條件。
  • 系統會使用 Cloud Storage 的 Pub/Sub 通知傳送事件。如果針對同一個值區註冊過多通知，可能會超出值區的通知上限，如錯誤 Cloud Storage bucket ...: Pub/Sub notification limit reached 所示。針對特定事件所設定的觸發通知，最多可以建立 10 個。如要查看更多配額和限制，請參閱 Cloud Storage 配額與限制頁面。
  • --service-account 旗標用於指定與觸發程序相關聯的身分與存取權管理 (IAM) 服務帳戶電子郵件。
  • (選用) 使用 --destination-run-path 旗標，在目的地 Cloud Run 服務上指定相對路徑，觸發條件的事件應傳送至該路徑。

範例：

gcloud eventarc triggers create helloworld-trigger \
    --location=us-central1 \
    --destination-run-service=helloworld-events \
    --destination-run-region=us-central1 \
    --event-filters="type=google.cloud.storage.object.v1.finalized" \
    --event-filters="bucket=my-bucket" \
    --service-account=${SERVICE_ACCOUNT_NAME}@${PROJECT_ID}.iam.gserviceaccount.com

這項指令會為 Cloud Storage 值區 my-bucket 和識別為 google.cloud.storage.object.v1.finalized 的事件，建立名為 helloworld-trigger 的觸發條件。

Terraform

您可以使用 Terraform 為 Cloud Run 目的地建立觸發程序。詳情請參閱「使用 Terraform 建立觸發條件」。

列出觸發條件

如要確認是否已建立觸發程序，請使用 Google Cloud CLI 或 Google Cloud 控制台列出 Eventarc 觸發程序。

主控台

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

    前往「Triggers」(觸發條件)

    這個頁面會列出所有位置的觸發條件，並包含名稱、區域、事件供應商、目的地等詳細資料。

  2. 如要篩選觸發條件，請按照下列步驟操作：

    1. 按一下「篩選器」或「篩選器觸發條件」欄位。
    2. 在「屬性」清單中，選取要用來篩選觸發條件的選項。

    您可以選取單一屬性，或使用邏輯運算子 OR 新增更多屬性。

  3. 如要排序觸發條件，請按一下任何支援的欄標題旁的「排序」。

gcloud

執行下列指令來列出觸發條件：

gcloud eventarc triggers list --location=-

這個指令會列出所有位置的觸發條件，並包含名稱、類型、目的地和狀態等詳細資料。

後續步驟