คุณทำให้โค้ด Node.js ใช้งานได้เพื่อจัดการเหตุการณ์ที่ทริกเกอร์จากการเปลี่ยนแปลงในฐานข้อมูล Cloud Firestore ด้วย Cloud Functions ซึ่งช่วยให้คุณเพิ่มฟังก์ชันฝั่งเซิร์ฟเวอร์ลงในแอปได้อย่างง่ายดายโดยไม่ต้องใช้เซิร์ฟเวอร์ของคุณเอง
ดูตัวอย่างกรณีการใช้งานได้ที่ฉันทำอะไรกับ Cloud 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 });
ระบุกลุ่มเอกสารโดยใช้ไวลด์การ์ด
หากคุณต้องการแนบทริกเกอร์กับกลุ่มเอกสาร เช่น เอกสารในคอลเล็กชันหนึ่ง ให้ใช้ {wildcard}
แทนรหัสเอกสาร ดังนี้
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"} });
ในตัวอย่างนี้ เมื่อมีการเปลี่ยนแปลงช่องในเอกสารใน users
ช่องนั้นจะตรงกับไวลด์การ์ดที่เรียกว่า userId
หากเอกสารใน users
มีคอลเล็กชันย่อย และช่องในเอกสารของคอลเล็กชันย่อยดังกล่าวมีการเปลี่ยนแปลง ระบบจะไม่ทริกเกอร์ไวลด์การ์ด userId
การจับคู่ไวลด์การ์ดจะแยกออกจากเส้นทางของเอกสารและจัดเก็บไว้ใน context.params
คุณอาจกำหนดไวลด์การ์ดได้มากเท่าที่ต้องการเพื่อแทนที่รหัสคอลเล็กชันหรือรหัสเอกสารที่อาจไม่เหมาะสม เช่น
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"} });
ตัวทริกเกอร์เหตุการณ์
เรียกใช้ฟังก์ชันเมื่อมีการสร้างเอกสารใหม่
คุณทริกเกอร์ให้ฟังก์ชันเริ่มทำงานทุกครั้งที่มีการสร้างเอกสารใหม่ในคอลเล็กชันได้โดยใช้เครื่องจัดการ 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 ... });
เรียกใช้ฟังก์ชันเมื่อมีการอัปเดตเอกสาร
คุณยังทริกเกอร์ให้ฟังก์ชันเริ่มทำงานเมื่อมีการอัปเดตเอกสารโดยใช้ฟังก์ชัน 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 ... });
เรียกใช้ฟังก์ชันเมื่อลบเอกสาร
คุณยังทริกเกอร์ฟังก์ชันเมื่อลบเอกสารโดยใช้ฟังก์ชัน 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 ... });
เรียกใช้ฟังก์ชันสำหรับการเปลี่ยนแปลงทั้งหมดในเอกสาร
หากไม่สนใจประเภทเหตุการณ์ที่เริ่มทำงาน คุณฟังการเปลี่ยนแปลงทั้งหมดในเอกสาร Cloud Firestore ได้โดยใช้ฟังก์ชัน onWrite()
ที่มีไวลด์การ์ด ฟังก์ชันตัวอย่างนี้เรียกใช้ 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 ... });
ข้อมูลการอ่านและการเขียน
เมื่อมีการทริกเกอร์ฟังก์ชัน ฟังก์ชันจะแสดงภาพรวมของข้อมูลที่เกี่ยวข้องกับเหตุการณ์ดังกล่าว คุณสามารถใช้สแนปชอตนี้เพื่ออ่านหรือเขียนในเอกสารที่ทริกเกอร์เหตุการณ์ หรือใช้ 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(); });
คุณจะเข้าถึงพร็อพเพอร์ตี้ได้เช่นเดียวกับในออบเจ็กต์อื่นๆ หรือจะใช้ฟังก์ชัน 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');
ข้อมูลการเขียน
การเรียกใช้ฟังก์ชันแต่ละรายการจะเชื่อมโยงกับเอกสารที่เฉพาะเจาะจงในฐานข้อมูล Cloud Firestore คุณเข้าถึงเอกสารนั้นเป็น DocumentReference
ในพร็อพเพอร์ตี้ ref
ของสแนปชอตที่ส่งไปยังฟังก์ชันของคุณได้
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}); });
ข้อมูลที่อยู่นอกเหตุการณ์ทริกเกอร์
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 Firestore สำหรับ Cloud Functions
- Cloud Functions (รุ่นที่ 1) ต้องมีฐานข้อมูล "(ค่าเริ่มต้น)" ที่มีอยู่ในโหมดดั้งเดิมของ Firestore และไม่รองรับฐานข้อมูลที่มีชื่อใน Cloud Firestore หรือโหมด Datastore โปรดใช้ Cloud Functions (รุ่นที่ 2) เพื่อกำหนดค่าเหตุการณ์ในกรณีเช่นนี้
- เราไม่รับประกันว่าจะสั่งซื้อ การเปลี่ยนแปลงอย่างรวดเร็วอาจเรียกฟังก์ชันในลำดับที่ไม่คาดคิดได้
- ระบบนำส่งเหตุการณ์อย่างน้อย 1 ครั้ง แต่เหตุการณ์เดียวอาจทำให้เกิดการเรียกใช้ฟังก์ชันหลายรายการ หลีกเลี่ยงการขึ้นอยู่กับกลไกการทำงานเพียงครั้งเดียวและเขียนฟังก์ชันอิมโพรเทนต์
- Cloud Firestore ในโหมด Datastore ต้องใช้ Cloud Functions (รุ่นที่ 2) Cloud Functions (รุ่นที่ 1) ไม่รองรับโหมด Datastore
- ทริกเกอร์เชื่อมโยงกับฐานข้อมูลเดียว คุณสร้างทริกเกอร์ที่ตรงกับหลายฐานข้อมูลไม่ได้
- การลบฐานข้อมูลจะไม่ลบทริกเกอร์สำหรับฐานข้อมูลนั้นโดยอัตโนมัติ ทริกเกอร์จะหยุดส่งเหตุการณ์แต่จะยังคงมีอยู่จนกว่าคุณจะลบทริกเกอร์
- หากเหตุการณ์ที่ตรงกันเกินขนาดคำขอสูงสุด ระบบอาจส่งเหตุการณ์ไปยัง Cloud Functions (รุ่นที่ 1) ไม่ได้
- ระบบไม่ได้ส่งเหตุการณ์เนื่องจากขนาดคำขอลงในบันทึกแพลตฟอร์ม และนับรวมกับการใช้งานบันทึกสำหรับโปรเจ็กต์
- คุณดูบันทึกเหล่านี้ได้ในเครื่องมือสำรวจบันทึกที่มีข้อความ "ส่งเหตุการณ์ไปยังฟังก์ชัน Cloud ไม่ได้เนื่องจากขนาดเกินขีดจำกัดสำหรับรุ่นที่ 1..." ของความรุนแรง
error
ชื่อฟังก์ชันจะอยู่ในช่องfunctionName
หากช่องreceiveTimestamp
ยังอยู่ในช่วงเวลา 1 ชั่วโมงนับจากนี้ คุณจะอนุมานเนื้อหาเหตุการณ์จริงได้โดยอ่านเอกสารที่เป็นปัญหาที่มีสแนปชอตก่อนและหลังการประทับเวลา - หากต้องการหลีกเลี่ยงความถี่ดังกล่าว โปรดทำดังนี้
- ย้ายข้อมูลและอัปเกรดเป็น Cloud Functions (รุ่นที่ 2)
- ลดขนาดเอกสาร
- ลบ Cloud Functions ที่มีปัญหา
- คุณสามารถปิดการบันทึกนั้นเองโดยใช้การยกเว้น แต่โปรดทราบว่าระบบจะไม่ส่งเหตุการณ์ที่ไม่เหมาะสม