على الرغم من أنّ عمليات Pipeline توفّر مجموعة غنية من الميزات، يقتصر محرّك "القواعد" على التعرّف على فلاتر المقارنة (مثل >) والفلاتر المنطقية (مثل or) لضمان استيفاء القيود والأمان.
تعبيرات الفلاتر المتوافقة
لكي تتقيّد عمليات Pipeline بالحدود التي تضعها قواعدك، يجب أن تستخدم عوامل التشغيل المنطقية وعوامل تشغيل المقارنة مع الثوابت. يتعرّف محرّك القواعد على أنواع الفلاتر التالية:
- المقارنات:
eqوneqوgtوgteوltوlteوinوarrayContains - المنطقية:
andوor
وإليك بعض الأمثلة:
where(eq("foo", 2))where(lt("foo", 2))documents("/user/1", "/user/2").where(...)
سمات الطلب
يمكنك مواصلة استخدام العنصر
request
للتحقّق من صحة المصادقة وسياق طلب البحث، مع العلم أنّ بعض السمات
المتاحة في طلبات البحث العادية غير متاحة في عمليات Pipeline.
السمات المتوافقة
يواصل المحرّك الجديد إتاحة السمات التالية:
request.auth: الوصول إلى بيانات الرمز المميّز ورقم تعريف المستخدم-
request.method: تحدّد العملية (على سبيل المثال،getوlist). -
request.path: مسار المورد الذي يتم الوصول إليه -
request.time: الطابع الزمني للطلب من جهة الخادم
السمات غير المتوافقة
لا يمكن استخدام سمات request.query، مثل limit وoffset وorderBy، في عمليات التحقّق من قواعد عمليات Pipeline بسبب صعوبة تحديد هذه القيم في طلبات البحث المتعدّدة المستويات.
معالجة مراحل المسار والأذونات
هناك مراحل مختلفة لمسار المعالجة يتم ربطها بعمليات دقيقة محدّدة في قواعد الأمان:
- أذونات
allow list: يتم تفعيلها من خلال مراحلcollection()وcollectionGroup()وdatabase(). - أذونات
allow get: يتم تفعيلها من خلال مرحلةdocuments()، والتي يتم التعامل معها بشكل مشابه لعمليةgetمجمّعة. - أذونات
allow create: يتم تفعيلها من خلال مراحلinsert()ومراحلupsert()عند إنشاء مستندات جديدة. - أذونات "
allow update": يتم تفعيلها من خلال مراحل "update()" ومراحل "upsert()" عند تعديل المستندات الحالية. - أذونات
allow delete: يتم تفعيلها من خلال مراحلdelete(). - أذونات
allow write: تنطبق على جميع عمليات لغة معالجة البيانات (insert()وupdate()وupsert()وdelete()). - مرحلة القيم الحرفية: لا تقرأ مرحلة
literals()من قاعدة البيانات ولكن يمكن أن تتكبّد تكاليف. لمنع إساءة الاستخدام، يجب إقرانها بمرحلة أخرى (مثلcollection()) يمكن التحقّق منها من خلال القواعد.
مراحل تعديل الحقول
لا تعمل القواعد إلا على البيانات المخزّنة وليس على القيم المشتقة. إذا كان المسار يتضمّن مراحل تعدّل الحقول (على سبيل المثال، add_fields(...) أو replace_with(...) أو select(...) أو remove_fields(...))، يتوقف محرّك القواعد عن تطبيق قيود الفلتر بعد الوصول إلى تلك المرحلة. لضمان عمل القواعد على النحو المتوقّع، ضَع مراحل الفلترة (مثل where) قبل أي مراحل يمكنها تعديل المستندات المخزَّنة الأصلية.
على سبيل المثال، لنأخذ قاعدة الأمان التالية:
match /databases/{database}/documents {
match /cities/{city} {
// Allow the user to read data if the document has the 'visibility'
// field set to 'public'
allow read: if resource.data.visibility == 'public';
}
}
مرفوض: ترفض هذه القاعدة المسار التالي لأنّ مرحلة addFields
تحدث قبل الفلترة إلى المستندات التي يكون فيها visibility هو public:
const results = await db.pipeline()
.collection("/cities")
// Filters after a modification stage are ignored by Rules.
.addFields(constant(1000).as("population"))
.where(eq(field("visibility"), constant("public")))
.execute();
مسموح به: تسمح هذه القاعدة بمسار التوصيل التالي لأنّ مرحلة where(eq(field("visibility"), constant("public"))) تحدث قبل أي مراحل تعديل:
const results = await db.pipeline()
.collection("/cities")
.where(eq(field("visibility"), constant("public")))
.addFields(constant(1000).as("population"))
.execute();
مراحل لغة معالجة البيانات وقواعد الأمان
عند تنفيذ مراحل لغة معالجة البيانات (DML) (insert() وupdate() وupsert() وdelete())، تقيّم قواعد الأمان الأذونات بشكل مختلف عن طلبات البحث للقراءة:
- تقييم القواعد لكل مستند: على عكس مسارات القراءة التي تتطلّب تعبيرات فلترة مسبقة لتقييد طلب البحث في وقت التخطيط، تقيّم عمليات DML قواعد الأمان لكل عملية تحويل مستند فردية.
- متغيّرات القاعدة:
-
request.resource: يحتوي على بيانات المستند المقترَحة لعملياتinsert()وupdate()وupsert(). resource: يحتوي على بيانات المستند الحالية المخزّنة في قاعدة البيانات قبل التعديل (متاح لـupdate()وdelete()وupsert()للمستندات الحالية).
-
حدود النظام وسلوك التنفيذ باستخدام لغة DML
عند تنفيذ عمليات DML باستخدام "قواعد الأمان"، يُرجى مراعاة حدود النظام وسلوكيات التنفيذ التالية:
الحدّ الأقصى لعمليات البحث في get() وexists() هو 20 عملية
تسمح "قواعد أمان Firebase" بإجراء 20 عملية بحث عن المستندات كحدّ أقصى (get() أو
exists()) في الطلب الواحد.
عند تشغيل مسار DML خارج معاملة صريحة، يعالج Cloud Firestore عمليات كتابة المستندات على دفعات. بما أنّ كل دفعة يتم تنفيذها في معاملتها الخاصة وقد يتم تعديل المستندات بشكل متزامن بين الدفعات، تتم إعادة تقييم قواعد الأمان وعمليات البحث عن المستندات لكل دفعة كتابة.
حتى إذا تم تقييم قواعد الأمان وفقًا لمستند ثابت واحد (على سبيل المثال، التحقّق مما إذا كان المستخدم مشرفًا):
rules_version = '2';
service cloud.firestore {
match /databases/{database}/documents {
match /posts/{postId} {
allow write: if get(/databases/$(database)/documents/users/$(request.auth.uid)).data.isAdmin == true;
}
}
}
تُجري كل دُفعة كتابة مكوّنة من 10 مستندات عملية بحث. نتيجةً لذلك، بعد كتابة جميع المستندات المحتملة، يتم الوصول إلى الحد الأقصى لعمليات البحث في الطلب، وهو 20 عملية بحث، ويتعذّر تنفيذ المسار مع ظهور الخطأ PERMISSION_DENIED. بالإضافة إلى ذلك، يتم احتساب تكلفة قراءة لكل عملية بحث يتم إجراؤها لكل دفعة كتابة.
نجاح جزئي وPERMISSION_DENIED
عند التنفيذ خارج معاملة، تلتزم عمليات لغة معالجة البيانات (DML) بالكتابة في دفعات متسلسلة. إذا تعذّر تنفيذ دفعة، إما بسبب عدم استيفاء مستند لشرط قاعدة أو بسبب تجاوز الحد الأقصى لعمليات البحث البالغ 20 عملية، يتوقف المسار ويعرض خطأ PERMISSION_DENIED.
ومع ذلك، لا يتم التراجع عن الدفعات التي تم تنفيذها. تظل قاعدة البيانات في حالة تحديث جزئي. بما أنّ العميل يتلقّى رسالة خطأ بدون قائمة بالمستندات المعدَّلة، عليك الاستعلام عن بياناتك لفحص عمليات الكتابة التي نجحت.
تشخيص حالات تعذُّر تطبيق القواعد باستخدام سجلّات تدقيق Cloud
لأسباب تتعلّق بالأمان، لا تكشف أخطاء PERMISSION_DENIED التي تظهر للعملاء عن شرط قاعدة الأمان الذي لم يتم استيفاؤه أو ما إذا تم بلوغ الحدّ الأقصى لعمليات البحث البالغ 20 عملية.
لتشخيص حالات تعذُّر تقييم القواعد، يمكن لمشرفي المشاريع فحص
"سجلّات تدقيق Cloud" في وحدة تحكّم Google Cloud (ضمن Firestore >
المراقبة أو في مستكشف السجلّات) لعرض إدخالات EvaluationError
مفصّلة.