安全地查詢資料

本頁面將延續建立安全性規則編寫安全性規則的條件中的概念,說明 Cloud Firestore Security Rules 如何與查詢互動。本課程將深入探討安全性規則如何影響您編寫的查詢,並說明如何確保查詢使用與安全性規則相同的限制條件。本頁也說明如何編寫安全性規則,根據 limitorderBy 等查詢屬性允許或拒絕查詢。

規則不是篩選器

編寫查詢以擷取文件時,請注意安全性規則並非篩選器,查詢結果只能是全部或無。為節省您的時間和資源,Cloud Firestore 會根據潛在的結果集評估查詢,而不是所有文件的實際欄位值。如果查詢可能會傳回用戶端沒有權限讀取的文件,整個要求就會失敗。

查詢和安全性規則

如以下範例所示,您必須按照安全性規則的限制編寫查詢。

根據 auth.uid 保護及查詢文件

以下範例說明如何編寫查詢,擷取受安全性規則保護的文件。請考慮包含 story 文件集合的資料庫:

/stories/{storyid}

{
  title: "A Great Story",
  content: "Once upon a time...",
  author: "some_auth_id",
  published: false
}

除了 titlecontent 欄位之外,每份文件也會儲存用於存取權控管的 authorpublished 欄位。這些範例假設應用程式會使用 Firebase 驗證,將 author 欄位設為建立文件的使用者 UID。Firebase 認證也會在安全性規則中填入 request.auth 變數。

下列安全性規則使用 request.authresource.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 查詢 (orinarray-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 變數包含查詢的 limitoffsetorderBy 屬性。舉例來說,安全性規則可以拒絕任何未將擷取的文件數量上限限制在特定範圍內的查詢:

allow list: if request.query.limit <= 10;

下列規則集說明如何編寫安全性規則,以便評估對查詢的限制。本範例會透過下列變更擴充先前的 stories 規則集:

  • 規則集會將讀取規則分為 getlist 的規則。
  • 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 的所有集合的集合群組中擷取結果。本節將說明如何使用安全性規則保護集合群組查詢。

根據集合群組保護及查詢文件

在安全性規則中,您必須為收集群組編寫規則,明確允許收集群組查詢:

  1. 請確認 rules_version = '2'; 是規則集的第一行。集合群組查詢需要使用安全規則第 2 版的新遞迴萬用字元 {name=**} 行為。
  2. 使用 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
    }
  }
}

後續步驟