Google is committed to advancing racial equity for Black communities. See how.
ترجمت واجهة Cloud Translation API‏ هذه الصفحة.
Switch to English

مشغلات Cloud Firestore

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

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

  1. ينتظر التغييرات على مستند معين.
  2. يتم تشغيله عند وقوع حدث وأداء مهامه (راجع ماذا يمكنني أن أفعل بوظائف السحابة؟ للحصول على أمثلة لحالات الاستخدام).
  3. يتلقى كائن بيانات يحتوي على لقطة من البيانات المخزنة في المستند المحدد. بالنسبة onWrite أو onUpdate ، يحتوي كائن البيانات على لقطتين تمثلان حالة البيانات قبل الحدث onWrite onUpdate .

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

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

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

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

إذا لم يكن لديك مشروع ممكّن لـ Cloud Functions لـ Firebase حتى الآن ، فاقرأ البدء: اكتب ونشر وظائفك الأولى لتهيئة وإعداد وظائف السحابة لمشروع Firebase.

كتابة وظائف Cloud Firestore التي يتم تشغيلها

تحديد مشغل الوظيفة

لتحديد مشغل Cloud Firestore ، حدد مسار المستند ونوع الحدث:

Node.js

const functions = require('firebase-functions');

exports.myFunction = functions.firestore
  .document('my-collection/{doc-id}')
  .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 للوظائف السحابية ميزة تجريبية مع بعض القيود المعروفة:

  • قد يستغرق الأمر ما يصل إلى 10 ثوانٍ حتى تستجيب إحدى الوظائف للتغييرات في Cloud Firestore.
  • الطلب غير مضمون. يمكن أن تؤدي التغييرات السريعة إلى استدعاءات الوظيفة بترتيب غير متوقع.
  • يتم تسليم الأحداث مرة واحدة على الأقل ، ولكن قد يؤدي حدث واحد إلى استدعاءات وظائف متعددة. تجنب الاعتماد على الميكانيكا مرة واحدة بالضبط ، واكتب وظائف ذاتية .
  • تتوفر مشغلات Cloud Firestore للوظائف السحابية فقط لـ Cloud Firestore في الوضع الأصلي . لا يتوفر لـ Cloud Firestore في وضع Datastore.