Catch up on everthing we announced at this year's Firebase Summit. Learn more

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 ...
    });

קריאה וכתיבה של נתונים

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

נתוני אירועים

קריאת נתונים

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

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