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

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

يصف هذا الدليل بناء الجملة الأساسي وبنية 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 حاويات، وعبارة match تحدّد اسم ملف، وتعبير 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 إلى الملفات. يمكن أن تشير عبارة match إلى ملف معيّن، كما في match /images/profilePhoto.png.

أحرف البدل في عبارة match

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

في المثال أعلاه، تستخدم عبارة match بناء جملة حرف البدل {imageId}. يعني ذلك أنّ القاعدة تنطبق على أي ملف يبدأ اسمه بـ /images/، مثل /images/profilePhoto.png أو /images/croppedProfilePhoto.png. عند تقييم تعبيرات allow في عبارة match، سيتم تحويل المتغيّر 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>;
      }
  }
}

أحرف البدل في عبارة match التكرارية

بالإضافة إلى أحرف البدل التي تطابِق السلاسل في نهاية اسم الملف وتعرضها، يمكن الإعلان عن حرف بدل متعدد الأجزاء لإجراء مطابقة أكثر تعقيدًا عن طريق إضافة =** إلى اسم حرف البدل، مثل {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 تساوي `true`، بينما يخضع الملف "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 المتداخلة

من الممكن أن يطابِق اسم الملف أكثر من عبارة 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