قم بتوسيع Cloud Firestore بوظائف السحابة

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

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

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

تقوم Cloud Functions for Firebase SDK بتصدير كائن 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 ...
    });

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

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