本頁面由 Cloud Translation API 翻譯而成。

擴充資料連接與雲端函數

使用 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 的參數以及它返回的資料。

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

擴充資料連接與雲端函數 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

常見用途

在 Data Connect 突變時觸發函數

基本變化事件函式

Node.js

Python

設定函式位置

Node.js

Python

篩選事件

Node.js

Python

通配符和捕獲組

Node.js

Python

存取使用者驗證資訊

Node.js

Python

存取事件資料

事件屬性

數據有效載荷

範例

Node.js

Python

擴充資料連接與雲端函數