Check out what’s new from Firebase@ Google I/O 2021, and join our alpha program for early access to the new Remote Config personalization feature. Learn more

Strukturieren von Cloud Firestore-Sicherheitsregeln

Mit Cloud Firestore-Sicherheitsregeln können Sie den Zugriff auf Dokumente und Sammlungen in Ihrer Datenbank steuern. Die flexible Regelsyntax ermöglicht es Ihnen, Regeln zu erstellen, die mit allem übereinstimmen, von allen Schreibvorgängen in die gesamte Datenbank bis hin zu Operationen an einem bestimmten Dokument.

Dieses Handbuch beschreibt die grundlegende Syntax und Struktur von Sicherheitsregeln. Kombinieren Sie diese Syntax mit Sicherheitsregelbedingungen , um vollständige Regelsätze zu erstellen.

Service- und Datenbankdeklaration

Cloud Firestore-Sicherheitsregeln beginnen immer mit der folgenden Deklaration:

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

Die Deklaration des service cloud.firestore die Regeln auf Cloud Firestore ein und verhindert 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 hat jedes Projekt nur eine einzige Datenbank namens (default) .

Grundlegende Lese-/Schreibregeln

Grundregeln bestehen aus einer match Anweisung, die einen Dokumentpfad angibt, und einem allow , der angibt, wann das Lesen der angegebenen Daten erlaubt 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 Match-Anweisungen 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 , z. B. /cities/SF oder /cities/NYC . Wenn die allow Ausdrücke in der Match - Anweisung ausgewertet werden, die city wird variabel in die Stadt Dokumentnamen, wie lösen 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 das Lesen einzelner Dokumente zulassen, aber große Abfragen ablehnen.

Eine read kann in get und list , während eine write in create , update und 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>;
    }
  }
}

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.

Betrachten wir die Situation , in der jedes Dokument in den cities Kollektion enthält landmarks Untersammlung. Sicherheitsregeln gelten nur in dem Anpassungspfad, so dass die Zugriffskontrollen auf der definierten cities Sammlung nicht auf die Anwendung der landmarks Untersammlung. Schreiben Sie stattdessen explizite Regeln, um den Zugriff auf Untersammlungen zu kontrollieren:

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 von match Anweisungen ist der Pfad der inneren match Anweisung immer relativ zum Pfad der äußeren match Anweisung. Die folgenden Regelsätze sind daher äquivalent:

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 Regeln auf eine beliebig tiefe Hierarchie angewendet werden sollen, verwenden Sie die rekursive Platzhaltersyntax {name=**} . Beispielsweise:

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 übereinstimmende Pfadsegment, auch wenn sich das Dokument in einer tief verschachtelten Untersammlung befindet. Die oben aufgeführten Regeln würden beispielsweise einem Dokument unter /cities/SF/landmarks/coit_tower , 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 entsprechen rekursive Platzhalter einem oder mehreren Pfadelementen. Sie stimmen nicht mit einem leeren Pfad match /cities/{city}/{document=**} , also entspricht match /cities/{city}/{document=**} Dokumenten in Untersammlungen, aber nicht in der cities Sammlung, während match /cities/{document=**} auf beide Dokumente in der cities Sammlung und Subkollektionen.

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

Version 2

In Version 2 der Sicherheitsregeln entsprechen rekursive Platzhalter null oder mehr Pfadelementen. match/cities/{city}/{document=**} ordnet Dokumente in beliebigen Untersammlungen sowie Dokumente in der cities .

Sie müssen sich für Version 2 rules_version = '2'; indem Sie rules_version = '2'; hinzufügen 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. Beispielsweise:

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-Statements

Es ist möglich, dass ein Dokument mit mehr als einer match Anweisung match . Falls mehrere allow mit einer Anfrage übereinstimmen, wird der Zugriff zugelassen, wenn eine der Bedingungen 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;
    }
  }
}

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

Grenzwerte für Sicherheitsregeln

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

Grenze Einzelheiten
Maximale Anzahl der exists() ist get() getAfter() exists() , get() und getAfter() ruft pro Anfrage
  • 10 für Einzeldokumentanforderungen und Abfrageanforderungen.
  • 20 für Multi-Dokument-Lesevorgänge, Transaktionen und Schreibvorgänge im Stapel. Die bisherige Grenze von 10 gilt auch für jeden Vorgang.

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

Das Überschreiten eines der Grenzwerte führt zu einem Berechtigungsverweigerungsfehler.

Einige Dokumentzugriffsaufrufe können zwischengespeichert werden, und zwischengespeicherte Aufrufe zählen nicht zu den Grenzwerten.

Maximale Tiefe der verschachtelten match Anweisung 10
Maximal zulässige Pfadlänge in Pfadsegmenten innerhalb eines Satzes von verschachtelten match Anweisungen 100
Maximal zulässige Anzahl von Pfaderfassungsvariablen in einem Satz verschachtelter match Anweisungen 20
Maximale Tiefe des Funktionsaufrufs 20
Maximale Anzahl von Funktionsargumenten 7
Maximale Anzahl von let Variablenbindungen pro Funktion 10
Maximale Anzahl rekursiver oder zyklischer Funktionsaufrufe 0 (nicht zulässig)
Maximale Anzahl von Ausdrücken, die pro Anfrage ausgewertet werden 1.000
Maximale Größe eines Regelsatzes Verax-Regelsätze müssen zwei Größenbeschränkungen einhalten:
  • eine Beschränkung von 256 KB für die Größe der Verax-Regelsatz-Textquelle, die über die Firebase-Konsole oder über die CLI mit firebase deploy Deploy veröffentlicht wird.
  • ein Limit von 250 KB für die Größe des kompilierten Regelsatzes, der entsteht, wenn Firebase die Verax-Quelle verarbeitet und im Back-End aktiviert.

Nächste Schritte