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:
- Accesso a Cloud Firestore da un ambiente con risorse limitate, come un dispositivo Internet delle cose (IoT), dove non è possibile eseguire una libreria client completa.
- Automatizzazione 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 Cloud Firestore accetta un token ID di autenticazione Firebase o un token OAuth 2.0 di Google Identity . Il token fornito influisce sull'autorizzazione della tua richiesta:
Utilizza i token ID Firebase per autenticare le richieste degli utenti della tua applicazione. Per queste richieste, Cloud Firestore utilizza le regole di sicurezza di Cloud 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 le richieste per l'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:
- Genera un token ID Firebase utilizzando l'API REST di autenticazione Firebase .
- Recupera il token ID Firebase di un utente da un SDK di autenticazione Firebase .
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 le richieste non autenticate, Cloud Firestore utilizza le regole di sicurezza di Cloud Firestore 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 API di Google o seguendo i passaggi in Utilizzo di OAuth 2.0 per applicazioni da server a server . Puoi anche generare un token con lo strumento da 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 di Cloud Firestore:
-
https://www.googleapis.com/auth/datastore
Se autentici le tue richieste con un account di servizio e un token Google Identity OAuth 2.0, Cloud Firestore presuppone che le tue richieste agiscano per conto della tua applicazione anziché di un singolo utente. Cloud Firestore consente a queste richieste di ignorare le tue regole di sicurezza. Cloud Firestore utilizza invece IAM per determinare se una richiesta è autorizzata.
Puoi controllare le autorizzazioni di accesso degli account di servizio assegnando ruoli IAM di Cloud 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 Cloud Firestore come intestazione Authorization impostata su Bearer {YOUR_TOKEN} .
Effettuare chiamate REST
Tutti gli endpoint API REST si trovano nell'URL di base https://firestore.googleapis.com/v1/ .
Per creare un percorso verso un documento con l'ID LA nelle cities di raccolta nel progetto YOUR_PROJECT_ID dovresti utilizzare 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 API Explorer , che genera automaticamente token Google Identity 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 il riferimento API REST o utilizza API Explorer .
v1.projects.databases.documents
Esegui operazioni CRUD sui documenti, simili a quelle descritte nelle guide per aggiungere dati o ottenere dati .
v1.projects.databases.collectionGroups.indexes
Eseguire azioni sugli indici come creare nuovi indici, disabilitare un indice esistente o elencare tutti gli indici correnti. Utile per automatizzare le migrazioni delle strutture dati o sincronizzare gli indici tra progetti.
Consente inoltre il recupero dei metadati del documento, come l'elenco di tutti i campi e le sottoraccolte per un determinato documento.
Codici di errore
Quando una richiesta Cloud Firestore ha esito positivo, l'API Cloud Firestore restituisce un codice di stato HTTP 200 OK e i dati richiesti. Quando una richiesta non riesce, l'API Cloud Firestore restituisce un codice di stato HTTP 4xx o 5xx e una risposta con informazioni sull'errore.
La tabella seguente elenca le azioni consigliate per ciascun codice di errore. Questi codici si applicano alle API REST e RPC di Cloud Firestore. Gli SDK Cloud Firestore e le librerie client potrebbero non restituire gli stessi codici di errore.
| Codice errore canonico | Descrizione | Azione raccomandata |
|---|---|---|
ABORTED | La richiesta è in conflitto con un'altra richiesta. | Per un commit non transazionale: Riprovare la richiesta o ristrutturare il modello dati per ridurre il conflitto. Per le richieste in una transazione: Riprovare l'intera transazione o ristrutturare il modello dati per ridurre il conflitto. |
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 una scadenza. | Riprovare utilizzando il backoff esponenziale. |
FAILED_PRECONDITION | La richiesta non soddisfaceva una delle sue precondizioni. Ad esempio, una richiesta di query potrebbe richiedere un indice non ancora definito. Vedere il campo del messaggio nella risposta all'errore per la precondizione che non è riuscita. | Non riprovare senza risolvere il problema. |
INTERNAL | Il server Cloud Firestore ha restituito un errore. | Non riprovare questa richiesta più di una volta. |
INVALID_ARGUMENT | Un parametro di richiesta include un valore non valido. Vedere 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 effettuare questa richiesta. | Non riprovare senza risolvere il problema. |
RESOURCE_EXHAUSTED | Il progetto ha superato la sua quota o la capacità regionale/multiregionale. | 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 un 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. | Riprovare utilizzando il backoff esponenziale. |