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

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

ملاحظة: لا تحتوي الحِزم في Cloud Storage إلا على ملفات، ولا تحتوي على مجلدات. في هذه الصفحة، سترى الشرطة المائلة / في أسماء الملفات، مثل /images/profilePhoto.png، ما يشير إلى أنّ هناك تسلسلاً هرميًا للدلائل والدلائل الفرعية في الحزمة. ومع ذلك، يمكن أن تتضمّن أسماء الملفات بادئات تحتوي على علامات slash للسماح لك بتحديد أسماء ملفات فريدة تشبه مسارات المجلدات الكاملة التي اعتدنا رؤيتها في أنظمة الملفات.

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

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

يبدأ Firebase Security Rules for 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.

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

بالإضافة إلى الإشارة إلى ملف واحد، يمكن لـ 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";
}

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

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

كما ذكرنا من قبل، لا يوجد هيكل هرمي داخل حزمة واحدة (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 لا يتم تطبيقها بشكل متسلسل، ولا يتم تقييم القواعد إلا عندما يتطابق مسار الطلب مع مسار يتضمّن قواعد محدّدة.

الإصدار 1

يستخدم Firebase Security Rules الإصدار 1 تلقائيًا. في الإصدار 1، تتم مطابقة العناصر النائبة المتكرّرة مع عنصر اسم ملف واحد أو أكثر، وليس صفرًا أو أكثر من العناصر. وبالتالي، تتطابق match /images/{filenamePrefixWildcard}/{imageFilename=**} مع اسم ملف. مثل /images/profilePics/profile.png، ولكن ليس /images/badge.png. استخدام /images/{imagePrefixorFilename=**} بدلاً من ذلك.

يجب أن تأتي أحرف البدل المتكررة في نهاية عبارة المطابقة.

وننصحك باستخدام الإصدار 2 للاستفادة من ميزاته الأكثر فعالية.

الإصدار 2

في الإصدار 2 من Firebase Security Rules، لا تتطابق أحرف البدل المتكررة مع مسار أو أكثر عناصر. وبالتالي، مباريات /images/{filenamePrefixWildcard}/{imageFilename=**} filenames /images/profilePics/profile.png و /images/badge.png.

عليك تفعيل الإصدار 2 من خلال إضافة rules_version = '2'; في أعلى قواعد الأمان:

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

يمكنك استخدام حرف بدل متكرّر واحد كحدّ أقصى لكلّ عبارة مطابقة، ولكن في الإصدار 2، يمكنك وضع هذا الحرف البدل في أيّ مكان في عبارة المطابقة. على سبيل المثال:

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.

ملاحظة: list Rules API وبالتالي Cloud Storage List API هي متوفّرة فقط في المشاريع التي تستخدم الإصدار 2 من Rules.

يمكن أن تكون قاعدة 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 (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: