將 Cloud Firestore 事件轉送至 Workflows

主控台

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

   前往專案選取器

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

   啟用 API

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

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

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

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

   2. 選取專案。

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

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

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

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

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

   6. 按一下「繼續」。

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

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. 啟用 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 Firestore 活動，請啟用firestore.googleapis.com。

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

   1. 建立服務帳戶：

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

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

   2. 授予必要的 Identity and Access Management (IAM) 角色或權限。詳情請參閱「工作流程目標的角色和權限」。

主控台

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

   前往「Triggers」(觸發條件)

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

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

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

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

6. 在「Event type」(事件類型) 清單中，從「Direct」(直接) 事件選取事件類型。
7. 在「事件資料內容類型」清單中，選取事件酬載的編碼。

   如果是來自 Cloud Firestore的直接事件，這必須是 application/protobuf，且事件資料為位元組陣列。如要進一步瞭解 Cloud Firestore 事件的 protobuf 訊息，請參閱「常見事件」。 請注意，您可以使用 Workflows 標準程式庫函式，將位元組編碼為 Base64 文字。詳情請參閱「傳回位元組」。

8. 在「Region」(區域) 清單中，選取與產生事件的Google Cloud 服務相同的區域。

   詳情請參閱「Eventarc 區域」。

9. 如果適用於活動供應商，請按一下「新增篩選器」，然後指定下列項目：
   1. 在「屬性 1」欄位中，根據您選擇的直接事件，選取可做為事件篩選器的資源 ID。
   2. 選取運算子：
      • 相等
      • 路徑模式：適用於 document (原生模式) 和 entity (Datastore 模式) 資源。使用萬用字元回應符合模式的變更。萬用字元 * 會比對單一區隔，而多區隔萬用字元 ** 則會比對模式中的零或多個區隔。請勿指定開頭的正斜線，例如：

        users/*或users/{userId}	比對 /users 集合中的所有文件。 與子集合中的文件不符，例如： /users/marie/messages/33e2IxYBD9enzS50SJ68
        users/**	比對 /users 集合中的所有文件，以及 /users/marie/messages/33e2IxYBD9enzS50SJ68 等子集合中的文件

        詳情請參閱「 瞭解路徑模式」。

   3. 在「屬性值 1」欄位中，根據所選運算子輸入確切值或套用路徑模式。
   4. 如要套用更多屬性篩選器，請按一下「新增篩選器」，然後指定適當的值。
10. 選取要叫用服務或工作流程的服務帳戶。

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

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

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

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

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

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

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

gcloud

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

旗標會因您執行 Firestore 時是採用原生模式或 Datastore 模式而有所不同。詳情請參閱「選擇原生模式或 Datastore 模式」。

原生模式

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="database=DATABASE" \
    --event-filters="namespace=NAMESPACE" \
    --event-filters-path-pattern="document=DOCUMENT" \
    --event-data-content-type="EVENT_DATA_CONTENT_TYPE" \
    --service-account="MY_SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com"

Datastore 模式

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="database=DATABASE" \
    --event-filters="namespace=NAMESPACE" \
    --event-filters-path-pattern="entity=ENTITY" \
    --event-data-content-type="EVENT_DATA_CONTENT_TYPE" \
    --service-account="MY_SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com"

更改下列內容：

• TRIGGER：觸發條件的 ID 或完整 ID。

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

  Eventarc 的 Cloud Firestore 觸發程序僅適用於特定位置，且觸發程序必須與 Cloud Firestore 資料庫位於相同位置。詳情請參閱「Eventarc 位置」和「Cloud Firestore 位置」。

• DESTINATION_WORKFLOW：已部署的工作流程 ID，用於接收觸發條件的事件。工作流程可位於任何 Workflows 支援的位置，不一定要與觸發程序位於相同位置。不過，工作流程必須與觸發程序位於相同專案中。
• DESTINATION_WORKFLOW_LOCATION (選用)：部署目的地工作流程的位置。如未指定，系統會假設工作流程與觸發程序位於相同位置。
• EVENT_FILTER_TYPE：事件的 ID。 方法的 API 呼叫成功時，系統會產生事件。如果是長時間執行的作業，系統只會在作業結束時產生事件，且僅限動作順利完成的情況。如需支援的事件類型清單，請參閱「Eventarc 支援的 Google 事件類型」。

Cloud Firestore 僅在原生模式中支援下列事件類型。

• google.cloud.firestore.document.v1.created：首次將文件寫入時傳送的事件
• google.cloud.firestore.document.v1.created.withAuthContext：首次寫入文件時，系統會傳送含有驗證資訊屬性的事件
• google.cloud.firestore.document.v1.updated：如果文件已存在，且任何值有所變更，系統就會傳送事件
• google.cloud.firestore.document.v1.updated.withAuthContext：如果文件已存在且有任何值變更，系統就會傳送含有驗證資訊屬性的事件
• google.cloud.firestore.document.v1.deleted：刪除文件時傳送的事件
• google.cloud.firestore.document.v1.deleted.withAuthContext：刪除文件時，系統會傳送含有驗證資訊屬性的事件
• google.cloud.firestore.document.v1.written：在建立、更新或刪除文件時傳送的事件
• google.cloud.firestore.document.v1.written.withAuthContext：文件建立、更新或刪除時，系統會傳送含有驗證資訊屬性的事件。

Cloud Firestore 僅在 Datastore 模式下支援下列事件類型。Firestore (Datastore 模式) 的資料物件又稱為「實體」。

• google.cloud.datastore.entity.v1.created：首次將實體寫入時傳送的事件
• google.cloud.datastore.entity.v1.created.withAuthContext：首次將實體寫入時，系統會傳送含有驗證資訊屬性的事件
• google.cloud.datastore.entity.v1.updated：當實體已存在且任何值有所變更時，系統會傳送事件
• google.cloud.datastore.entity.v1.updated.withAuthContext：如果實體已存在且有任何值變更，系統會傳送含有驗證資訊屬性的事件
• google.cloud.datastore.entity.v1.deleted：刪除實體時傳送的事件
• google.cloud.datastore.entity.v1.deleted.withAuthContext：刪除實體時，系統會傳送含有驗證資訊屬性的事件
• google.cloud.datastore.entity.v1.written：在建立、更新或刪除實體時傳送的事件
• google.cloud.datastore.entity.v1.written.withAuthContext：實體建立、更新或刪除時，會傳送含有驗證資訊屬性的事件

• DATABASE：Firestore 資料庫。 預設資料庫名稱請使用 (default)。
• NAMESPACE (選用)：Firestore 資料庫命名空間。如要使用 Datastore 模式的預設命名空間，請使用 (default)。如未指定，系統會比對任何出現的項目 (*)。
• DOCUMENT (選用)：僅適用於原生模式下執行的資料庫執行個體。您想在該路徑中建立、更新或刪除資料時接收事件的資料庫路徑。請勿指定開頭斜線。運算子可以是下列其中一個：
  • 相等；例如： --event-filters="document=DOCUMENT"
  • 路徑模式，例如 --event-filters-path-pattern="document=DOCUMENT"。

    使用萬用字元，對符合模式的文件變更做出回應。 萬用字元 * 可比對單一區隔，而多區隔萬用字元 ** 可比對模式中的零或多個區隔，例如：

    users/*或users/{userId}	比對 /users 集合中的所有文件。 與子集合中的文件不符，例如： /users/marie/messages/33e2IxYBD9enzS50SJ68
    users/**	比對 /users 集合中的所有文件，以及 /users/marie/messages/33e2IxYBD9enzS50SJ68 等子集合中的文件

    詳情請參閱「瞭解路徑模式」。
• ENTITY (選用)：僅適用於Datastore 模式下執行的資料庫執行個體。資料庫路徑，您希望在該路徑中建立、更新或刪除資料時收到事件。請勿指定開頭斜線。運算子可以是下列其中一項：
  • 相等；例如： --event-filters="document=ENTITY"
  • 路徑模式，例如： --event-filters-path-pattern="ENTITY=ENTITY"

    詳情請參閱「瞭解路徑模式」。

    請注意，您可能需要逸出種類 ID 和實體 ID 中的字元。逸出字元可讓事件篩選器正確解讀 ID。詳情請參閱「字元逸出」。

• EVENT_DATA_CONTENT_TYPE：事件酬載的編碼。如果是來自 Firestore 的直接事件，這必須是 application/protobuf，且事件資料為位元組陣列。如要進一步瞭解 Cloud Firestore 事件的 protobuf 訊息，請參閱「常見事件」。請注意，您可以使用 Workflows 標準程式庫函式，將位元組編碼為 Base64 文字。詳情請參閱「傳回位元組」。
• SERVICE_ACCOUNT_NAME：您建立的 IAM 服務帳戶名稱，並已授予 Workflows 所需的特定角色。
• PROJECT_ID：您的 Google Cloud 專案 ID

注意：

• 如果是來自 Cloud Firestore的直接事件，事件酬載的編碼為 application/protobuf。
• --event-filters="type=EVENT_FILTER_TYPE" 旗標為必要旗標。如未設定其他事件篩選器，系統會比對所有資源的事件。
• EVENT_FILTER_TYPE建立後即無法變更。如要變更 EVENT_FILTER_TYPE，請建立新觸發條件並刪除舊觸發條件。
• 每個觸發條件可以有多個事件篩選器，以逗號分隔，放在一個 --event-filters=[ATTRIBUTE=VALUE,...] 標記中，也可以重複標記來新增更多篩選器。只有符合所有篩選條件的事件會傳送至目的地。不支援萬用字元和規則運算式，但使用 --event-filters-path-pattern 旗標時，可以定義資源路徑模式。
• --service-account 旗標用於指定與觸發程序相關聯的身分與存取權管理 (IAM) 服務帳戶電子郵件。

範例：

gcloud eventarc triggers create helloworld-trigger \
    --location=us-east1 \
    --destination-workflow=my-workflow \
    --destination-workflow-location=us-east1 \
    --event-filters="type=google.cloud.firestore.document.v1.updated" \
    --event-filters="database=my-database" \
    --event-filters-path-pattern="document=users/my-document-*" \
    --event-data-content-type="application/protobuf" \
    --service-account="${TRIGGER_SA}@${PROJECT_ID}.iam.gserviceaccount.com"

這個指令會為以原生模式執行的 my-database 資料庫執行個體中，識別為 google.cloud.firestore.document.v1.updated 的事件建立名為 helloworld-trigger 的觸發程序，並篩選符合 users/my-document- 的 document 路徑事件。

Terraform

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

主控台

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

   前往「Triggers」(觸發條件)

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

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

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

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

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

gcloud

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

gcloud eventarc triggers list --location=-

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