التعرُّف على البنية الأساسية لقواعد أمان Firebase للغة Cloud Storage

تتيح لك Firebase Security Rules في Cloud Storage التحكّم في الوصول إلى العناصر المخزَّنة في حِزم Cloud Storage. تتيح لك بنية القواعد المرنة إنشاء قواعد للتحكّم في أي عملية، بدءًا من جميع عمليات الكتابة في حزمة Cloud Storage وصولاً إلى العمليات على ملف معيّن.

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 Cloud Storage data.

يصف هذا الدليل البنية الأساسية لـ Cloud Storage Security Rules لإنشاء مجموعات قواعد كاملة.

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

تبدأ دائمًا Firebase Security Rules لـ Cloud Storage بالإعلان التالي:

service firebase.storage {
    // ...
}

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

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

تتألف القواعد الأساسية من عبارة match تحدّد حِزم Cloud Storage، وعبارة مطابقة تحدّد اسم ملف، وتعبير allow يوضّح بالتفصيل الحالات التي يُسمح فيها بقراءة البيانات المحدّدة. تحدّد تعبيرات allow طرق الوصول (مثل القراءة والكتابة) المعنيّة والشروط التي يتم بموجبها السماح بالوصول أو رفضه.

في مجموعة القواعد التلقائية، تستخدم عبارة match الأولى تعبير حرف البدل {bucket} للإشارة إلى أنّ القواعد تنطبق على جميع الحِزم في مشروعك. سنناقش فكرة مطابقة أحرف البدل أكثر في القسم التالي.

service firebase.storage {
  // The {bucket} wildcard indicates we match files in all Cloud Storage buckets
  match /b/{bucket}/o {
    // Match filename
    match /filename {
      allow read: if <condition>;
      allow write: if <condition>;
    }
  }
}

تشير جميع عبارات المطابقة إلى ملفات. يمكن أن تشير عبارة المطابقة إلى ملف محدّد، كما في match /images/profilePhoto.png.

مطابقة أحرف البدل

بالإضافة إلى الإشارة إلى ملف واحد، يمكن أن يستخدم Security Rules أحرف البدل للإشارة إلى أي ملف يحتوي على بادئة سلسلة معيّنة في اسمه، بما في ذلك الشرطات المائلة، كما في match /images/{imageId}.

في المثال أعلاه، تستخدم عبارة المطابقة بنية حرف البدل {imageId}. هذا يعني أنّ القاعدة تنطبق على أي ملف يبدأ اسمه بـ /images/، مثل /images/profilePhoto.png أو /images/croppedProfilePhoto.png. عند تقييم تعبيرات allow في عبارة المطابقة، سيتم تحليل المتغيّر imageId إلى اسم ملف الصورة، مثل profilePhoto.png أو croppedProfilePhoto.png.

يمكن الإشارة إلى متغيّر حرف بدل من داخل match لتوفير اسم الملف أو تفويض المسار:

// Another way to restrict the name of a file
match /images/{imageId} {
  allow read: if imageId == "profilePhoto.png";
}

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

كما ذكرنا سابقًا، لا توجد بنية هرمية داخل حزمة Cloud Storage. ولكن باستخدام اصطلاح تسمية الملفات، غالبًا ما يتضمن شرطات مائلة في أسماء الملفات، يمكننا محاكاة بنية تبدو كسلسلة متداخلة من الأدلة والأدلة الفرعية. من المهم فهم كيفية تفاعل Firebase Security Rules مع أسماء الملفات هذه.

لنفترض أنّ لدينا مجموعة من الملفات تبدأ أسماؤها جميعًا بالجذر /images/. تنطبق Firebase Security Rules فقط على اسم الملف المطابق، لذا لا تنطبق عناصر التحكّم في الوصول المحدّدة في جذر /images/ على جذر /mp3s/. بدلاً من ذلك، اكتب قواعد صريحة تتطابق مع أنماط أسماء الملفات المختلفة:

service firebase.storage {
  match /b/{bucket}/o {
    match /images/{imageId} {
      allow read, write: if <condition>;
    }

    // Explicitly define rules for the 'mp3s' pattern
    match /mp3s/{mp3Id} {
      allow read, write: if <condition>;
    }
  }
}

عند دمج عبارات match، يتم دائمًا إلحاق مسار عبارة match الداخلية بمسار عبارة match الخارجية. وبالتالي، فإن مجموعتَي القواعد التاليتَين متكافئتان:

service firebase.storage {
  match /b/{bucket}/o {
    match /images {
      // Exact match for "images/profilePhoto.png"
      match /profilePhoto.png {
        allow write: if <condition>;
      }
    }
  }
}

service firebase.storage {
  match /b/{bucket}/o {
    // Exact match for "images/profilePhoto.png"
    match /images/profilePhoto.png {
      allow write: if <condition>;
      }
  }
}

أحرف البدل للمطابقة التكرارية

بالإضافة إلى أحرف البدل التي تطابق السلاسل وتعرضها في نهاية اسم الملف، يمكن الإعلان عن حرف بدل متعدد الأجزاء لإجراء مطابقة أكثر تعقيدًا من خلال إضافة =** إلى اسم حرف البدل، مثل {path=**}:

// Partial match for files that start with "images"
match /images {

  // Exact match for "images/**"
  // e.g. images/users/user:12345/profilePhoto.png is matched
  // images/profilePhoto.png is also matched!
  match /{allImages=**} {
    // This rule matches one or more path segments (**)
    // allImages is a path that contains all segments matched
    allow read: if <other_condition>;
  }
}

إذا تطابقت قواعد متعددة مع ملف، تكون النتيجة هي OR نتيجة جميع تقييمات القواعد. أي إذا تم تقييم أي قاعدة يتطابق معها الملف على أنّها true، تكون النتيجة true.

في القواعد أعلاه، يمكن قراءة الملف "images/profilePhoto.png" إذا كانت قيمة condition أو other_condition صحيحة، بينما يخضع الملف "images/users/user:12345/profilePhoto.png" لنتيجة other_condition فقط.

Cloud Storage Security Rules لا يتم تطبيقها بشكل متسلسل، ويتم تقييم القواعد فقط عندما يتطابق مسار الطلب مع مسار تم تحديد قواعد له.

rules_version = '2';
service cloud.storage {
  match /b/{bucket}/o {
   ...
 }
}

rules_version = '2';
service firebase.storage {
 match /b/{bucket}/o {
   // Matches any file in a songs "subdirectory" under the
   // top level of your Cloud Storage bucket.
   match /{prefixSegment=**}/songs/{mp3filenames} {
     allow read, write: if <condition>;
   }
  }
}

العمليات الدقيقة

في بعض الحالات، من المفيد تقسيم read وwrite إلى عمليات أكثر دقة. على سبيل المثال، قد يحتاج تطبيقك إلى فرض شروط مختلفة على إنشاء الملفات مقارنةً بحذف الملفات.

يمكن تقسيم عملية read إلى get وlist.

يمكن تقسيم قاعدة write إلى create وupdate وdelete:

service firebase.storage {
  match /b/{bucket}/o {
    // A read rule can be divided into read and list rules
    match /images/{imageId} {
      // Applies to single file read requests
      allow get: if <condition>;
      // Applies to list and listAll requests (Security Rules Version 2)
      allow list: if <condition>;

    // A write rule can be divided into create, update, and delete rules
    match /images/{imageId} {
      // Applies to writes to file contents
      allow create: if <condition>;

      // Applies to updates to (pre-existing) file metadata
      allow update: if <condition>;

      // Applies to delete operations
      allow delete: if <condition>;
    }
  }
 }
}

بيانات المطابقة المتداخلة

من الممكن أن يتطابق اسم ملف مع أكثر من عبارة match واحدة. في حال تطابق تعبيرات allow متعددة مع طلب، يتم السماح بالوصول إذا كان أي من الشروط true:

service firebase.storage {
  match b/{bucket}/o {
    // Matches file names directly inside of '/images/'.
    match /images/{imageId} {
      allow read, write: if false;
    }

    // Matches file names anywhere under `/images/`
    match /images/{imageId=**} {
      allow read, write: if true;
    }
  }
}

في المثال أعلاه، يُسمح بجميع عمليات القراءة والكتابة في الملفات التي يبدأ اسمها بـ /images/ لأنّ القاعدة الثانية هي دائمًا true، حتى عندما تكون القاعدة الأولى هي false.

القواعد ليست فلاتر

بمجرد تأمين بياناتك والبدء في إجراء عمليات الملفات، ضع في اعتبارك أن قواعد الأمان ليست عوامل تصفية. لا يمكنك تنفيذ عمليات على مجموعة من الملفات التي تتطابق مع نمط اسم ملف وتتوقع أن يصل Cloud Storage فقط إلى الملفات التي يملك العميل الحالي الإذن بالوصول إليها.

على سبيل المثال، لنأخذ قاعدة الأمان التالية:

service firebase.storage {
  match /b/{bucket}/o {
    // Allow the client to read files with contentType 'image/png'
    match /aFileNamePrefix/{aFileName} {
      allow read: if resource.contentType == 'image/png';
    }
  }
}

مرفوض: ترفض هذه القاعدة الطلب التالي لأنّ مجموعة النتائج يمكن أن تتضمّن ملفات لا يكون فيها contentType هو image/png:

filesRef = storage.ref().child("aFilenamePrefix");

filesRef.listAll()
    .then(function(result) {
      console.log("Success: ", result.items);
    })
});

تُقيّم القواعد في Cloud Storage Security Rules كل طلب بحث مقابل نتيجته المحتملة، وترفض الطلب إذا كان من الممكن أن يعرض ملفًا لا يملك العميل إذنًا بقراءته. يجب أن تتبع طلبات الوصول القيود التي تضعها قواعدك.

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

يمكنك تعميق فهمك لـ "Firebase Security Rules" في "Cloud Storage":

• تعرَّف على المفهوم الرئيسي التالي للغة "القواعد"، وهو الشروط الديناميكية التي تتيح لقواعدك التحقّق من تفويض المستخدم ومقارنة البيانات الحالية والواردة والتحقّق من صحة البيانات الواردة والمزيد.

• راجِع حالات الاستخدام النموذجية للأمان وتعريفات Firebase Security Rules التي تتناولها.

يمكنك استكشاف حالات استخدام Firebase Security Rules المتعلّقة بـ "Cloud Storage":