Testa la modalità Datastore utilizzando l'emulatore Firestore

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

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

Non utilizzare l'emulatore per i deployment in produzione. Poiché l'emulatore archivia solo i dati in memoria, i dati non vengono conservati 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 la versione più recente caratteristiche:

    gcloud components update

Esegui l'emulatore

  1. Esegui il seguente comando per avviare l'emulatore:

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

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

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

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

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

Connettiti all'emulatore

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

export DATASTORE_EMULATOR_HOST="HOST:PORT"

Importa le entità nell'emulatore

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

Puoi importare entità nell'emulatore in due modi. Il primo consiste nell'aggiungere segnala import-data al comando di avvio dell'emulatore. Il secondo metodo consiste nell'inviare una richiesta di importazione POST all'emulatore. Puoi utilizzare curl o uno strumento simile. Consulta le 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 una porta diversa.

Flag CLI

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

dove:

  • [PROJECT_ID] è l'ID del tuo 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"}

Esportare le entità nell'emulatore

La funzione di esportazione dell'emulatore 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 nei file di esportazione delle entità nel database in modalità Datastore in un'istanza dell'emulatore.

Puoi esportare le entità dall'emulatore in due modi. Il primo consiste nell'aggiungere il flag export-on-exit al comando di avvio dell'emulatore. Il secondo metodo consiste invia una richiesta di esportazione POST all'emulatore. Puoi utilizzare la modalità 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 una porta diversa.

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 tuo progetto.

  • [DATABASE_PATH] è il percorso del database. Ad esempio, un progetto con un database predefinito sarebbe simile al seguente:

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

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

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

Mantieni i dati nell'emulatore

Per impostazione predefinita, l'emulatore Firestore non rende persistenti i dati sul disco. Per salvare in modo permanente i dati dell'emulatore, esegui questo comando per usare le operazioni di importazione ed esportazione per caricare e salvare i dati nelle istanze dell'emulatore:

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

Reimposta dati dell'emulatore

L'emulatore Firestore include un endpoint REST per reimpostare tutti i dati nell'emulatore. Puoi usare questo endpoint per cancellare i dati tra i test senza arrestare l'emulatore.

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

http://HOST:PORT/reset

Regola l'host e la porta se l'emulatore non usa 127.0.0.1:8080. Il codice deve attendere la conferma REST che il ripristino è stato completato o non è riuscito.

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 significative.

Contemporaneità e coerenza

L'emulatore supporta solo la concorrenza pessimistica e la coerenza forte. L'emulatore non supporta la contemporaneità ottimistica e la coerenza finale impostazioni.

Transazioni

L'emulatore non implementa tutti i comportamenti delle transazioni visto in produzione. Quando testi funzionalità che richiedono più scrittura contemporaneamente in un documento, l'emulatore potrebbe essere lento a completare le richieste di scrittura. In alcuni casi, il rilascio dei blocchi può richiedere fino a 30 secondi. Valuta la possibilità di modificare i timeout dei test di conseguenza, se necessario.

Indici

L'emulatore non monitora gli indici composti, ma esegue qualsiasi query valida. Assicurati di testare l'app su un'istanza reale della modalità Datastore per determinare quali indici ti occorrono.

Limiti

L'emulatore non applica tutti i limiti applicati in produzione. Ad esempio: l'emulatore potrebbe consentire transazioni che verrebbero rifiutate in quanto troppo grandi dall' un servizio di produzione. Assicurati di conoscere le limiti documentati e che tu progetterai per la tua app evitarli in modo proattivo.

Passaggi successivi