تسمح لك Cloud Firestore Security Rules بالتحكّم في الوصول إلى المستندات المجموعات في قاعدة البيانات لديك. تسمح لك بنية القواعد المرنة بإنشاء قواعد تتطابق مع أي شيء، بدءًا من جميع عمليات الكتابة إلى قاعدة البيانات بأكملها إلى العمليات على مستند معيّن.
يصف هذا الدليل بنية وبناء الجملة الأساسية لقواعد الأمان. دمج هذه البنية مع شروط قواعد الأمان لإنشاء ومجموعات قواعد كاملة.
بيان الخدمة وقاعدة البيانات
تبدأ الدالة 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
.
العمليات الدقيقة
في بعض الحالات، من المفيد تقسيم 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() لكل طلب |
يؤدي تجاوز أي من هذين الحدّين إلى ظهور خطأ "تم رفض الإذن". قد يتم تخزين بعض مكالمات الوصول إلى المستندات مؤقتًا، ولن يتم احتساب الاتصالات المخزنة مؤقتًا ضمن الحدود المسموح بها. |
الحد الأقصى لعمق عبارة match المدمجة |
10 |
الحد الأقصى المسموح به لطول المسار، في أقسام المسار، ضمن مجموعة من عبارات
match المتداخلة |
100 |
الحد الأقصى لعدد متغيرات التقاط المسارات المسموح بها ضمن مجموعة من
عبارات match مدمَجة |
20 |
الحد الأقصى لعمق استدعاء الدالة | 20 |
الحد الأقصى لعدد وسيطات الدوال | 7 |
الحد الأقصى لعدد عمليات ربط المتغيّرات let لكل دالة |
10 |
الحد الأقصى لعدد طلبات الدوال التكرارية أو الدورية | 0 (غير مسموح به) |
الحد الأقصى لعدد التعبيرات التي يتم تقييمها لكل طلب | 1,000 |
الحد الأقصى لحجم مجموعة القواعد | يجب أن تلتزم مجموعات القواعد بحدود حجمَين:
|
الخطوات التالية
- اكتب شروط قواعد الأمان المخصّصة.
- اطّلِع على مرجع قواعد الأمان.