Google Cloud CLI fornisce un emulatore in memoria locale 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. 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 i deployment di produzione. Poiché l'emulatore archivia i dati solo in memoria, i dati non vengono conservati tra le esecuzioni.
Installa l'emulatore
Per installare l'emulatore Firestore, installa e aggiorna gcloud CLI:
Aggiorna l'installazione dell'interfaccia alla gcloud CLI per ottenere le ultime funzionalità:
gcloud components update
Esegui l'emulatore
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 su cui è in esecuzione.
Per impostazione predefinita, l'emulatore tenta di utilizzare
127.0.0.1:8080
. Per associare l'emulatore a una porta e a un host specifici, utilizza il flag facoltativo--host-port
, sostituendo HOST e PORT:gcloud emulators firestore start --database-mode=datastore-mode --host-port=HOST:PORT
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
. Se 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 entità da un set di file di esportazione delle entità nell'emulatore. I file di esportazione delle entità possono provenire da un'esportazione del database in modalità Datastore o da un'istanza di un emulatore.
Puoi importare 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 una porta diversa.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 un database predefinito sarebbe simile al seguente:{"database":"projects/myProject/databases/"}
[EXPORT_DIRECTORY]
è il percorso del fileoverall_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 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 dell'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 è
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 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 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 i file di esportazione delle entità. Questa directory non deve contenere già un insieme di file di esportazione delle entità. Ad esempio:{"export_directory":"/home/user/myexports/2024-03-26/"}
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 HTTP POST
sul
seguente endpoint, sostituendo HOST e PORT con
l'host e la porta selezionati e sostituendo PROJECT_ID con il
tuo ID progetto:
http://HOST:PORT/reset
Regola l'host e la porta se l'emulatore non usa 127.0.0.1:8080
.
Il codice dovrebbe attendere la conferma REST che conferma il completamento o l'esito negativo del ripristino.
Puoi eseguire questa operazione dalla shell utilizzando curl
:
$ curl -X POST "http://HOST:PORT/reset"
Differenze tra l'emulatore e la versione di 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 una contemporaneità pessimistica e un'elevata coerenza. L'emulatore non supporta le impostazioni di contemporaneità ottimistica e di coerenza finale.
Transazioni
L'emulatore non implementa tutti i comportamenti delle transazioni in produzione. Quando testi funzionalità che prevedono più scritture simultanee su 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 tiene traccia degli indici composti, ma esegue qualsiasi query valida. Assicurati di testare l'app con un'istanza in modalità Datastore reale per determinare quali indici sono necessari.
Limiti
L'emulatore non applica tutti i limiti applicati in produzione. Ad esempio, l'emulatore potrebbe consentire transazioni che verrebbero rifiutate come troppo grandi dal servizio di produzione. Assicurati di conoscere i limiti documentati e di progettare la tua app in modo da evitarli in modo proattivo.
Passaggi successivi
- Scopri come utilizzare Entità, proprietà e chiavi
- Scopri di più sulle query