مشغِّلات Cloud Firestore

الجيل الثاني الجيل الأول

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

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

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

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

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

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

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

ملاحظة: سيتم تشغيل أحداث Cloud Firestore فقط حول تغييرات الوثيقة. تحديث لمستند Cloud Firestore، حيث يتم جمع بدون تغيير (بدون كتابة)، لن يؤدي إلى إنشاء تحديث أو كتابة حدث. من المهم لا يمكن إضافة أحداث إلى حقول معيّنة.

إذا لم يكن لديك مشروع مفعَّل من أجل Cloud Functions for Firebase بعد، يُرجى قراءة البدء: كتابة الدوال الأولى ونشرها لضبط إعداد "وظائف السحابة الإلكترونية لبرنامج 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
    });
index.js

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

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

في هذا المثال، عند تغيير أي حقل في أي مستند في 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"}
    });
index.js

ملاحظة: يجب أن يشير المشغِّل دائمًا إلى مستند، حتى إذا كنت تستخدم حرف بدل. على سبيل المثال، users/{userId}/{messageCollectionId} غير صالح بسبب {messageCollectionId}. عبارة عن مجموعة. في المقابل، هي users/{userId}/{messageCollectionId}/{messageId} صالحة لأن {messageId} سيشير دائمًا إلى مستند.

عوامل تشغيل الأحداث

تشغيل دالة عند إنشاء مستند جديد

يمكنك تشغيل دالة في أي وقت يتم فيه إنشاء مستند جديد في مجموعة. باستخدام معالج 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 ...
    });
index.js

تشغيل دالة عند تعديل مستند

يمكنك أيضًا تشغيل دالة عند تحديث مستند باستخدام الدالة 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 ...
    });
index.js

تشغيل دالة عند حذف مستند

يمكنك أيضًا تشغيل دالة عند حذف مستند باستخدام الدالة 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 ...
    });
index.js

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

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

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

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

يمكنك الوصول إلى الخصائص كما تفعل في أي عنصر آخر. بدلاً من ذلك، يمكنك استخدام الدالة 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');
index.js

كتابة البيانات

يرتبط كل استدعاء للدالة بمستند معين في قاعدة بيانات Cloud Firestore. يمكنك الوصول إلى هذا المستند DocumentReference في السمة ref من اللقطة التي يتم عرضها في الدالة.

تأتي DocumentReference هذه من حزمة تطوير برامج 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});
    });
index.js

ملاحظة: في أي مرة تكتب فيها إلى المستند نفسه الذي أدّى إلى تشغيل دالة، يمكنك المعرضين لخطر إنشاء حلقة لانهائية. يُرجى توخي الحذر والحرص على الخروج من الدالة في حال عدم الحاجة إلى إجراء أي تغيير

البيانات خارج عامل التفعيل

يتم تنفيذ 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 بواسطة بقواعد الأمان، يمكنها الوصول إلى أي جزء من قاعدة البيانات.

القيود

لاحِظ القيود التالية على مشغّلات Cloud Firestore لوظائف السحابة الإلكترونية:

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