使用 Cloud Functions 擴充 Cloud Firestore

您可以使用 Cloud Functions 部署 Node.js 程式碼，處理 Cloud Firestore 資料庫變更而觸發的事件。這樣一來，您就能輕鬆在應用程式中加入伺服器端功能，而無需自行執行伺服器。

如需用途範例，請參閱「Cloud Functions 我可以做什麼？」一文。或前往 Functions 範例 GitHub 存放區。

Cloud Firestore 函式觸發條件

Cloud Functions for Firebase SDK 會匯出 functions.firestore 物件，讓您建立與特定 Cloud Firestore 事件相關聯的處理常式。

事件類型 觸發條件
onCreate 在第一次寫入文件時觸發。
onUpdate 在文件已經存在且已變更任何值時觸發。
onDelete 在刪除具有資料的文件時觸發。
onWrite 在觸發 onCreate、onUpdate 或 onDelete 時觸發。

如果您尚未啟用 Cloud Functions for Firebase 專案，請參閱「開始使用：編寫及部署第一個函式」，瞭解如何設定 Cloud Functions for Firebase 專案。

編寫 Cloud Firestore 觸發的函式

定義函式觸發條件

如要定義 Cloud Firestore 觸發條件，請指定文件路徑和事件類型：

Node.js

const functions = require('firebase-functions');

exports.myFunction = functions.firestore
  .document('my-collection/{docId}')
  .onWrite((change, context) => { /* ... */ });

文件路徑可以參照特定文件或萬用字元模式。

指定單一文件

如果想在特定文件發生「任何」變更時觸發事件，可以使用下列函式。

Node.js

// Listen for any change on document `marie` in collection `users`
exports.myFunctionName = functions.firestore
    .document('users/marie').onWrite((change, context) => {
      // ... Your code here
    });
index.js

使用萬用字元指定一組文件

如要為一組文件 (例如特定集合中的任何文件) 附加觸發條件，請使用 {wildcard} 取代文件 ID：

Node.js

// Listen for changes in all documents in the 'users' collection
exports.useWildcard = functions.firestore
    .document('users/{userId}')
    .onWrite((change, context) => {
      // If we set `/users/marie` to {name: "Marie"} then
      // context.params.userId == "marie"
      // ... and ...
      // change.after.data() == {name: "Marie"}
    });
index.js

在這個範例中，當 users 中任何文件的任何欄位發生變更時，就會與名為 userId 的萬用字元相符。

如果 users 中的文件含有子集合，且其中一個子集合文件中的欄位已變更，則「不會」觸發 userId 萬用字元。

系統會從文件路徑中擷取萬用字元比對結果，並儲存在 context.params 中。您可以視需要定義任意數量的萬用字元，用於替換明確的集合或文件 ID，例如：

Node.js

// Listen for changes in all documents in the 'users' collection and all subcollections
exports.useMultipleWildcards = functions.firestore
    .document('users/{userId}/{messageCollectionId}/{messageId}')
    .onWrite((change, context) => {
      // If we set `/users/marie/incoming_messages/134` to {body: "Hello"} then
      // context.params.userId == "marie";
      // context.params.messageCollectionId == "incoming_messages";
      // context.params.messageId == "134";
      // ... and ...
      // change.after.data() == {body: "Hello"}
    });
index.js

事件觸發條件

建立新文件時觸發函式

您可以使用 onCreate() 處理常式搭配萬用字元，在每次在集合中建立新文件時觸發函式。這個函式範例會在每次新增使用者設定檔時呼叫 createUser：

Node.js

exports.createUser = functions.firestore
    .document('users/{userId}')
    .onCreate((snap, context) => {
      // Get an object representing the document
      // e.g. {'name': 'Marie', 'age': 66}
      const newValue = snap.data();

      // access a particular field as you would any JS property
      const name = newValue.name;

      // perform desired operations ...
    });
index.js

在文件更新時觸發函式

您也可以使用 onUpdate() 函式搭配萬用字元，在文件更新時觸發函式。如果使用者變更個人資料，這個範例函式會呼叫 updateUser：

Node.js

exports.updateUser = functions.firestore
    .document('users/{userId}')
    .onUpdate((change, context) => {
      // Get an object representing the document
      // e.g. {'name': 'Marie', 'age': 66}
      const newValue = change.after.data();

      // ...or the previous value before this update
      const previousValue = change.before.data();

      // access a particular field as you would any JS property
      const name = newValue.name;

      // perform desired operations ...
    });
index.js

在文件刪除時觸發函式

您也可以使用 onDelete() 函式搭配萬用字元，在刪除文件時觸發函式。當使用者刪除個人資料時，這個範例函式會呼叫 deleteUser：

Node.js

exports.deleteUser = functions.firestore
    .document('users/{userID}')
    .onDelete((snap, context) => {
      // Get an object representing the document prior to deletion
      // e.g. {'name': 'Marie', 'age': 66}
      const deletedValue = snap.data();

      // perform desired operations ...
    });
index.js

針對文件的所有變更觸發函式

如果您不關心觸發事件的類型，可以使用 onWrite() 函式搭配萬用字元，監聽 Cloud Firestore 文件中的所有變更。這個範例函式會在建立、更新或刪除使用者時呼叫 modifyUser：

Node.js

exports.modifyUser = functions.firestore
    .document('users/{userID}')
    .onWrite((change, context) => {
      // Get an object with the current document value.
      // If the document does not exist, it has been deleted.
      const document = change.after.exists ? change.after.data() : null;

      // Get an object with the previous document value (for update or delete)
      const oldDocument = change.before.data();

      // perform desired operations ...
    });
index.js

讀取及寫入資料

觸發函式時，系統會提供事件相關資料的快照。您可以使用這個快照，讀取或寫入觸發事件的文件，也可以使用 Firebase Admin SDK 存取資料庫的其他部分。

事件資料

讀取資料

函式觸發時，您可能會想從已更新的文件中取得資料，或取得更新前的資料。您可以使用 change.before.data() 取得先前的資料，其中包含更新前的文件快照。同樣地，change.after.data() 會包含更新後的文件快照狀態。

Node.js

exports.updateUser2 = functions.firestore
    .document('users/{userId}')
    .onUpdate((change, context) => {
      // Get an object representing the current document
      const newValue = change.after.data();

      // ...or the previous value before this update
      const previousValue = change.before.data();
    });
index.js

您可以像存取任何其他物件一樣存取屬性。或者，您也可以使用 get 函式存取特定欄位：

Node.js

// Fetch data using standard accessors
const age = snap.data().age;
const name = snap.data()['name'];

// Fetch data using built in accessor
const experience = snap.get('experience');
index.js

寫入資料

每個函式叫用都與 Cloud Firestore 資料庫中的特定文件相關聯。您可以透過函式傳回的快照 ref 屬性，以 DocumentReference 的形式存取該文件。

這個 DocumentReference 來自 Cloud Firestore Node.js SDK，其中包含 update()、set() 和 remove() 等方法，方便您輕鬆修改觸發函式的文件。

Node.js

// Listen for updates to any `user` document.
exports.countNameChanges = functions.firestore
    .document('users/{userId}')
    .onUpdate((change, context) => {
      // Retrieve the current and previous value
      const data = change.after.data();
      const previousData = change.before.data();

      // We'll only update if the name has changed.
      // This is crucial to prevent infinite loops.
      if (data.name == previousData.name) {
        return null;
      }

      // Retrieve the current count of name changes
      let count = data.name_change_count;
      if (!count) {
        count = 0;
      }

      // Then return a promise of a set operation to update the count
      return change.after.ref.set({
        name_change_count: count + 1
      }, {merge: true});
    });
index.js

觸發事件以外的資料

Cloud Functions 會在可信任的環境中執行，也就是說，這些工作會在專案中以服務帳戶的身分授權。您可以使用 Firebase Admin SDK 執行讀取和寫入作業：

Node.js

const admin = require('firebase-admin');
admin.initializeApp();

const db = admin.firestore();

exports.writeToFirestore = functions.firestore
  .document('some/doc')
  .onWrite((change, context) => {
    db.doc('some/otherdoc').set({ ... });
  });

限制

請注意，Cloud Functions 的 Cloud Firestore 觸發條件有下列限制：

  • Cloud Functions (第 1 代) 必須在 Firestore 原生模式中使用現有的「(預設)」資料庫。不支援 Cloud Firestore 命名資料庫或 Datastore 模式。在這種情況下，請使用 Cloud Functions (第 2 代) 設定事件。
  • 我們不保證排序。快速變更可能會以非預期的順序觸發函式叫用。
  • 事件至少會傳送一次，但單一事件可能會導致多次函式叫用。避免依賴「一次一律」機制，並編寫冪等函式。
  • Cloud Firestore 在 Datastore 模式下需要 Cloud Functions (第 2 代)。Cloud Functions (第 1 代) 不支援 Datastore 模式。
  • 觸發條件會與單一資料庫相關聯。無法建立與多個資料庫相符的觸發條件。
  • 刪除資料庫時，系統不會自動刪除該資料庫的任何觸發事件。觸發事件會停止傳送事件，但會持續存在，直到您刪除觸發事件為止。
  • 如果相符的事件超過最大要求大小，事件可能不會傳送至 Cloud Functions (第 1 代)。
    • 如果事件是因要求大小而未傳遞，則會記錄在平台記錄中，並計入專案的記錄檔用量。
    • 您可以在記錄檔探索工具中找到這些記錄，其嚴重性為「Event can not be 如要將 to Cloud function with the limit is too of thest gen of 第 1 Gen...」(事件因大小超過第 1 代的限制，而嚴重性為 error)。您可以在 functionName 欄位下方找到函式名稱。如果 receiveTimestamp 欄位仍在現在起算一小時內，您可以透過時間戳記前後的快照，讀取相關文件，進而推斷實際事件內容。
    • 如要避免這種節奏，您可以採取下列做法：
      • 遷移並升級至 Cloud Functions (第 2 代)
      • 縮小文件大小
      • 刪除問題中的 Cloud Functions
    • 您可以使用排除條件來關閉記錄功能，但請注意，系統並不會傳送違規事件。