Reguły zabezpieczeń Cloud Firestore pozwalają kontrolować dostęp do dokumentów i kolekcji w bazie danych. Elastyczna składnia reguł umożliwia tworzenie reguł, które pasują do wszystkiego – od wszystkich zapisów do całej bazy danych po operacje na określonym dokumencie.
W tym przewodniku opisano podstawową składnię i strukturę reguł zabezpieczeń. Połącz tę składnię z warunkami reguł zabezpieczeń, aby utworzyć pełne zestawy reguł.
Deklaracja dotycząca usługi i bazy danych
Reguły zabezpieczeń Cloud Firestore zawsze zaczynają się od tej deklaracji:
service cloud.firestore {
match /databases/{database}/documents {
// ...
}
}
Deklaracja service cloud.firestore
ogranicza reguły do Cloud Firestore, co zapobiega konfliktom między regułami zabezpieczeń Cloud Firestore a regułami innych usług, takich jak Cloud Storage.
Deklaracja match /databases/{database}/documents
określa, że reguły powinny pasować do dowolnej bazy danych Cloud Firestore w projekcie. Obecnie każdy projekt ma tylko 1 bazę danych o nazwie (default)
.
Podstawowe reguły odczytu/zapisu
Reguły podstawowe składają się z instrukcji match
określającej ścieżkę dokumentu i wyrażenia allow
ze szczegółowymi informacjami o tym, że odczyt określonych danych jest dozwolony:
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>;
}
}
}
Wszystkie instrukcje dopasowania powinny wskazywać dokumenty, a nie kolekcje. Instrukcja dopasowania może wskazywać konkretny dokument, np. match /cities/SF
, lub używać symboli wieloznacznych do wskazywania dowolnego dokumentu w danej ścieżce, np. match /cities/{city}
.
W przykładzie powyżej instrukcja dopasowania używa składni z symbolem wieloznacznym {city}
.
Oznacza to, że reguła ma zastosowanie do wszystkich dokumentów w kolekcji cities
, np. /cities/SF
czy /cities/NYC
. Podczas oceniania wyrażeń allow
w instrukcjach dopasowania zmienna city
zwróci nazwę dokumentu miasta, np. SF
lub NYC
.
Operacje szczegółowe
W niektórych sytuacjach dobrze jest podzielić read
i write
na bardziej szczegółowe operacje. Na przykład aplikacja może wymuszać inne warunki przy tworzeniu dokumentów niż przy usuwaniu dokumentów. Możesz też zezwolić na odczyt pojedynczego dokumentu, ale odrzucać duże zapytania.
Reguły read
można podzielić na get
i list
, a regułę write
na create
, update
i 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>;
}
}
}
Dane hierarchiczne
Dane w Cloud Firestore są porządkowane w kolekcje dokumentów, a każdy dokument może rozszerzać hierarchię za pomocą podkolekcji. Ważne jest, aby zrozumieć, jak reguły zabezpieczeń współdziałają z danymi hierarchicznymi.
Weź pod uwagę sytuację, w której każdy dokument w kolekcji cities
zawiera kolekcję podrzędną landmarks
. Reguły zabezpieczeń są stosowane tylko w przypadku dopasowanej ścieżki, więc ustawienia dostępu zdefiniowane w kolekcji cities
nie mają zastosowania do podkolekcji landmarks
. Zamiast tego utwórz jawne reguły, aby kontrolować dostęp do podkolekcji:
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>;
}
}
}
}
Gdy zagnieżdżasz instrukcje match
, ścieżka wewnętrznej instrukcji match
jest zawsze określana względem ścieżki zewnętrznej instrukcji match
. Te zestawy reguł są więc równoważne:
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>;
}
}
}
Rekurencyjne symbole wieloznaczne
Jeśli chcesz, aby reguły były stosowane do dowolnej głębokiej hierarchii, użyj rekurencyjnej składni z symbolami wieloznacznymi ({name=**}
). Przykład:
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>;
}
}
}
Jeśli używasz składni rekurencyjnego symbolu wieloznacznego, zmienna z symbolem wieloznacznym będzie zawierać cały pasujący segment ścieżki, nawet jeśli dokument znajduje się w głęboko zagnieżdżonej kolekcji podrzędnej. Wymienione powyżej reguły będą na przykład pasować do dokumentu znajdującego się pod adresem /cities/SF/landmarks/coit_tower
, a wartość zmiennej document
będzie wynosić SF/landmarks/coit_tower
.
Pamiętaj jednak, że działanie rekurencyjnych symboli wieloznacznych zależy od wersji reguł.
Wersja 1
Reguły zabezpieczeń używają domyślnie wersji 1. W wersji 1 rekurencyjne symbole wieloznaczne pasują do co najmniej jednego elementu ścieżki. Nie pasują do pustej ścieżki, więc reguła match /cities/{city}/{document=**}
dopasowuje dokumenty w kolekcjach podrzędnych, ale nie do kolekcji cities
, natomiast match /cities/{document=**}
pasuje zarówno do dokumentów w kolekcji cities
, jak i w kolekcjach podrzędnych.
Rekurencyjne symbole wieloznaczne muszą znajdować się na końcu instrukcji dopasowania.
Wersja 2
W wersji 2 reguł zabezpieczeń rekurencyjne symbole wieloznaczne pasują do 0 lub więcej elementów ścieżki. match/cities/{city}/{document=**}
dopasowuje dokumenty ze wszystkich podkolekcji oraz dokumenty z kolekcji cities
.
Musisz zaakceptować wersję 2, dodając rules_version = '2';
u góry reguł zabezpieczeń:
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>;
}
}
}
W każdej instrukcji dopasowania można użyć maksymalnie 1 rekurencyjnego symbolu wieloznacznego, ale w wersji 2 możesz go umieścić w dowolnym miejscu w instrukcji dopasowania. Przykład:
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>;
}
}
}
Jeśli korzystasz z zapytań dotyczących grup kolekcji, musisz używać wersji 2. Więcej informacji o zabezpieczaniu zapytań dotyczących grup kolekcji.
Nakładające się instrukcje dopasowania
Dokument może pasować do więcej niż jednej instrukcji match
. W przypadku gdy do żądania pasuje wiele wyrażeń allow
, dostęp jest dozwolony, jeśli którykolwiek z warunków jest zgodny z 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;
}
}
}
W powyższym przykładzie wszystkie odczyty i zapisy w kolekcji cities
są dozwolone, ponieważ druga reguła to zawsze true
, choć pierwsza to zawsze false
.
Limity reguł zabezpieczeń
Podczas pracy z regułami zabezpieczeń pamiętaj o tych ograniczeniach:
Limit | Szczegóły |
---|---|
Maksymalna liczba wywołań exists() , get() i getAfter() na żądanie |
Przekroczenie dowolnego z limitów skutkuje błędem braku uprawnień. Niektóre wywołania dostępu do dokumentu mogą być przechowywane w pamięci podręcznej, a wywołania z pamięci podręcznej nie wliczają się do limitów. |
Maksymalna głębokość zagnieżdżonej instrukcji match |
10 |
Maksymalna długość ścieżki w segmentach ścieżki dozwolona w zbiorze zagnieżdżonych instrukcji match |
100 |
Maksymalna liczba zmiennych przechwytywania ścieżki dozwolona w zestawie zagnieżdżonych instrukcji match |
20 |
Maksymalna głębokość wywołania funkcji | 20 |
Maksymalna liczba argumentów funkcji | 7 |
Maksymalna liczba powiązań zmiennych na funkcję (let ) |
10 |
Maksymalna liczba rekurencyjnych lub cyklicznych wywołań funkcji | 0 (niedozwolone) |
Maksymalna liczba wyrażeń ocenianych na żądanie | 1000 |
Maksymalny rozmiar zestawu reguł | Zestawy reguł muszą przestrzegać 2 limitów rozmiarów:
|
Dalsze kroki
- Utwórz niestandardowe warunki reguł zabezpieczeń.
- Zapoznaj się z informacjami o regułach zabezpieczeń.