Una transazione è un insieme di operazioni su una o più entità. È garantito che ogni transazione sia atomica, il che significa che non vengono mai applicate parzialmente. Vengono applicate tutte le operazioni nella transazione o nessuna di esse.
Utilizzo delle transazioni
Le transazioni scadono dopo 270 secondi o se inattive per 60 secondi.
Un'operazione potrebbe non riuscire se:
- Vengono tentate troppe modifiche simultanee alla stessa entità.
- La transazione supera il limite di risorse.
- Il database in modalità Datastore riscontra un errore interno.
In tutti questi casi, l'API Datastore restituisce un errore.
Le transazioni sono una funzionalità facoltativa. Non è necessario utilizzare le transazioni per eseguire operazioni di database.
Un'applicazione può eseguire un insieme di istruzioni e operazioni in una singola transazione in modo che, se una qualsiasi istruzione o operazione genera un'eccezione, nessuna delle operazioni di database dell'insieme viene applicata. L'applicazione definisce le azioni da eseguire nella transazione.
Il seguente snippet mostra come eseguire una transazione. Trasferisce denaro da un account a un altro.
C#
Per scoprire come installare e utilizzare la libreria client per Cloud Datastore, consulta librerie client di Cloud Datastore. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Datastore C#.
Per eseguire l'autenticazione in Cloud Datastore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Go
Per scoprire come installare e utilizzare la libreria client per Cloud Datastore, consulta librerie client di Cloud Datastore. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Datastore Go.
Per eseguire l'autenticazione in Cloud Datastore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Java
Per scoprire come installare e utilizzare la libreria client per Cloud Datastore, consulta librerie client di Cloud Datastore. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Datastore Java.
Per eseguire l'autenticazione in Cloud Datastore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per scoprire come installare e utilizzare la libreria client per Cloud Datastore, consulta librerie client di Cloud Datastore. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Datastore Node.js.
Per eseguire l'autenticazione in Cloud Datastore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
PHP
Per scoprire come installare e utilizzare la libreria client per Cloud Datastore, consulta librerie client di Cloud Datastore. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Datastore PHP.
Per eseguire l'autenticazione in Cloud Datastore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Per scoprire come installare e utilizzare la libreria client per Cloud Datastore, consulta librerie client di Cloud Datastore. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Datastore Python.
Per eseguire l'autenticazione in Cloud Datastore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Ruby
Per scoprire come installare e utilizzare la libreria client per Cloud Datastore, consulta librerie client di Cloud Datastore. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Datastore Ruby.
Per eseguire l'autenticazione in Cloud Datastore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Tieni presente che, al fine di fornire esempi più concisi, a volte omettiamo rollback
se la transazione non va a buon fine. Nel codice di produzione, è importante garantire che per ogni transazione venga eseguito il commit esplicito o il rollback.
Cosa si può fare in una transazione
Le transazioni possono eseguire query o ricerche su un numero qualsiasi di entità. La dimensione massima di una transazione è 10 MiB. Puoi utilizzare una transazione di lettura-scrittura o una transazione di sola lettura.
Isolamento e coerenza
I database in modalità Datastore applicano l'isolamento seriale. I dati letti o modificati da una transazione non possono essere modificati contemporaneamente.
Query e ricerche in una transazione visualizzano uno snapshot coerente dello stato del database. È garantito che questo snapshot contenga l'effetto di tutte le transazioni e le scritture completate prima dell'inizio della transazione.
Questa visualizzazione snapshot coerente si estende anche alle letture dopo le scritture all'interno delle transazioni. A differenza della maggior parte dei database, per query e ricerche all'interno di una transazione in modalità Datastore non vengono visualizzati i risultati delle scritture precedenti all'interno di quella transazione. Nello specifico, se un'entità viene modificata o eliminata all'interno di una transazione, una query o una ricerca restituisce la versione originale dell'entità all'inizio della transazione o nulla se l'entità non esisteva all'inizio della transazione.
Al di fuori delle transazioni, anche le query e le ricerche hanno un isolamento serializzabile.
Modalità di contemporaneità
Firestore in modalità Datastore supporta tre modalità di contemporaneità. La modalità di contemporaneità è un'impostazione del database che determina il modo in cui le transazioni simultanee interagiscono. Puoi selezionare una delle seguenti modalità di contemporaneità:
Pessimistico
Le transazioni di lettura-scrittura utilizzano blocchi di lettura/scrittura per applicare l'isolamento e la serietà. Quando due o più transazioni di lettura-scrittura simultanee leggono o scrivono gli stessi dati, il blocco mantenuto da una transazione può ritardare le altre. Se la transazione non richiede operazioni di scrittura, puoi migliorare le prestazioni ed evitare conflitti con altre transazioni utilizzando una transazione di sola lettura. Le transazioni di sola lettura non richiedono alcun blocco.
I database di Firestore in modalità Datastore utilizzano la modalità di contemporaneità pessimistica per impostazione predefinita.
Ottimista
Quando due o più transazioni di lettura-scrittura simultanee leggono o scrivono gli stessi dati, ha esito positivo solo la prima transazione a cui è stato eseguito il commit delle modifiche. Altre transazioni che eseguono scritture non superano il commit.
I gruppi di entità sono ottimisti
Utilizza questa modalità di contemporaneità solo se la tua app dipende dalla semantica transazionale del gruppo di entità di Cloud Datastore precedente. Questa modalità di contemporaneità pone limiti aggiuntivi alle transazioni:
- Le transazioni sono limitate a 25 gruppi di entità.
- Le scritture in un gruppo di entità sono limitate a 1 al secondo.
- Le query nelle transazioni devono essere query dei predecessori.
Visualizza modalità di contemporaneità
Utilizza la risorsa REST Firestore projects.databases per visualizzare la modalità di contemporaneità del tuo database:
curl -X GET -H "Authorization: Bearer "$(gcloud auth print-access-token) \
"https://firestore.googleapis.com/v1/projects/PROJECT_ID/databases"
Cambia la modalità di contemporaneità
Per modificare la modalità di contemporaneità del database, invia una richiesta PATCH
alla risorsa REST Firestore
projects.databases:
curl --request PATCH \
--header "Authorization: Bearer "$(gcloud auth print-access-token) \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"concurrencyMode":"CONCURRENCY_MODE"}' \
"https://firestore.googleapis.com/v1/projects/PROJECT_ID/databases/(default)?updateMask=concurrencyMode"
dove:
- CONCURRENCY_MODE è
PESSIMISTIC
,OPTIMISTIC
oOPTIMISTIC_WITH_ENTITY_GROUPS
. - PROJECT_ID è l'ID del tuo progetto Google Cloud.
Utilizzi per le transazioni
Un uso delle transazioni è l'aggiornamento di un'entità con un nuovo valore della proprietà rispetto al suo valore attuale. L'esempio transferFunds
riportato sopra lo fa per due entità, prelevando denaro da un account e trasferendolo a un altro.
L'API Datastore non riprova automaticamente le transazioni, ma puoi aggiungere la tua logica per riprovare, ad esempio per gestire i conflitti quando un'altra richiesta aggiorna la stessa entità contemporaneamente.
C#
Per scoprire come installare e utilizzare la libreria client per Cloud Datastore, consulta librerie client di Cloud Datastore. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Datastore C#.
Per eseguire l'autenticazione in Cloud Datastore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Go
Per scoprire come installare e utilizzare la libreria client per Cloud Datastore, consulta librerie client di Cloud Datastore. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Datastore Go.
Per eseguire l'autenticazione in Cloud Datastore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Java
Per scoprire come installare e utilizzare la libreria client per Cloud Datastore, consulta librerie client di Cloud Datastore. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Datastore Java.
Per eseguire l'autenticazione in Cloud Datastore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per scoprire come installare e utilizzare la libreria client per Cloud Datastore, consulta librerie client di Cloud Datastore. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Datastore Node.js.
Per eseguire l'autenticazione in Cloud Datastore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
PHP
Per scoprire come installare e utilizzare la libreria client per Cloud Datastore, consulta librerie client di Cloud Datastore. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Datastore PHP.
Per eseguire l'autenticazione in Cloud Datastore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Per scoprire come installare e utilizzare la libreria client per Cloud Datastore, consulta librerie client di Cloud Datastore. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Datastore Python.
Per eseguire l'autenticazione in Cloud Datastore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Ruby
Per scoprire come installare e utilizzare la libreria client per Cloud Datastore, consulta librerie client di Cloud Datastore. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Datastore Ruby.
Per eseguire l'autenticazione in Cloud Datastore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Ciò richiede una transazione perché il valore di balance
in un'entità può essere aggiornato da un altro utente dopo che questo codice recupera l'oggetto, ma prima che venga salvato l'oggetto modificato. Senza una transazione, la richiesta dell'utente utilizza il valore balance
prima dell'aggiornamento dell'altro utente e il salvataggio sovrascrive il nuovo valore. Con una
transazione, all'applicazione viene comunicato l'aggiornamento dell'altro utente.
Un altro uso comune delle transazioni è il recupero di un'entità con una chiave denominata o la sua creazione se non esiste ancora (questo esempio si basa sull'esempio di TaskList derivante dalla creazione di un'entità):
C#
Per scoprire come installare e utilizzare la libreria client per Cloud Datastore, consulta librerie client di Cloud Datastore. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Datastore C#.
Per eseguire l'autenticazione in Cloud Datastore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Go
Per scoprire come installare e utilizzare la libreria client per Cloud Datastore, consulta librerie client di Cloud Datastore. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Datastore Go.
Per eseguire l'autenticazione in Cloud Datastore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Java
Per scoprire come installare e utilizzare la libreria client per Cloud Datastore, consulta librerie client di Cloud Datastore. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Datastore Java.
Per eseguire l'autenticazione in Cloud Datastore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per scoprire come installare e utilizzare la libreria client per Cloud Datastore, consulta librerie client di Cloud Datastore. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Datastore Node.js.
Per eseguire l'autenticazione in Cloud Datastore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
PHP
Per scoprire come installare e utilizzare la libreria client per Cloud Datastore, consulta librerie client di Cloud Datastore. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Datastore PHP.
Per eseguire l'autenticazione in Cloud Datastore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Per scoprire come installare e utilizzare la libreria client per Cloud Datastore, consulta librerie client di Cloud Datastore. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Datastore Python.
Per eseguire l'autenticazione in Cloud Datastore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Ruby
Per scoprire come installare e utilizzare la libreria client per Cloud Datastore, consulta librerie client di Cloud Datastore. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Datastore Ruby.
Per eseguire l'autenticazione in Cloud Datastore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Come in precedenza, una transazione è necessaria per gestire il caso in cui un altro utente stia tentando di creare o aggiornare un'entità con lo stesso ID stringa. Senza una transazione, se l'entità non esiste e due utenti tentano di crearla, il secondo sovrascrive la prima senza sapere che è avvenuta.
Se una transazione non va a buon fine, puoi fare in modo che l'app esegua un nuovo tentativo finché non va a buon fine oppure puoi consentire agli utenti di gestire l'errore propagandolo al livello dell'interfaccia utente della tua app. Non è necessario creare un ciclo di nuovi tentativi per ogni transazione.
Transazioni di sola lettura
Infine, puoi utilizzare una transazione per leggere uno snapshot coerente del database. Questo può essere utile quando hai bisogno di più letture per eseguire il rendering di una pagina o per esportare dati che devono essere coerenti. Per questi casi puoi creare una transazione di sola lettura.
Le transazioni di sola lettura non possono modificare le entità, ma in cambio non sono in concorrenza con altre transazioni e non devono essere tentate di nuovo. Se esegui le letture solo in una normale transazione di lettura-scrittura, tale transazione potrebbe entrare in concorrenza con una transazione che modifica gli stessi dati.
C#
Per scoprire come installare e utilizzare la libreria client per Cloud Datastore, consulta librerie client di Cloud Datastore. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Datastore C#.
Per eseguire l'autenticazione in Cloud Datastore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Go
Per scoprire come installare e utilizzare la libreria client per Cloud Datastore, consulta librerie client di Cloud Datastore. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Datastore Go.
Per eseguire l'autenticazione in Cloud Datastore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Java
Per scoprire come installare e utilizzare la libreria client per Cloud Datastore, consulta librerie client di Cloud Datastore. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Datastore Java.
Per eseguire l'autenticazione in Cloud Datastore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per scoprire come installare e utilizzare la libreria client per Cloud Datastore, consulta librerie client di Cloud Datastore. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Datastore Node.js.
Per eseguire l'autenticazione in Cloud Datastore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
PHP
Per scoprire come installare e utilizzare la libreria client per Cloud Datastore, consulta librerie client di Cloud Datastore. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Datastore PHP.
Per eseguire l'autenticazione in Cloud Datastore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Per scoprire come installare e utilizzare la libreria client per Cloud Datastore, consulta librerie client di Cloud Datastore. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Datastore Python.
Per eseguire l'autenticazione in Cloud Datastore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Ruby
Per scoprire come installare e utilizzare la libreria client per Cloud Datastore, consulta librerie client di Cloud Datastore. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Cloud Datastore Ruby.
Per eseguire l'autenticazione in Cloud Datastore, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Passaggi successivi
- Scopri di più sulle query.