Google Cloud CLI fornisce un emulatore locale in memoria per Firestore che puoi utilizzare per testare l'applicazione Firestore 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 memorizza i dati solo in memoria, non li mantiene nelle esecuzioni successive.
Installa l'emulatore
Per installare l'emulatore Firestore, installa e aggiorna l'interfaccia a riga di comando gcloud:
Aggiorna l'installazione di gcloud CLI per ottenere le funzionalità più recenti:
gcloud components update
Esegui l'emulatore
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 l'emulatore a un host e una porta 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 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 questo 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 insieme di esportazioni 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 emulatore.
Puoi importare le entità nell'emulatore in due modi. Il primo consiste nell'aggiungere il
flag import-data
al comando di avvio dell'emulatore. Il secondo metodo consiste
invia una richiesta di importazione 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:import \ -H 'Content-Type: application/json' \ -d '{"database":"DATABASE", "export_directory":"EXPORT_DIRECTORY"}'
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 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 fileoverall_export_metadata
di 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 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 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
curl o uno strumento simile. Consulta le
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"}'
localhost:8080
se l'emulatore utilizza una porta diversa.Flag CLI
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 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 mantenere i dati dell'emulatore, esegui il seguente comando per utilizzare i flag 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 tutte 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
Modifica l'host e la porta se l'emulatore non utilizza 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 cerca di replicare fedelmente il comportamento del servizio di produzione con alcune limitazioni degne di nota.
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 prevedono più scritture simultanee su un documento, l'emulatore potrebbe essere lento a completare la scrittura richieste. In alcuni casi, il rilascio dei blocchi può richiedere fino a 30 secondi. Se necessario, valuta la possibilità di modificare di conseguenza i timeout dei test.
Indici
L'emulatore non tiene traccia degli indici composti, ma esegue qualsiasi una 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 come troppo grandi dal servizio di produzione. Assicurati di conoscere i limiti documentati e di progettare l'app in modo da evitarli in modo proattivo.
Passaggi successivi
- Scopri come utilizzare entità, proprietà e chiavi
- Scopri di più sulle query