本頁面將延續建立安全性規則和編寫安全性規則的條件中的概念,說明 Cloud Firestore Security Rules 如何與查詢互動。本課程將深入探討安全性規則如何影響您編寫的查詢,並說明如何確保查詢使用與安全性規則相同的限制條件。本頁也說明如何編寫安全性規則,根據 limit
和 orderBy
等查詢屬性允許或拒絕查詢。
規則不是篩選器
編寫查詢以擷取文件時,請注意安全性規則並非篩選器,查詢結果只能是全部或無。為節省您的時間和資源,Cloud Firestore 會根據潛在的結果集評估查詢,而不是所有文件的實際欄位值。如果查詢可能會傳回用戶端沒有權限讀取的文件,整個要求就會失敗。
查詢和安全性規則
如以下範例所示,您必須按照安全性規則的限制編寫查詢。
根據 auth.uid
保護及查詢文件
以下範例說明如何編寫查詢,擷取受安全性規則保護的文件。請考慮包含 story
文件集合的資料庫:
/stories/{storyid}
{
title: "A Great Story",
content: "Once upon a time...",
author: "some_auth_id",
published: false
}
除了 title
和 content
欄位之外,每份文件也會儲存用於存取權控管的 author
和 published
欄位。這些範例假設應用程式會使用 Firebase 驗證,將 author
欄位設為建立文件的使用者 UID。Firebase 認證也會在安全性規則中填入 request.auth
變數。
下列安全性規則使用 request.auth
和 resource.data
變數,將每個 story
的讀取和寫入權限限制給作者:
service cloud.firestore {
match /databases/{database}/documents {
match /stories/{storyid} {
// Only the authenticated user who authored the document can read or write
allow read, write: if request.auth != null && request.auth.uid == resource.data.author;
}
}
}
假設您的應用程式包含一個頁面,可向使用者顯示他們撰寫的 story
文件清單。您可能會預期可以使用下列查詢來填入這個頁面。不過,由於這項查詢未納入與安全性規則相同的限制,因此會失敗:
無效:查詢限制條件不符合安全規則限制條件
// This query will fail
db.collection("stories").get()
即使當前使用者確實是每份 story
文件的作者,查詢仍會失敗。發生這種情況的原因是,Cloud Firestore 在套用安全性規則時,會根據查詢的潛在結果集評估查詢,而非根據資料庫中文件的實際屬性評估查詢。如果查詢「可能」包含違反安全性規則的文件,查詢就會失敗。
相反地,以下查詢會成功,因為它在 author
欄位上包含與安全性規則相同的限制條件:
有效:查詢限制條件符合安全性規則限制條件
var user = firebase.auth().currentUser;
db.collection("stories").where("author", "==", user.uid).get()
根據欄位保護及查詢文件
為進一步說明查詢和規則之間的互動情形,下方的安全性規則會擴充 stories
集合的讀取權限,讓任何使用者都能讀取 story
文件 (published
欄位設為 true
)。
service cloud.firestore {
match /databases/{database}/documents {
match /stories/{storyid} {
// Anyone can read a published story; only story authors can read unpublished stories
allow read: if resource.data.published == true || (request.auth != null && request.auth.uid == resource.data.author);
// Only story authors can write
allow write: if request.auth != null && request.auth.uid == resource.data.author;
}
}
}
針對已發布的網頁執行查詢時,必須納入與安全性規則相同的限制條件:
db.collection("stories").where("published", "==", true).get()
查詢限制 .where("published", "==", true)
可確保 resource.data.published
為任何結果的 true
。因此,這項查詢符合安全性規則,且可讀取資料。
OR
個查詢
當 Cloud Firestore 針對規則集評估邏輯 OR
查詢 (or
、in
或 array-contains-any
) 時,會分別評估每個比較值。每個比較值都必須符合安全規則限制。例如,針對下列規則:
match /mydocuments/{doc} {
allow read: if resource.data.x > 5;
}
無效:查詢無法保證所有潛在文件都會顯示 x > 5
// These queries will fail
query(db.collection("mydocuments"),
or(where("x", "==", 1),
where("x", "==", 6)
)
)
query(db.collection("mydocuments"),
where("x", "in", [1, 3, 6, 42, 99])
)
有效:查詢可確保所有潛在文件的 x > 5
query(db.collection("mydocuments"),
or(where("x", "==", 6),
where("x", "==", 42)
)
)
query(db.collection("mydocuments"),
where("x", "in", [6, 42, 99, 105, 200])
)
評估查詢限制
安全規則也可以根據限制條件接受或拒絕查詢。request.query
變數包含查詢的 limit
、offset
和 orderBy
屬性。舉例來說,安全性規則可以拒絕任何未將擷取的文件數量上限限制在特定範圍內的查詢:
allow list: if request.query.limit <= 10;
下列規則集說明如何編寫安全性規則,以便評估對查詢的限制。本範例會透過下列變更擴充先前的 stories
規則集:
- 規則集會將讀取規則分為
get
和list
的規則。 get
規則會限制單一文件的擷取作業,僅限於公用文件或使用者撰寫的文件。list
規則適用與get
相同的限制,但適用於查詢。也會檢查查詢限制,然後拒絕任何沒有限制或限制超過 10 的查詢。- 規則集定義了
authorOrPublished()
函式,以免程式碼重複。
service cloud.firestore {
match /databases/{database}/documents {
match /stories/{storyid} {
// Returns `true` if the requested story is 'published'
// or the user authored the story
function authorOrPublished() {
return resource.data.published == true || request.auth.uid == resource.data.author;
}
// Deny any query not limited to 10 or fewer documents
// Anyone can query published stories
// Authors can query their unpublished stories
allow list: if request.query.limit <= 10 &&
authorOrPublished();
// Anyone can retrieve a published story
// Only a story's author can retrieve an unpublished story
allow get: if authorOrPublished();
// Only a story's author can write to a story
allow write: if request.auth.uid == resource.data.author;
}
}
}
收集群組查詢和安全性規則
根據預設,查詢範圍會限定為單一集合,且只從該集合擷取結果。您可以使用集合群組查詢,從包含相同 ID 的所有集合的集合群組中擷取結果。本節將說明如何使用安全性規則保護集合群組查詢。
根據集合群組保護及查詢文件
在安全性規則中,您必須為收集群組編寫規則,明確允許收集群組查詢:
- 請確認
rules_version = '2';
是規則集的第一行。集合群組查詢需要使用安全規則第 2 版的新遞迴萬用字元{name=**}
行為。 - 使用
match /{path=**}/[COLLECTION_ID]/{doc}
為您的收集群組編寫規則。
舉例來說,假設論壇以 forum
文件的形式進行組織,其中包含 posts
子集合:
/forums/{forumid}/posts/{postid}
{
author: "some_auth_id",
authorname: "some_username",
content: "I just read a great story.",
}
在這個應用程式中,我們讓擁有者可以編輯貼文,而已驗證的使用者則可閱讀貼文:
service cloud.firestore {
match /databases/{database}/documents {
match /forums/{forumid}/posts/{post} {
// Only authenticated users can read
allow read: if request.auth != null;
// Only the post author can write
allow write: if request.auth != null && request.auth.uid == resource.data.author;
}
}
}
任何已驗證的使用者都可以擷取任何單一論壇的貼文:
db.collection("forums/technology/posts").get()
但如果您想向目前使用者顯示所有論壇中的貼文,該怎麼做呢?您可以使用集合群組查詢,從所有 posts
集合中擷取結果:
var user = firebase.auth().currentUser;
db.collectionGroup("posts").where("author", "==", user.uid).get()
在安全性規則中,您必須為 posts
集合群組編寫讀取或列舉規則,才能允許這項查詢:
rules_version = '2';
service cloud.firestore {
match /databases/{database}/documents {
// Authenticated users can query the posts collection group
// Applies to collection queries, collection group queries, and
// single document retrievals
match /{path=**}/posts/{post} {
allow read: if request.auth != null;
}
match /forums/{forumid}/posts/{postid} {
// Only a post's author can write to a post
allow write: if request.auth != null && request.auth.uid == resource.data.author;
}
}
}
不過,請注意,這些規則會套用至所有 ID 為 posts
的集合,不限階層。例如,下列規則適用於所有 posts
集合:
/posts/{postid}
/forums/{forumid}/posts/{postid}
/forums/{forumid}/subforum/{subforumid}/posts/{postid}
根據欄位保護集合群組查詢
與單一集合查詢一樣,集合群組查詢也必須符合安全性規則設定的限制。舉例來說,我們可以像上述 stories
範例一樣,為每個論壇貼文新增 published
欄位:
/forums/{forumid}/posts/{postid}
{
author: "some_auth_id",
authorname: "some_username",
content: "I just read a great story.",
published: false
}
接著,我們可以根據 published
狀態和 author
的發布內容,為 posts
收集群組編寫規則:
rules_version = '2';
service cloud.firestore {
match /databases/{database}/documents {
// Returns `true` if the requested post is 'published'
// or the user authored the post
function authorOrPublished() {
return resource.data.published == true || request.auth.uid == resource.data.author;
}
match /{path=**}/posts/{post} {
// Anyone can query published posts
// Authors can query their unpublished posts
allow list: if authorOrPublished();
// Anyone can retrieve a published post
// Authors can retrieve an unpublished post
allow get: if authorOrPublished();
}
match /forums/{forumid}/posts/{postid} {
// Only a post's author can write to a post
allow write: if request.auth.uid == resource.data.author;
}
}
}
有了這些規則,網頁、Apple 和 Android 用戶端就能執行下列查詢:
任何人都能在論壇中擷取已發布的貼文:
db.collection("forums/technology/posts").where('published', '==', true).get()
任何人都能在所有論壇中擷取作者發布的貼文:
db.collectionGroup("posts").where("author", "==", "some_auth_id").where('published', '==', true).get()
作者可以透過以下方式,在所有論壇中擷取所有已發布和未發布的文章:
var user = firebase.auth().currentUser; db.collectionGroup("posts").where("author", "==", user.uid).get()
根據集合群組和文件路徑保護及查詢文件
在某些情況下,您可能會想要根據文件路徑限制集合群組查詢。如要建立這些限制,您可以使用相同的技術,根據欄位保護及查詢文件。
請考慮以下應用程式,該應用程式會追蹤每位使用者在多個股票和加密貨幣交易所的交易:
/users/{userid}/exchange/{exchangeid}/transactions/{transaction}
{
amount: 100,
exchange: 'some_exchange_name',
timestamp: April 1, 2019 at 12:00:00 PM UTC-7,
user: "some_auth_id",
}
請留意 user
欄位。雖然我們可以從文件路徑得知哪位使用者擁有 transaction
文件,但我們會在每個 transaction
文件中複製這項資訊,因為這樣做可讓我們執行兩項操作:
撰寫集合群組查詢,限制在文件路徑中包含特定
/users/{userid}
的文件。例如:var user = firebase.auth().currentUser; // Return current user's last five transactions across all exchanges db.collectionGroup("transactions").where("user", "==", user).orderBy('timestamp').limit(5)
針對
transactions
收集資料群組的所有查詢強制執行這項限制,以免某位使用者擷取其他使用者的transaction
文件。
我們會在安全性規則中強制執行這項限制,並為 user
欄位加入資料驗證機制:
rules_version = '2';
service cloud.firestore {
match /databases/{database}/documents {
match /{path=**}/transactions/{transaction} {
// Authenticated users can retrieve only their own transactions
allow read: if resource.data.user == request.auth.uid;
}
match /users/{userid}/exchange/{exchangeid}/transactions/{transaction} {
// Authenticated users can write to their own transactions subcollections
// Writes must populate the user field with the correct auth id
allow write: if userid == request.auth.uid && request.data.user == request.auth.uid
}
}
}
後續步驟
- 如需角色型存取控制的詳細範例,請參閱「保護使用者和群組的資料存取權」。
- 請參閱安全性規則參考資料。