Esecuzione dell'emulatore Datastore

L'emulatore Datastore fornisce un'emulazione locale dell'ambiente Datastore di produzione. Puoi utilizzare l'emulatore per sviluppare e testare la tua applicazione localmente. Inoltre, l'emulatore può aiutarti a generare indici per l'istanza Datastore di produzione ed eliminare gli indici non necessari. Questa pagina descrive la procedura per installare l'emulatore, avviarlo e impostare le variabili di ambiente per collegare l'applicazione all'emulatore.

Problemi noti

Per impostazione predefinita, l'emulatore Datastore non emula le funzionalità introdotte da Firestore in modalità Datastore. I seguenti comportamenti predefiniti dell'emulatore non corrispondono alla modalità Datastore:

  • Per impostazione predefinita, l'emulatore simula la coerenza finale. Firestore in modalità Datastore è fortemente coerente.
  • L'emulatore non consente query non antecedenti all'interno delle transazioni. Firestore in modalità Datastore non ha più questa limitazione.
  • L'emulatore non supporta le query IN, != e NOT-IN.
  • L'emulatore non supporta le 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 antecedenti fortemente coerenti.
  • L'emulatore consente query non relative all'antenato all'interno delle transazioni.
  • L'emulatore rimuove la limitazione 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, devi avere:

Installazione dell'emulatore

L'emulatore Datastore è un componente dellgcloud CLI. Utilizza il comando gcloud components install per installare l'emulatore 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 memorizzando 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 viene mantenuto tra le sessioni dell'emulatore. Puoi configurare più directory di dati e considerarle come istanze separate e locali della modalità Datastore. 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 gli argomenti facoltativi della riga di comando forniti al gcloud CLI. Ad esempio:

  • --data-dir=[DATA_DIR] modifica la directory dei dati dell'emulatore. L'emulatore crea il file /WEB-INF/appengine-generated/local_db.bin all'interno di [DATA_DIR] o, se disponibile, utilizza un file esistente.

  • --no-store-on-disk configura l'emulatore in modo da non conservare alcun dato sul disco per la sessione dell'emulatore.

Consulta la documentazione di 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 produzione in modalità Datastore. Imposta queste 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 dai numeri di porta assegnati in modo dinamico che potrebbero cambiare quando riavvii l'emulatore.

Impostazione automatica delle variabili

Se l'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

L'applicazione si connetterà all'emulatore Datastore.

Impostazione manuale delle variabili

Se l'applicazione e l'emulatore vengono eseguiti su macchine diverse, imposta manualmente le variabili di ambiente:

  1. Esegui il comando env-init:

    gcloud beta emulators datastore env-init

  2. Sulla macchina su cui viene eseguita l'applicazione, imposta le variabili di ambiente e i valori 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

L'applicazione si connetterà all'emulatore Datastore. Tieni presente che l'ID progetto e la porta forniti dal comando saranno diversi dall'esempio riportato sopra.

Aggiornamento ed eliminazione di indici

Se esegui l'applicazione utilizzando l'emulatore, puoi generare indici per il database in modalità Datastore di produzione ed eliminare quelli non necessari. Scopri di più nella pagina Utilizzare l'interfaccia a riga di comando gcloud.

Rimuovere le variabili di ambiente

Al termine dell'utilizzo dell'emulatore, interrompilo (Control-C) e rimuovi le variabili di ambiente in modo che l'applicazione si connetta al database di produzione in modalità Datastore.

Rimozione automatica delle variabili

Se l'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

Ora l'applicazione si connetterà al database in modalità Datastore di produzione.

Rimuovere manualmente le variabili

Se l'applicazione e l'emulatore vengono eseguiti su macchine diverse,rimuovi le variabili di ambiente manualmente:

  1. Esegui il comando env-unset:

    gcloud beta emulators datastore env-unset

  2. Sulla macchina che esegue l'applicazione, rimuovi le variabili di ambiente come indicato dall'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=

Ora l'applicazione si connetterà al database in modalità Datastore di produzione.