用於雲端函數的 Data Connect 觸發器

使用 Cloud Functions for Firebase，您可以處理 Firebase Data Connect 中的事件。Cloud Functions 允許您執行伺服器端程式碼以回應事件，例如在您的 Data Connect 服務中執行 mutation。這樣一來，您無需部署自己的伺服器即可新增自訂邏輯。

常見用途

  • 資料同步:發生變更後，將資料複製或同步到其他系統（如Cloud Firestore、BigQuery 或外部 API）。

  • 非同步工作流程:在資料庫變更後啟動長時間運行的進程，例如映像處理或資料聚合。

  • 使用者互動: 在您的應用程式中發生特定變更事件（例如建立帳戶）後，向使用者發送電子郵件或Cloud Messaging通知。

在 Data Connect 突變時觸發函數

您可以使用 onMutationExecuted 事件處理程序在執行 Data Connect 變更時觸發一個函數。此觸發器在執行 mutation 時發生。

基本變化事件函式

以下基本範例是一個函數，用於記錄在您的 Data Connect 服務中執行的任何 mutation 的詳細資訊：

Node.js

import { onMutationExecuted } from "firebase-functions/dataconnect";
import { logger } from "firebase-functions";

export const logMutation = onMutationExecuted(
  {
    /* Trigger on all mutations, spanning all services and connectors
       in us-central1 */
  },
  (event) => {
    logger.info("A mutation was executed!", {
      data: event.data,
    });
  }
);

Python

from firebase_functions import dataconnect_fn, logger

@dataconnect_fn.on_mutation_executed()
def log_mutation(event: dataconnect_fn.Event):
  logger.info("A mutation was executed!", event.data)

當您在專案中觸發所有變更時，切勿在觸發處理程序中執行任何變更，否則將導致無限循環。如果要對事件觸發器執行變更操作，請使用下面描述的篩選選項，並注意不要觸發變更操作本身。

設定函式位置

這功能位置必須與Data Connect服務地點用於觸發該函數的事件。預設情況下，函數區域為 us-central1。

Node.js

import { onMutationExecuted } from "firebase-functions/dataconnect";

export const onMutationRegionOption = onMutationExecuted(
  {
    region: "europe-west1"  // Set if Data Connect service location is not us-central1
  },
  (event) => { /* ... */ }
);

Python

@dataconnect_fn.on_mutation_executed(
  region="europe-west1"  # Set if Data Connect service location is not us-central1
)
def mutation_executed_handler_region_option(event: dataconnect_fn.Event):
  pass

篩選事件

onMutationExecuted 處理程序可以配置選項，以根據特定屬性篩選事件。當您只想針對特定突變觸發函數時，這非常有用。

你可以依據 service、connector 和 operation 篩選：

Node.js

import { onMutationExecuted } from "firebase-functions/dataconnect";
import { logger } from "firebase-functions";

// Trigger this function only for the CreateUser mutation
// in the users connector of the myAppService service.
export const onUserCreate = onMutationExecuted(
  {
    service: "myAppService",
    connector: "users",
    operation: "CreateUser",
  },
  (event) => {
    logger.info("A new user was created!", event.data);
    // Add logic here: for example, sending a welcome email.
  }
);

Python

from firebase_functions import dataconnect_fn, logger

@dataconnect_fn.on_mutation_executed(
  service="myAppService",
  connector="users",
  operation="CreateUser"
):
def on_user_create(event: dataconnect_fn.Event):
  logger.info("A new user was created!", event.data)

通配符和捕獲組

您可以使用通配符和捕獲組來根據多個值篩選觸發器。擷取的群組會顯示在 event.params 中，供您使用。詳情請參閱「瞭解路徑模式」。

範例：

Node.js

import { onMutationExecuted } from "firebase-functions/dataconnect";

// Trigger on all operations that match the pattern `User*`, on any service and
// connector.
export const onMutationWildcards = onMutationExecuted(
  {
    operation: "User*",
  },
  (event) => {}
);

// Trigger on all operations that match the pattern `User*`, on any service and
// connector. Capture the operation name in the variable `op`.
export const onMutationCaptureWildcards = onMutationExecuted(
  {
    operation: "{op=User*}",
  },
  (event) => {
    // `event.params.op` contains the operation name.
  }
);

// Trigger on all operations on the service `myAppService`. Capture the
// operation name in the variable `operation`.
export const onMutationCaptures = onMutationExecuted(
  {
    service: "myAppService",
    operation: "{operation}",
  },
  (event) => {
    // `event.params.operation` contains the operation name.
  }
);

Python

from firebase_functions import dataconnect_fn

# Trigger on all operations that match the pattern `User*`, on any service and
# connector.
@dataconnect_fn.on_mutation_executed(
  operation="User*"
)
def on_mutation_wildcards(event: dataconnect_fn.Event):
  pass

# Trigger on all operations that match the pattern `User*`, on any service and
# connector. Capture the operation name in the variable `op`.
@dataconnect_fn.on_mutation_executed(
  operation="{op=User*}"
)
def on_mutation_capture_wildcards(event: dataconnect_fn.Event):
  # `event.params["op"]` contains the operation name.
  pass

# Trigger on all operations on the service `myAppService`. Capture the
# operation name in the variable `operation`.
@dataconnect_fn.on_mutation_executed(
  service="myAppService",
  operation="{operation}"
)
def on_mutation_captures(event: dataconnect_fn.Event):
  # `event.params["operation"]` contains the operation name.
  pass

存取使用者驗證資訊

您可以存取有關觸發事件的主體的使用者身份驗證資訊。如要進一步瞭解驗證環境中可用的資料，請參閱「驗證環境」。

以下範例說明如何擷取驗證資訊：

Node.js

import { onMutationExecuted } from "firebase-functions/dataconnect";

export const onMutation = onMutationExecuted(
  { operation: "MyMutation" },
  (event) => {
    // mutationExecuted event provides authType and authId:
    // event.authType
    // event.authId
  }
);

Python

from firebase_functions import dataconnect_fn

@dataconnect_fn.on_mutation_executed(operation="MyMutation")
def mutation_executed_handler(event: dataconnect_fn.Event):
  # mutationExecuted event provides auth_type and auth_id, which are accessed as follows
  # event.auth_type
  # event.auth_id
  pass

身份驗證類型和身份驗證 ID 將如下填入：

突變由發起 authtype authid
已認證的最終用戶 app_user Firebase Auth 權杖 UID
未通過驗證的使用者 unauthenticated 空白
管理員 SDK 模擬最終用戶 app_user Firebase Auth 令牌中被冒充使用者的 UID
管理員 SDK 模擬未經身份驗證的請求 unauthenticated 空白
具有完整權限的管理員 SDK admin 空白

存取事件資料

傳遞至函式的 CloudEvent 物件包含觸發事件的相關資訊。

事件屬性

屬性 類型 說明
id string 事件的專屬 ID。
source string 產生事件的連接器資源 (例如 //firebasedataconnect.googleapis.com/projects/*/locations/*/services/*/connectors/*)。
specversion string CloudEvents 規格版本 (例如 「1.0」)。
type string 活動類型：google.firebase.dataconnect.connector.v1.mutationExecuted。
time string 活動製作時間的時間戳記 (ISO 8601 格式)。
subject string (選用步驟) 事件情境的其他資訊，例如作業名稱。
params object 擷取的路徑模式地圖。
authType string 列舉，代表觸發事件的主體類型。
authId string 觸發事件的主體專屬 ID。
data MutationEventData Data Connect 事件的酬載。詳情請參閱下一節。

數據有效載荷

MutationEventData 物件包含 Data Connect 事件的酬載：

{
  // ...
  "authType": // ...
  "data": {
    "payload": {
      "variables": {
        "userId": "user123",
        "updateData": {
          "displayName": "New Name"
        }
      },
      "data": {
        "updateUser": {
          "id": "user123",
          "displayName": "New Name",
          "email": "user@example.com"
        }
      },
      "errors": []
    }
  }
}
  • payload.variables：包含傳遞至異動的變數。
  • payload.data：包含變動傳回資料的物件。
  • payload.errors: 突變執行過程中發生的任何錯誤的陣列。如果變異成功，則此數組為空。

範例

以下是如何存取突變變數和返回資料的方法：

Node.js

import { onMutationExecuted } from "firebase-functions/dataconnect";
import { logger } from "firebase-functions";

export const processNewUserData = onMutationExecuted(
  {
    "service": "myAppService",
    "connector": "users",
    "operation": "CreateUser",
  },
  (event) => {
    // The variables passed to the mutation
    const mutationVariables = event.data.payload.variables;

    // The data returned by the mutation
    const returnedData = event.data.payload.data;

    logger.info("Processing mutation with variables:", mutationVariables);
    logger.info("Mutation returned:", returnedData);

    // ... your custom logic here
  }
);

Python

from firebase_functions import dataconnect_fn, logger

@dataconnect_fn.on_mutation_executed(
  service="myAppService",
  connector="users",
  operation="CreateUser"
):
def process_new_user_data(event: dataconnect_fn.Event):
  # The variables passed to the mutation
  mutation_vars = event.data.payload.variables
  # The data returned by the mutation
  returned_data = event.data.payload.data

  logger.info("Processing mutation with variables:", mutationVariables)
  logger.info("Mutation returned", returnedData)

  # ... your custom logic here

請注意，與其他一些資​​料庫觸發器（如 Cloud Firestore 或 Realtime Database）不同，Data Connect 事件不提供資料的「之前」快照。因為 Data Connect 代理程式對底層資料庫的請求，所以無法透過事務取得資料的「之前」快照。相反，您可以存取傳遞給 mutation 的參數以及它返回的資料。

由此產生的一個後果是，你不能使用比較「之前」和「之後」快照的策略來避免無限循環，因為在無限循環中，一個事件觸發器會觸發同一個事件。如果必須從由突變事件觸發的函式執行突變，請使用事件篩選器，並確保突變絕不會觸發自身，即使是間接觸發也一樣。