مشغِّلات Cloud Firestore


باستخدام Cloud Functions، يمكنك التعامل مع الأحداث في Cloud Firestore بدون الحاجة إلى تعديل رمز العميل. يمكنك إجراء تغييرات على Cloud Firestore من خلال واجهة لقطة المستند أو من خلال Admin SDK.

في دورة حياة نموذجية، تنفّذ دالة Cloud Firestore ما يلي:

  1. تنتظر هذه الدالة حدوث تغييرات في مستند معيّن.
  2. يتم تشغيل هذا التطبيق عند وقوع حدث معيّن، وينفّذ مهامه.
  3. تتلقّى هذه الطريقة عنصر بيانات يحتوي على لقطة للبيانات المخزّنة في المستند المحدّد. بالنسبة إلى أحداث الكتابة أو التعديل، يحتوي عنصر البيانات على لقطتَين تمثّلان حالة البيانات قبل الحدث المشغِّل وبعده.

يمكن أن تؤدي المسافة بين موقع مثيل Firestore وموقع الدالة إلى حدوث تأخير كبير في الشبكة. لتحسين الأداء، ننصحك بتحديد موقع الدالة عند الاقتضاء.

مشغّلات وظائف Cloud Firestore

تصدِّر حزمة تطوير البرامج (SDK) Cloud Functions for Firebase عنصر functions.firestore يتيح لك إنشاء معالِجات مرتبطة بأحداث Cloud Firestore معيّنة.

نوع الحدث عامل التفعيل
onCreate يتم تشغيله عند كتابة مستند لأول مرة.
onUpdate يتم تشغيل هذا الحدث عندما يكون المستند متوفّرًا مسبقًا وتم تغيير أي قيمة فيه.
onDelete يتم تشغيله عند حذف مستند يتضمّن بيانات.
onWrite يتم تشغيله عند تشغيل onCreate أو onUpdate أو onDelete.

إذا لم يكن لديك مشروع مفعّل لاستخدام 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
    });

تحديد مجموعة من المستندات باستخدام أحرف البدل

إذا أردت إرفاق مشغّل بمجموعة من المستندات، مثل أي مستند في مجموعة معيّنة، استخدِم {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 ...
    });

تشغيل دالة لجميع التغييرات التي يتم إجراؤها على مستند

إذا لم يكن يهمّك نوع الحدث الذي يتم تنشيطه، يمكنك الاستماع إلى جميع التغييرات في مستند 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 ...
    });

قراءة البيانات وكتابتها

عندما يتم تشغيل دالة، فإنّها تقدّم لقطة من البيانات ذات الصلة بالحدث. يمكنك استخدام هذه اللقطة للقراءة من المستند الذي أدّى إلى تشغيل الحدث أو الكتابة إليه، أو استخدام حزمة تطوير البرامج (SDK) الخاصة بمشرف 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) الخاصة بـ Cloud 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});
    });

البيانات خارج حدث التشغيل

Cloud Functions التنفيذ في بيئة موثوقة، ما يعني أنّها معتمَدة كحساب خدمة في مشروعك. يمكنك إجراء عمليات قراءة وكتابة باستخدام 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 Functions:

  • تتطلّب Cloud Functions (الجيل الأول) توفّر قاعدة بيانات "(default)" حالية في وضع Firestore الأصلي. لا تتوافق مع Cloud Firestore قواعد البيانات المسماة أو وضع Datastore. يُرجى استخدام Cloud Functions (الجيل الثاني) لضبط الأحداث في مثل هذه الحالات.
  • لا نضمن ترتيب المقالات. يمكن أن تؤدي التغييرات السريعة إلى تفعيل استدعاءات الدوال بترتيب غير متوقّع.
  • يتم تسليم الأحداث مرة واحدة على الأقل، ولكن قد يؤدي حدث واحد إلى استدعاءات متعددة للدالة. تجنَّب الاعتماد على آليات التنفيذ مرة واحدة بالضبط، واكتب دوالاً متكررة.
  • يتطلّب Cloud Firestore في وضع Datastore Cloud Functions (الجيل الثاني). لا يتوافق اشتراك Cloud Functions (الجيل الأول) مع وضع Datastore.
  • يرتبط المشغّل بقاعدة بيانات واحدة. لا يمكنك إنشاء مشغّل يطابق قواعد بيانات متعددة.
  • لا يؤدي حذف قاعدة بيانات إلى حذف أي مشغّلات لهذه القاعدة تلقائيًا. يتوقف المشغّل عن إرسال الأحداث، ولكنّه يظل متاحًا إلى أن تحذفه.
  • إذا تجاوز حدث مطابق الحد الأقصى لحجم الطلب، قد لا يتم تسليم الحدث إلى Cloud Functions (الجيل الأول).
    • يتم تسجيل الأحداث التي لم يتم تسليمها بسبب حجم الطلب في سجلات النظام الأساسي ويتم احتسابها ضمن استخدام السجلّ للمشروع.
    • يمكنك العثور على هذه السجلات في "مستكشف السجلات" من خلال الرسالة "لا يمكن تسليم الحدث إلى دالة Cloud بسبب تجاوز الحجم الحدّ المسموح به للجيل الأول..." من error الخطورة. يمكنك العثور على اسم الدالة ضمن الحقل functionName. إذا كان الحقل receiveTimestamp لا يزال ضمن ساعة من الآن، يمكنك استنتاج محتوى الحدث الفعلي من خلال قراءة المستند المعني باستخدام لقطة قبل وبعد الطابع الزمني.
    • لتجنُّب هذا التكرار، يمكنك اتّباع الخطوات التالية:
      • نقل البيانات والترقية إلى Cloud Functions (الجيل الثاني)
      • تقليل حجم المستند
      • احذف Cloud Functions المعنيّ
    • يمكنك إيقاف التسجيل نفسه باستخدام الاستثناءات، ولكن يُرجى العِلم أنّه سيظل تعذُّر تسليم الأحداث المخالفة.