Il modo più semplice per usare Cloud Firestore è usare uno dei librerie client native, esistono alcune situazioni in cui è 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 IoT (Internet of Things), in cui non è possibile eseguire una libreria client completa.
- Automazione dell'amministrazione dei database o recupero di metadati dettagliati dei database.
Se utilizzi un lingua supportata da gRPC, valuta l'utilizzo della classe API RPC anziché l'API REST.
Autenticazione e autorizzazione
Per l'autenticazione, l'API REST Cloud Firestore accetta un token token ID Firebase Authentication o un Google Identity OAuth 2.0. Il token che fornisci pregiudica l'autorizzazione della tua 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 sia 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, Cloud Firestore usi Identity and Access Management (IAM) per determinare se un la richiesta è autorizzata.
Utilizzare i token ID Firebase
Puoi ottenere un token ID Firebase in due modi:
- Genera un ID Firebase utilizzando la proprietà API REST Firebase Authentication.
- Recupera il token ID Firebase di un utente da una SDK Firebase Authentication.
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 richieste, Cloud Firestore utilizza i tuoi Cloud Firestore Security Rules per determinare se la richiesta viene autorizzati.
Utilizzo dei token OAuth 2.0 di Google Identity
Puoi generare un token di accesso utilizzando un
account di servizio con un
Libreria client dell'API di Google
o seguendo la procedura descritta in
Utilizzo di OAuth 2.0 per applicazioni server-server. Tu
puoi anche generare un token con lo strumento a riga di comando gcloud
il comando gcloud auth application-default print-access-token
.
Per inviare richieste all'Cloud Firestore API REST, questo token deve avere il seguente ambito:
https://www.googleapis.com/auth/datastore
Se autentichi le richieste con un account di servizio e un'identità Google Token OAuth 2.0, Cloud Firestore presuppone che le tue richieste agiscano per conto della tua applicazione invece che di un singolo utente. Cloud Firestore consente a queste richieste per 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 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
il token, passalo agli endpoint Cloud Firestore come Authorization
impostata su Bearer {YOUR_TOKEN}
.
Effettuare 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 consulta la documentazione di riferimento dell'API REST oppure utilizza l'Explorer API.
v1.projects.databases.documents
Eseguire operazioni CRUD sui documenti, simili a quelle descritte nei aggiungi dati o ricevi 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 le migrazioni della struttura dei dati o la 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 Cloud Firestore ha esito positivo,
L'API Cloud Firestore restituisce un codice di stato HTTP 200 OK
e la classe
i dati richiesti. Quando una richiesta non va a buon fine, l'API Cloud 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 Cloud Firestore. La Cloud Firestore Gli SDK e le librerie client 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 modello dei dati per ridurre i conflitti. Per le richieste in una transazione: Riprova l'intera transazione o ristruttura il modello dei dati per ridurre i conflitti. |
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. | 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 di errore per la precondizione 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. 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. 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 Cloud Firestore ha restituito un errore. | Riprova utilizzando il backoff esponenziale. |