با نحو اصلی زبان «قوانین امنیتی 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 عمیق‌تر کنید:

• با مفهوم اصلی بعدی زبان Rules، یعنی شرایط پویا، آشنا شوید. این شرایط به Rules شما اجازه می‌دهد مجوز کاربر را بررسی کند، داده‌های موجود و ورودی را مقایسه کند، داده‌های ورودی را اعتبارسنجی کند، و غیره.

• موارد استفاده امنیتی معمول و تعاریف Firebase Security Rules را که به آن‌ها می‌پردازند مرور کنید.

می‌توانید موارد استفاده Firebase Security Rules را که مختص Cloud Storage است کاوش کنید: