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 theo các thay đổi trong cơ sở dữ liệu Cloud Firestore. Tính năng này cho phép bạn dễ dàng thêm phía máy chủ vào ứng dụng của bạn mà không cần chạy máy chủ của riêng bạn.
Để biết ví dụ về trường hợp sử dụng, hãy xem bài viết Tôi có thể làm gì với Cloud Functions? hoặc Kho lưu trữ Functions Samples trên GitHub.
Điều kiện kích hoạt hàm Cloud Firestore
SDK Cloud Functions for Firebase xuất một functions.firestore
cho phép bạn tạo các trình xử lý liên kết với các sự kiện Cloud Firestore cụ thể.
Loại sự kiện | Kích hoạt |
---|---|
onCreate |
Được kích hoạt khi người dùng viết tài liệu lần đầu tiên. |
onUpdate |
Được kích hoạt khi tài liệu đã tồn tại và có giá trị thay đổi. |
onDelete |
Được kích hoạt khi tài liệu có dữ liệu bị xoá. |
onWrite |
Được kích hoạt khi onCreate , onUpdate hoặc onDelete được kích hoạt. |
Nếu bạn chưa bật dự án nào cho Cloud Functions for Firebase, hãy đọc Bắt đầu: Viết và triển khai các hàm đầu tiên của bạn để định cấu hình và thiết lập dự án Cloud Functions for Firebase.
Viết các hàm được kích hoạt Cloud Firestore
Xác định điều kiện kích hoạt hàm
Để xác định một điều kiện 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 đến một tài liệu cụ thể hoặc mẫu ký tự đại diện.
Chỉ định một tài liệu
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 hàm 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 một điều kiện kích hoạt vào một nhóm tài liệu, chẳng hạn như tài liệu bất kỳ 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 tài liệu bất kỳ trong users
được thay đổi, trường đó khớp với
ký tự đại diện có tên là userId
.
Nếu một tài liệu trong users
có các tập hợp con và một trường thuộc một trong các tập hợp con đó
tài liệu được thay đổi thì ký tự đại diện userId
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à lưu trữ vào context.params
.
Bạn có thể xác định bao nhiêu ký tự đại diện tuỳ thích để thay thế tập hợp nội dung rõ ràng
hoặc mã nhận dạng tài liệu, 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 hàm khi tạo tài liệu mới
Bạn có thể kích hoạt một hàm để kích hoạt bất cứ khi nào một tài liệu mới được tạo trong một bộ sưu tập
bằng cách sử dụng trình xử lý onCreate()
có ký tự đại diện.
Hàm ví dụ này gọi createUser
mỗi khi một hồ sơ người dùng mới được thêm:
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 hàm khi cập nhật tài liệu
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 cách sử dụng
Hàm onUpdate()
có một 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 một hàm khi tài liệu bị xoá
Bạn cũng có thể kích hoạt một hàm khi tài liệu bị xoá bằng cách sử dụng
Hàm onDelete()
có một ký tự đại diện. Ví dụ này
hàm sẽ gọi deleteUser
khi người dùng xoá 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 hàm cho tất cả thay đổi đối với một tài liệu
Nếu bạn 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 hàm onWrite()
bằng một 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 bị xoá:
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 được kích hoạt, một hàm sẽ cung cấp thông tin tổng quan nhanh về 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ị của Firebase để truy cập vào các phần khác của cơ sở dữ liệu.
Dữ liệu sự kiện
Đọc dữ liệu
Khi một hàm đượ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 nhận 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
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 vào các thuộc tính như cách bạn thực hiện trong mọi đối tượng khác. Ngoài ra, bạn
có thể dùng hàm get
để truy cập vào 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');
Ghi 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. Bạn có thể truy cập vào 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 đến từ
SDK Node.js Cloud Firestore
đồng thời 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
Cloud Functions thực thi trong một môi trường đáng tin cậy, tức là chúng được cấp phép dưới dạng tài khoản dịch vụ trong dự án của bạn. Bạn có thể thực hiện thao tác đọc và ghi bằng cách sử dụng SDK quản trị của 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({ ... });
});
Các điểm hạn chế
Xin lưu ý các giới hạn sau đối với điều kiện kích hoạt Cloud Firestore cho Cloud Functions:
- Cloud Functions (thế hệ thứ 1) đòi hỏi điều kiện tiên quyết là "(mặc định)" hiện có cơ sở dữ liệu ở chế độ gốc Firestore. Cách này không hỗ trợ cơ sở dữ liệu có tên Cloud Firestore hoặc chế độ Kho dữ liệu. Vui lòng sử dụng Cloud Functions (thế hệ thứ 2) để định cấu hình các sự kiện trong những trường hợp như vậy.
- Chúng tôi không đảm bảo việc sắp xếp thứ tự. Những thay đổi nhanh chóng có thể kích hoạt lệnh gọi hàm trong một đơn đặt hàng 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 duy nhất có thể dẫn đến việc nhiều lệnh gọi hàm. Tránh phụ thuộc vào chính xác một lần và viết các hàm không thay đổi.
- Cloud Firestore ở chế độ Kho dữ liệu cần có Cloud Functions (thế hệ thứ 2). Cloud Functions (thế hệ thứ 1) không hỗ trợ chế độ Datastore.
- Mỗi điều kiện kích hoạt được liên kết với một cơ sở dữ liệu. Bạn không thể tạo một điều kiện kích hoạt khớp với nhiều cơ sở dữ liệu.
- Việc xoá một cơ sở dữ liệu sẽ không tự động xoá điều kiện kích hoạt nào trong cơ sở dữ liệu đó. Chiến lược phát hành đĩa đơn điều kiện kích hoạt sẽ 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 xoá điều kiện kích hoạt.
- Nếu một sự kiện được so khớ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 đến Cloud Functions (thế hệ 1).
- Các sự kiện không được gửi do quy mô yêu cầu đượ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 Trình khám phá nhật ký với thông báo "Sự kiện không thể phân phối đến
Hàm đám mây do kích thước vượt quá giới hạn của thế hệ 1..." /
error
mức độ nghiêm trọng. Bạn có thể tìm thấy tên hàm trong trườngfunctionName
. Nếu trườngreceiveTimestamp
vẫn còn trong vòng một giờ kể từ bây giờ, bạn có thể suy luận nội dung sự kiện thực tế bằng cách đọc tài liệu liên quan cùng với ảnh chụp nhanh trước và sau dấu thời gian. - Để tránh tần suất như vậy, bạn có thể:
- Di chuyển và nâng cấp lên Cloud Functions (thế hệ thứ 2)
- Giảm kích thước tài liệu
- Xoá Cloud Functions liên quan
- Bạn có thể tắt tính năng ghi nhật ký bằng tính năng loại trừ nhưng xin lưu ý rằng các sự kiện vi phạm sẽ vẫn không được gửi.