L'emulatore Datastore fornisce l'emulazione locale dell'ambiente datastore di produzione. Puoi usare l'emulatore per sviluppare e testare la tua applicazione in locale. Inoltre, l'emulatore può aiutarti a generare indici per l'istanza Datastore di produzione ed eliminare gli indici non necessari. Questa pagina ti guiderà attraverso l'installazione dell'emulatore, l'avvio dell'emulatore e l'impostazione delle variabili di ambiente per connettere la tua applicazione all'emulatore.
Problemi noti
Per impostazione predefinita, l'emulatore Datastore non emula caratteristiche introdotte da Firestore in modalità Datastore. I seguenti comportamenti predefiniti dell'emulatore non corrispondono alla modalità Datastore:
- L'emulatore simula la coerenza finale, per impostazione predefinita. Firestore in modalità Datastore è a elevata coerenza.
- L'emulatore non consente query non relative ai predecessori all'interno delle transazioni. Firestore in modalità Datastore non ha più questa limitazione.
- L'emulatore non supporta le query
IN
,!=
eNOT-IN
. - L'emulatore non supporta query di aggregazione come
COUNT(*)
.
Tuttavia, il flag --use-firestore-in-datastore-mode consente di allentare alcune delle limitazioni riportate sopra per Firestore in modalità Datastore.
- L'emulatore simula query non relative ai predecessori a elevata coerenza.
- L'emulatore consente query non relative ai predecessori all'interno delle transazioni.
- L'emulatore rimuove il limite di 25 gruppi di entità in una transazione.
Per emulare Firestore in modalità Datastore, utilizza gcloud emulators firestore start --database-mode=datastore-mode
.
Prima di iniziare
Per utilizzare l'emulatore Datastore, hai bisogno di:
- Un JRE Java (versione 11 o successive)
- Google Cloud CLI
- Un'applicazione creata utilizzando le librerie client di Google Cloud
Installazione dell'emulatore
L'emulatore Datastore è un componente di gcloud CLI.
Utilizza il comando gcloud components install
per installare l'emulatore di datastore:
gcloud components install cloud-datastore-emulator
Directory dei dati dell'emulatore
L'emulatore simula Datastore creando /WEB-INF/appengine-generated/local_db.bin
in una directory di dati specificata e archiviando i dati in local_db.bin
. Per impostazione predefinita, l'emulatore utilizza la directory dei dati ~/.config/gcloud/emulators/datastore/
.
Il file local_db.bin
persiste tra le sessioni dell'emulatore. Puoi configurare più directory di dati e considerarle come un'istanza separata in modalità Datastore locale. Per cancellare i contenuti di un file local_db.bin
, interrompi l'emulatore ed elimina manualmente il file.
Avvio dell'emulatore
Avvia l'emulatore eseguendo datastore start
da un prompt dei comandi:
gcloud emulators datastore start [flags]
dove [flags]
sono argomenti facoltativi della riga di comando forniti a gcloud CLI. Ad esempio:
--data-dir=[DATA_DIR]
cambia la directory di dati dell'emulatore. L'emulatore crea il file/WEB-INF/appengine-generated/local_db.bin
all'interno di[DATA_DIR]
oppure, se disponibile, utilizza un file esistente.--no-store-on-disk
configura l'emulatore in modo da non rendere persistenti i dati su disco per la sessione dell'emulatore.
Consulta il riferimento gcloud beta emulators datastore start
per l'elenco completo dei flag facoltativi.
Dopo aver avviato l'emulatore, dovresti visualizzare un messaggio simile al seguente:
...
[datastore] Dev App Server is now running.
Per interrompere l'emulatore, digita Ctrl+C al prompt dei comandi.
Imposta le variabili di ambiente
Dopo aver avviato l'emulatore, devi impostare le variabili di ambiente in modo che l'applicazione si connetta all'emulatore anziché al database in modalità Datastore. Imposta le variabili di ambiente sulla stessa macchina che utilizzi per eseguire l'applicazione.
Devi impostare le variabili di ambiente ogni volta che avvii l'emulatore. Le variabili di ambiente dipendono da numeri di porta assegnati dinamicamente che potrebbero cambiare quando riavvii l'emulatore.
Impostazione automatica delle variabili
Se la tua applicazione e l'emulatore vengono eseguiti sulla stessa macchina, puoi impostare automaticamente le variabili di ambiente:
Linux / macOS
Esegui env-init
utilizzando la sostituzione dei comandi:
$(gcloud beta emulators datastore env-init)
Windows
Crea ed esegui un file batch utilizzando l'output di env-init
:
gcloud beta emulators datastore env-init > set_vars.cmd && set_vars.cmd
La tua applicazione si connetterà all'emulatore Datastore.
Impostare manualmente le variabili
Se la tua applicazione e l'emulatore vengono eseguiti su macchine diverse, imposta manualmente le variabili di ambiente:
Esegui il comando
env-init
:gcloud beta emulators datastore env-init
Sulla macchina che esegue l'applicazione, imposta le variabili e i valori di ambiente come indicato dall'output del comando
env-init
. Ad esempio:Linux / macOS export DATASTORE_DATASET=my-project-id export DATASTORE_EMULATOR_HOST=::1:8432 export DATASTORE_EMULATOR_HOST_PATH=::1:8432/datastore export DATASTORE_HOST=http://::1:8432 export DATASTORE_PROJECT_ID=my-project-id
Windows set DATASTORE_DATASET=my-project-id set DATASTORE_EMULATOR_HOST=::1:8432 set DATASTORE_EMULATOR_HOST_PATH=::1:8432/datastore set DATASTORE_HOST=http://::1:8432 set DATASTORE_PROJECT_ID=my-project-id
La tua applicazione si connetterà all'emulatore Datastore. Tieni presente che la porta e l'ID progetto forniti dal comando saranno diversi dall'esempio riportato sopra.
Aggiornamento ed eliminazione degli indici
Eseguendo la tua applicazione utilizzando l'emulatore, puoi generare indici per il database di produzione in modalità Datastore, nonché eliminare gli indici non necessari. Scopri di più, consulta l'articolo sull'utilizzo di gcloud CLI.
Rimozione delle variabili di ambiente in corso...
Dopo aver finito di utilizzare l'emulatore, interrompi l'emulatore (Control-C) e rimuovi le variabili di ambiente in modo che la tua applicazione si connetta al database in modalità Datastore di produzione.
Rimozione automatica delle variabili
Se la tua applicazione e l'emulatore vengono eseguiti sulla stessa macchina, puoi rimuovere automaticamente le variabili di ambiente:
Linux / macOS
Esegui env-unset
utilizzando la sostituzione dei comandi:
$(gcloud beta emulators datastore env-unset)
Windows
Crea ed esegui un file batch utilizzando l'output di env-unset
:
gcloud beta emulators datastore env-unset > remove_vars.cmd && remove_vars.cmd
L'applicazione ora si connetterà al tuo database in modalità Datastore di produzione.
Rimozione manuale delle variabili
Se la tua applicazione e l'emulatore vengono eseguiti su macchine diverse, rimuovi manualmente le variabili di ambiente:
Esegui il comando
env-unset
:gcloud beta emulators datastore env-unset
Sulla macchina che esegue l'applicazione, rimuovi le variabili di ambiente come indicato nell'output del comando
env-unset
. Ad esempio:Linux / macOS unset DATASTORE_DATASET unset DATASTORE_EMULATOR_HOST unset DATASTORE_EMULATOR_HOST_PATH unset DATASTORE_HOST unset DATASTORE_PROJECT_ID
Windows set DATASTORE_DATASET= set DATASTORE_EMULATOR_HOST= set DATASTORE_EMULATOR_HOST_PATH= set DATASTORE_HOST= set DATASTORE_PROJECT_ID=
L'applicazione ora si connetterà al tuo database in modalità Datastore di produzione.