توسيع نطاق Cloud Firestore باستخدام Cloud Functions (الجيل الأول)

باستخدام Cloud Functions، يمكنك نشر رمز Node.js لمعالجة الأحداث التي يتم تشغيلها بسبب التغييرات في قاعدة بيانات Cloud Firestore. يتيح لك ذلك إضافة وظائف من جهة الخادم بسهولة إلى تطبيقك بدون تشغيل خوادمك الخاصة.

للاطّلاع على أمثلة على حالات الاستخدام، يُرجى مراجعة ما الذي يمكنني فعله باستخدام Cloud Functions؟ أو مستودع GitHub الخاص بأمثلة الدوال.

مشغِّلات دالة 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) لـ Node.js في Cloud Firestore ويتضمّن طرقًا مثل 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 في بيئة موثوقة، ما يعني أنّه مصرَّح به كحساب خدمة في مشروعك. يمكنك إجراء عمليات القراءة والكتابة باستخدام مدير 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 في Cloud Functions:

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