ด้วย Cloud Functions คุณจะปรับใช้โค้ด Node.js เพื่อจัดการเหตุการณ์ที่เกิดจากการเปลี่ยนแปลงในฐานข้อมูล Cloud Firestore ของคุณได้ ซึ่งช่วยให้คุณสามารถเพิ่มฟังก์ชันฝั่งเซิร์ฟเวอร์ลงในแอปของคุณได้อย่างง่ายดายโดยไม่ต้องใช้เซิร์ฟเวอร์ของคุณเอง
สำหรับตัวอย่างกรณีการใช้งาน โปรดดู ฉันสามารถทำอะไรกับฟังก์ชันคลาวด์ได้บ้าง หรือพื้นที่เก็บข้อมูล GitHub ตัวอย่างฟังก์ชัน
ทริกเกอร์ฟังก์ชัน Cloud Firestore
Cloud Functions for Firebase SDK ส่งออกออบเจ็กต์ functions.firestore
ที่ช่วยให้คุณสร้างเครื่องจัดการที่เชื่อมโยงกับเหตุการณ์ Cloud Firestore ที่เฉพาะเจาะจงได้
ประเภทเหตุการณ์ | สิ่งกระตุ้น |
---|---|
onCreate | ทริกเกอร์เมื่อมีการเขียนเอกสารเป็นครั้งแรก |
onUpdate | ทริกเกอร์เมื่อมีเอกสารอยู่แล้วและมีการเปลี่ยนแปลงค่าใดๆ |
onDelete | ทริกเกอร์เมื่อมีการลบเอกสารที่มีข้อมูล |
onWrite | ทริกเกอร์เมื่อมีการทริกเกอร์ onCreate , onUpdate หรือ onDelete |
หากคุณยังไม่ได้เปิดใช้งานโปรเจ็กต์สำหรับฟังก์ชันคลาวด์สำหรับ Firebase โปรดอ่าน เริ่มต้น: เขียนและปรับใช้ฟังก์ชันแรกของคุณ เพื่อกำหนดค่าและตั้งค่าโปรเจ็กต์ฟังก์ชันคลาวด์สำหรับ Firebase
กำลังเขียนฟังก์ชันที่เรียกใช้ Cloud Firestore
กำหนดทริกเกอร์ฟังก์ชัน
หากต้องการกำหนดทริกเกอร์ Cloud Firestore ให้ระบุเส้นทางเอกสารและประเภทเหตุการณ์:
โหนด js
const functions = require('firebase-functions');
exports.myFunction = functions.firestore
.document('my-collection/{docId}')
.onWrite((change, context) => { /* ... */ });
เส้นทางเอกสารสามารถอ้างอิงถึง เอกสารเฉพาะ หรือ รูปแบบไวด์การ์ด
ระบุเอกสารเดียว
หากคุณต้องการทริกเกอร์เหตุการณ์สำหรับการเปลี่ยนแปลง ใดๆ ในเอกสารใดเอกสารหนึ่ง คุณสามารถใช้ฟังก์ชันต่อไปนี้ได้
โหนด 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}
แทนรหัสเอกสาร:
โหนด 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
คุณสามารถกำหนดไวด์การ์ดได้มากเท่าที่คุณต้องการเพื่อทดแทนคอลเลกชันหรือรหัสเอกสารที่ชัดเจน เช่น:
โหนด 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
ทุกครั้งที่มีการเพิ่มโปรไฟล์ผู้ใช้ใหม่:
โหนด 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
หากผู้ใช้เปลี่ยนโปรไฟล์ของตน:
โหนด 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
เมื่อผู้ใช้ลบโปรไฟล์ผู้ใช้ของตน:
โหนด 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
หากผู้ใช้ถูกสร้าง อัปเดต หรือลบ:
โหนด 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()
มีสถานะสแน็ปช็อตเอกสารหลังจากการอัพเดต
โหนด 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
เพื่อเข้าถึงฟิลด์เฉพาะได้:
โหนด 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()
เพื่อให้คุณสามารถแก้ไขเอกสารที่เรียกใช้ฟังก์ชันนี้ได้อย่างง่ายดาย
โหนด 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}); });
ข้อมูลนอกเหตุการณ์ทริกเกอร์
ฟังก์ชันคลาวด์ดำเนินการในสภาพแวดล้อมที่เชื่อถือได้ ซึ่งหมายความว่าฟังก์ชันดังกล่าวได้รับอนุญาตเป็นบัญชีบริการในโปรเจ็กต์ของคุณ คุณสามารถอ่านและเขียนได้โดยใช้ Firebase Admin SDK :
โหนด 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 สำหรับฟังก์ชันคลาวด์:
- ไม่รับประกันการสั่งซื้อ การเปลี่ยนแปลงอย่างรวดเร็วสามารถทริกเกอร์การเรียกใช้ฟังก์ชันในลำดับที่ไม่คาดคิดได้
- มีการจัดกิจกรรมอย่างน้อยหนึ่งครั้ง แต่เหตุการณ์เดียวอาจส่งผลให้เกิดการเรียกใช้ฟังก์ชันหลายรายการ หลีกเลี่ยงการขึ้นอยู่กับกลไกเพียงครั้งเดียว และเขียน ฟังก์ชัน idempotent
- Cloud Firestore ในโหมด Datastore ต้องใช้ฟังก์ชันคลาวด์ (รุ่นที่ 2) ฟังก์ชันคลาวด์ (รุ่นที่ 1) ไม่รองรับโหมด Datastore
- Cloud Functions (รุ่นที่ 1) ใช้งานได้กับฐานข้อมูล "(ค่าเริ่มต้น)" เท่านั้น และไม่รองรับฐานข้อมูลที่มีชื่อ Cloud Firestore โปรดใช้ฟังก์ชันคลาวด์ (รุ่นที่ 2) เพื่อกำหนดค่าเหตุการณ์สำหรับฐานข้อมูลที่มีชื่อ
- ทริกเกอร์เชื่อมโยงกับฐานข้อมูลเดียว คุณไม่สามารถสร้างทริกเกอร์ที่ตรงกับหลายฐานข้อมูลได้
- การลบฐานข้อมูลจะไม่ลบทริกเกอร์ใดๆ สำหรับฐานข้อมูลนั้นโดยอัตโนมัติ ทริกเกอร์หยุดส่งเหตุการณ์แต่จะยังคงอยู่จนกว่าคุณ จะลบทริกเกอร์
- หากเหตุการณ์ที่ตรงกันเกิน ขนาดคำขอสูงสุด กิจกรรมอาจไม่ถูกส่งไปยัง Cloud Functions (รุ่นที่ 1)
- กิจกรรมที่ไม่ได้จัดส่งเนื่องจากขนาดคำขอจะถูกบันทึกไว้ใน บันทึกของแพลตฟอร์ม และนับรวมในการใช้งานบันทึกสำหรับโปรเจ็กต์
- คุณสามารถค้นหาบันทึกเหล่านี้ได้ใน Logs Explorer โดยมีข้อความ "ไม่สามารถส่งเหตุการณ์ไปยังฟังก์ชัน Cloud ได้เนื่องจากขนาดเกินขีดจำกัดสำหรับรุ่นที่ 1..." ของระดับ
error
คุณสามารถค้นหาชื่อฟังก์ชันได้ใต้ช่องfunctionName
หากฟิลด์receiveTimestamp
ยังคงอยู่ภายในหนึ่งชั่วโมงนับจากนี้ คุณสามารถอนุมานเนื้อหาเหตุการณ์จริงได้โดยการอ่านเอกสารที่เป็นปัญหาพร้อมสแน็ปช็อตก่อนและหลังการประทับเวลา - เพื่อหลีกเลี่ยงจังหวะดังกล่าว คุณสามารถ:
- ย้ายและอัปเกรดเป็น Cloud Functions (รุ่นที่ 2)
- ลดขนาดเอกสาร
- ลบฟังก์ชันคลาวด์ที่ต้องการ
- คุณสามารถปิดการบันทึกได้โดยใช้ การยกเว้น แต่โปรดทราบว่าเหตุการณ์ที่ละเมิดจะยังไม่ถูกส่งออกไป