טריגרים של Cloud Firestore

דור שני דור ראשון

עם Cloud Functions אפשר לטפל באירועים בתוך Cloud Firestore ללא צורך לעדכן את קוד הלקוח. אפשר לבצע שינויים ב-Cloud Firestore דרך הממשק של קובץ snapshot של מסמך או דרך Admin SDK.

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

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

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

טריגרים של פונקציית Cloud Firestore

ערכת ה-SDK Cloud Functions for Firebase מייצאת functions.firestore שמאפשר ליצור handlers שקשורים לאירועים ספציפיים ב-Cloud Firestore.

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

הערה: אירועים של Cloud Firestore יופעלו רק בכל שינוי במסמך. עדכון של מסמך ב-Cloud Firestore, שבו הנתונים לא השתנו (כתיבה ללא פעולה), לא יגרום ליצירת אירוע עדכון או כתיבה. זה כן אין אפשרות להוסיף אירועים לשדות ספציפיים.

אם עדיין לא הפעלת פרויקט עבור 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

הערה: הטריגר חייב תמיד להפנות למסמך, גם אם משתמשים בתו כללי לחיפוש. לדוגמה, הערך users/{userId}/{messageCollectionId} אינו חוקי כי {messageCollectionId} הוא אוסף. עם זאת, הערך users/{userId}/{messageCollectionId}/{messageId} תקף כי הערך {messageId} תמיד יצביע על מסמך.

טריגרים של אירועים

הפעלת פונקציה כשיוצרים מסמך חדש

אפשר להפעיל פונקציה שתופעל בכל פעם שייווצר מסמך חדש באוסף באמצעות טיפולן 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(), שמכיל את קובץ snapshot של המסמך לפני העדכון. באופן דומה, המשתנה 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 של קובץ ה-snapshot שמוחזר לפונקציה.

הערך של 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});
    });
index.js

הערה: בכל פעם שכותבים לאותו מסמך שהפעיל פונקציה, אתם עלולות ליצור לולאה אינסופית. חשוב לנהוג בזהירות ולוודא לצאת מהפונקציה כשלא נדרש שינוי.

נתונים שלא נכללים באירוע של הטריגר

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

מגבלות

חשוב לשים לב למגבלות הבאות לגבי טריגרים של Cloud Firestore ל-Cloud Functions:

• Cloud Functions (דור ראשון) נדרשת כדי לעמוד בדרישות מוקדמות של '(ברירת מחדל)' מסד נתונים במצב נייטיב של Firestore. הוא לא תומכים במסדי נתונים בעלי שם של Cloud Firestore או במצב Datastore. יש להשתמש ב-Cloud Functions (דור שני) להגדרת אירועים במקרים כאלה.
• ההזמנה לא מובטחת. שינויים מהירים יכולים להפעיל הפעלות של פונקציות הזמנה בלתי צפויה.
• אירועים מועברים לפחות פעם אחת, אבל אירוע אחד עלול לגרום כמה הפעלות של פונקציות. הימנעו מהסתמכות על מנגנונים של 'פעם אחת בלבד', וכתבו פונקציות חד-ערכיות (idempotent).
• Cloud Firestore במצב Datastore נדרש Cloud Functions (דור שני). ב-Cloud Functions (דור ראשון) אין תמיכה במצב Datastore.
• טריגר משויך למסד נתונים אחד. אי אפשר ליצור טריגר שתואם לכמה מסדי נתונים.
• מחיקת מסד נתונים לא מובילה למחיקה אוטומטית של טריגרים של אותו מסד נתונים. הטריגר יפסיק לשלוח אירועים, אבל הוא ימשיך להתקיים עד שתמחקו אותו.
• אם אירוע שנמצאה בו התאמה חורג מגודל הבקשה המקסימלי, המאפיין יכול להיות שהאירוע לא יישלח אל Cloud Functions (דור ראשון).
  • אירועים שלא נשלחו בגלל גודל הבקשה מתועדים ביומני הפלטפורמה ומספרם נספר בשימוש ביומן של הפרויקט.
  • היומנים האלה מופיעים ב-Logs Explorer עם ההודעה 'האירוע לא יכול למסור אל הפונקציה של Cloud Functions בגלל הגודל חורג מהמגבלה שחלה על דור ראשון..." מתוך error חוּמרה. שם הפונקציה מופיע בשדה functionName. אם השדה receiveTimestamp עדיין מתייחס לשעה הקרובה, תוכלו להסיק את תוכן האירוע בפועל על ידי קריאת המסמך הרלוונטי באמצעות קובץ snapshot לפני ואחרי חותמת הזמן.
  • כדי להימנע מקצב כזה, אפשר:
    • העברה ושדרוג ל-Cloud Functions (דור שני)
    • הקטנת המסמך
    • מוחקים את ה-Cloud Functions הרלוונטי
  • אפשר להשבית את הרישום ביומן באמצעות החרגות, אבל חשוב לזכור שהאירועים הבעייתיים עדיין לא יישלחו.