Cloud Firestore מפעיל

באמצעות פונקציות ענן, אתה יכול לטפל באירועים ב- Cloud Firestore ללא צורך לעדכן את קוד הלקוח. אתה יכול לעשות ענן Firestore שינויים באמצעות DocumentSnapshot הממשק או באמצעות SDK של הניהול .

במחזור חיים טיפוסי, פונקציית Cloud Firestore עושה את הפעולות הבאות:

  1. ממתין לשינויים במסמך מסוים.
  2. מפעיל כאשר מתרחש אירוע ומבצע המשימות שלה (ראה מה אני יכול לעשות עם פונקציות ענן? דוגמה של מקרי שימוש).
  3. מקבל אובייקט נתונים המכיל תמונת מצב של הנתונים המאוחסנים במסמך שצוין. עבור onWrite או onUpdate אירועים, אובייקט נתון מכיל שתי תמונות המייצגות את מדינת הנתונים לפני ואחרי האירוע המפעיל.

המרחק בין מיקום מופע Firestore למיקום הפונקציה יכול ליצור זמן אחזור משמעותי ברשת. לביצועי מטב, לשקול המפרטים את מיקום הפונקציה ישימה.

פונקצית Cloud Firestore מופעלת

תפקידי הענן עבור Firebase SDK מייצאים functions.firestore אובייקט המאפשר לך ליצור מטפלים קשור לאירועים ספציפיים הענן firestore.

סוג אירוע הדק
onCreate מופעל כאשר נכתב לראשונה למסמך.
onUpdate מופעל כאשר מסמך כבר קיים ושינוי ערך כלשהו.
onDelete מופעל כאשר מסמך עם נתונים נמחק.
onWrite מופעל כאשר onCreate , onUpdate או onDelete מופעל.

אם אין לך פרויקט מופעל עבור פונקציות ענן עבור Firebase עדיין, אז לקרוא תחילת תהליך: כתוב ולפרוס הפונקציות הראשונות שלך להגדיר להגדיר פונקציות הענן עבור פרויקט 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 ...
    });

מפעילים פונקציה לכל השינויים במסמך

אם לא אכפת לך על סוג של אירוע מפוטר, אתה יכול להקשיב לכל השינויים במסמך ענן 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 מגיע SDK ענן Firestore 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});
    });

נתונים מחוץ לאירוע הטריגר

פונקציות ענן מתבצעות בסביבה מהימנה, מה שאומר שהן מורשות כחשבון שירות בפרויקט שלך. ניתן לבצע קורא וכותב באמצעות SDK של ניהול Firebase :

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 עבור פונקציות ענן היא תכונת בטא עם מגבלות ידועות:

  • יכולות להימשך עד 10 שניות עד לפונקציה להגיב לשינויים בענן Firestore.
  • ההזמנה אינה מובטחת. שינויים מהירים יכולים לעורר קריאות לתפקוד בסדר לא צפוי.
  • אירועים מועברים לפחות פעם אחת, אך אירוע בודד עלול לגרום להזמנות פונקציות מרובות. הימנע תלוי בדיוק-פעם מכניקה, ולכתוב פונקציות idempotent .
  • ענן Firestore טריגרים עבור פונקציות ענן זמינים רק עבור הענן Firestore במצב Native . זה לא זמין עבור Cloud Firestore במצב Datastore.