הרחבת Cloud Firestore באמצעות Cloud Functions (דור שני)

בעזרת Cloud Functions, אפשר לפרוס קוד לטיפול באירועים שמופעלים על ידי שינויים במסד הנתונים של Cloud Firestore. כך תוכלו להוסיף בקלות פונקציונליות בצד השרת לאפליקציה שלכם בלי להפעיל שרתים משלכם.

Cloud Functions (דור שני)

Cloud Functions for Firebase (דור שני) מבוסס על Cloud Run ועל Eventarc, ומספק תשתית חזקה יותר, שליטה מתקדמת בביצועים ובמדרגיות ושליטה רבה יותר בזמן הריצה של הפונקציות. מידע נוסף על דור שני זמין במאמר בנושא Cloud Functions for Firebase (דור שני). מידע נוסף על דור ראשון זמין במאמר הרחבת Cloud Firestore באמצעות Cloud Functions.

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

ערכת ה-SDK של Cloud Functions for Firebase מייצאת את טריגרים האירועים הבאים של Cloud Firestore כדי לאפשר לכם ליצור פונקציות לטיפול באירועים שקשורות לאירועים ספציפיים:Cloud Firestore

Node.js

סוג האירוע הפעלה
onDocumentCreated מופעל כשמסמך נכתב בפעם הראשונה.
onDocumentUpdated מופעל כשהמסמך כבר קיים וערך כלשהו בו השתנה.
onDocumentDeleted מופעל כשמסמך נמחק.
onDocumentWritten מופעל כשמופעלים onDocumentCreated, onDocumentUpdated או onDocumentDeleted.
onDocumentCreatedWithAuthContext onDocumentCreated עם פרטי אימות נוספים
onDocumentWrittenWithAuthContext onDocumentWritten עם פרטי אימות נוספים
onDocumentDeletedWithAuthContext onDocumentDeleted עם פרטי אימות נוספים
onDocumentUpdatedWithAuthContext onDocumentUpdated עם פרטי אימות נוספים

Python

סוג האירוע הפעלה
on_document_created מופעל כשמסמך נכתב בפעם הראשונה.
on_document_updated מופעל כשהמסמך כבר קיים וערך כלשהו בו השתנה.
on_document_deleted מופעל כשמסמך נמחק.
on_document_written מופעל כשמופעלים on_document_created, on_document_updated או on_document_deleted.
on_document_created_with_auth_context on_document_created עם פרטי אימות נוספים
on_document_updated_with_auth_context on_document_updated עם פרטי אימות נוספים
on_document_deleted_with_auth_context on_document_deleted עם פרטי אימות נוספים
on_document_written_with_auth_context on_document_written עם פרטי אימות נוספים

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

אם עדיין לא הפעלתם פרויקט ל-Cloud Functions for Firebase, כדאי לקרוא את המאמר תחילת העבודה עם Cloud Functions for Firebase (דור שני) כדי להגדיר את הפרויקט שלכם ב-Cloud Functions for Firebase.

כתיבת פונקציות שמופעלות על ידי Cloud Firestore

הגדרת טריגר של פונקציה

כדי להגדיר Cloud Firestoreטריגר, מציינים נתיב מסמך וסוג אירוע:

Node.js

import {
  onDocumentWritten,
  onDocumentCreated,
  onDocumentUpdated,
  onDocumentDeleted,
  Change,
  FirestoreEvent
} from "firebase-functions/v2/firestore";

exports.myfunction = onDocumentWritten("my-collection/{docId}", (event) => {
   /* ... */ 
});

Python

from firebase_functions.firestore_fn import (
  on_document_created,
  on_document_deleted,
  on_document_updated,
  on_document_written,
  Event,
  Change,
  DocumentSnapshot,
)

@on_document_created(document="users/{userId}")
def myfunction(event: Event[DocumentSnapshot]) -> None:

נתיבי מסמכים יכולים להפנות למסמך ספציפי או לתבנית של תווים כלליים.

ציון מסמך יחיד

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

Node.js

import {
  onDocumentWritten,
  Change,
  FirestoreEvent
} from "firebase-functions/v2/firestore";

exports.myfunction = onDocumentWritten("users/marie", (event) => {
  // Your code here
});

Python

from firebase_functions.firestore_fn import (
  on_document_written,
  Event,
  Change,
  DocumentSnapshot,
)

@on_document_written(document="users/marie")
def myfunction(event: Event[Change[DocumentSnapshot]]) -> None:

הגדרת קבוצת מסמכים באמצעות תווים כלליים לחיפוש

אם רוצים לצרף טריגר לקבוצת מסמכים, כמו כל מסמך באוסף מסוים, צריך להשתמש ב-{wildcard} במקום במזהה המסמך:

Node.js

import {
  onDocumentWritten,
  Change,
  FirestoreEvent
} from "firebase-functions/v2/firestore";

exports.myfunction = onDocumentWritten("users/{userId}", (event) => {
  // If we set `/users/marie` to {name: "Marie"} then
  // event.params.userId == "marie"
  // ... and ...
  // event.data.after.data() == {name: "Marie"}
});

Python

from firebase_functions.firestore_fn import (
  on_document_written,
  Event,
  Change,
  DocumentSnapshot,
)

@on_document_written(document="users/{userId}")
def myfunction(event: Event[Change[DocumentSnapshot]]) -> None:
  # If we set `/users/marie` to {name: "Marie"} then
  event.params["userId"] == "marie"  # True
  # ... and ...
  event.data.after.to_dict() == {"name": "Marie"}  # True

בדוגמה הזו, כשמשנים שדה כלשהו במסמך כלשהו ב-users, הוא תואם לתו כל כללי שנקרא userId.

אם במסמך ב-users יש אוספי משנה, ושדה באחד מהמסמכים של אוספי המשנה האלה משתנה, התו הכללי userId לא מופעל.

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

Node.js

import {
  onDocumentWritten,
  Change,
  FirestoreEvent
} from "firebase-functions/v2/firestore";

exports.myfunction = onDocumentWritten("users/{userId}/{messageCollectionId}/{messageId}", (event) => {
    // If we set `/users/marie/incoming_messages/134` to {body: "Hello"} then
    // event.params.userId == "marie";
    // event.params.messageCollectionId == "incoming_messages";
    // event.params.messageId == "134";
    // ... and ...
    // event.data.after.data() == {body: "Hello"}
});

Python

from firebase_functions.firestore_fn import (
  on_document_written,
  Event,
  Change,
  DocumentSnapshot,
)

@on_document_written(document="users/{userId}/{messageCollectionId}/{messageId}")
def myfunction(event: Event[Change[DocumentSnapshot]]) -> None:
  # If we set `/users/marie/incoming_messages/134` to {body: "Hello"} then
  event.params["userId"] == "marie"  # True
  event.params["messageCollectionId"] == "incoming_messages"  # True
  event.params["messageId"] == "134"  # True
  # ... and ...
  event.data.after.to_dict() == {"body": "Hello"}

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

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

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

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

Node.js

import {
  onDocumentCreated,
  Change,
  FirestoreEvent
} from "firebase-functions/v2/firestore";

exports.createuser = onDocumentCreated("users/{userId}", (event) => {
    // Get an object representing the document
    // e.g. {'name': 'Marie', 'age': 66}
    const snapshot = event.data;
    if (!snapshot) {
        console.log("No data associated with the event");
        return;
    }
    const data = snapshot.data();

    // access a particular field as you would any JS property
    const name = data.name;

    // perform more operations ...
});

למידע נוסף על אימות, אפשר להשתמש ב-onDocumentCreatedWithAuthContext.

Python

from firebase_functions.firestore_fn import (
  on_document_created,
  Event,
  DocumentSnapshot,
)

@on_document_created(document="users/{userId}")
def myfunction(event: Event[DocumentSnapshot]) -> None:
  # Get a dictionary representing the document
  # e.g. {'name': 'Marie', 'age': 66}
  new_value = event.data.to_dict()

  # Access a particular field as you would any dictionary
  name = new_value["name"]

  # Perform more operations ...

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

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

Node.js

import {
  onDocumentUpdated,
  Change,
  FirestoreEvent
} from "firebase-functions/v2/firestore";

exports.updateuser = onDocumentUpdated("users/{userId}", (event) => {
    // Get an object representing the document
    // e.g. {'name': 'Marie', 'age': 66}
    const newValue = event.data.after.data();

    // access a particular field as you would any JS property
    const name = newValue.name;

    // perform more operations ...
});

למידע נוסף על אימות, אפשר להשתמש ב-onDocumentUpdatedWithAuthContext.

Python

from firebase_functions.firestore_fn import (
  on_document_updated,
  Event,
  Change,
  DocumentSnapshot,
)

@on_document_updated(document="users/{userId}")
def myfunction(event: Event[Change[DocumentSnapshot]]) -> None:
  # Get a dictionary representing the document
  # e.g. {'name': 'Marie', 'age': 66}
  new_value = event.data.after.to_dict()

  # Access a particular field as you would any dictionary
  name = new_value["name"]

  # Perform more operations ...

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

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

Node.js

import {
  onDocumentDeleted,
  Change,
  FirestoreEvent
} from "firebase-functions/v2/firestore";

exports.deleteuser = onDocumentDeleted("users/{userId}", (event) => {
    // Get an object representing the document
    // e.g. {'name': 'Marie', 'age': 66}
    const snap =  event.data;
    const data =  snap.data();

    // perform more operations ...
});

למידע נוסף על אימות, אפשר להשתמש ב-onDocumentDeletedWithAuthContext.

Python

from firebase_functions.firestore_fn import (
  on_document_deleted,
  Event,
  DocumentSnapshot,
)

@on_document_deleted(document="users/{userId}")
def myfunction(event: Event[DocumentSnapshot|None]) -> None:
  # Perform more operations ...

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

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

Node.js

import {
  onDocumentWritten,
  Change,
  FirestoreEvent
} from "firebase-functions/v2/firestore";

exports.modifyuser = onDocumentWritten("users/{userId}", (event) => {
    // Get an object with the current document values.
    // If the document does not exist, it was deleted
    const document =  event.data.after.data();

    // Get an object with the previous document values
    const previousValues =  event.data.before.data();

    // perform more operations ...
});

למידע נוסף על אימות, אפשר להשתמש ב-onDocumentWrittenWithAuthContext.

Python

from firebase_functions.firestore_fn import (
  on_document_written,
  Event,
  Change,
  DocumentSnapshot,
)

@on_document_written(document="users/{userId}")
def myfunction(event: Event[Change[DocumentSnapshot | None]]) -> None:
  # Get an object with the current document values.
  # If the document does not exist, it was deleted.
  document = (event.data.after.to_dict()
              if event.data.after is not None else None)

  # Get an object with the previous document values.
  # If the document does not exist, it was newly created.
  previous_values = (event.data.before.to_dict()
                     if event.data.before is not None else None)

  # Perform more operations ...

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

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

נתוני אירוע

נתוני הקריאה

כשפונקציה מופעלת, יכול להיות שתרצו לקבל נתונים ממסמך שעודכן, או לקבל את הנתונים לפני העדכון. אפשר לקבל את הנתונים הקודמים באמצעות event.data.before, שמכיל את תמונת המסמך לפני העדכון. באופן דומה, event.data.after מכיל את מצב תמונת המצב של המסמך אחרי העדכון.

Node.js

exports.updateuser2 = onDocumentUpdated("users/{userId}", (event) => {
    // Get an object with the current document values.
    // If the document does not exist, it was deleted
    const newValues =  event.data.after.data();

    // Get an object with the previous document values
    const previousValues =  event.data.before.data();
});

Python

@on_document_updated(document="users/{userId}")
def myfunction(event: Event[Change[DocumentSnapshot]]) -> None:
  # Get an object with the current document values.
  new_value = event.data.after.to_dict()

  # Get an object with the previous document values.
  prev_value = event.data.before.to_dict()

אפשר לגשת למאפיינים כמו בכל אובייקט אחר. לחלופין, אפשר להשתמש בפונקציה get כדי לגשת לשדות ספציפיים:

Node.js

// Fetch data using standard accessors
const age = event.data.after.data().age;
const name = event.data.after.data()['name'];

// Fetch data using built in accessor
const experience = event.data.after.data.get('experience');

Python

# Get the value of a single document field.
age = event.data.after.get("age")

# Convert the document to a dictionary.
age = event.data.after.to_dict()["age"]

כתיבת נתונים

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

הפניה למסמך כוללת שיטות כמו update(), set() ו-remove(), כך שאפשר לשנות את המסמך שהפעיל את הפונקציה.

Node.js

import { onDocumentUpdated } from "firebase-functions/v2/firestore";

exports.countnamechanges = onDocumentUpdated('users/{userId}', (event) => {
  // Retrieve the current and previous value
  const data = event.data.after.data();
  const previousData = event.data.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 data.after.ref.set({
    name_change_count: count + 1
  }, {merge: true});

});

Python

@on_document_updated(document="users/{userId}")
def myfunction(event: Event[Change[DocumentSnapshot]]) -> None:
  # Get the current and previous document values.
  new_value = event.data.after
  prev_value = event.data.before

  # We'll only update if the name has changed.
  # This is crucial to prevent infinite loops.
  if new_value.get("name") == prev_value.get("name"):
      return

  # Retrieve the current count of name changes
  count = new_value.to_dict().get("name_change_count", 0)

  # Update the count
  new_value.reference.update({"name_change_count": count + 1})

גישה לפרטי אימות משתמשים

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

Node.js

  • onDocumentCreatedWithAuthContext
  • onDocumentWrittenWithAuthContext
  • onDocumentDeletedWithAuthContext
  • onDocumentUpdatedWithAuthContext

Python

  • on_document_created_with_auth_context
  • on_document_updated_with_auth_context
  • on_document_deleted_with_auth_context
  • on_document_written_with_auth_context

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

Node.js

import { onDocumentWrittenWithAuthContext } from "firebase-functions/v2/firestore"

exports.syncUser = onDocumentWrittenWithAuthContext("users/{userId}", (event) => {
    const snapshot = event.data.after;
    if (!snapshot) {
        console.log("No data associated with the event");
        return;
    }
    const data = snapshot.data();

    // retrieve auth context from event
    const { authType, authId } = event;

    let verified = false;
    if (authType === "system") {
      // system-generated users are automatically verified
      verified = true;
    } else if (authType === "unknown" || authType === "unauthenticated") {
      // admin users from a specific domain are verified
      if (authId.endsWith("@example.com")) {
        verified = true;
      }
    }

    return data.after.ref.set({
        created_by: authId,
        verified,
    }, {merge: true}); 
}); 

Python

@on_document_updated_with_auth_context(document="users/{userId}")
def myfunction(event: Event[Change[DocumentSnapshot]]) -> None:

  # Get the current and previous document values.
  new_value = event.data.after
  prev_value = event.data.before

  # Get the auth context from the event
  user_auth_type = event.auth_type
  user_auth_id = event.auth_id

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

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

Node.js

const { initializeApp } = require('firebase-admin/app');
const { getFirestore, Timestamp, FieldValue } = require('firebase-admin/firestore');

initializeApp();
const db = getFirestore();

exports.writetofirestore = onDocumentWritten("some/doc", (event) => {
    db.doc('some/otherdoc').set({ ... });
  });

  exports.writetofirestore = onDocumentWritten('users/{userId}', (event) => {
    db.doc('some/otherdoc').set({
      // Update otherdoc
    });
  });

Python

from firebase_admin import firestore, initialize_app
import google.cloud.firestore

initialize_app()

@on_document_written(document="some/doc")
def myfunction(event: Event[Change[DocumentSnapshot | None]]) -> None:
  firestore_client: google.cloud.firestore.Client = firestore.client()
  firestore_client.document("another/doc").set({
      # ...
  })

מגבלות

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

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