Strukturieren von Cloud Firestore-Sicherheitsregeln

Mit Cloud Firestore-Sicherheitsregeln können Sie den Zugriff auf Dokumente und Sammlungen in Ihrer Datenbank steuern. Mit der flexiblen Regelsyntax können Sie Regeln erstellen, die alles abdecken, von allen Schreibvorgängen in der gesamten Datenbank bis hin zu Vorgängen an einem bestimmten Dokument.

In diesem Handbuch werden die grundlegende Syntax und Struktur von Sicherheitsregeln beschrieben. Kombinieren Sie diese Syntax mit Sicherheitsregelbedingungen, um vollständige Regelsätze zu erstellen.

Dienst- und Datenbankdeklaration

Cloud Firestore-Sicherheitsregeln beginnen immer mit der folgenden Erklärung:

service cloud.firestore {
  match /databases/{database}/documents {
    // ...
  }
}

Die Deklaration des service cloud.firestore beschränkt die Regeln auf Cloud Firestore und verhindert so Konflikte zwischen Cloud Firestore-Sicherheitsregeln und Regeln für andere Produkte wie Cloud Storage.

Die match /databases/{database}/documents Deklaration gibt an, dass Regeln mit jeder Cloud Firestore-Datenbank im Projekt übereinstimmen sollen. Derzeit verfügt jedes Projekt nur über eine einzige Datenbank mit dem Namen (default) .

Grundlegende Lese-/Schreibregeln

Grundregeln bestehen aus einer match Anweisung, die einen Dokumentpfad angibt, und einem allow , der detailliert angibt, wann das Lesen der angegebenen Daten zulässig ist:

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

Alle Übereinstimmungsanweisungen sollten auf Dokumente verweisen, nicht auf Sammlungen. Eine Match-Anweisung kann auf ein bestimmtes Dokument verweisen, wie in match /cities/SF , oder Platzhalter verwenden, um auf ein beliebiges Dokument im angegebenen Pfad zu verweisen, wie in match /cities/{city} .

Im obigen Beispiel verwendet die match-Anweisung die Platzhaltersyntax {city} . Dies bedeutet, dass die Regel für jedes Dokument in der cities gilt, z. B. /cities/SF oder /cities/NYC . Wenn die allow in der Match-Anweisung ausgewertet werden, wird die city in den Namen des Stadtdokuments aufgelöst, z. B. SF oder NYC .

Granulare Operationen

In manchen Situationen ist es sinnvoll, read und write in detailliertere Vorgänge aufzuteilen. Beispielsweise möchte Ihre App möglicherweise andere Bedingungen für die Dokumenterstellung als für das Löschen von Dokumenten erzwingen. Oder Sie möchten möglicherweise das Lesen einzelner Dokumente zulassen, große Abfragen jedoch ablehnen.

Eine read kann in get und list unterteilt werden, während eine write in create , update und delete unterteilt werden kann:

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

Hierarchische Daten

Daten in Cloud Firestore sind in Dokumentensammlungen organisiert, und jedes Dokument kann die Hierarchie durch Untersammlungen erweitern. Es ist wichtig zu verstehen, wie Sicherheitsregeln mit hierarchischen Daten interagieren.

Stellen Sie sich die Situation vor, in der jedes Dokument in der cities eine Untersammlung landmarks enthält. Sicherheitsregeln gelten nur für den übereinstimmenden Pfad, daher gelten die für die cities definierten Zugriffskontrollen nicht für die Untersammlung landmarks . Schreiben Sie stattdessen explizite Regeln, um den Zugriff auf Untersammlungen zu steuern:

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

Beim Verschachteln match Anweisungen ist der Pfad der inneren match Anweisung immer relativ zum Pfad der äußeren match Anweisung. Die folgenden Regelsätze sind daher gleichwertig:

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

Rekursive Platzhalter

Wenn Sie möchten, dass Regeln auf eine beliebig tiefe Hierarchie angewendet werden, verwenden Sie die rekursive Platzhaltersyntax {name=**} . Zum Beispiel:

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

Bei Verwendung der rekursiven Platzhaltersyntax enthält die Platzhaltervariable das gesamte passende Pfadsegment, auch wenn sich das Dokument in einer tief verschachtelten Untersammlung befindet. Beispielsweise würden die oben aufgeführten Regeln mit einem Dokument übereinstimmen, das sich unter /cities/SF/landmarks/coit_tower befindet, und der Wert der document wäre SF/landmarks/coit_tower .

Beachten Sie jedoch, dass das Verhalten rekursiver Platzhalter von der Regelversion abhängt.

Version 1

Sicherheitsregeln verwenden standardmäßig Version 1. In Version 1 stimmen rekursive Platzhalter mit einem oder mehreren Pfadelementen überein. Sie stimmen nicht mit einem leeren Pfad überein, daher stimmt match /cities/{city}/{document=**} mit Dokumenten in Untersammlungen, aber nicht mit der cities überein, wohingegen match /cities/{document=**} mit beiden Dokumenten in der Sammlung übereinstimmt cities und Untersammlungen.

Rekursive Platzhalter müssen am Ende einer Match-Anweisung stehen.

Version 2

In Version 2 der Sicherheitsregeln stimmen rekursive Platzhalter mit null oder mehr Pfadelementen überein. match/cities/{city}/{document=**} gleicht Dokumente in allen Untersammlungen sowie Dokumente in der cities ab.

Sie müssen sich für Version 2 anmelden, indem Sie rules_version = '2'; ganz oben in Ihren Sicherheitsregeln:

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

Sie können höchstens einen rekursiven Platzhalter pro Match-Anweisung verwenden, aber in Version 2 können Sie diesen Platzhalter an einer beliebigen Stelle in der Match-Anweisung platzieren. Zum Beispiel:

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

Wenn Sie Sammlungsgruppenabfragen verwenden, müssen Sie Version 2 verwenden, siehe Sichern von Sammlungsgruppenabfragen .

Überlappende Match-Anweisungen

Es ist möglich, dass ein Dokument mit mehr als einer match Anweisung übereinstimmt. Falls mehrere allow mit einer Anfrage übereinstimmen, wird der Zugriff zugelassen, wenn eine der Bedingungen true ist:

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

Im obigen Beispiel sind alle Lese- und Schreibvorgänge in der Sammlung „ cities “ zulässig, da die zweite Regel immer true ist, obwohl die erste Regel immer „ false ist.

Grenzwerte der Sicherheitsregeln

Beachten Sie beim Arbeiten mit Sicherheitsregeln die folgenden Einschränkungen:

Grenze Einzelheiten
Maximale Anzahl von exists() , get() - und getAfter() Aufrufen pro Anfrage
  • 10 für Einzeldokumentanfragen und Abfrageanfragen.
  • 20 für das Lesen mehrerer Dokumente, Transaktionen und Batch-Schreibvorgänge. Für jeden Vorgang gilt auch die bisherige Grenze von 10.

    Stellen Sie sich beispielsweise vor, Sie erstellen eine Batch-Schreibanforderung mit drei Schreibvorgängen und Ihre Sicherheitsregeln verwenden zwei Dokumentzugriffsaufrufe, um jeden Schreibvorgang zu validieren. In diesem Fall verwendet jeder Schreibvorgang zwei seiner 10 Zugriffsaufrufe und die gestapelte Schreibanforderung verwendet 6 seiner 20 Zugriffsaufrufe.

Das Überschreiten eines dieser Grenzwerte führt zu einem Fehler, bei dem die Berechtigung verweigert wurde.

Einige Dokumentzugriffsaufrufe werden möglicherweise zwischengespeichert und zwischengespeicherte Aufrufe werden nicht auf die Grenzwerte angerechnet.

Maximale Tiefe der verschachtelten match Anweisung 10
Maximale Pfadlänge in Pfadsegmenten, die innerhalb einer Reihe verschachtelter match Anweisungen zulässig ist 100
Maximal zulässige Anzahl von Pfaderfassungsvariablen innerhalb einer Reihe verschachtelter match Anweisungen 20
Maximale Funktionsaufruftiefe 20
Maximale Anzahl von Funktionsargumenten 7
Maximale Anzahl von let Variablenbindungen pro Funktion 10
Maximale Anzahl rekursiver oder zyklischer Funktionsaufrufe 0 (nicht erlaubt)
Maximale Anzahl ausgewerteter Ausdrücke pro Anfrage 1.000
Maximale Größe eines Regelsatzes Regelsätze müssen zwei Größenbeschränkungen einhalten:
  • eine 256-KB-Grenze für die Größe der Regelsatztextquelle, die über die Firebase-Konsole oder über die CLI mithilfe von firebase deploy veröffentlicht wird.
  • eine 250-KB-Grenze für die Größe des kompilierten Regelsatzes, die sich ergibt, wenn Firebase die Quelle verarbeitet und im Back-End aktiviert.

Nächste Schritte