Utilizzo dell'API REST Firestore

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

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

  • Accedi a Firestore da un ambiente con risorse limitate. come un dispositivo IoT (Internet of Things), in cui è in esecuzione un client completo non è possibile.
  • Automazione dell'amministrazione dei database o recupero di metadati dettagliati del database.

Se utilizzi un linguaggio supportato da gRPC, ti consigliamo di utilizzare l'API RPC anziché l'API REST.

Autenticazione e autorizzazione

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

  • Utilizza i token ID Firebase per autenticare le richieste degli utenti della tua applicazione. Per queste richieste, Firestore utilizza le regole di sicurezza 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 dal tuo come le richieste per l'amministrazione dei 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:

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

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

Questo token deve avere il seguente ambito per inviare richieste al API REST Firestore:

  • 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 presume che le richieste vengano eseguite per conto della tua applicazione anziché di un singolo utente. Firestore consente a queste richieste per ignorare le tue regole di sicurezza. Firestore utilizza IAM per determinare se una richiesta è autorizzata.

Puoi controllare le autorizzazioni di accesso degli account di servizio assegnando 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, trasmettelo agli endpoint Firestore come intestazione Authorization impostata su Bearer {YOUR_TOKEN}.

Esecuzione di chiamate REST

Tutti gli endpoint dell'API REST si trovano nell'URL di base https://firestore.googleapis.com/v1/.

Per creare un percorso a un documento con ID LA nella raccolta cities nel progetto YOUR_PROJECT_ID useresti 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 l'identità Google token OAuth 2.0 e consente di esaminare l'API.

Metodi

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

v1.projects.databases.documents

Esegui operazioni CRUD sui documenti, simili a quelle descritte nelle guide su come aggiungere dati o ricevere dati.

v1.projects.databases.collectionGroups.indexes

Eseguire azioni sugli indici, ad esempio creare nuovi indici e disabilitare una rete esistente indice o elencare tutti gli indici attuali. Utile per automatizzare la struttura dei dati migrazioni o sincronizzazione degli indici tra progetti.

Consente inoltre il recupero dei metadati dei documenti, ad esempio l'elenco di tutti i campi e le sottocollezioni di 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 su l'errore.

La tabella seguente elenca le azioni consigliate per ciascun codice di errore. Questi codici si applicano alle API REST e RPC di Firestore. Gli SDK e le librerie client 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 a inviare la richiesta o ristruttura il modello di dati per ridurre le contese.

Per le richieste in una transazione:
riprova a inviare l'intera transazione o ristruttura il modello di dati per ridurre le 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 precondizioni. Ad esempio, una richiesta di query potrebbe richiedere un indice non ancora definito. Controlla il campo del messaggio nella risposta all'errore per la precondizione non riuscita. Non riprovare senza risolvere il problema.
INTERNAL Il server Firestore ha restituito un errore. Non riprovare questa richiesta più di una volta.
INVALID_ARGUMENT Un parametro di richiesta include un valore non valido. Verifica il valore non valido nel campo del messaggio nella risposta di errore. 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 sua quota o la capacità in una regione o in più regioni. Verifica di non aver superato la quota del progetto. Se hai superato una quota del progetto, non riprovare senza risolvere il problema.

Altrimenti, 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.