Với Cloud Functions, bạn có thể triển khai mã Node.js để xử lý các sự kiện được kích hoạt bởi những thay đổi trong cơ sở dữ liệu Cloud Firestore của bạn. Điều này cho phép bạn dễ dàng thêm chức năng phía máy chủ vào ứng dụng của mình mà không cần chạy máy chủ của riêng bạn.
Để biết ví dụ về các trường hợp sử dụng, hãy xem Tôi có thể làm gì với Chức năng đám mây? hoặc kho lưu trữ GitHub Mẫu hàm.
Trình kích hoạt chức năng Cloud Firestore
SDK Cloud Functions cho Firebase xuất một đối tượng functions.firestore
cho phép bạn tạo các trình xử lý gắn với các sự kiện Cloud Firestore cụ thể.
Loại sự kiện | Cò súng |
---|---|
onCreate | Được kích hoạt khi tài liệu được ghi vào 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 thay đổi. |
onDelete | Được kích hoạt khi một tài liệu có dữ liệu bị xóa. |
onWrite | Được kích hoạt khi onCreate , onUpdate hoặc onDelete được kích hoạt. |
Nếu bạn chưa kích hoạt dự án cho Chức năng đám mây cho Firebase, hãy đọc Bắt đầu: Viết và triển khai các chức năng đầu tiên của bạn để định cấu hình và thiết lập dự án Chức năng đám mây cho Firebase của bạn.
Viết các hàm kích hoạt Cloud Firestore
Xác định 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 có thể tham chiếu 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 cho bất kỳ thay đổi nào đối với một tài liệu cụ thể thì bạn có thể sử dụng chức năng sau.
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 ký tự đại diện
Nếu bạn muốn đính kèm trình kích hoạt vào một nhóm tài liệu, chẳng hạn như bất kỳ tài liệu nào trong một bộ sưu tập nhất định, thì hãy sử dụng {wildcard}
thay cho ID tài liệu:
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ỳ trường nào trên bất kỳ tài liệu nào trong users
bị thay đổi, nó sẽ khớp với ký tự đại diện có tên userId
.
Nếu một tài liệu trong users
có các bộ sưu tập con và một trường trong một trong các tài liệu của các bộ sưu tập con đó bị thay đổi thì ký tự đại diện userId
sẽ không được kích hoạt.
Các kết quả khớp với ký tự đại diện được trích xuất từ đường dẫn tài liệu và được 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 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 hàm để kích hoạt bất kỳ lúc nào một tài liệu mới được tạo trong bộ sưu tập bằng cách sử dụng trình xử lý onCreate()
với ký tự đại diện . Hàm ví dụ này gọi createUser
mỗi khi hồ sơ người dùng 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 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 hàm để kích hoạt khi tài liệu được cập nhật bằng hàm onUpdate()
với ký tự đại diện . Hàm 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 chức năng khi tài liệu bị xóa
Bạn cũng có thể kích hoạt một hàm khi tài liệu bị xóa bằng hàm onDelete()
với ký tự đại diện . Hàm 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 chức năng cho tất cả các thay đổi đối với tài liệu
Nếu không quan tâm đến loại sự kiện được kích hoạt, bạn có thể lắng nghe tất cả các thay đổi trong tài liệu Cloud Firestore bằng cách sử dụng hàm onWrite()
với ký tự đại diện . Hàm ví dụ này gọi modifyUser
nếu người dùng được tạo, 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ó sẽ 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ừ mộ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()
, chứa ảnh chụp nhanh tài liệu trước khi cập nhật. Tương tự, change.after.data()
chứa trạng thái chụp nhanh 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ư cách 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 hàm get
để truy cập các trường 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 tài liệu đó dưới dạng DocumentReference
trong thuộc tính ref
của ảnh chụp nhanh được trả về hàm của bạn.
DocumentReference
này xuất phát từ SDK Cloud Firestore Node.js và bao gồm các phương thức như update()
, set()
và remove()
để bạn có thể dễ dàng sửa đổi tài liệu đã kích hoạt hàm.
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
Chức năng đám mây thực thi trong môi trường đáng tin cậy, có nghĩa là chúng được ủy quyền làm tài khoản dịch vụ trong dự án của bạn. Bạn có thể thực hiện đọc và ghi bằng SDK quản trị Firebase :
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:
- Việc đặt hàng không được đảm bảo. Những 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 cơ chế chính xác một lần và viết các hàm lũy thừa .
- Cloud Firestore ở chế độ Kho dữ liệu yêu cầu Chức năng đám mây (thế hệ 2). Chức năng đám mây (thế hệ 1) không hỗ trợ chế độ Kho dữ liệu.
- Chức năng đám mây (thế hệ 1) chỉ hoạt động với cơ sở dữ liệu "(mặc định)" và không hỗ trợ cơ sở dữ liệu có tên Cloud Firestore. Vui lòng sử dụng Chức năng đám mây (thế hệ 2) để định cấu hình sự kiện cho cơ sở dữ liệu được đặt tên.
- Một trình kích hoạt được liên kết với một cơ sở dữ liệu duy nhất. Bạn không thể tạo trình kích hoạt khớp với nhiều cơ sở dữ liệu.
- Việc xóa cơ sở dữ liệu sẽ không tự động xóa bất kỳ trình kích hoạt nào cho cơ sở dữ liệu đó. Trình kích hoạt ngừng phân phối sự kiện nhưng vẫn tiếp tục tồn tại cho đến khi bạn xóa trình kích hoạt .
- Nếu một sự kiện phù hợp vượt quá kích thước yêu cầu tối đa thì sự kiện đó có thể không được gửi tới Cloud Functions (thế hệ 1).
- Các sự kiện không được gửi do kích thước yêu cầu sẽ được ghi vào nhật ký nền tảng và được tính vào mức sử dụng nhật ký cho dự án.
- Bạn có thể tìm thấy các nhật ký này trong Logs Explorer với thông báo "Sự kiện không thể gửi tới chức năng Đám mây do kích thước vượt quá giới hạn cho thế hệ 1..." về mức độ nghiêm trọng của
error
. Bạn có thể tìm thấy tên hàm trong trường TênfunctionName
. Nếu trườngreceiveTimestamp
vẫn còn trong vòng một giờ kể từ bây giờ, bạn có thể suy ra nội dung sự kiện thực tế bằng cách đọc tài liệu được đề cập kèm theo ảnh chụp nhanh trước và sau dấu thời gian. - Để tránh nhịp độ như vậy, bạn có thể:
- Di chuyển và nâng cấp lên Cloud Functions (thế hệ 2)
- Giảm kích thước tài liệu
- Xóa các chức năng đám mây được đề cập
- Bạn có thể tắt tính năng ghi nhật ký bằng cách sử dụng loại trừ nhưng lưu ý rằng các sự kiện vi phạm sẽ vẫn không được gửi.