Utilizzo dell'API REST Firestore

Sebbene il modo più semplice per utilizzare Firestore sia utilizzare una delle librerie client native, in alcuni casi è utile chiamare direttamente l'API REST.

L'API REST può essere utile per i seguenti casi d'uso:

Accesso a Firestore da un ambiente con risorse limitate, ad esempio un dispositivo IoT (Internet of Things), in cui non è possibile eseguire una libreria client completa.
Automazione dell'amministrazione dei database o recupero di metadati dettagliati del database.

Se utilizzi un linguaggio supportato da gRPC, valuta la possibilità di utilizzare l'API RPC anziché l'API REST.

autentica e autorizza

Per l'autenticazione, l'API REST di Firestore accetta un token ID Firebase Authentication o un token OAuth 2.0 di Google Identity. Il token che fornisci influisce sull'autorizzazione della tua richiesta:

Utilizza i token ID Firebase per autenticare le richieste degli utenti della tua applicazione. Per queste richieste, Firestore utilizza le regole di sicurezza di Firestore per determinare se una richiesta è autorizzata.
Utilizza un token OAuth 2.0 di Google Identity e un account di servizio per autenticare le richieste dalla tua applicazione, ad esempio quelle per l'amministrazione del database. Per queste richieste, Firestore utilizza Identity and Access Management (IAM) per determinare se una richiesta è autorizzata.

Utilizzare i token ID Firebase

Puoi ottenere un token ID Firebase in due modi:

Recuperando il token ID Firebase di un utente, puoi effettuare richieste per conto dell'utente.

Per le richieste autenticate con un token ID Firebase e per quelle non autenticate, Firestore utilizza le regole di sicurezza di Firestore per determinare se una richiesta è autorizzata.

Utilizzare i token OAuth 2.0 di Google Identity

Puoi generare un token di accesso utilizzando un account di servizio con una libreria client delle API di Google oppure seguendo i passaggi descritti in Utilizzare OAuth 2.0 per applicazioni da server a server. Puoi anche generare un token con lo strumento a riga di comando gcloud e il comando gcloud auth application-default print-access-token.

Per inviare richieste all'API REST di Firestore, questo token deve avere il seguente ambito:

https://www.googleapis.com/auth/datastore

Se autentichi le richieste con un account di servizio e un token OAuth 2.0 di Google Identity, Firestore presuppone che le richieste agiscano per conto della tua applicazione anziché di un singolo utente. Firestore consente a queste richieste di ignorare le regole di sicurezza. Firestore utilizza invece IAM per determinare se una richiesta è autorizzata.

Puoi controllare le autorizzazioni di accesso degli account di servizio assegnando i ruoli IAM di Firestore.

Autenticazione con un token di accesso

Dopo aver ottenuto un token ID Firebase o un token OAuth 2.0 di Google Identity, passalo agli endpoint Firestore come intestazione Authorization impostata su Bearer {YOUR_TOKEN}.

Effettuare chiamate REST

Tutti gli endpoint API REST sono presenti nell'URL di base https://firestore.googleapis.com/v1/.

Per creare un percorso a un documento con ID LA nella raccolta cities del progetto YOUR_PROJECT_ID, utilizzerai la seguente struttura.

/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA

Per interagire con questo percorso, combinalo con l'URL dell'API di base.

https://firestore.googleapis.com/v1/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA

Il modo migliore per iniziare a sperimentare con l'API REST è utilizzare Explorer API, che genera automaticamente i token OAuth 2.0 di Google Identity e consente di esaminare l'API.

Metodi

Di seguito sono riportate brevi descrizioni dei due più importanti gruppi di metodi. Per un elenco completo, consulta il riferimento sull'API REST o utilizza Explorer API.

`v1.projects.databases.documents`

Esegui operazioni CRUD sui documenti, simili a quelle descritte nelle guide per aggiungere dati o recuperare dati.

`v1.projects.databases.collectionGroups.indexes`

Esegui azioni sugli indici, ad esempio la creazione di nuovi indici, la disattivazione di un indice esistente o l'elenco di tutti gli indici correnti. Utile per automatizzare le migrazioni della struttura di dati o sincronizzare gli indici tra progetti.

Consente inoltre il recupero dei metadati dei documenti, come l'elenco di tutti i campi e le sottoraccolte per un determinato documento.

Codici di errore

Quando una richiesta Firestore ha esito positivo, l'API Firestore restituisce un codice di stato HTTP 200 OK e i dati richiesti. Quando una richiesta non va a buon fine, l'API Firestore restituisce un codice di stato HTTP 4xx o 5xx e una risposta con informazioni sull'errore.

Nella tabella seguente sono elencate le azioni consigliate per ogni codice di errore. Questi codici si applicano alle API REST e RPC di Firestore. Gli SDK e le librerie client di Firestore potrebbero non restituire gli stessi codici di errore.

Codice di errore canonico	Descrizione	Azione consigliata
`ABORTED`	La richiesta è in conflitto con un'altra richiesta.	Per un commit non transazionale: Riprova la richiesta o ristruttura il tuo modello di dati per ridurre la contesa. Per le richieste in una transazione: Riprova l'intera transazione o riorganizza il modello dei dati per ridurre la contesa.
`ALREADY_EXISTS`	La richiesta ha tentato di creare un documento già esistente.	Non riprovare senza risolvere il problema.
`DEADLINE_EXCEEDED`	Il server Firestore che gestisce la richiesta ha superato una scadenza.	Riprova utilizzando il backoff esponenziale.
`FAILED_PRECONDITION`	La richiesta non soddisfa una delle precondizioni. Ad esempio, una richiesta di query potrebbe richiedere un indice non ancora definito. Controlla il campo del messaggio nella risposta di errore per conoscere la precondizione non riuscita.	Non riprovare senza risolvere il problema.
`INTERNAL`	Il server Firestore ha restituito un errore.	Non riprovare più di una volta.
`INVALID_ARGUMENT`	Un parametro di richiesta include un valore non valido. Controlla il campo del messaggio nella risposta di errore per verificare il valore non valido.	Non riprovare senza risolvere il problema.
`NOT_FOUND`	La richiesta ha tentato di aggiornare un documento che non esiste.	Non riprovare senza risolvere il problema.
`PERMISSION_DENIED`	L'utente non è autorizzato a effettuare questa richiesta.	Non riprovare senza risolvere il problema.
`RESOURCE_EXHAUSTED`	Il progetto ha superato la propria quota o la capacità a livello di regione/più regioni.	Verifica di non aver superato la quota del progetto. Se hai superato una quota del progetto, non riprovare senza risolvere il problema. In caso contrario, riprova con un backoff esponenziale.
`UNAUTHENTICATED`	La richiesta non includeva credenziali di autenticazione valide.	Non riprovare senza risolvere il problema.
`UNAVAILABLE`	Il server Firestore ha restituito un errore.	Riprova utilizzando il backoff esponenziale.