建構 Cloud Firestore 安全性規則

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 細分為更常見的 ID 執行精細作業舉例來說，您的應用程式可能想強制執行 建立文件時以外的條件或者您可能需要 允許單一文件讀取，但拒絕大型查詢。

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。

不過請注意，遞迴萬用字元的行為取決於規則 版本。

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>;
    }
  }
}

如果您使用集合群組查詢，請務必使用 請參閱「保護集合群組查詢」一節。

重疊的比對聲明

文件可能會比對多個 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，但第 1 項 則一律為 false。

安全性規則限制

處理安全性規則時，請注意以下限制：

後續步驟

• 編寫自訂安全性規則條件。
• 閱讀安全性規則參考資料。