בעזרת Cloud Functions, אתם יכולים לפרוס קוד לטיפול באירועים שמופעלים בעקבות שינויים במסד הנתונים של Cloud Firestore. כך אפשר להוסיף לאפליקציה פונקציונליות בצד השרת בלי להפעיל שרתים משלכם.
Cloud Functions (דור שני)
הדור השני של Cloud Functions for Firebase מבוסס על Cloud Run ועל Eventarc, ומספק תשתית חזקה יותר, שליטה מתקדמת בביצועים וביכולת ההתאמה לעומס, ושליטה רבה יותר בזמן הריצה של הפונקציות. מידע נוסף על הדור השני זמין במאמר Cloud Functions for Firebase (דור שני).
טריגרים של פונקציות 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
const {
onDocumentWritten,
onDocumentCreated,
onDocumentUpdated,
onDocumentDeleted,
Change,
FirestoreEvent
} = require('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
const {
onDocumentWritten,
Change,
FirestoreEvent
} = require('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
const {
onDocumentWritten,
Change,
FirestoreEvent
} = require('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.
התאמות של תווים כלליים לחיפוש נשלפות מהנתיב של המסמך ונשמרות ב-event.params.
הטריגר חייב תמיד להפנות למסמך, גם אם משתמשים בתו כללי לחיפוש.
טריגרים של אירועים
הפעלת פונקציה כשנוצר מסמך חדש
אתם יכולים להפעיל פונקציה בכל פעם שנוצר מסמך חדש באוסף. הפונקציה לדוגמה הזו מופעלת בכל פעם שנוסף פרופיל משתמש חדש:
Node.js
const {
onDocumentCreated,
Change,
FirestoreEvent
} = require('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
const {
onDocumentUpdated,
Change,
FirestoreEvent
} = require('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
const {
onDocumentDeleted,
Change,
FirestoreEvent
} = require('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 באמצעות הטריגר של האירוע "מסמך נכתב". הפונקציה לדוגמה הזו מופעלת אם משתמש נוצר, מעודכן או נמחק:
Node.js
const {
onDocumentWritten,
Change,
FirestoreEvent
} = require('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 ...
קריאה וכתיבה של נתונים
כשפונקציה מופעלת, היא מספקת תמונת מצב של הנתונים שקשורים לאירוע. אתם יכולים להשתמש בתמונת המצב הזו כדי לקרוא מהמסמך שהפעיל את האירוע או לכתוב אליו, או להשתמש ב-SDK של Firebase לאדמינים כדי לגשת לחלקים אחרים במסד הנתונים.
נתוני אירוע
נתוני הקריאה
כשפונקציה מופעלת, יכול להיות שתרצו לקבל נתונים ממסמך שעודכן, או לקבל את הנתונים לפני העדכון. כדי לקבל את הנתונים הקודמים, אפשר להשתמש ב-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
const {onDocumentUpdated} = require('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 event.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
onDocumentCreatedWithAuthContextonDocumentWrittenWithAuthContextonDocumentDeletedWithAuthContextonDocumentUpdatedWithAuthContext
Python
on_document_created_with_auth_contexton_document_updated_with_auth_contexton_document_deleted_with_auth_contexton_document_written_with_auth_context
למידע על הנתונים שזמינים בהקשר לצורכי אימות, ראו הקשר לצורכי אימות. בדוגמה הבאה אפשר לראות איך לאחזר את פרטי האימות:
Node.js
const {onDocumentWrittenWithAuthContext} = require('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 פועלים בסביבה מהימנה. הם מורשים כחשבון שירות בפרויקט שלכם, ואתם יכולים לבצע פעולות קריאה וכתיבה באמצעות ה-SDK של Firebase לאדמינים:
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({
# ...
})
מגבלות
- אין הבטחה שההזמנה תתבצע. שינויים מהירים יכולים להפעיל פונקציות בסדר לא צפוי.
- אירועים נשלחים לפחות פעם אחת, אבל אירוע בודד יכול לגרום להפעלה של כמה פונקציות. אל תסתמכו על מנגנונים של "פעם אחת בדיוק", וכתבו פונקציות אידמפוטנטיות.
- טריגר משויך למסד נתונים אחד. אי אפשר ליצור טריגר שתואם לכמה מסדי נתונים.
- מחיקת מסד נתונים לא מוחקת באופן אוטומטי את הטריגרים של אותו מסד נתונים. הטריגר מפסיק להעביר אירועים אבל ממשיך להתקיים עד שמוחקים אותו.
- מסמכים שגדולים מ-10 MiB לא נכללים במטען הייעודי (payload) של האירוע. כדי לאחזר את המסמך עם הגרסאות, משתמשים בזמן קריאה של שחזור מערכת מנקודה מסוימת בזמן (PITR).