Questa pagina è stata tradotta dall'API Cloud Translation.
Switch to English

Strutturare le regole di sicurezza del Firestore Cloud

Le regole di sicurezza di Cloud Firestore ti consentono di controllare l'accesso a documenti e raccolte nel tuo database. La sintassi delle regole flessibile consente di creare regole che corrispondono a qualsiasi cosa, da tutte le scritture all'intero database 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 di servizio e database

Le regole di sicurezza di Cloud Firestore iniziano sempre con la seguente dichiarazione:

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

La dichiarazione del service cloud.firestore le regole a Cloud Firestore, prevenendo conflitti tra le regole di sicurezza di Cloud Firestore e le regole per altri prodotti come Cloud Storage.

La dichiarazione match /databases/{database}/documents specifica che le regole devono corrispondere a qualsiasi database Cloud Firestore nel progetto. Attualmente ogni progetto ha un solo database chiamato (default) .

Regole di lettura / scrittura di base

Le regole di base sono costituite da un'istruzione di match che specifica un percorso del documento e sono allow dettagli di un'espressione allow 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 dichiarazioni di corrispondenza devono puntare a documenti, non a raccolte. Una dichiarazione di corrispondenza può puntare a un documento specifico, come in match /cities/SF o utilizzare i caratteri jolly per puntare a qualsiasi documento nel percorso specificato, come in match /cities/{city} .

Nell'esempio sopra, l'istruzione match utilizza la sintassi jolly {city} . Ciò significa che la regola si applica a qualsiasi documento nella raccolta delle cities , come /cities/SF o /cities/NYC . Quando vengono valutate le espressioni allow nell'istruzione di corrispondenza, la variabile della city si risolverà nel nome del documento di città, come SF o NYC .

Operazioni granulari

In alcune situazioni, è utile suddividere la read e la write in operazioni più granulari. Ad esempio, l'app potrebbe voler applicare condizioni diverse per la creazione del documento rispetto alla cancellazione del documento. Oppure potresti voler consentire la lettura di singoli documenti ma negare query di grandi dimensioni.

Una regola di read può essere suddivisa in get e list , mentre una regola di write può essere suddivisa in create , update ed 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 Cloud Firestore sono organizzati in raccolte di documenti e ogni documento può estendere la gerarchia attraverso le raccolte secondarie. È importante capire come le regole di sicurezza interagiscono con i dati gerarchici.

Considera la situazione in cui ciascun documento nella raccolta delle cities contiene un sottocollection di landmarks . Le regole di sicurezza si applicano solo nel percorso abbinato, quindi i controlli di accesso definiti nella raccolta delle cities non si applicano alla raccolta secondaria dei landmarks . Invece, scrivi regole esplicite per controllare l'accesso alle raccolte secondarie:

 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 annidano le istruzioni di match , il percorso dell'istruzione di match interna è sempre relativo al percorso dell'istruzione di match esterna. I seguenti set di regole sono quindi 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 ricorsivi

Se si desidera applicare le regole a una gerarchia arbitrariamente profonda, utilizzare la sintassi jolly ricorsiva, {name=**} . Per 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 si utilizza la sintassi jolly ricorsiva, la variabile jolly conterrà l'intero segmento del percorso corrispondente, anche se il documento si trova in una raccolta secondaria nidificata. Ad esempio, le regole sopra elencate corrisponderebbero a un documento situato in /cities/SF/landmarks/coit_tower e il valore della variabile del document sarebbe SF/landmarks/coit_tower .

Si noti, 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, pertanto match /cities/{city}/{document=**} corrisponde ai documenti nelle raccolte secondarie ma non nella raccolta delle cities , mentre match /cities/{document=**} corrisponde a entrambi i documenti nella raccolta e sottocollezioni di cities .

I caratteri jolly ricorsivi devono arrivare alla fine di una dichiarazione di corrispondenza.

Versione 2

Nella versione 2 delle regole di sicurezza, i caratteri jolly ricorsivi corrispondono a zero o più elementi del percorso. match/cities/{city}/{document=**} corrisponde ai documenti in qualsiasi raccolta secondaria e ai documenti nella raccolta delle 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 jolly ricorsivo per ogni istruzione di corrispondenza, ma nella versione 2 puoi posizionare questo jolly in qualsiasi punto dell'istruzione di corrispondenza. Per 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 si utilizzano query del gruppo di raccolta , è necessario utilizzare la versione 2, vedere protezione delle query del gruppo di raccolta .

Dichiarazioni di corrispondenza sovrapposte

È possibile che un documento corrisponda a più di una dichiarazione di match . Nel caso in cui più espressioni allow corrispondano a una richiesta, l'accesso è consentito se una 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 sopra, tutte le letture e le scritture nella raccolta delle cities saranno consentite perché la seconda regola è sempre true , anche se la prima regola è sempre false .

Limiti delle regole di sicurezza

Mentre lavori con le regole di sicurezza, nota i seguenti limiti:

Limite Dettagli
Numero massimo di chiamate exists() , get() e getAfter() per richiesta
  • 10 per richieste di documenti singoli e richieste di query.
  • 20 per letture di più documenti, transazioni e scritture in batch. Il limite precedente di 10 si applica anche a ciascuna operazione.

    Ad esempio, immagina di creare una richiesta di scrittura in batch con 3 operazioni di scrittura e che le tue regole di sicurezza utilizzino 2 chiamate di accesso al documento per convalidare ogni scrittura. In questo caso, ogni scrittura utilizza 2 delle sue 10 chiamate di accesso e la richiesta di scrittura in batch utilizza 6 delle sue 20 chiamate di accesso.

Il superamento 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 contano ai fini dei limiti.

Profondità massima dell'istruzione di match nidificata 10
Lunghezza massima del percorso, in segmenti di percorso, consentita all'interno di una serie di istruzioni di match nidificate 100
Numero massimo di variabili di acquisizione del percorso consentite in un set di istruzioni di match nidificate 20
Profondità di chiamata massima della funzione 20
Numero massimo di argomenti di funzioni 7
Numero massimo di associazioni variabili let per funzione 10
Numero massimo di chiamate di funzioni cicliche o ricorsive 0 (non consentito)
Numero massimo di espressioni valutate per richiesta 1.000
Dimensione massima di una serie di regole I set di regole Verax devono rispettare due limiti di dimensione:
  • un limite di 256 KB per la dimensione dell'origine del testo del set di regole Verax pubblicata dalla console di Firebase o dalla CLI usando la firebase deploy .
  • un limite di 250 KB sulla dimensione del set di regole compilato che risulta quando Firebase elabora il sorgente Verax e lo rende attivo sul back-end.

Prossimi passi