Connetti la tua app all'emulatore di Cloud Firestore

Prima di connettere la tua app all'emulatore Cloud Firestore, assicurati di comprendere il flusso di lavoro complessivo di Firebase Local Emulator Suite e di installare e configurare Local Emulator Suite, nonché di esaminare i relativi comandi dell'interfaccia a riga di comando.

Scegli un progetto Firebase

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 nell'interfaccia a riga di comando nella directory di lavoro. In alternativa, puoi passare il flag --project a ogni comando dell'emulatore.

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

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

• Configurazione più semplice, poiché puoi eseguire gli emulatori senza creare un progetto Firebase
• Maggiore sicurezza, poiché se il codice richiama accidentalmente risorse non emulate (di produzione), non c'è alcuna possibilità di modifica dei dati, utilizzo e fatturazione
• Migliore supporto offline, poiché non è necessario accedere a internet per scaricare la configurazione dell'SDK.

Strumenta la tua app per comunicare con gli emulatori

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

I database denominati vengono creati implicitamente anche in risposta a qualsiasi chiamata SDK o API REST all'emulatore che fa riferimento a un database specifico. Questi database creati in modo implicito operano con regole aperte.

Per lavorare in modo interattivo con i database predefiniti e denominati nella Emulator Suite UI, aggiorna l'URL nella barra degli indirizzi del browser per selezionare il database predefinito o un database denominato.

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

Avvia l'emulatore in una versione specifica

L'emulatore verrà avviato nella versione specificata nella sezione firestore.edition del file firebase.json. Puoi anche specificare un'edizione nella sezione emulators.firestore.edition del tuo firebase.json. I valori validi per edition sono standard e enterprise. Se specifichi edition in entrambe le configurazioni, emulators.firestore.edition ha la precedenza.

    {
      ...
      "firestore": {
        "rules": "firestore.rules",
        "indexes": "firestore.indexes.json",
        "edition": "enterprise"
      },
      "emulators": {
        "firestore": {
          "port": 8080,
          "edition": "enterprise" // Takes precedence over `firestore.edition`
        }
      },
      ...
    }

SDK per Android, piattaforme Apple e web

Configura le classi di configurazione o di test in-app per interagire con Cloud Firestore come segue. Tieni presente che negli esempi seguenti il codice dell'app si connette al database del progetto predefinito. Per esempi che coinvolgono database Cloud Firestore aggiuntivi oltre al database predefinito, consulta la guida per più database.

// 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

// 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

let settings = Firestore.firestore().settings
settings.host = "127.0.0.1:8080"
settings.cacheSettings = MemoryCacheSettings()
settings.isSSLEnabled = false
Firestore.firestore().settings = settings
ViewController.swift

FirebaseFirestore db = FirebaseFirestore.DefaultInstance;
// Connects to the Firestore Emulator running on port 8080
db.Settings.Host = "127.0.0.1:8080";
db.Settings.SslEnabled = false;

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

// 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 attivato da eventi Firestore utilizzando l'emulatore. Quando gli emulatori Firestore e Cloud Functions sono entrambi in esecuzione, funzionano automaticamente insieme.

Admin SDK s

I Firebase Admin SDK si connettono automaticamente all'emulatore Cloud Firestore quando viene impostata la variabile di ambiente FIRESTORE_EMULATOR_HOST:

export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080"

Se il codice è in esecuzione all'interno dell'emulatore Cloud Functions, l'ID progetto e altre configurazioni vengono impostati automaticamente quando chiami initializeApp.

Se vuoi che il tuo 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.

admin.initializeApp({ projectId: "your-project-id" });

export GCLOUD_PROJECT="your-project-id"

API REST Cloud Firestore

L'emulatore Cloud Firestore fornisce un endpoint REST per interagire con il tuo database. Tutte le chiamate API REST devono essere effettuate all'endpoint http://localhost:8080/v1.

Il percorso completo per una chiamata REST segue il pattern:

http://localhost:8080/v1/projects/{project_id}/databases/{database_id}/documents/{document_path}

Ad esempio, per elencare tutti i documenti nella raccolta users per il progetto my-project-id, puoi utilizzare curl:

curl -X GET "http://localhost:8080/v1/projects/my-project-id/databases/(default)/documents/users"

Cancella il database tra un test e l'altro

Firestore in produzione non fornisce alcun metodo SDK della piattaforma per lo svuotamento del database, ma l'emulatore Firestore offre un endpoint REST specifico per questo scopo, che può essere chiamato da un passaggio di configurazione/smantellamento del framework di test, da una classe di test o dalla shell (ad es. con curl) prima dell'avvio di un test. Puoi utilizzare questo approccio in alternativa alla semplice chiusura del processo dell'emulatore.

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

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

Naturalmente, il codice deve attendere la conferma REST che lo svuotamento è stato completato o non è 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 sequenziare i test e attivare le funzioni con la certezza che i dati precedenti verranno eliminati tra un'esecuzione e l'altra e che utilizzerai una nuova configurazione di test di riferimento.

Importazione ed esportazione di dati

Gli emulatori del database e di Cloud Storage for Firebase ti consentono di esportare i dati da un'istanza dell'emulatore in esecuzione. Definisci un set di dati di riferimento da utilizzare nei test delle unità o nei workflow di integrazione continua, quindi esportalo per condividerlo con il 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 un percorso di esportazione o semplicemente utilizzando il percorso passato al flag --import.

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

Queste opzioni di importazione ed esportazione dei dati funzionano anche con il comando firebase emulators:exec. Per saperne di più, consulta il riferimento dei comandi dell'emulatore.

Visualizza l'attività delle regole di sicurezza

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

Utilizza lo strumento di monitoraggio delle richieste

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

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

Visualizza i report sulle valutazioni delle regole

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

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

Per ottenere i report, esegui una query su un endpoint esposto nell'emulatore mentre è in esecuzione. Per una versione compatibile con 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 passare il 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 query:

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

Qui, la versione HTML del report evidenzia le valutazioni che generano errori di valori non definiti e nulli:

Differenze tra l'emulatore Cloud Firestore e la produzione

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

Supporto di più database per Cloud Firestore

Al momento, Emulator Suite UI supporta la creazione, la modifica, l'eliminazione, il monitoraggio delle richieste e la visualizzazione della sicurezza interattive per un database predefinito, ma non per database aggiuntivi con nome.

Tuttavia, l'emulatore crea un database denominato in base alla configurazione nel file firebase.json e implicitamente in risposta alle chiamate SDK o API REST.

Transazioni

Al momento l'emulatore non implementa tutti i comportamenti delle transazioni osservati in produzione. Quando testi funzionalità che prevedono più scritture simultanee in 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. Se necessario, valuta la possibilità di modificare i timeout dei test di conseguenza.

Indici

L'emulatore non monitora gli indici composti, ma esegue qualsiasi query valida. Assicurati di testare la tua app su un'istanza Cloud 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 perché troppo grandi dal servizio di produzione. Assicurati di avere familiarità con i limiti documentati e di progettare la tua app in modo da evitarli in modo proattivo.

Cosa devo fare adesso?

• Per una raccolta di video selezionati ed esempi dettagliati di istruzioni, segui la playlist di formazione sugli emulatori Firebase.
• Esamina i casi d'uso avanzati che prevedono il test delle regole di sicurezza e l'SDK Firebase Test: Testa le regole di sicurezza (Firestore).
• Poiché le funzioni attivate sono una tipica integrazione con Cloud Firestore, scopri di più sull'emulatore Cloud Functions for Firebase in Esegui le funzioni in locale.