根據 Firestore 事件建立觸發條件

本指南將說明如何根據 Firestore 事件，為 Cloud Run 服務和函式建立觸發事件。

您可以設定 Cloud Run 服務，讓服務由 Firestore 資料庫中的事件觸發。觸發時，服務會透過 Firestore API 和用戶端程式庫讀取及更新 Firestore 資料庫，以回應這些事件。

在一般生命週期中，當 Cloud Run 服務由 Firestore 事件觸發時，會發生下列情況：

  1. 服務會等待特定文件的變更。

  2. 發生變更時，系統會觸發服務並執行相關工作。

  3. 服務會接收含有受影響文件快照的資料物件。對於 write 或 update 事件，資料物件包含快照，代表觸發事件前後的文件狀態。

事件類型

Firestore 支援 create、update、delete 和 write 事件。write 事件涵蓋文件的所有修改作業。

事件類型 觸發條件
google.cloud.firestore.document.v1.created (預設) 在第一次寫入文件時觸發。
google.cloud.firestore.document.v1.updated 在文件已經存在且已變更任何值時觸發。
google.cloud.firestore.document.v1.deleted 在刪除具有資料的文件時觸發。
google.cloud.firestore.document.v1.written 在建立、更新或刪除文件時觸發。

萬用字元會在觸發事件中使用大括號編寫，例如： projects/YOUR_PROJECT_ID/databases/(default)/documents/collection/{document_wildcard}

指定文件路徑

如要觸發服務，請指定要監聽的文件路徑。文件路徑必須與服務位於相同的 Google Cloud 專案中。

以下列舉幾個有效文件路徑的範例：

  • users/marie：有效的觸發條件。監控單一文件 /users/marie。

  • users/{username}：有效的觸發條件。監控所有使用者文件。萬用字元可用於監控集合中的所有文件。

  • users/{username}/addresses：無效觸發事件。指的是子集合 addresses，而非文件。

  • users/{username}/addresses/home：有效的觸發條件。監控所有使用者的住家地址文件。

  • users/{username}/addresses/{addressId}：有效的觸發條件。監控所有地址文件。

  • users/{user=**}：有效的觸發條件。監控所有使用者文件，以及每個使用者文件 (例如 /users/userID/address/home 或 /users/userID/phone/work) 下方子集合中的任何文件。

萬用字元和參數

如果不知道要監控的特定文件，請使用 {wildcard} 而非文件 ID：

  • users/{username} 會監聽所有使用者文件的變更。

在這個範例中，當 users 中任何文件的任何欄位發生變更時，就會比對名為 {username} 的萬用字元。

如果 users 中的文件含有子集合，且其中一個子集合文件中的欄位有所變更，則 {username} 萬用字元不會觸發。如果您也想回應子集合中的事件，請使用多分段萬用字元 {username=**}。

系統會從文件路徑中擷取萬用字元比對項目。您可以視需要定義任意數量的萬用字元，用於取代明確的集合或文件 ID。您最多可以使用一個多區隔萬用字元，例如 {username=**}。

事件結構

這個觸發條件會使用類似以下的事件叫用您的服務：

{
    "oldValue": { // Update and Delete operations only
        A Document object containing a pre-operation document snapshot
    },
    "updateMask": { // Update operations only
        A DocumentMask object that lists changed fields.
    },
    "value": {
        // A Document object containing a post-operation document snapshot
    }
}

每個 Document 物件都包含一或多個 Value 物件。如需類型參照，請參閱 Value 說明文件。

事前準備

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

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

    啟用 API

必要的角色

您或管理員必須為部署者帳戶、觸發器身分，以及 Pub/Sub 服務代理人 (選用) 授予下列 IAM 角色。

部署者帳戶的必要角色

如要取得從 Firestore 事件觸發所需的權限，請要求管理員為您授予專案的下列 IAM 角色：

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

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

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

觸發條件身分的必要角色

  1. 請記下 Compute Engine 預設服務帳戶，因為您會將其附加至 Eventarc 觸發事件，以便代表觸發事件的身分，用於測試用途。啟用或使用使用 Compute Engine 的 Google Cloud 服務後，系統會自動建立這個服務帳戶，且電子郵件格式如下：

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    將 PROJECT_NUMBER 替換為您的 Google Cloud專案編號。您可以在 Google Cloud 控制台的「歡迎」頁面上找到專案編號，也可以執行下列指令：

    gcloud projects describe PROJECT_ID --format='value(projectNumber)'

    對於實際環境，我們強烈建議建立新的服務帳戶，並授予一或多個包含必要最低權限的 IAM 角色，並遵循最低權限原則。

  2. 根據預設，只有專案擁有者、專案編輯者，以及 Cloud Run 管理員和叫用者可以叫用 Cloud Run 服務。您可以依服務控制存取權，但為了測試，請將 Google Cloud 專案的 Cloud Run 叫用者角色 (run.invoker) 授予 Compute Engine 服務帳戶。這樣一來，系統就會為專案中的所有 Cloud Run 服務和工作授予這個角色。
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/run.invoker

    請注意，如果您為經過驗證的 Cloud Run 服務建立觸發條件，但未授予 Cloud Run 叫用者角色，系統會成功建立觸發條件並啟用。不過，觸發條件無法正常運作，而且記錄中會顯示類似以下的訊息：

    The request was not authenticated. Either allow unauthenticated invocations or set the proper Authorization header.
  3. 將專案的 Eventarc 事件接收者角色 (roles/eventarc.eventReceiver) 授予 Compute Engine 預設服務帳戶，以便 Eventarc 觸發條件接收事件供應商的事件。
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/eventarc.eventReceiver

Pub/Sub 服務代理人的選用角色

  • 如果您是在 2021 年 4 月 8 日當天或之前啟用 Cloud Pub/Sub 服務代理，以便支援經過驗證的 Pub/Sub 推送要求，請將 服務帳戶權杖建立者角色 (roles/iam.serviceAccountTokenCreator) 授予服務代理。否則，系統會預設授予這個角色：
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountTokenCreator

設定 Firestore 資料庫

在部署服務之前，您必須建立 Firestore 資料庫：

  1. 前往 Firestore 資料頁面。

  2. 選取「建立資料庫」。

  3. 按一下「原生模式」，然後選取「繼續」。

  4. 在「資料庫名稱」欄位中輸入資料庫 ID，例如 firestore-db。

  5. 在「位置類型」中，選取「區域」，然後選擇資料庫所在的區域。選定後即無法變更。

  6. 將「安全性規則」部分保留原樣。

  7. 按一下 [Create database] (建立資料庫)。

Firestore 資料模型包含內含文件的集合。文件包含一組鍵/值組合。

建立觸發條件

視您部署的服務類型而定，您可以：

為服務建立觸發條件

您可以在部署服務後指定觸發條件。

按一下分頁標籤，瞭解如何使用自選工具。

主控台

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

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

    前往 Cloud Run

  3. 在服務清單中按一下現有服務。

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

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

  6. 在「Eventarc trigger」窗格中，修改觸發條件詳細資料，如下所示：

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

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

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

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

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

    4. 在「Event type」清單中，選取「type=google.cloud.firestore.document.v1.created」。觸發條件設定會因支援的事件類型而異。詳情請參閱「事件類型」。

    5. 在「篩選器」部分，選取資料庫、運算和屬性值，或使用預設選項。

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

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

    8. 您可以視需要指定要傳送傳入要求的服務網址路徑。這是目的地服務中的相對路徑，應將觸發事件傳送至此路徑。例如：/、/route、route 和 route/subroute。

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

  7. 建立觸發條件後，請確認「Triggers」分頁上有勾號 ，以驗證觸發條件的健康狀態。

gcloud

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

  2. 執行下列指令，建立用於篩選事件的觸發條件：

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=EVENTARC_TRIGGER_LOCATION \
    --destination-run-service=SERVICE  \
    --destination-run-region=REGION \
    --event-filters="type=google.cloud.firestore.document.v1.created" \
    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    取代：

    • TRIGGER_NAME 替換為觸發條件的名稱。

    • EVENTARC_TRIGGER_LOCATION 與 Eventarc 觸發條件的所在位置。一般來說，Eventarc 觸發事件的位置應與您要監控事件的 Google Cloud 資源位置相符。在大多數情況下，您也應在相同的地區部署服務。詳情請參閱「Eventarc 位置」。

    • SERVICE 改為您要部署的服務名稱。

    • REGION 與服務的 Cloud Run region 相同。

    • PROJECT_NUMBER 換成您的 Google Cloud 專案編號。Eventarc 觸發事件會連結至服務帳戶，以便在叫用服務時做為身分使用。Eventarc 觸發事件的服務帳戶必須具備叫用服務的權限。根據預設，Cloud Run 會使用預設的 Compute 服務帳戶。

    • event-filters 標記可指定觸發事件監控的事件篩選器。符合所有 event-filters 的事件會觸發對服務的呼叫。每個觸發條件都必須有支援的事件類型。建立後即無法變更事件篩選器類型。如要變更事件篩選器類型，您必須建立新的觸發條件，並刪除舊的觸發條件。您可以選擇在 ATTRIBUTE=VALUE 表單中重複使用支援的篩選器，藉此新增更多篩選器。--event-filters

Terraform

如要為 Cloud Run 服務建立 Eventarc 觸發條件，請參閱「使用 Terraform 建立觸發條件」一文。

為函式建立觸發條件

按一下分頁標籤，瞭解如何使用自選工具。

主控台

使用 Google Cloud 控制台建立函式時，您也可以為函式新增觸發條件。請按照下列步驟為函式建立觸發條件：

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

    前往 Cloud Run

  2. 按一下「編寫函式」，然後輸入函式詳細資料。如要進一步瞭解如何在部署期間設定函式，請參閱「部署函式」。

  3. 在「觸發條件」部分中，按一下「新增觸發條件」。

  4. 選取「Firestore 觸發條件」。

  5. 在「Eventarc trigger」窗格中，修改觸發條件詳細資料，如下所示：

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

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

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

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

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

    4. 在「Event type」清單中，選取「type=google.cloud.firestore.document.v1.created」。觸發條件設定會因支援的事件類型而異。詳情請參閱「事件類型」。

    5. 在「篩選器」部分，選取資料庫、運算和屬性值，或使用預設選項。

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

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

    8. 您可以視需要指定要傳送傳入要求的服務網址路徑。這是目的地服務中的相對路徑，用於傳送觸發事件。例如：/、/route、route 和 route/subroute。

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

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 區域。例如：us-central1。

  2. 執行下列指令，建立用於篩選事件的觸發條件：

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=EVENTARC_TRIGGER_LOCATION \
    --destination-run-service=FUNCTION  \
    --destination-run-region=REGION \
    --event-filters="type=google.cloud.firestore.document.v1.created" \
    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    取代：

    • TRIGGER_NAME 替換為觸發條件的名稱。

    • EVENTARC_TRIGGER_LOCATION 與 Eventarc 觸發條件的所在位置。一般來說，Eventarc 觸發事件的位置應與您要監控事件的 Google Cloud 資源位置相符。在大多數情況下，您也應在相同的區域中部署函式。詳情請參閱「Eventarc 位置」。

    • FUNCTION 改為您要部署的函式名稱。

    • REGION 與函式的 Cloud Run region 搭配使用。

    • PROJECT_NUMBER 換成您的 Google Cloud 專案編號。Eventarc 觸發事件會連結至服務帳戶，以便在叫用函式時做為身分識別資訊使用。Eventarc 觸發事件的服務帳戶必須具備叫用函式的權限。根據預設，Cloud Run 會使用預設的 Compute 服務帳戶。

    • event-filters 標記可指定觸發事件監控的事件篩選器。符合所有 event-filters 的事件會觸發對函式的呼叫，每個觸發條件都必須有支援的事件類型。建立後即無法變更事件篩選器類型。如要變更事件篩選器類型，您必須建立新的觸發條件，並刪除舊的觸發條件。您可以選擇在 ATTRIBUTE=VALUE 表單中重複使用支援的篩選器，藉此新增更多篩選器。--event-filters

Terraform

如要為 Cloud Run 函式建立 Eventarc 觸發條件，請參閱「使用 Terraform 建立觸發條件」一文。

後續步驟

  • 請參閱函式範例，瞭解在指定集合中變更文件時會觸發的函式。