Utilizzare l'emulatore Firestore localmente

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

Non utilizzare l'emulatore per i deployment in produzione. Poiché l'emulatore memorizza i dati solo in memoria, non li manterrà nelle esecuzioni successive.

Installa l'emulatore

Per installare l'emulatore Firestore, installa e aggiorna l'interfaccia a riga di comando gcloud:

  1. Installa la gcloud CLI.

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

    gcloud components update

Esegui l'emulatore

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

    gcloud emulators firestore start

    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 --host-port=HOST:PORT

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

    curl -d '' HOST:PORT/shutdown

Connettiti all'emulatore

Il modo in cui ti connetti all'emulatore dipende dal tipo di libreria client, dalla libreria client del server o dall'SDK mobile/web.

Librerie client server

Per collegare 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"

Android, piattaforme Apple e SDK web

Gli esempi riportati di seguito mostrano come collegare le piattaforme Android, Apple e gli SDK 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 cancella i contenuti del database quando viene arrestato. Poiché la cache offline dell'SDK Firestore non viene cancellata automaticamente, ti consigliamo di disattivare la persistenza locale nella configurazione dell'emulatore per evitare discrepanze tra il database simulato 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 nell'emulatore. Puoi utilizzare questo endpoint per cancellare i dati tra un test e l'altro senza arrestare l'emulatore.

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

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

Modifica l'host e la porta se l'emulatore non utilizza 127.0.0.1:8080. Il codice deve attendere la conferma REST dell'avvenuta o mancata eliminazione.

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

Transazioni

L'emulatore non implementa tutti i comportamenti di transazione osservati 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, la disattivazione 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 eseguirà invece qualsiasi query valida. Assicurati di testare l'app su un'istanza Firestore reale per determinare gli indici di cui hai bisogno.

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.