Cloud Functions ช่วยให้คุณจัดการเหตุการณ์ใน Cloud Firestore ได้โดยไม่ต้องอัปเดตโค้ดไคลเอ็นต์ คุณสามารถทำการเปลี่ยนแปลง Cloud Firestore ผ่านอินเทอร์เฟซ DocumentSnapshot
หรือผ่าน Admin SDK
ในวงจรชีวิตทั่วไป ฟังก์ชัน Cloud Firestore จะทำสิ่งต่อไปนี้:
- รอการเปลี่ยนแปลงในเอกสารเฉพาะ
- ทริกเกอร์เมื่อเหตุการณ์เกิดขึ้นและดำเนินงาน (ดู ฉันจะทำอะไรกับ Cloud Functions ได้บ้าง สำหรับตัวอย่างกรณีการใช้งาน)
- รับออบเจ็กต์ข้อมูลที่มีสแน็ปช็อตของข้อมูลที่จัดเก็บไว้ในเอกสารที่ระบุ สำหรับเหตุการณ์
onWrite
หรือonUpdate
ออบเจ็กต์ข้อมูลจะมีสแน็ปช็อตสองรายการที่แสดงสถานะข้อมูลก่อนและหลังเหตุการณ์ที่ทริกเกอร์
ระยะห่างระหว่างตำแหน่งของอินสแตนซ์ Firestore และตำแหน่งของฟังก์ชันสามารถสร้างเวลาแฝงของเครือข่ายที่สำคัญได้ ในการเพิ่มประสิทธิภาพการทำงาน ให้พิจารณาระบุ ตำแหน่งของฟังก์ชัน ตามความเหมาะสม
ทริกเกอร์ฟังก์ชัน Cloud Firestore
Cloud Functions for Firebase SDK ส่งออกอ็อบเจ็กต์ functions.firestore
ที่ให้คุณสร้างเครื่องจัดการที่เชื่อมโยงกับเหตุการณ์ Cloud Firestore ที่เฉพาะเจาะจงได้
ประเภทงาน | สิ่งกระตุ้น |
---|---|
onCreate | ทริกเกอร์เมื่อมีการเขียนเอกสารเป็นครั้งแรก |
onUpdate | ทริกเกอร์เมื่อมีเอกสารอยู่แล้วและมีการเปลี่ยนแปลงค่าใดๆ |
onDelete | ทริกเกอร์เมื่อเอกสารที่มีข้อมูลถูกลบ |
onWrite | ทริกเกอร์เมื่อมีการทริกเกอร์ onCreate , onUpdate หรือ onDelete |
หากคุณยังไม่ได้เปิดใช้โปรเจ็กต์สำหรับ Cloud Functions for Firebase ให้อ่าน Get Started: Write and Deploy Your First Functions เพื่อกำหนดค่าและตั้งค่า Cloud Functions สำหรับโปรเจ็กต์ 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}
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"} });
ในตัวอย่างนี้ เมื่อฟิลด์ใดๆ ในเอกสารใน users
มีการเปลี่ยนแปลง ฟิลด์นั้นจะตรงกับ wildcard ที่เรียกว่า userId
หากเอกสารใน users
มีคอลเล็กชันย่อย และฟิลด์ในเอกสารของคอลเลกชั่นย่อยรายการใดรายการหนึ่งมีการเปลี่ยนแปลง ไวด์การ์ด userId
จะ ไม่ ถูกทริกเกอร์
การจับคู่สัญลักษณ์แทนจะถูกแยกจากพาธเอกสารและจัดเก็บไว้ใน context.params
คุณสามารถกำหนดไวด์การ์ดได้มากเท่าที่คุณต้องการเพื่อแทนที่คอลเลกชั่นที่ชัดเจนหรือ ID เอกสาร ตัวอย่างเช่น:
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()
ด้วย wildcard ฟังก์ชันตัวอย่างนี้เรียก 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:
- ไม่รับประกันการสั่งซื้อ การเปลี่ยนแปลงอย่างรวดเร็วสามารถทริกเกอร์การเรียกใช้ฟังก์ชันในลำดับที่ไม่คาดคิดได้
- เหตุการณ์ถูกส่งอย่างน้อยหนึ่งครั้ง แต่เหตุการณ์เดียวอาจส่งผลให้มีการเรียกใช้ฟังก์ชันหลายรายการ หลีกเลี่ยงการขึ้นอยู่กับกลไกเพียงครั้งเดียว และเขียน ฟังก์ชัน idempotent
- ทริกเกอร์ Cloud Firestore สำหรับ Cloud Functions พร้อมใช้งานสำหรับ Cloud Firestore ในโหมด เนทิฟเท่านั้น ไม่พร้อมใช้งานสำหรับ Cloud Firestore ในโหมด Datastore