Installare, configurare e integrare Local Emulator Suite

Firebase Local Emulator Suite può essere installato e configurato per diversi ambienti di test e prototipi, dalle sessioni di prototipazione una tantum ai flussi di lavoro di integrazione continua su larga scala.

Installa Local Emulator Suite

Prima di installare Emulator Suite, devi disporre di:

• Node.js versione 16.0 o successive.
• JDK Java 11 o versioni successive.

Per installare Emulator Suite:

1. Installa l'interfaccia a riga di comando Firebase. Se non hai ancora installato l'interfaccia a riga di comando di Firebase, installala ora. Per utilizzare Emulator Suite, è necessaria l'interfaccia a riga di comando 8.14.0 o versioni successive. Puoi controllare la versione installata utilizzando il seguente comando:

   firebase --version

2. Se non lo hai già fatto, inizializza la directory di lavoro corrente come progetto Firebase, seguendo le istruzioni sullo schermo per specificare i prodotti da utilizzare:

   firebase init

3. Configura Emulator Suite. Questo comando avvia una procedura guidata di configurazione che consente di selezionare gli emulatori di interesse, scaricare i file binari degli emulatori corrispondenti e impostare le porte degli emulatori se quelle predefinite non sono appropriate.

   firebase init emulators

Una volta installato un emulatore, non vengono eseguiti controlli di aggiornamento e non verranno eseguiti altri download automatici finché non aggiornerai la versione dell'interfaccia a riga di comando di Firebase.

Configura Emulator Suite

Facoltativamente, puoi configurare le porte di rete degli emulatori e il percorso alle definizioni delle regole di sicurezza nel file firebase.json:

• Modifica le porte dell'emulatore eseguendo firebase init emulators o modificando manualmente firebase.json.
• Modifica il percorso alle definizioni delle regole di sicurezza modificando firebase.json manualmente.

Se non configuri queste impostazioni, gli emulatori ascolteranno sulle proprie porte predefinite e gli emulatori Cloud Firestore, Realtime Database e Cloud Storage for Firebase funzioneranno con la sicurezza dei dati aperti.

Configurazione delle porte

Ogni emulatore si associa a una porta diversa della macchina con un valore predefinito preferito.

Configurazione dell'ID progetto

A seconda di come richiami gli emulatori, puoi eseguire più istanze di un emulatore utilizzando ID progetto Firebase diversi o più istanze di emulatore per un determinato ID progetto. In questi casi, le istanze dell'emulatore vengono eseguite in un ambiente distinto.

In genere, è buona prassi impostare un ID progetto per tutte le invocazioni dell'emulatore, in modo che Emulator Suite UI, diversi emulatori di prodotti e tutte le istanze in esecuzione di un determinato emulatore possano comunicare correttamente in tutti i casi.

Local Emulator Suite emette avvisi quando rileva più ID progetto nell'ambiente, anche se puoi ignorare questo comportamento impostando la chiave singleProjectMode su false in firebase.json.

Puoi controllare la presenza di mancate corrispondenze nelle dichiarazioni dell'ID progetto in:

• Il progetto predefinito nella riga di comando. Per impostazione predefinita, l'ID progetto verrà utilizzato all'avvio dal progetto selezionato con firebase init o firebase use. Per visualizzare l'elenco dei progetti (e vedere quale è selezionato), usa firebase projects:list.
• Test di unità delle regole. L'ID progetto viene spesso specificato nelle chiamate ai metodi della raccolta di test di unità delle regole initializeTestEnvironment o initializeTestApp.
• Il flag --project della riga di comando. Il passaggio del flag dell'interfaccia a riga di comando Firebase --project sostituisce il progetto predefinito. Devi assicurarti che il valore del flag corrisponda all'ID progetto nei test di unità e nell'inizializzazione dell'app.

Controlla anche le configurazioni degli ID progetto specifici della piattaforma che hai impostato durante la configurazione dei progetti per le piattaforme Apple, Android e web.

Configurazione delle regole di sicurezza

Gli emulatori acquisiranno la configurazione delle regole di sicurezza dalle chiavi di configurazione database, firestore e storage in firebase.json.

{
  // Existing firebase configuration ...
  "database": {
    "rules": "database.rules.json"
  },
  "firestore": {
    "rules": "firestore.rules"
  },
  "storage": {
    "rules": "storage.rules"
  }

  // ...

  // Optional emulator configuration. Default
  // values are used if absent.
  "emulators": {
    "singleProjectMode": false, // do not warn on detection of multiple project IDs
    "firestore": {
      "port": "8080"
    },
    "ui": {
      "enabled": true,      // Default is `true`
      "port": 4000          // If unspecified, see CLI log for selected port
    },
    "auth": {
      "port": "9099"
    },
    "pubsub": {
      "port": "8085"
    }
  }
}

Specifica delle opzioni Java

L'emulatore Realtime Database, l'emulatore Cloud Firestore e parte dell'emulatore Cloud Storage for Firebase si basano su Java, che può essere personalizzato con i flag JVM tramite la variabile di ambiente JAVA_TOOL_OPTIONS.

Ad esempio, se si verificano errori relativi allo spazio heap Java, puoi aumentare la dimensione massima dello heap Java a 4 GB:

export JAVA_TOOL_OPTIONS="-Xmx4g"
firebase emulators:start

È possibile specificare più flag tra virgolette separate da spazi, ad esempio JAVA_TOOL_OPTIONS="-Xms2g -Xmx4g". I flag influiscono solo sui componenti basati su Java degli emulatori e non hanno alcun effetto su altre parti della CLI di Firebase, come Emulator Suite UI.

Avvia gli emulatori

Puoi avviare gli emulatori in modo che vengano eseguiti fino all'interruzione manuale o per la durata di uno script di test designato, per poi arrestarsi automaticamente.

Il metodo firebase emulators:exec è in genere più appropriato per i flussi di lavoro di integrazione continua.

Esportare e importare i dati dell'emulatore

Puoi esportare i dati dagli emulatori Authentication, Cloud Firestore, Realtime Database e Cloud Storage for Firebase da utilizzare come set di dati di riferimento comuni e condivisibili. Questi set di dati possono essere importati utilizzando il flag --import, come описано sopra.

Eseguire l'integrazione con il sistema CI

Esecuzione di immagini di Emulator Suite containerizzate

L'installazione e la configurazione di Emulator Suite con i container in una configurazione tipica di CI sono semplici.

Esistono alcuni problemi da tenere presente:

• I file JAR vengono installati e memorizzati nella cache in ~/.cache/firebase/emulators/.

  • Ti consigliamo di aggiungere questo percorso alla configurazione della cache CI per evitare download ripetuti.

• Se nel repository non è presente un file firebase.json, devi aggiungere un argomento della riga di comando al comando emulators:start o emulators:exec per specificare quali emulatori devono essere avviati. Ad esempio,
  --only functions,firestore.

Generare un token di autenticazione (solo emulatore di hosting)

Se i tuoi flussi di lavoro di integrazione continua si basano su Firebase Hosting, devi accedere utilizzando un token per eseguire firebase emulators:exec. Gli altri emulatori non richiedono l'accesso.

Per generare un token, esegui firebase login:ci nel tuo ambiente locale. Questa operazione non deve essere eseguita da un sistema CI. Segui le istruzioni per l'autenticazione. Dovresti eseguire questo passaggio una sola volta per progetto, poiché il token sarà valido per tutte le build. Il token deve essere trattato come una password; assicurati che venga mantenuto segreto.

Se il tuo ambiente CI ti consente di specificare variabili di ambiente che possono essere utilizzate negli script di compilazione, crea semplicemente una variabile di ambiente chiamata FIREBASE_TOKEN, con il valore della stringa del token di accesso. Firebase CLI acquisirà automaticamente la variabile di ambiente FIREBASE_TOKEN e gli emulatori verranno avviati correttamente.

Come ultima risorsa, puoi semplicemente includere il token nello script di compilazione, ma assicurati che le parti non attendibili non abbiano accesso. Per questo approccio hardcoded, puoi aggiungere --token "YOUR_TOKEN_STRING_HERE" al comando firebase emulators:exec.

Utilizzare l'API REST di Emulator Hub

Elenca gli emulatori in esecuzione

Per elencare gli emulatori attualmente in esecuzione, invia una richiesta GET all'endpoint /emulators di Emulator Hub.

curl localhost:4400/emulators

Il risultato sarà un oggetto JSON che elenca tutti gli emulatori in esecuzione e la relativa configurazione di host/porta, ad esempio:

{
  "hub":{
    "name": "hub",
    "host": "localhost",
    "port": 4400
  },
  "functions": {
    "name": "functions",
    "host": "localhost",
    "port": 5001
  }
  "firestore": {
    "name": "firestore",
    "host": "localhost",
    "port": 8080
  }
}

Attivare/disattivare gli attivatori della funzione in background

In alcune situazioni dovrai disattivare temporaneamente gli attivatori di funzioni e estensioni locali. Ad esempio, potresti voler eliminare tutti i dati nell'emulatore Cloud Firestore senza attivare le funzioni onDelete in esecuzione negli emulatori Cloud Functions o Extensions.

Per disattivare temporaneamente i trigger di funzione locali, invia una richiesta PUT all'endpoint /functions/disableBackgroundTriggers dell'hub dell'emulatore.

curl -X PUT localhost:4400/functions/disableBackgroundTriggers

Il risultato sarà un oggetto JSON che descrive lo stato attuale.

{
  "enabled": false
}

Per attivare gli attivatori delle funzioni locali dopo che sono stati disattivati, invia una richiesta PUT all'endpoint /functions/enableBackgroundTriggers di Emulator Hub.

curl -X PUT localhost:4400/functions/enableBackgroundTriggers

Il risultato sarà un oggetto JSON che descrive lo stato attuale.

{
  "enabled": true
}

Integrazioni dell'SDK dell'emulatore

Le tabelle in questa sezione indicano quali emulatori sono supportati dagli SDK client e Admin. Futuro indica che il supporto dell'emulatore è pianificato, ma non è ancora disponibile.

Disponibilità dell'SDK client

Disponibilità dell'SDK Admin