ساختاردهی Cloud Firestore Security Rules

Cloud Firestore Security Rules به شما امکان می‌دهد دسترسی به اسناد و مجموعه‌ها را در پایگاه داده‌تان کنترل کنید. نحو قوانین انعطاف‌پذیر به شما امکان می‌دهد قوانینی ایجاد کنید که با هرچیزی مطابقت داشته باشند، از همه نوشتن‌ها در کل پایگاه داده گرفته تا عملیات روی یک سند خاص.

این راهنما نحو و ساختار پایه قوانین امنیتی را شرح می‌دهد. این نحو را با شرایط قوانین امنیتی ترکیب کنید تا مجموعه‌های کامل قوانین را ایجاد کنید.

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 Firestore data.

اظهارنامه سرویس و پایگاه داده

‫Cloud Firestore Security Rules همیشه با اظهارنامه زیر شروع می‌شود:

service cloud.firestore {
  // The {database} wildcard allows the rules to reference any database,
  // but these rules are only active on databases where they are explicitly deployed.
  match /databases/{database}/documents {
    // ...
  }
}

اعلامیه service cloud.firestore دامنه قوانین را به قوانین محدود می‌کند و از تداخل بین Cloud Firestore Security Rules و قوانین سایر محصولات مانند Cloud Storage جلوگیری می‌کند.

اعلامیه match /databases/{database}/documents مشخص می‌کند که قوانین باید با هر پایگاه داده Rules در پروژه مطابقت داشته باشد. درحالی‌که یک پروژه می‌تواند تا ۱۰۰ پایگاه داده داشته باشد، فقط اولین پایگاه داده ایجادشده به‌عنوان پیش‌فرض تعیین می‌شود.

Cloud Firestore Security Rules به‌طور جداگانه برای هر پایگاه داده نام‌گذاری‌شده در پروژه شما اعمال می‌شود. این یعنی اگر چند پایگاه داده ایجاد کنید، باید قوانین را برای هرکدام به‌طور جداگانه مدیریت و مستقر کنید. برای دستورالعمل‌های دقیق درباره استقرار به‌روزرسانی‌ها، به استقرار به‌روزرسانی‌ها مراجعه کنید.

قوانین خواندن/نوشتن پایه

قوانین پایه شامل یک عبارت match است که مسیر سند را مشخص می‌کند و یک عبارت allow که جزئیات زمان مجاز بودن خواندن داده‌های مشخص‌شده را شرح می‌دهد:

service cloud.firestore {
  match /databases/{database}/documents {

    // Match any document in the 'cities' collection
    match /cities/{city} {
      allow read: if <condition>;
      allow write: if <condition>;
    }
  }
}

همه عبارت‌های منطبق باید به اسناد اشاره کنند، نه مجموعه‌ها. عبارت match می‌تواند به سند خاصی اشاره کند، مانند match /cities/SF، یا از نویسه‌های عام برای اشاره به هر سندی در مسیر مشخص‌شده استفاده کند، مانند match /cities/{city}.

در مثال بالا، عبارت مطابقت از نحو نویسه عام {city} استفاده می‌کند. یعنی این قانون بر هر سندی در مجموعه cities اعمال می‌شود، مثل /cities/SF یا /cities/NYC. وقتی عبارت‌های allow در عبارت مطابقت ارزیابی می‌شوند، متغیر city به نام سند شهر، مانند SF یا NYC، حل می‌شود.

عملیات جزئی

در برخی شرایط، مفید است که read و write را به عملیات‌های جزئی‌تر تقسیم کنید. برای مثال، ممکن است برنامه‌تان بخواهد شرایط متفاوتی را برای ایجاد سند نسبت به حذف سند اعمال کند. یا ممکن است بخواهید خواندن سند تکی را مجاز کنید اما پُرسمان‌های بزرگ را رد کنید.

قانون read را می‌توان به get و list تقسیم کرد، درحالی‌که قانون write را می‌توان به create، update، و delete تقسیم کرد:

service cloud.firestore {
  match /databases/{database}/documents {
    // A read rule can be divided into get and list rules

    match /cities/{city} {
      // Applies to single document read requests
      allow get: if <condition>;

      // Applies to queries and collection read requests
      allow list: if <condition>;
    }
    // A write rule can be divided into create, update, and delete rules
    match /cities/{city} {
      // Applies to writes to nonexistent documents
      allow create: if <condition>;

      // Applies to writes to existing documents
      allow update: if <condition>;

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

داده‌های سلسله‌مراتبی

داده‌ها در «قوانین» در مجموعه‌هایی از اسناد سازمان‌دهی می‌شوند و هر سند ممکن است سلسله‌مراتب را ازطریق زیرمجموعه‌ها گسترش دهد. مهم است که بدانید قوانین امنیتی چگونه با داده‌های سلسله‌مراتبی تعامل دارند.

موقعیتی را درنظر بگیرید که هر سند در مجموعه cities حاوی یک زیرمجموعه landmarks است. قوانین امنیتی فقط در مسیر منطبق اعمال می‌شوند، بنابراین کنترل‌های دسترسی تعریف‌شده در مجموعه cities برای زیرمجموعه landmarks اعمال نمی‌شوند. به‌جای آن، قوانین صریحی برای کنترل دسترسی به زیرمجموعه‌ها بنویسید:

service cloud.firestore {
  match /databases/{database}/documents {
    match /cities/{city} {
      allow read, write: if <condition>;

        // Explicitly define rules for the 'landmarks' subcollection
        match /landmarks/{landmark} {
          allow read, write: if <condition>;
        }
    }
  }
}

هنگام تودرتو کردن عبارت‌های match، مسیر عبارت match داخلی همیشه نسبت به مسیر عبارت match خارجی است. بنابراین، مجموعه‌قوانین زیر معادل هستند:

service cloud.firestore {
  match /databases/{database}/documents {
    match /cities/{city} {
      match /landmarks/{landmark} {
        allow read, write: if <condition>;
      }
    }
  }
}

service cloud.firestore {
  match /databases/{database}/documents {
    match /cities/{city}/landmarks/{landmark} {
      allow read, write: if <condition>;
    }
  }
}

کارت‌های جایگزین تکرارشونده

اگر می‌خواهید قوانین برای سلسله‌مراتب عمیق دلخواه اعمال شود، از نحو نویسه عام بازگشتی، {name=**}، استفاده کنید. برای مثال:

service cloud.firestore {
  match /databases/{database}/documents {
    // Matches any document in the cities collection as well as any document
    // in a subcollection.
    match /cities/{document=**} {
      allow read, write: if <condition>;
    }
  }
}

When using the recursive wildcard syntax, the wildcard variable will contain the entire matching path segment, even if the document is located in a deeply nested subcollection. برای مثال، قوانین فهرست‌شده در بالا با سندی که در /cities/SF/landmarks/coit_tower قرار دارد مطابقت دارد و مقدار متغیر document برابر با SF/landmarks/coit_tower خواهد بود.

اما توجه داشته باشید که رفتار نویسه‌های عام بازگشتی به نسخه قوانین بستگی دارد.

rules_version = '2';
service cloud.firestore {
 match /databases/{database}/documents {
   // Matches any document in the cities collection as well as any document
   // in a subcollection.
   match /cities/{city}/{document=**} {
     allow read, write: if <condition>;
   }
 }
}

rules_version = '2';
service cloud.firestore {
 match /databases/{database}/documents {
   // Matches any document in the songs collection group
   match /{path=**}/songs/{song} {
     allow read, write: if <condition>;
   }
 }
}

اگر از پرسمان‌های گروه مجموعه استفاده می‌کنید، باید از نسخه ۲ استفاده کنید، ایمن‌سازی پرسمان‌های گروه مجموعه را ببینید.

بیانیه‌های مطابقت هم‌پوشان

ممکن است یک سند با بیش‌از یک عبارت match مطابقت داشته باشد. در مواردی که چند عبارت allow با درخواست مطابقت داشته باشد، اگر هرکدام از شرایط true باشد، دسترسی مجاز است:

service cloud.firestore {
  match /databases/{database}/documents {
    // Matches any document in the 'cities' collection.
    match /cities/{city} {
      allow read, write: if false;
    }

    // Matches any document in the 'cities' collection or subcollections.
    match /cities/{document=**} {
      allow read, write: if true;
    }
  }
}

در مثال بالا، همه خواندن‌ها و نوشتن‌ها در مجموعه cities مجاز خواهد بود زیرا قانون دوم همیشه true است، هرچند قانون اول همیشه false است.

محدودیت‌های قانون امنیتی

هنگام کار با قوانین امنیتی، به محدودیت‌های زیر توجه کنید:

مراحل بعدی

• شرایط قوانین امنیتی سفارشی را بنویسید.
• مرجع قوانین امنیتی را بخوانید.