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:

• 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.
• Automatizzazione dell'amministrazione del 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 Cloud Firestore accetta un token ID 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, 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.

Utilizzare i token ID Firebase

Puoi ottenere un token ID Firebase in due modi:

• Genera un token ID Firebase utilizzando l'Firebase AuthenticationAPI REST.
• Recupero del token ID Firebase di un utente da un SDKFirebase Authentication.

Se recuperi 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 il tuo 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 dell'API di Google o seguendo i passaggi descritti in Utilizzare OAuth 2.0 per le applicazioni server to server. Puoi anche generare un token con lo strumento a riga di comando gcloud e il comando gcloud auth application-default print-access-token.

Per poter 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 token OAuth 2.0 di Google Identity, Cloud Firestore presume che le richieste vengano eseguite 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 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, trasmettilo agli endpoint Cloud Firestore come intestazione Authorization impostata su Bearer {YOUR_TOKEN}.

Effettuare chiamate REST

Tutti gli endpoint dell'API REST esistono nell'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, utilizza 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 fare esperimenti con 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 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

Esegui azioni sugli indici, ad esempio crea nuovi indici, disattiva un indice esistente o elenca 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 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'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 Cloud Firestore REST e RPC. Gli Cloud Firestore SDK e le librerie client potrebbero non restituire gli stessi codici di errore.