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

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.

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

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.

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

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

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

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