Firebase Local Emulator Suite può essere installato e configurato per diversi ambienti di prototipazione e test, dalle sessioni di prototipazione una tantum ai flussi di lavoro di integrazione continua su scala di produzione.
Installa Local Emulator Suite
Prima di installare Emulator Suite, ti serviranno:
Per installare Emulator Suite:
- Installa la Firebase CLI.
Se non hai ancora installato l'interfaccia a riga di comando di Firebase,
installala ora.
Per utilizzare Emulator Suite, devi avere la versione 8.14.0 o successive della CLI. Puoi
controllare la versione installata utilizzando il seguente comando:
firebase --version
- Se non l'hai ancora fatto, inizializza la directory di lavoro corrente
come progetto Firebase, seguendo le istruzioni sullo schermo per specificare quali
prodotti utilizzare:
firebase init
- Configura Emulator Suite. Questo comando avvia una procedura guidata di configurazione che
ti consente di selezionare gli emulatori di interesse, scaricare i file binari dell'emulatore corrispondenti e impostare le porte dell'emulatore se i valori predefiniti non sono appropriati.
firebase init emulators
Una volta installato un emulatore, non vengono eseguiti controlli di aggiornamento e non vengono eseguiti download automatici aggiuntivi finché non aggiorni la versione dell'interfaccia a riga di comando di Firebase.
Configurare Emulator Suite
Se vuoi, puoi configurare le porte di rete e il percorso dei file di definizione delle regole di sicurezza degli emulatori nel file firebase.json:
- Modifica le porte dell'emulatore eseguendo
firebase init emulatorso modificandofirebase.jsonmanualmente. - Modifica manualmente il percorso delle definizioni delle regole di sicurezza modificando
firebase.json.
Se non configuri queste impostazioni, gli emulatori ascolteranno le porte predefinite e gli emulatori Cloud Firestore, Realtime Database e Cloud Storage for Firebase verranno eseguiti con la sicurezza dei dati aperta.
| Comando | Descrizione |
|---|---|
| init emulators | Avvia una procedura guidata di inizializzazione dell'emulatore. Identifica gli emulatori da installare e specifica facoltativamente le impostazioni della porta dell'emulatore. init emulators non è distruttivo; l'accettazione dei valori predefiniti manterrà la configurazione attuale dell'emulatore. |
Configurazione della porta
Ogni emulatore si associa a una porta diversa sulla macchina con un valore predefinito preferito.
| Emulatore | Porta predefinita |
|---|---|
| Authentication | 9099 |
| App Hosting | 5002 |
| Emulator Suite UI | 4000 |
| Cloud Functions | 5001 |
| Eventarc | 9299 |
| Realtime Database | 9000 |
| Cloud Firestore | 8080 |
| Cloud Storage for Firebase | 9199 |
| Firebase Hosting | 5000 |
| Pub/Sub | 8085 |
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 separato.
In genere, è consigliabile impostare un ID progetto per tutte le chiamate dell'emulatore, in modo che Emulator Suite UI, i diversi emulatori di prodotto e tutte le istanze in esecuzione di un particolare emulatore possano comunicare correttamente in tutti i casi.
Local Emulator Suite mostra avvisi quando rileva più ID progetto nell'ambiente, anche se puoi ignorare questo comportamento impostando la chiave singleProjectMode su false nel file firebase.json.
Puoi verificare la presenza di discrepanze nelle dichiarazioni degli ID progetto in:
- Il progetto predefinito nella riga di comando. Per impostazione predefinita, l'ID progetto
viene recuperato all'avvio dal progetto selezionato con
firebase initofirebase use. Per visualizzare l'elenco dei progetti (e vedere quale è selezionato), utilizzafirebase projects:list. - Test delle unità delle regole. L'ID progetto viene spesso specificato nelle chiamate ai metodi della libreria Rules
Unit Testing
initializeTestEnvironmentoinitializeTestApp. - Il flag della riga di comando
--project. Il passaggio del flag Firebase CLI--projectsostituisce il progetto predefinito. Devi assicurarti che il valore del flag corrisponda all'ID progetto nei test unitari e nell'inizializzazione dell'app.
Controlla anche le configurazioni dell'ID progetto specifiche per la piattaforma che hai impostato durante la configurazione dei progetti Apple, Android e web.
Configurazione delle regole di sicurezza
Gli emulatori prenderanno 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"
}
}
}
Specificare le 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 dell'heap Java a 4 GB:
export JAVA_TOOL_OPTIONS="-Xmx4g"
firebase emulators:start
È possibile specificare più flag tra virgolette separati da spazi, ad esempio
JAVA_TOOL_OPTIONS="-Xms2g -Xmx4g". I flag influiscono solo sui componenti degli emulatori basati su Java e non hanno effetto su altre parti della CLI Firebase, ad esempio Emulator Suite UI.
Avviare 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.
| Comando | Descrizione | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| emulators:start | Avvia gli emulatori per i prodotti Firebase configurati in firebase.json.
I processi dell'emulatore continueranno a essere eseguiti finché non vengono interrotti esplicitamente. Chiamata
emulators:start scaricherà gli emulatori in ~/.cache/firebase/emulators/ se
non sono già installati.
|
||||||||||||||
| emulators:exec scriptpath | Esegui lo script alle ore scriptpath dopo aver avviato gli emulatori per i prodotti Firebase
configurati in firebase.json. I processi dell'emulatore si interromperanno automaticamente al termine dell'esecuzione dello script.
|
Il metodo firebase emulators:exec è generalmente 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 comune e condivisibile. Questi set di dati possono essere importati utilizzando il flag --import, come
descritto sopra.
| emulators:export export_directory |
Authentication, Cloud Firestore, Realtime Database o Cloud Storage for Firebase.
Esporta i dati da un'istanza dell'emulatore Cloud Firestore, Realtime Database o Cloud Storage for Firebase in esecuzione. Il
Puoi indicare agli emulatori di esportare automaticamente i dati quando vengono chiusi utilizzando i
flag |
Integrare il sistema CI
Esecuzione di immagini containerizzate di Emulator Suite
L'installazione e la configurazione di Emulator Suite con i container in una configurazione CI tipica sono semplici.
Ci sono alcuni problemi da notare:
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 non hai un file
firebase.jsonnel repository, devi aggiungere un argomento della riga di comando al comandoemulators:startoemulators:execper 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 di integrazione continua. 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, quindi assicurati che rimanga segreto.
Se il tuo ambiente CI ti consente di specificare variabili di ambiente che possono essere
utilizzate negli script di build, crea semplicemente una variabile di ambiente chiamata
FIREBASE_TOKEN, con il valore della stringa del token di accesso. La CLI Firebase
rileverà automaticamente la variabile di ambiente FIREBASE_TOKEN e gli
emulatori verranno avviati correttamente.
Come ultima risorsa, puoi semplicemente includere il token nello script di build, ma
assicurati che terze 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 Emulator Hub
Elenca emulatori in esecuzione
Per elencare gli emulatori attualmente in esecuzione, invia una richiesta GET all'endpoint /emulators
di Emulator Hub.
curl localhost:4400/emulatorsIl risultato sarà un oggetto JSON che elenca tutti gli emulatori in esecuzione e la relativa configurazione 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 i trigger di funzioni in background
In alcune situazioni dovrai disattivare temporaneamente la funzione locale e
i trigger delle estensioni. Ad esempio, potresti voler eliminare tutti i dati nell'emulatore Cloud Firestore senza attivare alcuna funzione onDelete in esecuzione negli emulatori Cloud Functions o Extensions.
Per disattivare temporaneamente i trigger di funzioni locali, invia una richiesta PUT all'endpoint
/functions/disableBackgroundTriggers di Emulator Hub.
curl -X PUT localhost:4400/functions/disableBackgroundTriggersIl risultato sarà un oggetto JSON che descrive in dettaglio lo stato attuale.
{
"enabled": false
}
Per attivare i trigger di funzioni locali dopo che sono stati disattivati, invia una richiesta PUT
all'endpoint /functions/enableBackgroundTriggers dell'Emulator
Hub.
curl -X PUT localhost:4400/functions/enableBackgroundTriggersIl risultato sarà un oggetto JSON che descrive in dettaglio 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 significa che il supporto dell'emulatore è pianificato, ma non è ancora disponibile.
Disponibilità dell'SDK client
| Android | Piattaforme Apple | Web |
Firebase UI Android |
Firebase UI iOS |
Firebase UI Web |
|
|---|---|---|---|---|---|---|
| Realtime Database | 19.4.0 | 7.2.0 | 8.0.0 | 6.4.0 | Future | N/D |
| Cloud Firestore | 21.6.0 | 7.2.0 | 8.0.0 | 6.4.0 | Future | N/D |
| Authentication | 20.0.0 | 7.0.0 | 8.0.0 | 7.0.0 | Future | 4.7.2 |
| Cloud Storage for Firebase | 20.0.0 | 8.0.0 | 8.4.0 | 7.0.0 | 11.0.0 | N/D |
| Cloud Functions | 19.1.0 | 7.2.0 | 8.0.0 | N/D | N/D | N/D |
| Hosting | N/D | N/D | N/D | N/D | N/D | N/D |
| Extensions | N/D | N/D | N/D | N/D | N/D | N/D |
Disponibilità dell'SDK Admin
| Nodo | Java | Python | Go | |
|---|---|---|---|---|
| Realtime Database | 8.6.0 | 6.10.0 | 2.18.0 | Future |
| Cloud Firestore | 8.0.0 | 6.10.0 | 3.0.0 | 1.0.0 |
| Authentication | 9.3.0 | 7.2.0 | 5.0.0 | 4.2.0 |
| Cloud Storage for Firebase | 9.8.0 | Future | Future | Future |
| Cloud Functions | N/D | N/D | N/D | N/D |
| Hosting | N/D | N/D | N/D | N/D |
| Extensions | N/D | N/D | N/D | N/D |