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

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

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

Help me use Firebase in my app.
1. Make sure that **Firebase agent skills** are installed and updated. For Claude Code, Codex, or Cursor agents, help me install the Firebase plugin. For other agents, run `npx skills add firebase/agent-skills`. Always try to use **Firebase agent skills** for Firebase-related tasks.
2. Help me write, validate, and deploy Firebase Security Rules to protect my app's Firestore data.

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

تبدأ 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 نطاق القواعد على Rules، ما يمنع التعارض بين Cloud Firestore Security Rules وقواعد المنتجات الأخرى، مثل Cloud Storage.

يحدّد بيان match /databases/{database}/documents أنّ القواعد يجب أن تتطابق مع أي قاعدة بيانات للقواعد في المشروع. على الرغم من أنّ المشروع يمكن أن يحتوي على ما يصل إلى 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>;
    }
  }
}

البيانات الهرمية

يتم تنظيم البيانات في "القواعد" ضمن مجموعات من المستندات، ويمكن لكل مستند توسيع التسلسل الهرمي من خلال المجموعات الفرعية. من المهم فهم كيفية تفاعل قواعد الأمان مع البيانات الهرمية.

لنفترض أنّ كل مستند في مجموعة 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.

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

عند العمل مع قواعد الأمان، يُرجى مراعاة الحدود التالية:

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

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