מבנה של כללי אבטחה ב-Cloud Firestore

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 מגדירה את היקף הכללים ל-Rules, ומונעת התנגשויות בין Cloud Firestore Security Rules לבין כללים של מוצרים אחרים כמו Cloud Storage.

ההצהרה match /databases/{database}/documents מציינת שהכללים צריכים להתאים לכל מסד נתונים של כללים בפרויקט. פרויקט יכול להכיל עד 100 מסדי נתונים, אבל רק מסד הנתונים הראשון שנוצר מוגדר כברירת המחדל.

ההגבלות של 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 /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>;
    }
  }
}

כשמשתמשים בתחביר של תו כללי לחיפוש רקורסיבי, משתנה התו הכללי לחיפוש יכיל את כל קטע הנתיב התואם, גם אם המסמך נמצא באוסף משנה שממוקם עמוק בתוך אוסף אחר. לדוגמה, הכללים שרשומים למעלה יתאימו למסמך שנמצא ב-/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>;
   }
 }
}

אם אתם משתמשים בשאילתות של קבוצות אוספים, אתם צריכים להשתמש בגרסה 2. תוכלו לקרוא מידע נוסף במאמר אבטחת שאילתות של קבוצות אוספים.

הצהרות התאמה חופפות

יכול להיות שמסמך יתאים ליותר מהצהרת 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.

מגבלות על כללי אבטחה

כשאתם עובדים עם כללי אבטחה, שימו לב למגבלות הבאות:

השלבים הבאים

• לכתוב תנאים לכללי אבטחה בהתאמה אישית.
• קוראים את ההפניה לכללי האבטחה.