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

تسمح لك قواعد أمان 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() لكل طلب
  • 10 لطلبات مستند واحد وطلبات البحث.

  • 20 للقراءات المتعددة المستندات والمعاملات والكتابات المجمّعة. وينطبق أيضًا الحد السابق البالغ 10 على كل عملية.

    على سبيل المثال، تخيَّل أنّك أنشأت طلب كتابة مُجمَّع مع 3 عمليات كتابة وأنّ قواعد الأمان تستخدم طلبَي وصول إلى مستندين للتحقّق من كل عملية كتابة. في هذه الحالة، تستخدم كل عملية كتابة طلبَي وصول من أصل 10، ويستخدم طلب الكتابة المجمّعة 6 من طلبات الوصول البالغ عددها 20.

يؤدي تجاوز أي من هذين الحدّين إلى ظهور خطأ "تم رفض الإذن".

قد يتم تخزين بعض طلبات الوصول إلى المستندات مؤقتًا، ولا يتم احتساب المكالمات المخزّنة مؤقتًا ضمن الحدود المسموح بها.
الحد الأقصى لعمق عبارة match المدمجة 10
الحد الأقصى لطول المسار، في أجزاء المسار، مسموح به ضمن مجموعة من عبارات match المدمجة 100
الحد الأقصى لعدد متغيّرات التقاط المسارات المسموح بها ضمن مجموعة من عبارات match المدمجة 20
الحد الأقصى لعمق طلب الدالة 20
الحد الأقصى لعدد وسيطات الدوال 7
الحد الأقصى لعدد عمليات ربط المتغيّرات let لكل دالة 10
الحد الأقصى لعدد طلبات الدوال التكرارية أو الدورية 0 &lpar;غير مسموح به&rpar;
الحد الأقصى لعدد التعبيرات التي تم تقييمها لكل طلب 1,000
الحد الأقصى لحجم مجموعة القواعد يجب أن تتّبع القواعد حدَين أقصى للحجم:
  • حد أقصى يبلغ 256 كيلوبايت لحجم مصدر نص مجموعة القواعد الذي يتم نشره من وحدة تحكُّم Firebase أو من واجهة سطر الأوامر باستخدام firebase deploy.
  • حد أقصى يبلغ 250 كيلوبايت لحجم مجموعة القواعد المجمّعة، وهي ناتجة عن معالجة Firebase للمصدر وتفعيله في الخلفية.

الخطوات اللاحقة