ขยาย Cloud Firestore ด้วย Cloud Functions

คุณสามารถใช้ Cloud Functions เพื่อทำให้โค้ด Node.js ใช้งานได้ในการจัดการกับเหตุการณ์ที่ทริกเกอร์ โดยการเปลี่ยนแปลงในฐานข้อมูล Cloud Firestore ซึ่งจะช่วยให้คุณเพิ่มฝั่งเซิร์ฟเวอร์ ฟังก์ชันที่มีอยู่ลงในแอปของคุณโดยไม่ต้องใช้เซิร์ฟเวอร์ของคุณเอง

ดูตัวอย่างกรณีการใช้งานได้ที่ฉันจะทำอะไรได้บ้างกับ Cloud Functions หรือ ฟังก์ชันตัวอย่างที่เก็บ GitHub

ทริกเกอร์ฟังก์ชัน Cloud Firestore รายการ

SDK Cloud Functions for Firebase จะส่งออก 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
    });
index.js

ระบุกลุ่มเอกสารโดยใช้ไวลด์การ์ด

ถ้าคุณต้องการแนบทริกเกอร์กับกลุ่มเอกสาร เช่น เอกสารใดๆ ใน คอลเล็กชันที่ต้องการ ให้ใช้ {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"}
    });
index.js

ในตัวอย่างนี้ เมื่อช่องใดก็ตามในเอกสารใน 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"}
    });
index.js

ตัวทริกเกอร์เหตุการณ์

เรียกใช้ฟังก์ชันเมื่อมีการสร้างเอกสารใหม่

คุณสามารถเรียกให้ฟังก์ชันเริ่มทำงานทุกครั้งที่มีการสร้างเอกสารใหม่ในคอลเล็กชัน โดยใช้เครื่องจัดการ 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 ...
    });
index.js

เรียกใช้ฟังก์ชันเมื่อมีการอัปเดตเอกสาร

นอกจากนี้ คุณยังสามารถทริกเกอร์ให้ฟังก์ชันเริ่มทำงานเมื่อมีการอัปเดตเอกสารโดยใช้ ฟังก์ชัน 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 ...
    });
index.js

เรียกใช้ฟังก์ชันเมื่อลบเอกสาร

นอกจากนี้คุณยังเรียกใช้ฟังก์ชันได้เมื่อลบเอกสารโดยใช้ ฟังก์ชัน 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 ...
    });
index.js

เรียกใช้ฟังก์ชันสำหรับการเปลี่ยนแปลงทั้งหมดในเอกสาร

หากไม่สนใจประเภทเหตุการณ์ที่เริ่มทำงาน ก็เลือกฟังทั้งหมดได้ การเปลี่ยนแปลงในเอกสาร 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 ...
    });
index.js

ข้อมูลการอ่านและการเขียน

เมื่อมีการทริกเกอร์ฟังก์ชัน ฟังก์ชันดังกล่าวจะแสดงภาพรวมของข้อมูลที่เกี่ยวข้องกับฟังก์ชัน กิจกรรม คุณสามารถใช้สแนปชอตนี้เพื่ออ่านหรือเขียนในเอกสารที่ ทริกเกอร์เหตุการณ์ หรือใช้ 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();
    });
index.js

คุณจะเข้าถึงพร็อพเพอร์ตี้ได้เช่นเดียวกับในออบเจ็กต์อื่นๆ หรือคุณอาจเลือก ใช้ฟังก์ชัน 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');
index.js

ข้อมูลการเขียน

การเรียกใช้ฟังก์ชันแต่ละรายการจะเชื่อมโยงกับเอกสารเฉพาะในเอกสาร ฐานข้อมูล Cloud Firestore คุณสามารถเข้าถึงเอกสารนั้นเป็น DocumentReference ในพร็อพเพอร์ตี้ ref ของสแนปชอตกลับไปที่ฟังก์ชัน

DocumentReference นี้มาจาก Cloud Firestore SDK ของ Node.js และรวมเมธอด เช่น 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});
    });
index.js

ข้อมูลที่อยู่นอกเหตุการณ์ทริกเกอร์

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 แต่ไม่ รองรับฐานข้อมูลที่มีชื่อหรือโหมด Datastore Cloud Firestore โปรดใช้ Cloud Functions (รุ่นที่ 2) เพื่อกำหนดค่าเหตุการณ์ในกรณีเช่นนี้
  • เราไม่รับประกันว่าจะสั่งซื้อ การเปลี่ยนแปลงอย่างรวดเร็วจะเรียกใช้การเรียกใช้ฟังก์ชันได้ใน คำสั่งซื้อที่ไม่คาดคิด
  • มีการส่งเหตุการณ์อย่างน้อย 1 ครั้ง แต่เหตุการณ์เดียวอาจทําให้ การเรียกใช้ฟังก์ชันหลายรายการ หลีกเลี่ยง ครั้งเดียวเท่านั้น และเขียน ฟังก์ชันนิรนาม
  • Cloud Firestore ในโหมด Datastore ต้องใช้ Cloud Functions (รุ่นที่ 2) Cloud Functions (รุ่นที่ 1) ไม่เท่ากับ รองรับโหมด Datastore
  • ทริกเกอร์เชื่อมโยงกับฐานข้อมูลเดียว คุณสร้างทริกเกอร์ที่ตรงกับหลายฐานข้อมูลไม่ได้
  • การลบฐานข้อมูลจะไม่ลบทริกเกอร์สำหรับฐานข้อมูลนั้นโดยอัตโนมัติ ทริกเกอร์จะหยุดส่งเหตุการณ์แต่จะยังคงมีอยู่จนกว่าคุณจะลบทริกเกอร์
  • หากเหตุการณ์ที่ตรงกันเกินขนาดคำขอสูงสุด ระบบจะดำเนินการ เหตุการณ์อาจไม่ได้ส่งไปยัง Cloud Functions (รุ่นที่ 1)
    • ระบบไม่ได้ส่งเหตุการณ์เนื่องจากขนาดคำขอไว้ในบันทึกแพลตฟอร์ม และนับรวมกับการใช้งานบันทึกสำหรับโปรเจ็กต์
    • คุณสามารถค้นหาบันทึกเหล่านี้ได้ในเครื่องมือสำรวจบันทึกที่มีข้อความ "ส่งเหตุการณ์ไปยังไม่ได้" Cloud Function เนื่องจากขนาดเกินขีดจำกัดสำหรับรุ่นที่ 1..." จาก error ความรุนแรง ชื่อฟังก์ชันจะอยู่ในช่อง functionName ถ้า ฟิลด์ receiveTimestamp ยังคงอยู่ภายใน 1 ชั่วโมงจากนี้ คุณสามารถอนุมาน เนื้อหาเหตุการณ์จริงโดยการอ่านเอกสารที่เป็นปัญหา ก่อนและหลังการประทับเวลา
    • หากต้องการหลีกเลี่ยงความถี่ดังกล่าว โปรดทำดังนี้
      • ย้ายข้อมูลและอัปเกรดเป็น Cloud Functions (รุ่นที่ 2)
      • ลดขนาดเอกสาร
      • ลบ Cloud Functions ที่เป็นปัญหา
    • คุณปิดการบันทึกได้โดยใช้การยกเว้น แต่โปรดทราบว่าระบบจะยังไม่นำส่งกิจกรรมที่ไม่เหมาะสม