將 Cloud Storage 事件轉送至 Workflows

標準

Eventarc 觸發條件會宣告您對特定事件或一組事件感興趣。您可以指定觸發條件的篩選器 (包括事件來源) 和目標工作流程，設定事件轉送。

系統會透過 HTTP 要求，以 CloudEvents 格式傳送事件。Workflows 服務會將事件轉換為 JSON 物件 (遵循 CloudEvents 規格)，並將事件做為工作流程執行階段引數傳遞至工作流程執行作業。請確認事件大小未超過 512 KB。如果事件大於 Workflows 引數大小上限，就不會觸發工作流程執行作業。

這些操作說明會示範如何設定事件路由，以便在收到直接Cloud Storage event 時觸發工作流程執行作業。這適用於 Cloud Storage 事件供應商。詳情請參閱支援的直接事件清單。

注意： 如果 Google 供應商同時支援直接和稽核記錄事件，建議您建立觸發條件，篩選直接事件。直接事件相較於稽核記錄事件，有許多優點。詳情請參閱「事件路徑」一文。

準備建立觸發條件

為目標工作流程建立 Eventarc 觸發程序前，請先完成下列工作。

控制台

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

   注意： 如果您不打算保留在這項程序中建立的資源，請建立新專案，而不要選取現有專案。完成這些步驟後，您就可以刪除專案，並移除與該專案相關聯的所有資源。

   前往專案選取器

2. 啟用 Eventarc、Eventarc Publishing、Workflows 和 Workflow Executions API。

   啟用 API

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

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

   1. 前往 Google Cloud 控制台的「Service accounts」(服務帳戶) 頁面。

      前往「Service Accounts」(服務帳戶)

   2. 選取專案。

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

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

   4. 點按「Create and continue」(建立並繼續)。

   5. 如要提供適當的存取權，請在「Select a role」(請選擇角色) 清單中，選取要授予服務帳戶的必要 Identity and Access Management (IAM) 角色。詳情請參閱「Workflows 目標的角色和權限」。

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

   6. 按一下「繼續」。

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

5. 將 Pub/Sub 發布者角色授予 Cloud Storage 服務代理。通常是 [e-mail]。您可以擷取 Cloud Storage 服務代理的電子郵件地址。

   1. 前往 Google Cloud 控制台的「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. 在 Google Cloud 控制台中啟用 Cloud Shell。

   啟用 Cloud Shell

   Google Cloud 主控台底部會開啟一個 Cloud Shell 工作階段，並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已針對您目前的專案設定好相關值。工作階段可能要幾秒鐘的時間才能初始化。

2. 啟用 Eventarc、Eventarc Publishing、Workflows 和 Workflow Executions API：

   gcloud services enable eventarc.googleapis.com \
       eventarcpublishing.googleapis.com \
       workflows.googleapis.com \
       workflowexecutions.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) 角色或權限。 詳情請參閱「Workflows 目標的角色和權限」。

5. 如要為直接 Cloud Storage 事件建立觸發條件，請將 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 (gcloud 或 Terraform) 或 Google Cloud 控制台，建立以已部署工作流程做為事件接收者的 Eventarc 觸發程序。

注意： 篩選作業會進行完全比對，不支援萬用字元或規則運算式。

控制台

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. 在「Event data content type」(事件資料內容類型) 清單中，選取事件酬載的編碼。

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

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

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

9. 選取「Region」(區域)。

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

   重要事項：由於 Eventarc Standard 使用 Pub/Sub 做為傳輸層，如果 Cloud Storage 事件來自 Pub/Sub 訊息儲存政策不允許的地區，且強制執行傳輸中作業 ("enforceInTransit": true)，Cloud Storage 觸發條件可能會失敗。在多區域位置建立 Cloud Storage 觸發條件時，請確保訊息儲存政策允許該多區域內的所有來源區域。詳情請參閱「設定訊息儲存政策」。

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

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

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

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

11. 在「Event destination」(事件目的地) 清單中，選取「Workflows」。
12. 選取工作流程。
    

    這是要將事件傳送至的工作流程名稱。工作流程執行的事件會經過轉換，並以執行階段引數的形式傳遞至工作流程。

    詳情請參閱 建立 Workflows 的觸發條件。

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

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

gcloud

gcloud eventarc triggers create TRIGGER \
    --location=LOCATION \
    --destination-workflow=DESTINATION_WORKFLOW  \
    --destination-workflow-location=DESTINATION_WORKFLOW_LOCATION \
    --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 觸發條件的位置，適用於單一區域、雙區域和多區域位置；您無法建立 globalEventarc 觸發條件。請注意，Cloud Storage bucket 必須與 Eventarc 觸發條件位於相同 Google Cloud 專案和區域。詳情請參閱「Eventarc 位置」。
  重要事項：由於 Eventarc Standard 使用 Pub/Sub 做為傳輸層，如果 Cloud Storage 事件來自 Pub/Sub 訊息儲存政策不允許的地區，且強制執行傳輸中作業 ("enforceInTransit": true)，Cloud Storage 觸發條件可能會失敗。在多區域位置建立 Cloud Storage 觸發條件時，請確保訊息儲存政策允許該多區域內的所有來源區域。詳情請參閱「設定訊息儲存政策」。
• DESTINATION_WORKFLOW：已部署的工作流程 ID，用於接收觸發條件傳送的事件。工作流程可位於任何 Workflows 支援的位置，不一定要與觸發程序位於相同位置。不過，工作流程必須與觸發程序位於相同專案。
• DESTINATION_WORKFLOW_LOCATION (選用)：部署目的地工作流程的位置。如未指定，系統會假設工作流程與觸發程序位於相同位置。
• EVENT_FILTER_TYPE：Cloud Storage 事件的 ID，可以是下列其中一項：
  • google.cloud.storage.object.v1.finalized：在 bucket 中建立新物件 (或覆寫現有物件，並建立該物件的新一代) 時，會傳送這個事件。
  • 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：您建立的 IAM 服務帳戶名稱，並已授予 Workflows 要求的特定角色。
• PROJECT_ID：您的 Google Cloud 專案 ID

注意：

• 如果是來自 Cloud Storage的直接事件，事件酬載的編碼為 application/json。
• 這些旗標為必填：
  • --event-filters="type=EVENT_FILTER_TYPE"
  • --event-filters="bucket=BUCKET"
• 觸發條件建立後，就無法變更 EVENT_FILTER_TYPE。如要使用其他事件類型，請建立新的觸發條件。
• --service-account： Eventarc 觸發條件將用來叫用工作流程執行的 IAM 服務帳戶電子郵件地址。強烈建議您使用僅具備必要權限的服務帳戶，存取所需資源。如要進一步瞭解服務帳戶，請參閱「建立及管理服務帳戶」。
• 系統會使用 Cloud Storage 的 Pub/Sub 通知傳送事件。為同一個 bucket 註冊過多通知，可能會超出 bucket 的通知上限，如錯誤訊息 Cloud Storage bucket ...: Pub/Sub notification limit reached 所示。bucket 最多可以有 10 項通知設定，在特定事件發生時觸發通知。如要查看更多配額和限制，請參閱 Cloud Storage 配額與限制頁面。
• 每個觸發條件可以有多個事件篩選器，以逗號分隔，並以一個 --event-filters=[ATTRIBUTE=VALUE,...] 標記表示，也可以重複標記來新增更多篩選器。只有符合所有篩選條件的事件，才會傳送至目的地。不支援萬用字元和規則運算式。
• Cloud Storage bucket 必須與 Eventarc 觸發程序位於相同專案和 Google Cloud區域或多區域。
• 根據預設，為 Eventarc 建立的 Pub/Sub 訂閱項目會持續存在，不會因活動而異，也不會過期。如要變更閒置時間長度，請參閱「訂閱屬性」。

範例：

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

這個指令會為 Cloud Storage bucket my-project-bucket 建立名為 helloworld-trigger 的觸發程序，以及識別為 google.cloud.storage.object.v1.finalized 的事件。

Terraform

您可以使用 Terraform 建立工作流程的觸發條件。詳情請參閱「使用 Eventarc 和 Terraform 觸發工作流程」。

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

列出觸發條件

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

控制台

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

   前往「Triggers」(觸發條件)

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

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

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

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

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

gcloud

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

gcloud eventarc triggers list --location=-

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

後續步驟

• 使用 Eventarc 和 Terraform 觸發工作流程

• 透過 Cloud Storage 中的事件觸發 Workflows

• 使用 Pub/Sub 訊息觸發工作流程

• 進一步瞭解 Eventarc