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

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

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

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

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

service cloud.firestore {
  // The {database} wildcard allows the rules to reference any database,
  // but these rules are only active on databases where they are explicitly deployed.
  match /databases/{database}/documents {
    // ...
  }
}

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

يحدّد البيان match /databases/{database}/documents أنّ القواعد يجب أن تطابق أي قاعدة بيانات Cloud Firestore في المشروع. على الرغم من أنّ المشروع يمكن أن يحتوي على ما يصل إلى 100 قاعدة بيانات، يتم تحديد قاعدة البيانات الأولى التي تم إنشاؤها فقط كقاعدة بيانات تلقائية.

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

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

تتألف القواعد الأساسية من عبارة 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.

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

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>;
   }
 }
}

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.

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

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

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

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