Utilizzare l'emulatore Firestore localmente

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

Non utilizzare l'emulatore per i deployment di produzione. Poiché l'emulatore archivia i dati solo in memoria, non li conserverà tra le esecuzioni.

Installare l'emulatore

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

  1. Installa gcloud CLI.

  2. Aggiorna l'installazione di gcloud CLI per ottenere le funzionalità più recenti:

    gcloud components update

Esegui l'emulatore

  1. Esegui questo comando per avviare l'emulatore:

    gcloud emulators firestore start

    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 una porta specifici, utilizza il flag facoltativo --host-port, sostituendo HOST e PORT:

    gcloud emulators firestore start --host-port=HOST:PORT

  2. Digita Control + C per arrestare l'emulatore. L'emulatore può anche essere arrestato con un POST a /shutdown. Ad esempio:

    curl -d '' HOST:PORT/shutdown

Connettersi all'emulatore

La modalità di connessione all'emulatore dipende dal tipo di libreria client, libreria client server o SDK mobile/web.

Librerie client server

Per connettere una libreria client server Firestore (C#, Go, Java, Node.js, PHP, Python e Ruby), imposta la variabile di ambiente FIRESTORE_EMULATOR_HOST. Quando questa variabile di ambiente è impostata, le librerie client del server si connettono automaticamente all'emulatore.

export FIRESTORE_EMULATOR_HOST="HOST:PORT"

SDK per Android, piattaforme Apple e web

Gli esempi riportati di seguito mostrano come connettere gli SDK per Android, le piattaforme Apple e il web all'emulatore Firestore:

Android
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
FirebaseFirestore firestore = FirebaseFirestore.getInstance();
firestore.useEmulator("10.0.2.2", 8080);

FirebaseFirestoreSettings settings = new FirebaseFirestoreSettings.Builder()
        .setPersistenceEnabled(false)
        .build();
firestore.setFirestoreSettings(settings);
EmulatorSuite.java
Swift
let settings = Firestore.firestore().settings
settings.host = "127.0.0.1:8080"
settings.cacheSettings = MemoryCacheSettings()
settings.isSSLEnabled = false
Firestore.firestore().settings = settings
ViewController.swift

Versione web 9

import { getFirestore, connectFirestoreEmulator } from "firebase/firestore";

// firebaseApps previously initialized using initializeApp()
const db = getFirestore();
connectFirestoreEmulator(db, '127.0.0.1', 8080);
fs_emulator_connect.js

Versione web 8

// Firebase previously initialized using firebase.initializeApp().
var db = firebase.firestore();
if (location.hostname === "localhost") {
  db.useEmulator("127.0.0.1", 8080);
}
emulator-suite.js

L'emulatore Firestore in modalità Native cancella i contenuti del database quando viene arrestato. Poiché la cache offline dell'SDK Firestore non viene cancellata automaticamente, potresti disattivare la persistenza locale nella configurazione dell'emulatore per evitare discrepanze tra il database emulato e le cache locali; nell'SDK web, la persistenza è disattivata per impostazione predefinita.

Cancellare i dati dell'emulatore

L'emulatore Firestore include un endpoint REST per eliminare tutti i dati attualmente presenti nell'emulatore. Puoi utilizzare questo endpoint per cancellare i dati tra i test senza spegnere l'emulatore.

Per eliminare tutti i dati nell'emulatore, esegui un'operazione HTTP DELETE sull'endpoint seguente, sostituendo HOST e PORT con l'host e la porta selezionati e sostituendo PROJECT_ID con il tuo ID progetto:

http://HOST:PORT/emulator/v1/projects/PROJECT_ID/databases/(default)/documents

Regola l'host e la porta se l'emulatore non utilizza 127.0.0.1:8080. Il codice deve attendere la conferma REST che l'eliminazione è stata completata o non è andata a buon fine.

Puoi eseguire questa operazione dalla shell utilizzando curl:

$ curl -v -X DELETE "http://HOST:PORT/emulator/v1/projects/PROJECT_ID/databases/(default)/documents"

Differenze tra l'emulatore Firestore e la produzione

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

Transazioni

L'emulatore non tenta di imitare il comportamento delle transazioni osservato in produzione. Utilizza un semplice approccio di blocco e non tenta di rispecchiare le varie modalità di concorrenza offerte nell'ambiente di produzione.

Quando testi funzionalità che comportano più scritture simultanee in un documento, l'emulatore potrebbe impiegare più tempo per completare le richieste di scrittura. Potrebbero essere necessari fino a 30 secondi prima che l'emulatore rilasci i blocchi. Se devi modificare gli intervalli di timeout del test, fallo.

L'emulatore non tenta inoltre di imitare tutti i limiti di produzione, come timeout e limiti di dimensioni, che riguardano le transazioni. Se testi funzionalità che dipendono da questi limiti di produzione, ti consigliamo di utilizzare un ambiente di produzione anziché un emulatore.

Indici

L'emulatore non tiene traccia degli indici composti ed esegue invece qualsiasi query valida. Assicurati di testare la tua app su un'istanza Firestore reale per determinare gli indici 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.