Strutturare le regole di sicurezza
Le regole di sicurezza di Firestore consentono di controllare l'accesso ai documenti e alle raccolte nel tuo database. La sintassi delle regole flessibili consente di creare regole che corrispondono a qualsiasi cosa, dalle scritture all'intero database fino alle operazioni su un documento specifico.
Questa guida descrive la sintassi e la struttura di base delle regole di sicurezza. Combina questa sintassi con le condizioni delle regole di sicurezza per creare set di regole completi.
Dichiarazione relativa a servizi e database
Le regole di sicurezza di Firestore iniziano sempre con la seguente dichiarazione:
service cloud.firestore {
match /databases/{database}/documents {
// ...
}
}
La dichiarazione service cloud.firestore
definisce l'ambito delle regole su Firestore, evitando conflitti tra le regole di sicurezza e le regole di Firestore per altri prodotti come Cloud Storage.
La dichiarazione match /databases/{database}/documents
specifica che le regole devono
corrispondere a qualsiasi database Firestore del progetto. Attualmente ogni progetto ha un solo database denominato (default)
.
Regole di lettura/scrittura di base
Le regole di base sono composte da un'istruzione match
che specifica un percorso del documento e da un'espressione allow
che fornisce informazioni dettagliate durante la lettura dei dati specificati:
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>;
}
}
}
Tutte le istruzioni di corrispondenza devono puntare ai documenti, non alle raccolte. Un'istruzione
di corrispondenza può puntare a un documento specifico, come match /cities/SF
, o utilizzare caratteri jolly
per puntare a qualsiasi documento nel percorso specificato, come in match /cities/{city}
.
Nell'esempio precedente, l'istruzione di corrispondenza utilizza la sintassi del carattere jolly {city}
.
Ciò significa che la regola si applica a qualsiasi documento nella raccolta cities
, ad esempio /cities/SF
o /cities/NYC
. Quando vengono valutate le espressioni allow
nell'istruzione di corrispondenza, la variabile city
si risolverà nel nome del documento della città, ad esempio SF
o NYC
.
Operazioni granulari
In alcune situazioni, è utile suddividere read
e write
in operazioni più
granulari. Ad esempio, l'app potrebbe voler applicare condizioni diverse
sulla creazione dei documenti rispetto all'eliminazione. Oppure puoi consentire le letture di singoli
documenti ma rifiutare le query di grandi dimensioni.
Una regola read
può essere suddivisa in get
e list
, mentre una regola write
può
essere suddivisa in create
, update
e 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>;
}
}
}
Dati gerarchici
I dati in Firestore sono organizzati in raccolte di documenti e ogni documento può estendere la gerarchia tramite sottoraccolte. È importante capire in che modo le regole di sicurezza interagiscono con i dati gerarchici.
Considera la situazione in cui ogni documento nella raccolta cities
contiene una
sottoraccolta landmarks
. Le regole di sicurezza si applicano solo nel percorso corrispondente, quindi i controlli di accesso definiti nella raccolta cities
non si applicano alla sottoraccolta landmarks
. Scrivi invece regole esplicite per controllare
l'accesso alle sottoraccolte:
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>;
}
}
}
}
Quando si nidificano le istruzioni match
, il percorso dell'istruzione match
interna è sempre
relativo al percorso dell'istruzione match
esterna. Pertanto, i seguenti set di regole
sono equivalenti:
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>;
}
}
}
Caratteri jolly ricorrenti
Se vuoi applicare le regole a una gerarchia arbitraria, utilizza la sintassi con caratteri jolly, {name=**}
. Ad esempio:
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>;
}
}
}
Quando utilizzi la sintassi con carattere jolly ricorsivo, la variabile con caratteri jolly conterrà l'intero segmento del percorso corrispondente, anche se il documento si trova in una sottoraccolta molto nidificata. Ad esempio, le regole elencate sopra corrispondono a un documento situato in /cities/SF/landmarks/coit_tower
e il valore della variabile document
è SF/landmarks/coit_tower
.
Tieni presente, tuttavia, che il comportamento dei caratteri jolly ricorsivi dipende dalla versione delle regole.
Versione 1
Le regole di sicurezza utilizzano la versione 1 per impostazione predefinita. Nella versione 1, i caratteri jolly ricorsivi
corrispondono a uno o più elementi del percorso. Non corrispondono a un percorso vuoto, di conseguenza
match /cities/{city}/{document=**}
corrisponde ai documenti nelle sottoraccolte, ma
non nella raccolta cities
, mentre match /cities/{document=**}
corrisponde
a entrambi i documenti nella raccolta e nelle sottoraccolte cities
.
I caratteri jolly ricorrenti devono trovarsi alla fine di un'istruzione di corrispondenza.
Versione 2
Nella versione 2 delle regole di sicurezza, i caratteri jolly ricorrenti corrispondono a zero o più elementi del percorso. match/cities/{city}/{document=**}
corrisponde ai documenti in qualsiasi raccolta secondaria e ai documenti nella raccolta cities
.
Devi attivare la versione 2 aggiungendo rules_version = '2';
nella parte superiore
delle regole di sicurezza:
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>;
}
}
}
Puoi avere al massimo un carattere jolly ricorsivo per istruzione di corrispondenza, ma nella versione 2 puoi inserire questo carattere jolly in qualsiasi punto dell'istruzione di corrispondenza. Ad esempio:
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>;
}
}
}
Se utilizzi le query sui gruppi di raccolte, devi utilizzare la versione 2. Consulta la sezione sulla protezione gruppo di raccolte di raccolte.
Dichiarazioni di corrispondenza sovrapposte
È possibile che un documento corrisponda a più di un'istruzione match
. Nel caso in cui più espressioni allow
corrispondano a una richiesta, l'accesso è consentito se una qualsiasi delle condizioni è 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;
}
}
}
Nell'esempio precedente, tutte le operazioni di lettura e scrittura nella raccolta cities
saranno consentite perché la seconda regola è sempre true
, anche se la prima regola è sempre false
.
Limiti delle regole di sicurezza
Quando utilizzi le regole di sicurezza, tieni presente i seguenti limiti:
Limite | Dettagli |
---|---|
Numero massimo di chiamate exists() , get() e getAfter() per richiesta |
Il superamento di uno dei limiti comporta un errore di autorizzazione negata. Alcune chiamate di accesso ai documenti possono essere memorizzate nella cache e le chiamate nella cache non vengono considerate ai fini dei limiti. |
Profondità massima delle istruzioni match nidificate |
10 |
Lunghezza massima del percorso, in segmenti di percorso, consentita all'interno di un set di istruzioni match nidificate |
100 |
Numero massimo di variabili di acquisizione percorso consentite all'interno di un set di istruzioni match nidificate |
20 |
Profondità massima delle chiamate funzione | 20 |
Numero massimo di argomenti di funzione | 7 |
Numero massimo di associazioni di variabili let per funzione |
10 |
Numero massimo di chiamate di funzione ricorsive o cicliche | 0 (non consentite) |
Numero massimo di espressioni valutate per richiesta | 1000 |
Dimensione massima di un set di regole | I set di regole devono rispettare due limiti di dimensione:
|
Passaggi successivi
- Scrivi condizioni delle regole di sicurezza personalizzate.
- Leggi la documentazione di riferimento sulle regole di sicurezza.