Join us in person and online for Firebase Summit on October 18, 2022. Learn how Firebase can help you accelerate app development, release your app with confidence, and scale with ease. Register now

محرک های Cloud Firestore

با مجموعه‌ها، منظم بمانید ذخیره و دسته‌بندی محتوا براساس اولویت‌های شما.

با توابع Cloud، می توانید رویدادها را در Cloud Firestore بدون نیاز به به روز رسانی کد مشتری مدیریت کنید. می‌توانید تغییرات Cloud Firestore را از طریق رابط DocumentSnapshot یا از طریق Admin SDK انجام دهید.

در یک چرخه عمر معمولی، یک تابع Cloud Firestore کارهای زیر را انجام می دهد:

  1. منتظر تغییرات در یک سند خاص است.
  2. هنگامی که یک رویداد رخ می‌دهد و وظایفش را انجام می‌دهد، فعال می‌شود (برای نمونه‌هایی از موارد استفاده، به «چه کاری می‌توانم با توابع ابری انجام دهم؟» مراجعه کنید.
  3. یک شی داده را دریافت می کند که حاوی یک عکس فوری از داده های ذخیره شده در سند مشخص شده است. برای onWrite یا onUpdate ، شی داده حاوی دو عکس فوری است که نشان دهنده وضعیت داده قبل و بعد از رویداد راه اندازی است.

فاصله بین مکان نمونه Firestore و محل تابع می تواند تاخیر شبکه قابل توجهی ایجاد کند. برای بهینه سازی عملکرد، مکان عملکرد را در صورت امکان مشخص کنید.

عملکرد Cloud Firestore فعال می شود

Cloud Functions برای Firebase SDK یک شی functions.firestore را صادر می کند که به شما امکان می دهد کنترل کننده های مرتبط با رویدادهای Cloud Firestore خاص ایجاد کنید.

نوع رویداد ماشه
onCreate هنگامی که یک سند برای اولین بار روی آن نوشته می شود فعال می شود.
onUpdate زمانی فعال می شود که سندی از قبل وجود داشته باشد و هر مقداری تغییر کرده باشد.
onDelete هنگامی که یک سند دارای داده حذف می شود فعال می شود.
onWrite هنگامی که onCreate ، onUpdate یا onDelete می شود، فعال می شود.

اگر هنوز پروژه‌ای را برای Cloud Functions برای Firebase فعال نکرده‌اید، شروع کنید: Write and Deploy Your First Functions را بخوانید تا پروژه Cloud Functions برای 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 ...
    });

یک تابع را برای همه تغییرات یک سند فعال کنید

اگر به نوع رویدادی که اجرا می‌شود اهمیتی نمی‌دهید، می‌توانید با استفاده از تابع onWrite() با علامت عام به تمام تغییرات یک سند Cloud Firestore گوش دهید. اگر کاربر ایجاد، به‌روزرسانی یا حذف شود، این تابع مثال 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 از 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});
    });

داده های خارج از رویداد ماشه

توابع ابری در یک محیط قابل اعتماد اجرا می شوند، به این معنی که آنها به عنوان یک حساب سرویس در پروژه شما مجاز هستند. با استفاده از Firebase Admin SDK می توانید خواندن و نوشتن را انجام دهید:

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 برای عملکردهای ابری توجه کنید:

  • سفارش تضمین نمی شود. تغییرات سریع می تواند فراخوانی عملکرد را با ترتیب غیرمنتظره ای آغاز کند.
  • رویدادها حداقل یک بار تحویل داده می شوند، اما یک رویداد ممکن است منجر به فراخوانی چند تابع شود. از وابستگی به مکانیک دقیقاً یکبار خودداری کنید و توابع بی توان را بنویسید.
  • محرک‌های Cloud Firestore برای Cloud Functions فقط برای Cloud Firestore در حالت Native در دسترس است. برای Cloud Firestore در حالت Datastore در دسترس نیست.
،

با توابع Cloud، می توانید رویدادها را در Cloud Firestore بدون نیاز به به روز رسانی کد مشتری مدیریت کنید. می‌توانید تغییرات Cloud Firestore را از طریق رابط DocumentSnapshot یا از طریق Admin SDK انجام دهید.

در یک چرخه عمر معمولی، یک تابع Cloud Firestore کارهای زیر را انجام می دهد:

  1. منتظر تغییرات در یک سند خاص است.
  2. هنگامی که یک رویداد رخ می‌دهد و وظایفش را انجام می‌دهد، فعال می‌شود (برای نمونه‌هایی از موارد استفاده، به «چه کاری می‌توانم با توابع ابری انجام دهم؟» مراجعه کنید.
  3. یک شی داده را دریافت می کند که حاوی یک عکس فوری از داده های ذخیره شده در سند مشخص شده است. برای onWrite یا onUpdate ، شی داده حاوی دو عکس فوری است که نشان دهنده وضعیت داده قبل و بعد از رویداد راه اندازی است.

فاصله بین مکان نمونه Firestore و محل تابع می تواند تاخیر شبکه قابل توجهی ایجاد کند. برای بهینه سازی عملکرد، مکان عملکرد را در صورت امکان مشخص کنید.

عملکرد Cloud Firestore فعال می شود

Cloud Functions برای Firebase SDK یک شی functions.firestore را صادر می کند که به شما امکان می دهد کنترل کننده های مرتبط با رویدادهای Cloud Firestore خاص ایجاد کنید.

نوع رویداد ماشه
onCreate هنگامی که یک سند برای اولین بار روی آن نوشته می شود فعال می شود.
onUpdate زمانی فعال می شود که سندی از قبل وجود داشته باشد و هر مقداری تغییر کرده باشد.
onDelete هنگامی که یک سند دارای داده حذف می شود فعال می شود.
onWrite هنگامی که onCreate ، onUpdate یا onDelete می شود، فعال می شود.

اگر هنوز پروژه‌ای را برای Cloud Functions برای Firebase فعال نکرده‌اید، شروع کنید: Write and Deploy Your First Functions را بخوانید تا پروژه Cloud Functions برای 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 ...
    });

یک تابع را برای همه تغییرات یک سند فعال کنید

اگر به نوع رویدادی که اجرا می‌شود اهمیتی نمی‌دهید، می‌توانید با استفاده از تابع onWrite() با علامت عام به تمام تغییرات یک سند Cloud Firestore گوش دهید. اگر کاربر ایجاد، به‌روزرسانی یا حذف شود، این تابع مثال 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 از 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});
    });

داده های خارج از رویداد ماشه

توابع ابری در یک محیط قابل اعتماد اجرا می شوند، به این معنی که آنها به عنوان یک حساب سرویس در پروژه شما مجاز هستند. با استفاده از Firebase Admin SDK می توانید خواندن و نوشتن را انجام دهید:

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 برای عملکردهای ابری توجه کنید:

  • سفارش تضمین نمی شود. تغییرات سریع می تواند فراخوانی عملکرد را با ترتیب غیرمنتظره ای آغاز کند.
  • رویدادها حداقل یک بار تحویل داده می شوند، اما یک رویداد ممکن است منجر به فراخوانی عملکردهای متعدد شود. از وابستگی به مکانیک دقیقاً یکبار خودداری کنید و توابع بی توان را بنویسید.
  • محرک‌های Cloud Firestore برای Cloud Functions فقط برای Cloud Firestore در حالت Native در دسترس است. برای Cloud Firestore در حالت Datastore در دسترس نیست.