Cloud Firestore Security Rules 可讓您控管資料庫中文件和集合的存取權。您可以使用彈性的規則語法，建立可比對任何內容的規則，從對整個資料庫的所有寫入作業，到對特定文件的作業皆可。
本指南將說明安全性規則的基本語法和結構。搭配使用這個語法和安全性規則條件，即可建立完整的規則集。
服務和資料庫宣告
Cloud Firestore Security Rules 一律會以以下宣告開頭：
service cloud.firestore {
match /databases/{database}/documents {
// ...
}
}
service cloud.firestore 宣告會將規則範圍限制為 Cloud Firestore，避免 Cloud Firestore Security Rules 與 Cloud Storage 等其他產品的規則發生衝突。
match /databases/{database}/documents 宣告會指定規則應與專案中的任何 Cloud Firestore 資料庫相符。目前每個專案都只有一個名為 (default) 的資料庫。
基本讀取/寫入規則
基本規則包含 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>;
}
}
}
階層式資料
Cloud Firestore 中的資料會整理成文件集合，每份文件都可能透過子集合擴充階層。因此，請務必瞭解安全性規則與階層資料的互動方式。
請考慮以下情況：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。
不過，請注意，遞迴萬用字元的行為取決於規則版本。
版本 1
安全性規則預設使用第 1 版。在 1 版中，遞迴萬用字元會比對一或多個路徑項目。由於這兩者不符合空白路徑，因此 match /cities/{city}/{document=**} 只會比對子集合中的文件，而不會比對 cities 集合中的文件；match /cities/{document=**} 則會比對 cities 集合和子集合中的文件。
遞迴萬用字元必須放在比對陳述式的結尾。
版本 2
在安全性規則第 2 版中，遞迴萬用字元會比對零個或多個路徑項目。match/cities/{city}/{document=**} 會比對任何子集合中的文件，以及 cities 集合中的文件。
您必須在安全性規則頂端新增 rules_version = '2';，才能選擇採用第 2 版：
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>;
}
}
}
每個比對陳述式最多只能有一個遞迴萬用字元，但在第 2 版中，您可以在比對陳述式的任何位置放置這個萬用字元。例如：
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 也一樣。
安全性規則限制
使用安全性規則時，請注意下列限制：
| 限制 | 說明 |
|---|---|
每項要求的 exists()、get() 和 getAfter() 呼叫數量上限 |
超過任一項限制都會引發權限遭拒的錯誤。 系統可能會快取部分的文件存取呼叫，已快取的呼叫不會計入限制中。 |
巢狀 match 陳述式深度上限 |
10 |
一組巢狀 match 陳述式中允許的路徑長度上限 (以路徑區段為單位) |
100 |
一組巢狀 match 陳述式中允許的路徑擷取變數數量上限 |
20 |
| 函式呼叫深度上限 | 20 |
| 函式引數數量上限 | 7 |
每個函式的 let 變數繫結上限 |
10 |
| 遞迴或循環函式呼叫的數量上限 | 0 (不允許) |
| 每個要求中經評估的運算式數量上限 | 1,000 個 |
| 規則集的大小上限 | 規則集必須遵守下列兩項大小限制：
|