Testa la modalità Datastore utilizzando l'emulatore Firestore

Google Cloud CLI fornisce un emulatore in memoria locale per Firestore che puoi utilizzare per testare Firestore in applicazione in modalità Datastore. Puoi utilizzare l'emulatore con tutte le librerie client in modalità Datastore. Dovresti usare l'emulatore solo per i test locali.

Utilizza gcloud emulators firestore con --database-mode=datastore-mode per testare il comportamento di Firestore in modalità Datastore.

Non utilizzare l'emulatore per le implementazioni di produzione. Poiché l'emulatore archivia i dati solo in memoria, non memorizza i dati tra le esecuzioni.

Installa l'emulatore

Per installare l'emulatore Firestore, installa e aggiorna gcloud CLI:

  1. Installa gcloud CLI.

  2. Aggiorna l'installazione di gcloud CLI per ottenere le ultime funzionalità:

    gcloud components update

Esegui l'emulatore

  1. Esegui questo comando per avviare l'emulatore:

    gcloud emulators firestore start --database-mode=datastore-mode

    L'emulatore stampa l'host e il numero di porta in cui è in esecuzione.

    Per impostazione predefinita, l'emulatore tenta di utilizzare 127.0.0.1:8080. Per associare l'emulatore a un host e a una porta specifici, usa il flag --host-port facoltativo, sostituendo HOST e PORT:

    gcloud emulators firestore start --database-mode=datastore-mode --host-port=HOST:PORT

  2. Usa la scorciatoia da tastiera Control + C per interrompere l'emulatore.

Connettiti all'emulatore

Per connettere una libreria client e un'app all'emulatore, imposta la variabile di ambiente DATASTORE_EMULATOR_HOST. Quando questa variabile di ambiente è impostata, le librerie client si connettono automaticamente all'emulatore.

export DATASTORE_EMULATOR_HOST="HOST:PORT"

Importa entità nell'emulatore

La funzionalità di importazione dell'emulatore ti consente di caricare nell'emulatore le entità da un insieme di file di esportazione delle entità. I file di esportazione delle entità possono provenire da un'esportazione del database in modalità Datastore o da un'istanza di emulatore.

Puoi importare le entità nell'emulatore in due modi. La prima consiste nell'aggiungere il flag import-data al comando di avvio dell'emulatore. Il secondo metodo consiste nell'inviare una richiesta di importazione POST all'emulatore. Puoi usare curl o uno strumento simile. Fai riferimento ai seguenti esempi.

Protocollo

curl -X POST http://localhost:8080/emulator/v1/projects/[PROJECT_ID]:import \
-H 'Content-Type: application/json' \
-d '{"database":"[DATABASE]", "export_directory":"[EXPORT_DIRECTORY]"}'
Modifica localhost:8080 se l'emulatore utilizza un'altra porta.

Flag interfaccia a riga di comando

gcloud emulators firestore start --database-mode=datastore-mode --import-data=[EXPORT_DIRECTORY]

dove:

  • [PROJECT_ID] è l'ID del progetto.

  • [DATABASE] è il percorso del database. Ad esempio, un progetto con database predefinito avrà il seguente aspetto:

    {"database":"projects/myProject/databases/"}

  • [EXPORT_DIRECTORY] è il percorso del file overall_export_metadata dei file di esportazione delle entità. Ad esempio:

    {"export_directory":"/home/user/myexports/2024-03-26T19:39:33_443/2024-03-26T19:39:33_443.overall_export_metadata"}

Esporta entità nell'emulatore

La funzionalità di esportazione dell'emulatore ti consente di salvare le entità nell'emulatore in un insieme di file di esportazione delle entità. Puoi quindi utilizzare un'operazione di importazione per caricare le entità nei file di esportazione delle entità nel database in modalità Datastore o in un'istanza di emulatore.

Puoi esportare le entità dall'emulatore in due modi. La prima consiste nell'aggiungere il flag export-on-exit al comando di avvio dell'emulatore. Il secondo metodo consiste nell'inviare una richiesta di esportazione POST all'emulatore. Puoi usare curl o uno strumento simile. Fai riferimento ai seguenti esempi.

Protocollo

curl -X POST http://localhost:8080/emulator/v1/projects/[PROJECT_ID]:export \
-H 'Content-Type: application/json' \
-d '{"database":"[DATABASE_PATH]", "export_directory":"EXPORT_DIRECTORY"}'
Modifica localhost:8080 se l'emulatore utilizza un'altra porta.

Flag interfaccia a riga di comando

gcloud emulators firestore start --database-mode=datastore-mode --export-on-exit=EXPORT_DIRECTORY

dove:

  • [PROJECT_ID] è l'ID del progetto.

  • [DATABASE_PATH] è il percorso del database. Ad esempio, un progetto con database predefinito avrà il seguente aspetto:

    {"database":"projects/myProject/databases/"}

  • [EXPORT_DIRECTORY] specifica la directory in cui l'emulatore salva i file di esportazione delle entità. Questa directory non deve contenere già un set di file di esportazione delle entità. Ad esempio:

    {"export_directory":"/home/user/myexports/2024-03-26/"}

Reimposta dati emulatore

L'emulatore Firestore include un endpoint REST per reimpostare tutti i dati al suo interno. Puoi usare questo endpoint per cancellare i dati tra i test senza spegnere l'emulatore.

Per reimpostare tutti i dati nell'emulatore, esegui un'operazione POST HTTP sul seguente endpoint, sostituendo HOST e PORT con l'host e la porta che hai selezionato e sostituendo PROJECT_ID con il tuo ID progetto:

http://HOST:PORT/reset

Regola l'host e la porta se l'emulatore non utilizza 127.0.0.1:8080. Il codice dovrebbe attendere la conferma da parte di REST che la reimpostazione è terminata o non è riuscita.

Puoi eseguire questa operazione dalla shell utilizzando curl:

$ curl -X POST "http://HOST:PORT/reset"

Differenze tra l'emulatore e la produzione

L'emulatore tenta di replicare fedelmente il comportamento del servizio di produzione con alcune limitazioni degne di nota.

Contemporaneità e coerenza

L'emulatore supporta solo contemporaneità pessimistica e elevata coerenza. L'emulatore non supporta le impostazioni di contemporaneità ottimistica e coerenza finale.

Transazioni

L'emulatore non implementa tutti i comportamenti delle transazioni visti in produzione. Quando stai testando funzionalità che prevedono più scritture simultanee in un documento, l'emulatore potrebbe essere lento a completare le richieste di scrittura. In alcuni casi, il rilascio delle serrature può richiedere fino a 30 secondi. Se necessario, valuta la possibilità di modificare di conseguenza i timeout dei test.

Indici

L'emulatore non monitora gli indici composti ed esegue invece qualsiasi query valida. Assicurati di testare l'app su un'istanza in modalità Datastore reale per determinare gli indici richiesti.

Limiti

L'emulatore non applica tutti i limiti applicati in produzione. Ad esempio, l'emulatore potrebbe consentire transazioni che verrebbero rifiutate dal servizio di produzione in quanto troppo grandi. Assicurati di conoscere i limiti documentati e di progettare la tua app in modo da evitarli in modo proattivo.

Passaggi successivi