了解 2023 年 Google I/O 大会上介绍的 Firebase 亮点。了解详情

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

مشغِّلات Cloud Firestore

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

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

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

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

مشغلات وظيفة Cloud Firestore

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

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

إذا لم يكن لديك مشروع مفعَّل لاستخدام دوال السحابة الإلكترونية في 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

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

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

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

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

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