تسمح لك قواعد أمان Cloud Firestore بالتحكم في الوصول إلى المستندات والمجموعات في قاعدة البيانات. يتيح لك بناء جملة القواعد المرنة إنشاء قواعد تتطابق مع أي شيء، من جميع عمليات الكتابة إلى قاعدة البيانات بأكملها إلى العمليات في مستند معين.
يصف هذا الدليل البنية الأساسية لقواعد الأمان وبنيتها. يمكنك دمج هذه البنية مع شروط قواعد الأمان لإنشاء مجموعات قواعد كاملة.
بيان الخدمة وقاعدة البيانات
تبدأ قواعد أمان Cloud Firestore دائمًا بالتعريف التالي:
service cloud.firestore {
match /databases/{database}/documents {
// ...
}
}
يحدّد بيان service cloud.firestore
القواعد على Cloud Firestore، ما يمنع التعارض بين قواعد أمان Cloud Firestore والقواعد الخاصة بالمنتجات الأخرى، مثل 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 |
الحد الأقصى لحجم مجموعة القواعد | يجب أن تتّبع القواعد حدَين أقصى للحجم:
|
الخطوات اللاحقة
- كتابة شروط قواعد الأمان المخصَّصة
- اطّلِع على مرجع قواعد الأمان.