Trình kích hoạt Cloud Firestore

Với Chức năng đám mây, bạn có thể xử lý các sự kiện trong Cloud Firestore mà không cần cập nhật mã ứng dụng khách. Bạn có thể thực hiện thay đổi Mây FireStore qua DocumentSnapshot giao diện hoặc thông qua SDK quản trị .

Trong một vòng đời điển hình, chức năng Cloud Firestore thực hiện những việc sau:

  1. Chờ các thay đổi đối với một tài liệu cụ thể.
  2. Triggers khi một sự kiện xảy ra và thực hiện nhiệm vụ của mình (xem Những gì tôi có thể làm với Cloud Chức năng? Cho ví dụ về các trường hợp sử dụng).
  3. Nhận một đối tượng dữ liệu có chứa ảnh chụp nhanh của dữ liệu được lưu trữ trong tài liệu được chỉ định. Đối với onWrite hoặc onUpdate các sự kiện, các đối tượng dữ liệu chứa hai bức ảnh chụp mà đại diện cho nhà nước số liệu trước và sau sự kiện kích hoạt.

Khoảng cách giữa vị trí của cá thể Firestore và vị trí của hàm có thể tạo ra độ trễ mạng đáng kể. Để hiệu suất tối ưu hóa, hãy xem xét xác định vị trí chức năng khi áp dụng.

Kích hoạt chức năng Cloud Firestore

Chức năng đám mây cho căn cứ hỏa lực SDK xuất khẩu một functions.firestore đối tượng cho phép bạn tạo ra các bộ xử lý gắn liền với các sự kiện đám mây FireStore cụ thể.

Loại sự kiện Kích hoạt
onCreate Được kích hoạt khi một tài liệu được viết lần đầu tiên.
onUpdate Được kích hoạt khi tài liệu đã tồn tại và có bất kỳ giá trị nào bị thay đổi.
onDelete Được kích hoạt khi tài liệu có dữ liệu bị xóa.
onWrite Kích hoạt khi onCreate , onUpdate hoặc onDelete được kích hoạt.

Nếu bạn không có một dự án được kích hoạt cho Cloud Chức năng cho căn cứ hỏa lực nào, sau đó đọc Bắt đầu: Viết và Triển khai chức năng đầu tiên của bạn để cấu hình và thiết lập chức năng Cloud Print của bạn cho dự án căn cứ hỏa lực.

Viết các chức năng do Cloud Firestore kích hoạt

Xác định một trình kích hoạt chức năng

Để xác định trình kích hoạt Cloud Firestore, hãy chỉ định đường dẫn tài liệu và loại sự kiện:

Node.js

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

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

Đường dẫn tài liệu tham khảo có thể hoặc là một tài liệu cụ thể hoặc một mẫu ký tự đại diện .

Chỉ định một tài liệu duy nhất

Nếu bạn muốn kích hoạt một sự kiện đối với bất kỳ sự thay đổi vào một tài liệu cụ thể thì bạn có thể sử dụng chức năng sau đây.

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
    });

Chỉ định một nhóm tài liệu bằng cách sử dụng ký tự đại diện

Nếu bạn muốn đính kèm một kích hoạt cho một nhóm các tài liệu, chẳng hạn như tài liệu bất kỳ trong một bộ sưu tập nào đó, sau đó sử dụng một {wildcard} ở vị trí của tài liệu 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"}
    });

Trong ví dụ này, khi bất kỳ lĩnh vực trên tài liệu nào ở users được thay đổi, nó phù hợp với một ký tự đại diện gọi userId .

Nếu một tài liệu users có bộ sưu tập con, và một trường trong một văn bản những bộ sưu tập con được thay đổi, userId ký tự đại diện không được kích hoạt.

Trận wildcard được chiết xuất từ đường dẫn tài liệu và lưu trữ vào context.params . Bạn có thể xác định bao nhiêu ký tự đại diện tùy thích để thay thế ID tài liệu hoặc bộ sưu tập rõ ràng, ví dụ:

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"}
    });

Trình kích hoạt sự kiện

Kích hoạt một chức năng khi một tài liệu mới được tạo

Bạn có thể kích hoạt một chức năng để bắn bất cứ lúc nào một tài liệu mới được tạo ra trong một bộ sưu tập bằng cách sử dụng một onCreate() xử lý với một ký tự đại diện . Chức năng ví dụ này gọi createUser mỗi khi một lý lịch thành viên mới được thêm vào:

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 ...
    });

Kích hoạt một chức năng khi tài liệu được cập nhật

Bạn cũng có thể kích hoạt một chức năng để lửa khi một tài liệu được cập nhật bằng cách sử dụng onUpdate() chức năng với một ký tự đại diện . Chức năng ví dụ này gọi updateUser nếu người dùng thay đổi hồ sơ của họ:

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 ...
    });

Kích hoạt một chức năng khi tài liệu bị xóa

Bạn cũng có thể kích hoạt một chức năng khi một tài liệu bị xóa bằng cách sử dụng onDelete() chức năng với một ký tự đại diện . Chức năng ví dụ này gọi deleteUser khi người dùng xóa hồ sơ người dùng của họ:

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 ...
    });

Kích hoạt một chức năng cho tất cả các thay đổi đối với tài liệu

Nếu bạn không quan tâm đến các loại sự kiện con người bị sa thải, bạn có thể nghe tất cả các thay đổi trong tài liệu của Cloud FireStore sử dụng onWrite() chức năng với một ký tự đại diện . Chức năng ví dụ này gọi modifyUser nếu người dùng được tạo ra, cập nhật, hoặc xóa:

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 ...
    });

Đọc và ghi dữ liệu

Khi một chức năng được kích hoạt, nó cung cấp ảnh chụp nhanh dữ liệu liên quan đến sự kiện. Bạn có thể sử dụng ảnh chụp nhanh này để đọc hoặc ghi vào tài liệu đã kích hoạt sự kiện hoặc sử dụng SDK quản trị Firebase để truy cập các phần khác trong cơ sở dữ liệu của bạn.

Dữ liệu sự kiện

Đọc dữ liệu

Khi một chức năng được kích hoạt, bạn có thể muốn lấy dữ liệu từ tài liệu đã được cập nhật hoặc lấy dữ liệu trước khi cập nhật. Bạn có thể lấy dữ liệu trước bằng cách sử dụng change.before.data() , trong đó có các bản chụp tài liệu trước khi cập nhật. Tương tự như vậy, change.after.data() chứa các trạng thái ảnh chụp tài liệu sau khi cập nhật.

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();
    });

Bạn có thể truy cập các thuộc tính như bạn làm trong bất kỳ đối tượng nào khác. Ngoài ra, bạn có thể sử dụng get chức năng để lĩnh vực truy cập cụ thể:

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');

Viết dữ liệu

Mỗi lệnh gọi hàm được liên kết với một tài liệu cụ thể trong cơ sở dữ liệu Cloud Firestore của bạn. Bạn có thể truy cập vào tài liệu đó như là một DocumentReference trong ref tài sản của ảnh chụp trở lại chức năng của bạn.

Đây DocumentReference xuất phát từ đám mây FireStore Node.js SDK và bao gồm các phương pháp như update() , set() , và remove() , do đó bạn có thể dễ dàng chỉnh sửa các tài liệu đã làm hiển thị các chức năng.

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});
    });

Dữ liệu bên ngoài sự kiện kích hoạt

Các Chức năng Đám mây thực thi trong một môi trường đáng tin cậy, có nghĩa là chúng được ủy quyền như một tài khoản dịch vụ trong dự án của bạn. Bạn có thể thực hiện đọc và viết bằng cách sử dụng căn cứ hỏa lực SDK quản trị :

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({ ... });
  });

Hạn chế

Lưu ý các hạn chế sau đối với trình kích hoạt Cloud Firestore cho Chức năng đám mây:

  • Đặt hàng không được đảm bảo. Các thay đổi nhanh chóng có thể kích hoạt các lệnh gọi hàm theo thứ tự không mong muốn.
  • Các sự kiện được phân phối ít nhất một lần, nhưng một sự kiện có thể dẫn đến nhiều lệnh gọi hàm. Tránh phụ thuộc vào chính xác một lần cơ, và ghi chức năng idempotent .
  • Đám mây FireStore trigger Cloud Chức năng chỉ có sẵn cho đám mây FireStore trong chế độ Native . Nó không khả dụng cho Cloud Firestore ở chế độ Datastore.