Collega la tua app all'emulatore Cloud Functions

Prima di collegare l'app all'emulatore Cloud Functions, 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

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

Per selezionare il progetto da utilizzare, prima di avviare gli emulatori, nell'interfaccia a riga di comando esegui firebase use 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 dimostrativi.

Tipo di progetto Funzionalità Utilizzo con emulatori
Reale

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

I progetti reali hanno risorse attive, come istanze di database, bucket di archiviazione, funzioni o qualsiasi altra risorsa configurata per il progetto Firebase.

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

Per tutti i prodotti che non stai emulando, le tue app e il tuo codice interagiranno con la risorsa in produzione (istanza di database, bucket di archiviazione, funzione e così via).

Demo

Un progetto Firebase dimostrativo non ha una configurazione Firebase reale o risorse attive. In genere, si accede a questi progetti tramite codelab o altri tutorial.

Gli ID progetto per i progetti demo hanno il prefisso demo-.

Quando utilizzi progetti Firebase di prova, le tue app e il tuo codice interagiscono solo con gli emulatori. Se la tua app tenta di interagire con una risorsa per cui non è in esecuzione un emulatore, il codice non andrà a buon fine.

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

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

Instrumenta l'app per comunicare con gli emulatori

Strumenti della tua app per le funzioni richiamabili

Se le attività di test e del prototipo prevedono funzioni di backend richiamabili, configura l'interazione con l'emulatore Cloud Functions for Firebase come segue:

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 functions = Firebase.functions
functions.useEmulator("10.0.2.2", 5001)
MainActivity.kt
Java
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
FirebaseFunctions functions = FirebaseFunctions.getInstance();
functions.useEmulator("10.0.2.2", 5001);
MainActivity.java
Swift
Functions.functions().useFunctionsEmulator(origin: "http://127.0.0.1:5001")
ViewController.swift

Web

import { getApp } from "firebase/app";
import { getFunctions, connectFunctionsEmulator } from "firebase/functions";

const functions = getFunctions(getApp());
connectFunctionsEmulator(functions, "127.0.0.1", 5001);
fb_functions_emulator_connect.js

Web

firebase.functions().useEmulator("127.0.0.1", 5001);
emulator-suite.js

Strumenti della tua app per l'emulazione delle funzioni HTTPS

Ogni funzione HTTPS nel codice verrà pubblicata dall'emulatore locale utilizzando il seguente formato dell'URL:

http://$HOST:$PORT/$PROJECT/$REGION/$NAME

Ad esempio, una funzione helloWorld semplice con la porta e la regione dell'host predefinite verrebbe gestita all'indirizzo:

https://localhost:5001/$PROJECT/us-central1/helloWorld

Strumenta l'app per l'emulazione delle funzioni della coda di attività

L'emulatore configura automaticamente le code di attività emulate in base alle definizioni degli attivatori e l'Admin SDK reindirizza le richieste in coda all'emulatore se rileva che è in esecuzione tramite la variabile di ambiente CLOUD_TASKS_EMULATOR_HOST.

Tieni presente che il sistema di invio utilizzato in produzione è più complesso di quello implementato nell'emulatore, pertanto non dovresti aspettarti che il comportamento simulato rispecchi esattamente gli ambienti di produzione. I parametri all'interno dell'emulatore forniscono limiti superiori alla frequenza con cui le attività vengono inviate e riprovate.

Esegui l'instrumentazione dell'app per l'emulazione delle funzioni attivate in background

L'emulatore Cloud Functions supporta le funzioni attivate in background dalle seguenti origini:

  • Emulatore Realtime Database
  • Emulatore Cloud Firestore
  • emulatore Authentication
  • emulatore Pub/Sub
  • Emulatore di avvisi Firebase

Per attivare eventi in background, modifica le risorse di backend utilizzando Emulator Suite UI oppure connettendo la tua app o il codice di test agli emulatori utilizzando l'SDK per la tua piattaforma.

Testare i gestori per gli eventi personalizzati emessi dalle estensioni

Per le funzioni che implementi per gestire gli eventi personalizzati Firebase Extensions con Cloud Functions v2, l'emulatore Cloud Functions si accoppia con l'emulatore Eventarc per supportare gli trigger Eventarc.

Per testare i gestori di eventi personalizzati per le estensioni che emettono eventi, devi installare gli emulatori Cloud Functions ed Eventarc.

Il runtime Cloud Functions imposta la variabile di ambiente EVENTARC_EMULATOR su localhost:9299 nel processo corrente se l'emulatore Eventarc è in esecuzione. I Firebase Admin SDK si connettono automaticamente all'emulatore Eventarc quando è impostata la variabile di ambiente EVENTARC_EMULATOR. Puoi modificare la porta predefinita come descritto in Configura Local Emulator Suite.

Quando le variabili di ambiente sono configurate correttamente, Firebase Admin SDK invia automaticamente gli eventi all'emulatore Eventarc. A sua volta, l'emulatore Eventarc richiama l'emulatore Cloud Functions per attivare eventuali gestori registrati.

Puoi controllare i log di Functions in Emulator Suite UI per informazioni dettagliate sull'esecuzione dell'handler.

Configurare un ambiente di test locale

Se le tue funzioni si basano su configurazione dell'ambiente basata su dotenv, puoi emulare questo comportamento nell'ambiente di test locale.

Quando utilizzi un emulatore Cloud Functions locale, puoi eseguire l'override delle variabili di ambiente per il tuo progetto configurando un file .env.local. I contenuti di .env.local hanno la precedenza su .env e sul file .env specifico del progetto.

Ad esempio, un progetto potrebbe includere questi tre file contenenti valori leggermente diversi per lo sviluppo e i test locali:

.env .env.dev .env.local
PLANET=Earth

AUDIENCE=Utenti

AUDIENCE=Dev Humans AUDIENCE=Persone locali

Quando viene avviato nel contesto locale, l'emulatore carica le variabili di ambiente come mostrato di seguito:

  $ firebase emulators:start
  i  emulators: Starting emulators: functions
  # Starts emulator with following environment variables:
  #  PLANET=Earth
  #  AUDIENCE=Local Humans

Secret e credenziali nell'emulatore Cloud Functions

L'emulatore Cloud Functions supporta l'utilizzo di secret per archiviare e accedere a informazioni di configurazione sensibili. Per impostazione predefinita, l'emulatore tenterà di accedere ai secret di produzione utilizzando le credenziali predefinite dell'applicazione. In alcune situazioni, ad esempio negli ambienti CI, l'emulatore potrebbe non riuscire ad accedere ai valori segreti a causa di limitazioni delle autorizzazioni.

Analogamente al supporto dell'emulatore Cloud Functions per le variabili di ambiente, puoi eseguire l'override dei valori dei secret impostando un file .secret.local. In questo modo, puoi testare facilmente le funzioni localmente, soprattutto se non hai accesso al valore del secret.

Quali altri strumenti per il test di Cloud Functions esistono?

L'emulatore Cloud Functions è integrato da altri strumenti per prototipi e test:

  • La shell di Cloud Functions, che consente la prototipazione e lo sviluppo di funzioni iterative e interattive. La shell utilizza l'emulatore Cloud Functions con un'interfaccia in stile REPL per lo sviluppo. Non viene fornita alcuna integrazione con gli emulatori Cloud Firestore o Realtime Database. Utilizzando la shell, puoi simulare i dati ed eseguire chiamate di funzione per simulare l'interazione con i prodotti che al momento non sono supportati da Local Emulator Suite: Analytics, Remote Config e Crashlytics.
  • L'SDK di test Firebase per Cloud Functions, un framework Node.js con Mocha per lo sviluppo di funzioni. In effetti, l'SDK di test di Cloud Functions fornisce automazione sulla shell di Cloud Functions.

Puoi scoprire di più sulla shell di Cloud Functions e sull'SDK di test di Cloud Functions in Testare le funzioni in modo interattivo e Test di unità di Cloud Functions.

Differenze dell'emulatore Cloud Functions dalla produzione

L'emulatore Cloud Functions è abbastanza simile all'ambiente di produzione per la maggior parte dei casi d'uso. Ci siamo impegnati per assicurare che tutti gli elementi del runtime di Node siano il più vicini possibile alla produzione. Tuttavia, l'emulatore non simula l'ambiente di produzione containerizzato completo, pertanto, anche se il codice della funzione verrà eseguito in modo realistico, altri aspetti dell'ambiente (ad es. file locali, comportamento dopo gli arresti anomali delle funzioni e così via) saranno diversi.

Cloud IAM

Firebase Emulator Suite non tenta di replicare o rispettare alcun comportamento correlato all'IAM per l'esecuzione. Gli emulatori rispettano le Regole di sicurezza di Firebase fornite, ma nelle situazioni in cui normalmente verrebbe utilizzato IAM, ad esempio per impostare l'account di servizio che richiama Cloud Functions e quindi le autorizzazioni, l'emulatore non è configurabile e utilizzerà l'account disponibile a livello globale sulla tua macchina dello sviluppatore, in modo simile all'esecuzione diretta di uno script locale.

Limitazioni di memoria e del processore

L'emulatore non applica limitazioni di memoria o del processore per le tue funzioni. Tuttavia, l'emulatore supporta le funzioni di timeout tramite l'argomento di runtime timeoutSeconds.

Tieni presente che il tempo di esecuzione della funzione può essere diverso da quello di produzione quando le funzioni vengono eseguite nell'emulatore. Dopo aver progettato e testato le funzioni con l'emulatore, ti consigliamo di eseguire test limitati in produzione per confermare i tempi di esecuzione.

Pianificazione delle differenze tra gli ambienti locali e di produzione

Poiché l'emulatore viene eseguito sulla tua macchina locale, dipende dal tuo ambiente locale per le applicazioni, i programmi e le utilità integrati.

Tieni presente che l'ambiente locale per lo sviluppo di Cloud Functions potrebbe essere diverso dall'ambiente di produzione di Google:

  • Le applicazioni installate localmente per simulare l'ambiente di produzione (ad es. ImageMagick in questo tutorial) potrebbero avere un comportamento diverso dalla produzione, soprattutto se sono necessarie versioni diverse o se sono state sviluppate in un ambiente non Linux. Valuta la possibilità di eseguire il deployment della tua copia binaria del programma mancante insieme al deployment delle funzioni.

  • Analogamente, le utilità integrate (ad es. i comandi shell come ls, mkdir) possono essere diverse dalle versioni disponibili in produzione, soprattutto se stai sviluppando in un ambiente non Linux (ad es. macOS). Puoi risolvere il problema utilizzando alternative solo Node ai comandi nativi o compilando i binari Linux da includere nel tuo deployment.

Nuovo tentativo in corso…

L'emulatore Cloud Functions non supporta la ripetizione delle funzioni in caso di errore.

Che cosa succede ora?