هيكلة قواعد أمان Cloud Firestore

تسمح لك Cloud Firestore Security Rules بالتحكّم في الوصول إلى المستندات والمجموعات في قاعدة البيانات. تسمح لك بنية القواعد المرنة بإنشاء قواعد تتطابق مع أي شيء، بدءًا من جميع عمليات الكتابة إلى قاعدة البيانات بأكملها إلى العمليات على مستند معيّن.

يصف هذا الدليل البنية الأساسية لقواعد الأمان وبنيتها. يمكنك دمج هذه البنية مع شروط قواعد الأمان لإنشاء قواعد قواعد كاملة.

ملاحظة: تتجاوز مكتبات برامج خادم العميل كل Cloud Firestore Security Rules وتتم المصادقة من خلال بيانات الاعتماد التلقائية لتطبيق Google. إذا كنت تستخدِم مكتبات عملاء الخادم أو واجهات برمجة التطبيقات REST أو RPC، احرص على إعداد إدارة الهوية والوصول (IAM) لـ Cloud Firestore.

بيان الخدمة وقاعدة البيانات

يبدأ Cloud Firestore Security Rules دائمًا بالبيان التالي:

service cloud.firestore {
  match /databases/{database}/documents {
    // ...
  }
}

يحدّد بيان service cloud.firestore القواعد على Cloud Firestore، ما يمنع التعارض بين Cloud Firestore Security Rules والقواعد الخاصة بالمنتجات الأخرى، مثل Cloud Storage.

يحدّد تعريف match /databases/{database}/documents أنّ القواعد يجب أن تتطابق مع أي قاعدة بيانات Cloud Firestore في المشروع. يحتوي كل مشروع حاليًا على قاعدة بيانات واحدة فقط باسم (default).

قواعد القراءة/الكتابة الأساسية

تتكون القواعد الأساسية من عبارة match تحدد مسار المستند وتعبير allow يوضح بالتفصيل عند قراءة البيانات المحددة:

service cloud.firestore {
  match /databases/{database}/documents {

    // Match any document in the 'cities' collection
    match /cities/{city} {
      allow read: if <condition>;
      allow write: if <condition>;
    }
  }
}

يجب أن تشير جميع عبارات المطابقة إلى المستندات، وليس المجموعات. يمكن أن يشير بيان المطابقة إلى مستند معيّن، كما هو الحال في match /cities/SF أو استخدام أحرف البدل للإشارة إلى أي مستند في المسار المحدّد، كما هو الحال في match /cities/{city}.

في المثال أعلاه، تستخدِم عبارة المطابقة بنية حرف البدل {city}. وهذا يعني أنّ القاعدة تنطبق على أي مستند في مجموعة cities، مثل /cities/SF أو /cities/NYC. عند تقييم تعبيرات allow في عبارة المطابقة، سيتفق المتغير city مع اسم مستند المدينة، مثل SF أو NYC.

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

العمليات الدقيقة

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

يمكن تقسيم قاعدة read إلى get وlist، في حين يمكن تقسيم قاعدة write إلى create وupdate وdelete:

service cloud.firestore {
  match /databases/{database}/documents {
    // A read rule can be divided into get and list rules
    match /cities/{city} {
      // Applies to single document read requests
      allow get: if <condition>;

      // Applies to queries and collection read requests
      allow list: if <condition>;
    }

    // A write rule can be divided into create, update, and delete rules
    match /cities/{city} {
      // Applies to writes to nonexistent documents
      allow create: if <condition>;

      // Applies to writes to existing documents
      allow update: if <condition>;

      // Applies to delete operations
      allow delete: if <condition>;
    }
  }
}

البيانات الهرمية

يتم تنظيم البيانات في Cloud Firestore في مجموعات من المستندات، وقد يعمل كل مستند على توسيع التسلسل الهرمي من خلال المجموعات الفرعية. من المهم معرفة كيفية تفاعل قواعد الأمان مع البيانات الهرمية.

لنفترض أنّ كل مستند في مجموعة cities يحتوي على مجموعة فرعية landmarks. لا تنطبق قواعد الأمان إلا على المسار المطابق، لذا لا تنطبق عناصر التحكّم في الوصول المحدّدة في مجموعة cities على المجموعة الفرعية landmarks. بدلاً من ذلك، يمكنك كتابة قواعد صريحة للتحكّم في الوصول إلى المجموعات الفرعية:

service cloud.firestore {
  match /databases/{database}/documents {
    match /cities/{city} {
      allow read, write: if <condition>;

        // Explicitly define rules for the 'landmarks' subcollection
        match /landmarks/{landmark} {
          allow read, write: if <condition>;
        }
    }
  }
}

عند دمج عبارات match، يكون مسار عبارة match الداخلية دائمًا نسبًا لمسار عبارة match الخارجية. وبالتالي، فإنّ قواعد القواعد التالية متكافئة:

service cloud.firestore {
  match /databases/{database}/documents {
    match /cities/{city} {
      match /landmarks/{landmark} {
        allow read, write: if <condition>;
      }
    }
  }
}

service cloud.firestore {
  match /databases/{database}/documents {
    match /cities/{city}/landmarks/{landmark} {
      allow read, write: if <condition>;
    }
  }
}

أحرف البدل المتكرّرة

إذا كنت تريد تطبيق القواعد على تسلسل هرمي عميق بشكل عشوائي، استخدِم بنية حرف البدل المتكرّر {name=**}. على سبيل المثال:

service cloud.firestore {
  match /databases/{database}/documents {
    // Matches any document in the cities collection as well as any document
    // in a subcollection.
    match /cities/{document=**} {
      allow read, write: if <condition>;
    }
  }
}

عند استخدام بنية أحرف البدل المتكررة، سيحتوي متغيّر أحرف البدل على جزء المسار المطابق بالكامل، حتى إذا كان المستند مضمّنًا في مجموعة فرعية مُدمجة بشكل عميق. على سبيل المثال، ستتطابق القواعد المدرَجة أعلاه مع مستند يقع على العنوان /cities/SF/landmarks/coit_tower، وستكون قيمة المتغيّر document هي SF/landmarks/coit_tower.

مع ذلك، يُرجى العِلم أنّ سلوك أحرف البدل المتكرّرة يعتمد على إصدار القواعد.

الإصدار 1

تستخدم قواعد الأمان الإصدار 1 تلقائيًا. في الإصدار 1، تتم مطابقة العناصر البديلة المتكرّرة بعنصر مسار واحد أو أكثر. لا تتطابق هاتان الخدمتان مع مسار فارغ، لذا فإنّ match /cities/{city}/{document=**} يطابق المستندات الموجودة في المجموعات الفرعية وليس في مجموعة cities، بينما يطابق match /cities/{document=**} كلا المستندين في المجموعة cities والمجموعات الفرعية.

يجب أن تظهر أحرف البدل المتكرّرة في نهاية عبارة المطابقة.

الإصدار 2

في الإصدار 2 من قواعد الأمان، لا تتطابق أحرف البدل المتكررة مع عناصر المسار أو أكثر. تتطابق match/cities/{city}/{document=**} مع المستندات في أي مجموعات فرعية بالإضافة إلى المستندات في مجموعة cities.

عليك تفعيل الإصدار 2 من خلال إضافة rules_version = '2'; في أعلى قواعد الأمان:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // Matches any document in the cities collection as well as any document
    // in a subcollection.
    match /cities/{city}/{document=**} {
      allow read, write: if <condition>;
    }
  }
}

يمكنك استخدام حرف بدل متكرر واحد كحد أقصى لكل عبارة مطابقة، ولكن في الإصدار 2، يمكنك وضع هذا الحرف البدل في أي مكان في عبارة المطابقة. على سبيل المثال:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // Matches any document in the songs collection group
    match /{path=**}/songs/{song} {
      allow read, write: if <condition>;
    }
  }
}

إذا كنت تستخدم طلبات بحث مجموعات المجموعات، يجب استخدام الإصدار 2، راجِع تأمين طلبات بحث مجموعات المجموعات.

تداخل عبارات المطابقة

من الممكن أن يتطابق المستند مع أكثر من بيان match واحد. في الحالة التي تتطابق فيها عبارات allow متعددة مع طلب، يُسمح بالوصول إذا كان أي من الشروط true:

service cloud.firestore {
  match /databases/{database}/documents {
    // Matches any document in the 'cities' collection.
    match /cities/{city} {
      allow read, write: if false;
    }

    // Matches any document in the 'cities' collection or subcollections.
    match /cities/{document=**} {
      allow read, write: if true;
    }
  }
}

في المثال أعلاه، سيتم السماح بجميع عمليات القراءة والكتابة في المجموعة cities لأنّ القاعدة الثانية هي true دائمًا، على الرغم من أنّ القاعدة الأولى هي false دائمًا.

حدود قواعد الأمان

أثناء العمل مع قواعد الأمان، يُرجى مراعاة الحدود التالية:

الحدّ المسموح به	التفاصيل
الحد الأقصى لعدد المكالمات: exists() وget() وgetAfter() لكل طلب	10 لطلبات مستند واحد وطلبات البحث. 20 لعمليات القراءة والمعاملات المتعدّدة للمستندات والعمليات الكتابية المجمّعة وينطبق أيضًا الحد السابق البالغ 10 على كل عملية. على سبيل المثال، تخيَّل أنّك أنشأت طلب كتابة مُجمَّع باستخدام 3 عمليات كتابة وأنّ قواعد الأمان تستخدم طلبَي وصول إلى مستندين للتحقّق من كل عملية كتابة. في هذه الحالة، يستخدم كل إجراء كتابة طلبَي وصول من أصل 10 طلبات، ويستخدم طلب الكتابة المجمّعة 6 من طلبَي الوصول العشرين. ويؤدي تجاوز أي من الحدّين إلى ظهور خطأ يفيد برفض الإذن. قد يتم تخزين بعض طلبات الوصول إلى المستندات مؤقتًا، ولا يتم احتساب الطلبات المخزّنة مؤقتًا ضمن الحدود المسموح بها.
الحد الأقصى لعمق بيان match المُدمَج	10
الحد الأقصى المسموح به لطول المسار، في أقسام المسار، ضمن مجموعة من عبارات match المتداخلة	100
الحد الأقصى لعدد متغيّرات تسجيل المسارات المسموح بها ضمن مجموعة من عبارات match المتداخلة	20
الحد الأقصى لعمق استدعاء الدالة	20
الحد الأقصى لعدد وسيطات الدالة	7
الحد الأقصى لعدد عمليات ربط المتغيّرات let لكل دالة	10
الحد الأقصى لعدد عمليات استدعاء الدوالّ المتكررة أو الدورية	0 (غير مسموح به)
الحد الأقصى لعدد التعبيرات التي تم تقييمها لكل طلب	1,000
الحد الأقصى لحجم مجموعة القواعد	يجب أن تلتزم مجموعات القواعد بحدود حجمَين: حدّ أقصى يبلغ 256 كيلوبايت لحجم مصدر نصّ قاعدة القواعد المنشور من وحدة تحكّم Firebase أو من سطر الأوامر باستخدام firebase deploy حدّ أقصى يبلغ 250 كيلوبايت لحجم مجموعة القواعد المجمّعة التي تنتج عندما تعالج Firebase المصدر وتجعله نشطًا في الخلفية

الخطوات التالية

• كتابة شروط قواعد الأمان المخصَّصة
• اطّلِع على مرجع قواعد الأمان.