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

يسمح لك تطبيق Firebase Security Rules for 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 الحزم، وعبارة مطابقة لتحديد اسم ملف، وتعبير 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";
}

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

كما ذكرنا سابقًا، لا يتوفّر هيكل هرمي داخل حزمة 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، تتطابق أحرف البدل المتكرّرة مع صفر أو أكثر من ملف PATH. وبالتالي، يتطابق /images/{filenamePrefixWildcard}/{imageFilename=**} مع اسمَي الملفَين ‎ /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.

يمكن تفتيت قاعدة 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":