您可以使用 Cloud Firestore 安全性規則,控管資料庫中文件和集合的存取權。彈性的規則語法可讓您建立比對任何內容的規則,無論是所有寫入作業、整個資料庫還是特定文件的作業,都包含在內。
本指南將說明安全性規則的基本語法和結構。將這個語法與安全性規則條件結合,即可建立完整規則集。
宣告服務和資料庫
Cloud Firestore 安全性規則的開頭一律為下列宣告:
service cloud.firestore {
match /databases/{database}/documents {
// ...
}
}
service cloud.firestore
宣告會將規則的範圍限定至 Cloud Firestore,可避免 Cloud Firestore 安全性規則與 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;
}
}
}
在上述範例中,由於第二個規則一律為 false
,因此第二個規則一律為 true
,因此系統會允許 cities
集合的所有讀取和寫入作業。
安全性規則限制
處理安全性規則時,請注意以下限制:
限制 | 詳細資料 |
---|---|
每項要求的 exists() 、get() 和 getAfter() 呼叫數量上限 |
超過任一項限制都會引發權限遭拒的錯誤。 系統可能會快取部分的文件存取呼叫,已快取的呼叫不會計入限制中。 |
巢狀 match 陳述式深度上限 |
10 |
一組巢狀 match 陳述式中允許的路徑長度上限 (以路徑區段為單位) |
100 |
一組巢狀 match 陳述式中允許的路徑擷取變數數量上限 |
20 |
函式呼叫深度上限 | 20 |
函式引數數量上限 | 7 |
每個函式的 let 變數繫結上限 |
10 |
遞迴或循環函式呼叫的數量上限 | 0 (不允許) |
每個要求中經評估的運算式數量上限 | 1,000 個 |
規則集的大小上限 | 規則集必須遵守以下兩項大小限制:
|