Questa pagina si basa sui concetti riportati in Struttura delle regole di sicurezza e Scrittura di condizioni per le regole di sicurezza per spiegare come puoi utilizzare Cloud Firestore Security Rules per creare regole che consentano ai client di eseguire operazioni su alcuni campi di un documento ma non su altri.
A volte potresti voler controllare le modifiche a un documento non a livello di documento, ma a livello di campo.
Ad esempio, potresti voler consentire a un cliente di creare o modificare un documento, ma non di modificare determinati campi al suo interno. In alternativa, potresti volere imporre che qualsiasi documento creato da un cliente contenga sempre un determinato insieme di campi. Questa guida spiega come eseguire alcune di queste attività utilizzandoCloud Firestore Security Rules.
Consentire l'accesso in lettura solo per campi specifici
Le letture in Cloud Firestore vengono eseguite a livello di documento. Puoi recuperare il documento completo o non recuperare nulla. Non è possibile recuperare un documento parziale. È impossibile utilizzare solo le regole di sicurezza per impedire agli utenti di leggere campi specifici all'interno di un documento.
Se in un documento ci sono determinati campi che vuoi mantenere nascosti per alcuni utenti, il modo migliore è inserirli in un documento separato. Ad esempio, potresti prendere in considerazione la creazione di un documento in una private sottoraccolta come segue:
/dipendenti/{emp_id}
name: "Alice Hamilton",
department: 461,
start_date: <timestamp>
/employees/{emp_id}/private/finances
salary: 80000,
bonus_mult: 1.25,
perf_review: 4.2
Poi puoi aggiungere regole di sicurezza con diversi livelli di accesso per le due raccolte. In questo esempio utilizziamo i claim di autenticazione personalizzati per indicare che solo gli utenti con il claim di autenticazione personalizzato role uguale a Finance possono visualizzare le informazioni finanziarie di un dipendente.
service cloud.firestore {
match /databases/{database}/documents {
// Allow any logged in user to view the public employee data
match /employees/{emp_id} {
allow read: if request.resource.auth != null
// Allow only users with the custom auth claim of "Finance" to view
// the employee's financial data
match /private/finances {
allow read: if request.resource.auth &&
request.resource.auth.token.role == 'Finance'
}
}
}
}
Limitare i campi durante la creazione del documento
Cloud Firestore è senza schema, il che significa che non ci sono limitazioni a livello di database per i campi contenuti in un documento. Sebbene questa flexibilità possa semplificare lo sviluppo, a volte potresti dover assicurarti che i client possano creare solo documenti che contengono campi specifici o che non contengono altri campi.
Puoi creare queste regole esaminando il metodo keys dell'oggetto
request.resource.data. Questo è un elenco di tutti i campi che il cliente sta tentando di scrivere in questo nuovo documento. Combinando questo insieme di campi con funzioni come hasOnly() o hasAny(), puoi aggiungere una logica che limiti i tipi di documenti che un utente può aggiungere a Cloud Firestore.
Richiesta di campi specifici nei nuovi documenti
Supponiamo che tu voglia assicurarti che tutti i documenti creati in una raccolta restaurant contengano almeno un campo name, location e city. Puoi farlo chiamando hasAll() nell'elenco delle chiavi del nuovo documento.
service cloud.firestore {
match /databases/{database}/documents {
// Allow the user to create a document only if that document contains a name
// location, and city field
match /restaurant/{restId} {
allow create: if request.resource.data.keys().hasAll(['name', 'location', 'city']);
}
}
}
In questo modo è possibile creare ristoranti anche con altri campi, ma garantisce che tutti i documenti creati da un client contengano almeno questi tre campi.
Vietare campi specifici nei nuovi documenti
Analogamente, puoi impedire ai client di creare documenti contenenti campi specifici utilizzando hasAny() in base a un elenco di campi vietati. Questo metodo restituisce true se un
documento contiene uno di questi campi, quindi probabilmente vorrai negare il
risultato per vietare determinati campi.
Ad esempio, nell'esempio seguente, i client non sono autorizzati a creare un documento contenente un campo average_score o rating_count, poiché questi campi verranno aggiunti in un secondo momento da una chiamata al server.
service cloud.firestore {
match /databases/{database}/documents {
// Allow the user to create a document only if that document does *not*
// contain an average_score or rating_count field.
match /restaurant/{restId} {
allow create: if (!request.resource.data.keys().hasAny(
['average_score', 'rating_count']));
}
}
}
Creazione di una lista consentita di campi per i nuovi documenti
Invece di vietare determinati campi nei nuovi documenti, potresti voler creare un elenco dei soli campi esplicitamente consentiti nei nuovi documenti. Poi puoi utilizzare la funzione hasOnly() per assicurarti che i nuovi documenti creati contengano solo questi campi (o un sottoinsieme di questi campi) e nessun altro.
service cloud.firestore {
match /databases/{database}/documents {
// Allow the user to create a document only if that document doesn't contain
// any fields besides the ones listed below.
match /restaurant/{restId} {
allow create: if (request.resource.data.keys().hasOnly(
['name', 'location', 'city', 'address', 'hours', 'cuisine']));
}
}
}
Combinazione di campi obbligatori e facoltativi
Puoi combinare le operazioni hasAll e hasOnly nelle regole di sicurezza per richiedere alcuni campi e consentirne altri. Ad esempio, questo esempio richiede che tutti i nuovi documenti contengano i campi name, location e city e, facoltativamente, consente i campi address, hours e cuisine.
service cloud.firestore {
match /databases/{database}/documents {
// Allow the user to create a document only if that document has a name,
// location, and city field, and optionally address, hours, or cuisine field
match /restaurant/{restId} {
allow create: if (request.resource.data.keys().hasAll(['name', 'location', 'city'])) &&
(request.resource.data.keys().hasOnly(
['name', 'location', 'city', 'address', 'hours', 'cuisine']));
}
}
}
In uno scenario reale, ti consigliamo di spostare questa logica in una funzione di supporto per evitare di duplicare il codice e combinare più facilmente i campi facoltativi e obbligatori in un unico elenco, come segue:
service cloud.firestore {
match /databases/{database}/documents {
function verifyFields(required, optional) {
let allAllowedFields = required.concat(optional);
return request.resource.data.keys().hasAll(required) &&
request.resource.data.keys().hasOnly(allAllowedFields);
}
match /restaurant/{restId} {
allow create: if verifyFields(['name', 'location', 'city'],
['address', 'hours', 'cuisine']);
}
}
}
Limitare i campi in caso di aggiornamento
Una pratica di sicurezza comune è consentire ai client di modificare solo alcuni campi e non altri. Non puoi farlo solo esaminando l'elenco request.resource.data.keys() descritto nella sezione precedente, poiché questo elenco rappresenta il documento completo così come apparirà dopo l'aggiornamento e includerà quindi i campi che il cliente non ha modificato.
Tuttavia, se utilizzassi la funzione diff(), potresti confrontare request.resource.data con l'oggetto resource.data, che rappresenta il documento nel database prima dell'aggiornamento. Viene creato un oggetto mapDiff, ovvero un oggetto che contiene tutte le modifiche tra due diverse mappe.
Chiamando il metodo affectedKeys() su questa mappa di differenze, puoi ottenere un insieme di campi modificati in una modifica. Poi puoi utilizzare funzioni come
hasOnly()
o hasAny()
per assicurarti che questo insieme contenga (o meno) determinati elementi.
Impedire la modifica di alcuni campi
Utilizzando il metodo hasAny()
sul set generato da affectedKeys()
e poi negando il risultato, puoi rifiutare qualsiasi richiesta del client che tenta di
modificare i campi che non vuoi modificare.
Ad esempio, puoi consentire ai clienti di aggiornare le informazioni su un ristorante senza modificare il punteggio medio o il numero di recensioni.
service cloud.firestore {
match /databases/{database}/documents {
match /restaurant/{restId} {
// Allow the client to update a document only if that document doesn't
// change the average_score or rating_count fields
allow update: if (!request.resource.data.diff(resource.data).affectedKeys()
.hasAny(['average_score', 'rating_count']));
}
}
}
Consentire la modifica solo di alcuni campi
Anziché specificare i campi che non vuoi modificare, puoi anche utilizzare la funzione
hasOnly()
per specificare un elenco di campi che vuoi modificare. In genere, questo approccio è considerato più sicuro perché le scritture in qualsiasi nuovo campo del documento sono vietate per impostazione predefinita finché non le consenti esplicitamente nelle regole di sicurezza.
Ad esempio, anziché non consentire il campo average_score e rating_count, puoi creare regole di sicurezza che consentano ai client di modificare solo i campi name, location, city, address, hours e cuisine.
service cloud.firestore {
match /databases/{database}/documents {
match /restaurant/{restId} {
// Allow a client to update only these 6 fields in a document
allow update: if (request.resource.data.diff(resource.data).affectedKeys()
.hasOnly(['name', 'location', 'city', 'address', 'hours', 'cuisine']));
}
}
}
Ciò significa che se, in un'iterazione futura della tua app, i documenti del ristorante
includeranno un campo telephone, i tentativi di modifica del campo non andranno a buon fine
finché non torni indietro e aggiungi il campo all'elenco hasOnly() nelle regole
di sicurezza.
Applicazione dei tipi di campo
Un altro effetto dell'assenza di schema in Cloud Firestore è che non viene applicata alcuna verifica a livello di database per i tipi di dati che possono essere archiviati in campi specifici. Puoi però applicare questa impostazione nelle regole di sicurezza
con l'operatore is.
Ad esempio, la seguente regola di sicurezza impone che il campo score
di una recensione debba essere un numero intero, i campi headline, content e author_name
siano stringhe e review_date sia un timestamp.
service cloud.firestore {
match /databases/{database}/documents {
match /restaurant/{restId} {
// Restaurant rules go here...
match /review/{reviewId} {
allow create: if (request.resource.data.score is int &&
request.resource.data.headline is string &&
request.resource.data.content is string &&
request.resource.data.author_name is string &&
request.resource.data.review_date is timestamp
);
}
}
}
}
I tipi di dati validi per l'operatore is sono bool, bytes, float, int,
list, latlng, number, path, map, string e timestamp. L'operatore is supporta anche i tipi di dati constraint, duration, set e map_diff, ma poiché questi vengono generati dal linguaggio delle regole di sicurezza stesso e non dai client, vengono utilizzati raramente nella maggior parte delle applicazioni pratiche.
I tipi di dati list e map non supportano i generici o gli argomenti di tipo.
In altre parole, puoi utilizzare le regole di sicurezza per fare in modo che un determinato campo contenga un elenco o una mappa, ma non puoi imporre che un campo contenga un elenco di tutti i numeri interi o tutte le stringhe.
Analogamente, puoi utilizzare le regole di sicurezza per applicare valori di tipo per voci specifiche in un elenco o in una mappa (utilizzando rispettivamente la notazione delle parentesi o i nomi delle chiavi), ma non esiste alcuna scorciatoia per applicare contemporaneamente i tipi di dati di tutti i membri in una mappa o in un elenco.
Ad esempio, le seguenti regole assicurano che un campo tags in un documento contenga un elenco e che la prima voce sia una stringa. Assicura inoltre che il campo product contenga una mappa che a sua volta contenga un nome di prodotto costituito da una stringa e una quantità che sia un numero intero.
service cloud.firestore {
match /databases/{database}/documents {
match /orders/{orderId} {
allow create: if request.resource.data.tags is list &&
request.resource.data.tags[0] is string &&
request.resource.data.product is map &&
request.resource.data.product.name is string &&
request.resource.data.product.quantity is int
}
}
}
}
I tipi di campo devono essere applicati sia durante la creazione che durante l'aggiornamento di un documento. Pertanto, ti consigliamo di creare una funzione di supporto che puoi chiamare sia nelle sezioni di creazione che di aggiornamento delle regole di sicurezza.
service cloud.firestore {
match /databases/{database}/documents {
function reviewFieldsAreValidTypes(docData) {
return docData.score is int &&
docData.headline is string &&
docData.content is string &&
docData.author_name is string &&
docData.review_date is timestamp;
}
match /restaurant/{restId} {
// Restaurant rules go here...
match /review/{reviewId} {
allow create: if reviewFieldsAreValidTypes(request.resource.data) &&
// Other rules may go here
allow update: if reviewFieldsAreValidTypes(request.resource.data) &&
// Other rules may go here
}
}
}
}
Applicazione forzata dei tipi per i campi facoltativi
È importante ricordare che l'utilizzo di request.resource.data.foo in un
documento in cui request.resource.data.foo non esiste genera un errore e, pertanto, qualsiasi
regola di sicurezza che esegue questa chiamata rifiuterà la richiesta. Puoi gestire questa
situazione utilizzando il metodo get
su request.resource.data. Il metodo get ti consente di fornire un
argomento predefinito per il campo che stai recuperando da una mappa se il campo
non esiste.
Ad esempio, se i documenti di revisione contengono anche un campo photo_url facoltativo
e un campo tags facoltativo che vuoi verificare siano rispettivamente stringhe e elenchi, puoi farlo riscrivendo la funzione
reviewFieldsAreValidTypes in modo simile al seguente:
function reviewFieldsAreValidTypes(docData) {
return docData.score is int &&
docData.headline is string &&
docData.content is string &&
docData.author_name is string &&
docData.review_date is timestamp &&
docData.get('photo_url', '') is string &&
docData.get('tags', []) is list;
}
In questo modo vengono rifiutati i documenti in cui esiste tags, ma non è un elenco, pur consentendo i documenti che non contengono un campo tags (o photo_url).
Le scritture parziali non sono mai consentite
Un'ultima nota sui valori Cloud Firestore Security Rules: consentono al cliente di apportare una modifica a un documento o rifiutano l'intera modifica. Non puoi creare regole di sicurezza che accettino le scritture in alcuni campi del documento e ne rifiutino altre nella stessa operazione.