Utilizzo dell'API REST di Firestore

Il modo più semplice per utilizzare Firestore è utilizzare una delle librerie client native, ma esistono alcune situazioni in cui è utile chiamare direttamente l'API REST.

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

  • Accedere a Firestore da un ambiente con risorse limitate, ad esempio un dispositivo Internet of cose (IoT), in cui non è possibile eseguire una libreria client completa.
  • Automazione dell'amministrazione del 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.

Autenticazione e autorizzazione

Per l'autenticazione, l'API REST di Firestore accetta un token ID Firebase Authentication o un token Google Identity OAuth 2.0. Il token fornito influisce sulla 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 firewall per determinare se una richiesta è autorizzata.

  • Utilizza un token OAuth 2.0 di Google Identity e un account di servizio per autenticare le richieste dall'applicazione, ad esempio le richieste di amministrazione del database. Per queste richieste,Firestore utilizza Identity and Access Management (IAM) per determinare se una richiesta è autorizzata.

Utilizzo dei token ID Firebase

Puoi ottenere un token ID Firebase in due modi:

Ricevendo il token ID Firebase di un utente, puoi inviare richieste per conto dell'utente.

Per le richieste autenticate con un token ID Firebase e per le richieste non autenticate, Firestore utilizza le tue regole di sicurezza di firewall 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 dell'API di Google o seguendo la procedura descritta in Utilizzare OAuth 2.0 per applicazioni server-server. Puoi anche generare un token con lo strumento a riga di comando gcloud e il comando gcloud auth application-default print-access-token.

Questo token deve avere il seguente ambito per inviare richieste all'API REST diFistore:

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

Se autentichi le tue richieste con un account di servizio e un token OAuth 2.0 di Google Identity, Firestore presume che le tue 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 IAMFistore.

Autenticazione con un token di accesso

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

Effettuare chiamate REST

Tutti gli endpoint dell'API REST esistono sotto l'URL di base https://firestore.googleapis.com/v1/.

Per creare un percorso a un documento con l'ID LA nella raccolta cities nel 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 API di base.

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

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

Metodi

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

v1.projects.databases.documents

Esegui operazioni CRUD sui documenti, come quelli descritti nelle guide per aggiungere dati o ottenere dati.

v1.projects.databases.collectionGroups.indexes

Esegui azioni sugli indici, come creare nuovi indici, disattivare un indice esistente o elencare tutti gli indici correnti. Utile per automatizzare le migrazioni della struttura dei dati o sincronizzare gli indici tra progetti.

Consente inoltre di recuperare i metadati di documenti, come l'elenco di tutti i campi e delle sottoraccolte per un determinato documento.

Codici di errore

Quando una richiesta Firestore va a buon fine, 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.

La tabella riportata di seguito elenca le azioni consigliate per ogni codice di errore. Questi codici si applicano alle API REST e RPC di Firestore. Gli SDK Firestore e le librerie client potrebbero non restituire gli stessi codici di errore.

Codice di errore canonico Descrizione Azione consigliata
ABORTED La richiesta era in conflitto con un'altra richiesta. Per un commit non transazionale:
Riprova a riformulare la richiesta o ristruttura il modello dei dati per ridurre il numero di contese.

Per le richieste in una transazione:
Riprova per ristrutturare l'intera transazione o ristruttura il modello dei dati per ridurre il numero di contese.
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 ha soddisfatto una delle sue condizioni preliminari. Ad esempio, una richiesta di query potrebbe richiedere un indice non ancora definito. Controlla il campo del messaggio nella risposta all'errore per la condizione preliminare che non è riuscita. Non riprovare senza risolvere il problema.
INTERNAL Il server Firestore ha restituito un errore. Non riprovare più volte.
INVALID_ARGUMENT Un parametro di richiesta include un valore non valido. Controlla il campo del messaggio nella risposta all'errore per 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 inviare questa richiesta. Non riprovare senza risolvere il problema.
RESOURCE_EXHAUSTED Il progetto ha superato la quota o la capacità a livello di area geografica/multiarea geografica. Verifica di non aver superato la quota di progetto. Se hai superato la quota del progetto, non riprovare senza risolvere il problema.

In caso contrario, riprova con il 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.