Connetti la tua app all'emulatore di Cloud Firestore

Prima di collegare l'app all'emulatore Cloud Firestore, assicurati di comprendere il flusso di lavoro complessivo di Firebase Local Emulator Suite, di installare e configurare Local Emulator Suite e di esaminare i relativi comandi CLI.

Scegli un progetto Firebase

L'elemento Firebase Local Emulator Suite emula i prodotti per un singolo progetto Firebase.

Per selezionare il progetto da utilizzare, prima di avviare gli emulatori, esegui firebase use nella directory di lavoro in CLI. In alternativa, puoi passare il flag --project per ogni emulatore .

Local Emulator Suite supporta l'emulazione di progetti Firebase reali e progetti demo.

Tipo di progetto Funzionalità Usa con emulatori
Reale

Un vero progetto Firebase è un progetto che hai creato e configurato (molto probabilmente tramite la console Firebase).

I progetti reali includono risorse in tempo reale, ad esempio istanze di database, bucket, funzioni o qualsiasi altra risorsa configurata per l'account Firebase progetto.

Quando lavori con progetti Firebase reali, puoi eseguire emulatori per qualsiasi o tutti i prodotti supportati.

Per i prodotti non emulati, le tue app e il tuo codice interagiscono con la risorsa live (istanza di database, bucket, funzione e così via).

Demo

Un progetto Firebase dimostrativo non ha una configurazione Firebase reale e nessuna risorsa attiva. Questi progetti sono in genere accessibili tramite codelab o altri tutorial.

Gli ID progetto dei progetti demo hanno il prefisso demo-.

Quando lavori con progetti Firebase dimostrativi, le app e il codice interagiscono con solo emulatori. Se la tua app tenta di interagire con una risorsa per cui non è in esecuzione un emulatore, il codice restituirà un errore.

Ti consigliamo di utilizzare i progetti dimostrativi, se possibile. I vantaggi includono:

  • Configurazione più semplice, in quanto è possibile eseguire gli emulatori senza mai creare un Progetto Firebase
  • Maggiore sicurezza, poiché se il codice richiama accidentalmente la modalità non emulata di produzione, non c'è la possibilità che i dati vengano modificati, utilizzati e fatturati
  • Migliore supporto offline, in quanto non è necessario accedere a Internet per scarica la configurazione SDK.
di Gemini Advanced.

Imposta la tua app per comunicare con gli emulatori

All'avvio, l'emulatore Cloud Firestore crea un database predefinito e un oggetto per ogni configurazione firestore nel tuo firebase.json file.

I database denominati vengono creati anche implicitamente in risposta a qualsiasi SDK o Chiamate API REST all'emulatore che fanno riferimento a un database specifico. Questi database creati implicitamente funzionano con regole aperte.

Per utilizzare i database predefiniti e denominati in modo interattivo in Emulator Suite UI, aggiorna l'URL nella barra degli indirizzi del browser e seleziona predefinito o denominato.

  • Ad esempio, per sfogliare i dati nell'istanza predefinita, aggiorna l'URL in localhost:4000/firestore/default/data
  • Per sfogliare un'istanza denominata ecommerce, esegui l'aggiornamento a localhost:4000/firestore/ecommerce/data.

Piattaforme Android, Apple e SDK web

Configura la configurazione in-app o i test di classe per interagire con Cloud Firestore come segue. Tieni presente che negli esempi riportati di seguito, il codice dell'app si sta connettendo al database di progetto predefinito. Per esempi che coinvolgono database Cloud Firestore aggiuntivi oltre a quello predefinito, consulta la guida per più database.

Kotlin+KTX
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
val firestore = Firebase.firestore
firestore.useEmulator("10.0.2.2", 8080)

firestore.firestoreSettings = firestoreSettings {
    isPersistenceEnabled = false
}
EmulatorSuite.kt
Java
// 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

Web

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

Web

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

Non è necessaria alcuna configurazione aggiuntiva per testare Cloud Functions attivata da eventi Firestore usando l'emulatore. Quando gli emulatori di Firestore e Cloud Functions sono entrambi in esecuzione, interagiscono automaticamente.

Admin SDK s

I Firebase Admin SDK si connettono automaticamente al Cloud Firestore quando è impostata la variabile di ambiente FIRESTORE_EMULATOR_HOST:

export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080"

Se il tuo codice è in esecuzione nell'emulatore Cloud Functions, il tuo ID progetto e altre configurazioni vengono impostate automaticamente quando chiami initializeApp.

Se vuoi che il codice Admin SDK si connetta a un emulatore condiviso in esecuzione in un altro ambiente, devi specificare lo stesso ID progetto che hai impostato utilizzando l'interfaccia a riga di comando di Firebase. Puoi passare un ID progetto direttamente a initializeApp o impostare la variabile di ambiente GCLOUD_PROJECT.

SDK Node.js Admin
admin.initializeApp({ projectId: "your-project-id" });
Variabile di ambiente
export GCLOUD_PROJECT="your-project-id"

Svuotare il database tra un test e l'altro

Firestore non fornisce alcun metodo SDK della piattaforma per lo svuotamento del database, ma l'emulatore Firestore ti fornisce un endpoint REST specifico per questo scopo, che può essere chiamato da un passaggio di configurazione/teardown di un framework di test, da una classe di test o dalla shell (ad esempio, con curl) prima che venga avviato un test. Puoi usare questo approccio in alternativa all'arresto del semplice processo dell'emulatore.

In un metodo appropriato, esegui un'operazione HTTP DELETE, fornendo il tuo ID progetto Firebase, ad esempio firestore-emulator-example, al seguente endpoint:

"http://localhost:8080/emulator/v1/projects/firestore-emulator-example/databases/(default)/documents"

Ovviamente, il codice dovrebbe attendere la conferma REST che lo svuotamento sia terminato o non sia riuscito.

Puoi eseguire questa operazione dalla shell:

// Shell alternative…
$ curl -v -X DELETE "http://localhost:8080/emulator/v1/projects/firestore-emulator-example/databases/(default)/documents"

Dopo aver implementato un passaggio come questo, puoi sequenza i tuoi test e attivare le tue funzioni con la certezza che i vecchi dati verranno eliminati definitivamente tra le esecuzioni utilizzi una configurazione di test di base aggiornata.

Importazione ed esportazione di dati

Gli emulatori di database e Cloud Storage for Firebase ti consentono di esportare i dati da un'istanza di emulatore in esecuzione. Definisci un set di dati di riferimento da utilizzare nel tuo test delle unità o flussi di lavoro di integrazione continua, quindi esportali per condividerli nel team.

firebase emulators:export ./dir

Nei test, all'avvio dell'emulatore, importa i dati di riferimento.

firebase emulators:start --import=./dir

Puoi indicare all'emulatore di esportare i dati all'arresto, specificando percorso di esportazione o semplicemente utilizzando il percorso passato a --import flag.

firebase emulators:start --import=./dir --export-on-exit

Queste opzioni di importazione ed esportazione dei dati funzionano con firebase emulators:exec. Per ulteriori informazioni, consulta riferimento per i comandi dell'emulatore.

Visualizza l'attività delle regole di sicurezza

Mentre lavori ai prototipi e ai cicli di test, puoi utilizzare gli strumenti di visualizzazione e i report forniti da Local Emulator Suite.

Utilizzare il Monitoraggio richieste

L'emulatore Cloud Firestore ti consente di visualizzare le richieste del client Emulator Suite UI, incluso il tracciamento della valutazione per Firebase Security Rules.

Apri Firestore > Richieste per visualizzare la valutazione dettagliata una sequenza per ogni richiesta.

Monitoraggio delle richieste dell'emulatore Firestore che mostra le valutazioni delle regole di sicurezza

Visualizza i report di valutazione delle regole

Man mano che aggiungi regole di sicurezza al tuo prototipo, puoi eseguirne il debug Strumenti di debug di Local Emulator Suite.

Dopo aver eseguito una suite di test, puoi accedere e report sulla copertura che mostrano come è stata valutata ciascuna delle tue regole di sicurezza.

Per ottenere i report, esegui una query su un endpoint esposto sull'emulatore sia in esecuzione. Per una versione ottimizzata per il browser, utilizza il seguente URL:

http://localhost:8080/emulator/v1/projects/<database_name>:ruleCoverage.html

In questo modo, le regole vengono suddivise in espressioni e sottoespressioni su cui puoi eseguire il passaggio del mouse per visualizzare ulteriori informazioni, tra cui il numero di valutazioni e i valori restituiti. Per la versione JSON non elaborata di questi dati, includi il seguente URL nella tua query:

http://localhost:8080/emulator/v1/projects/<database_name>:ruleCoverage

In questo caso, la versione HTML del report evidenzia le valutazioni che generano errori non definiti e con valore nullo:

Differenze dell'emulatore Cloud Firestore dalla produzione

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

Supporto di più database per Cloud Firestore

Attualmente, l'Emulator Suite UI supporta la creazione, la modifica e eliminazione, monitoraggio delle richieste e visualizzazione della sicurezza per un database predefinito ma non altri database denominati.

Tuttavia, l'emulatore stesso crea un database denominato basato sul configurazione nel file firebase.json e implicitamente in risposta all'SDK o Chiamate API REST.

Transazioni

Al momento 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, la disattivazione delle serrature 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 una query valida. Assicurati di testare l'app su un'istanza Cloud Firestore reale per determinare quali indici ti serviranno.

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.

Che cosa succede ora?