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

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

ดูตัวอย่าง Use Case ได้ที่หัวข้อฉันทำอะไรได้บ้างกับ Cloud Functions หรือที่เก็บ GitHub ของตัวอย่าง Functions

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