Utilizzare l'API REST di Cloud Firestore

Sebbene il modo più semplice per utilizzare Cloud 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:

  • Accedere a Cloud Firestore da un ambiente con risorse limitate, ad esempio un dispositivo IoT (Internet of Things), in cui non è possibile eseguire una libreria client completa.
  • Automatizzare l'amministrazione del database o recuperare metadati dettagliati del database.

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

Autenticazione e autorizzazione

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

  • Utilizza i token ID Firebase per autenticare le richieste degli utenti della tua applicazione. Per queste richieste, Cloud Firestore utilizza Cloud Firestore Security Rules per determinare se una richiesta è autorizzata.

  • Utilizza un token OAuth 2.0 di Google Identity e un account di servizio per autenticare le richieste della tua applicazione, ad esempio le richieste di amministrazione del database. Per queste richieste, Cloud 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 suo conto.

Per le richieste autenticate con un token ID Firebase e per le richieste non autenticate richieste, Cloud Firestore utilizza le tue Cloud Firestore Security Rules per determinare se una richiesta è autorizzata.

Utilizzo dei 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 o seguendo i passaggi descritti in Utilizzare OAuth 2.0 per le applicazioni da server a server. Puoi anche generare un token con lo gcloud strumento a riga di comando e il comando gcloud auth application-default print-access-token.

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

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

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

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

Autenticazione con un token di accesso

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

Effettuare chiamate REST

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

Per creare un percorso a un documento con l'ID LA nella raccolta cities sotto il progetto YOUR_PROJECT_ID, utilizza la seguente struttura.

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

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

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 l' Explorer API, che genera automaticamente i token OAuth 2.0 di Google Identity e ti consente di esaminare l'API.

Metodi

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

v1.projects.databases.documents

Esegui operazioni CRUD sui documenti, simili a quelle descritte nelle guide Aggiungere dati o Ottenere 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 dei dati o sincronizzare gli indici tra i progetti.

Consente inoltre di recuperare i metadati dei documenti, ad esempio l'elenco di tutti i campi e le sottoraccolte per un determinato documento.

Codici di errore

Quando una richiesta Cloud Firestore va a buon fine, l'API Cloud Firestore restituisce un codice di stato HTTP 200 OK e i dati richiesti. Quando una richiesta non va a buon fine, l'Cloud Firestore API 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 ogni codice di errore. Questi codici si applicano alle API REST e RPC di Cloud Firestore. Gli Cloud Firestore SDK e le librerie client di Cloud 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 la contesa.

Per le richieste in una transazione:
Riprova a eseguire l'intera transazione o ristruttura il modello di 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 Cloud Firestore che gestisce la richiesta ha superato un termine. 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. Consulta il campo del messaggio nella risposta di errore per la precondizione non riuscita. Non riprovare senza risolvere il problema.
INTERNAL Il server Cloud Firestore ha restituito un errore. Non riprovare a inviare questa richiesta più di una volta.
INVALID_ARGUMENT Un parametro della richiesta include un valore non valido. Consulta il campo del messaggio nella risposta di errore per il valore non valido. Non riprovare senza risolvere il problema.
NOT_FOUND La richiesta ha tentato di aggiornare un documento inesistente. 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à della regione/multiregione. 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 utilizzando il backoff esponenziale.
UNAUTHENTICATED La richiesta non includeva credenziali di autenticazione valide. Non riprovare senza risolvere il problema.
UNAVAILABLE Il server Cloud Firestore ha restituito un errore. Riprova utilizzando il backoff esponenziale.