Collega la tua app all'emulatore Cloud Functions

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

Scegliere 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 nella CLI 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 dimostrativi.

Tipo di progetto Funzionalità Utilizzo con emulatori
Reale

Un progetto Firebase reale è un progetto 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 quel progetto Firebase.

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

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

Demo

Un progetto Firebase dimostrativo non ha una configurazione Firebase reale e nessuna risorsa live. In genere, si accede a questi progetti tramite codelab o altri tutorial.

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

Quando lavori con i progetti demo Firebase, 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 funzionerà.

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

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

Strumenta l'app per comunicare con gli emulatori

Strumentare l'app per le funzioni richiamabili

Se le attività di prototipazione e test coinvolgono funzioni di backend chiamabili, configura l'interazione con l'emulatore Cloud Functions for Firebase nel seguente modo:

Kotlin
// 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().useEmulator(withHost: "localhost", port: 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

Instrumenta l'app per l'emulazione delle funzioni HTTPS

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

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

Ad esempio, una semplice funzione helloWorld con la porta host e la regione predefinite verrà pubblicata all'indirizzo:

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

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

L'emulatore configura automaticamente le code di attività emulate in base alle definizioni dei trigger e l'SDK Admin 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 distribuzione utilizzato in produzione è più complesso di quello implementato nell'emulatore, quindi non devi aspettarti che il comportamento emulato rifletta con precisione gli ambienti di produzione. I parametri all'interno dell'emulatore forniscono limiti superiori alla frequenza con cui le attività vengono inviate e riprovate.

Strumentare l'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 gli eventi in background, modifica le risorse di backend utilizzando Emulator Suite UI o collegando l'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 Firebase Extensions eventi personalizzati con Cloud Functions v2, l'emulatore Cloud Functions si accoppia con l'emulatore Eventarc per supportare i trigger Eventarc.

Per testare i gestori di eventi personalizzati per le estensioni che generano 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 è in esecuzione l'emulatore Eventarc. Firebase Admin SDK si connettono automaticamente all'emulatore Eventarc quando viene 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 i gestori registrati.

Puoi controllare i log di Functions in Emulator Suite UI per i dettagli sull'esecuzione del gestore.

Configurare un ambiente di test locale

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

Quando utilizzi un emulatore locale di Cloud Functions, puoi sostituire le 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=Humans

AUDIENCE=Dev Humans AUDIENCE=Local Humans

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

Credenziali e dati segreti nell'emulatore Cloud Functions

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

Analogamente al supporto dell'emulatore Cloud Functions per le variabili di ambiente, puoi ignorare i valori dei secret configurando un file .secret.local. In questo modo, puoi testare facilmente le tue 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 di prototipazione e test:

  • La shell Cloud Functions, che consente lo sviluppo e la prototipazione interattivi e iterativi delle funzioni. La shell utilizza il simulatore Cloud Functions con un'interfaccia in stile REPL per lo sviluppo. Non è prevista alcuna integrazione con gli emulatori Cloud Firestore o Realtime Database. Utilizzando la shell, puoi simulare i dati ed eseguire chiamate di funzioni per simulare l'interazione con i prodotti che Local Emulator Suite non supporta attualmente: Analytics, Remote Config e Crashlytics.
  • L'SDK Firebase Test per Cloud Functions, un framework Node.js con mocha per lo sviluppo di funzioni. In effetti, l'SDK di test di Cloud Functions fornisce l'automazione sopra la shell di Cloud Functions.

Puoi trovare ulteriori informazioni sulla shell Cloud Functions e sul Cloud Functions Test SDK in Testare le funzioni in modo interattivo e Test delle unità di Cloud Functions.

Differenze tra l'emulatore Cloud Functions e la produzione

L'emulatore Cloud Functions è abbastanza simile all'ambiente di produzione per la maggior parte dei casi d'uso. Abbiamo lavorato a lungo per assicurarci che tutto all'interno del runtime Node sia il più vicino possibile alla produzione. Tuttavia, l'emulatore non simula l'intero ambiente di produzione containerizzato, quindi, anche se il codice della funzione verrà eseguito in modo realistico, altri aspetti dell'ambiente (ad es. file locali, comportamento dopo l'arresto anomalo delle funzioni e così via) saranno diversi.

Cloud IAM

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

Limitazioni di memoria e processore

L'emulatore non applica limitazioni di memoria o processore alle tue funzioni. Tuttavia, l'emulatore supporta il timeout delle funzioni tramite l'argomento di runtime timeoutSeconds.

Tieni presente che il tempo di esecuzione della funzione potrebbe differire dalla produzione quando le funzioni vengono eseguite nell'emulatore. Ti consigliamo di eseguire test limitati in produzione dopo aver progettato e testato le funzioni con l'emulatore per confermare i tempi di esecuzione.

Pianificazione delle differenze tra gli ambienti locali e di produzione

Poiché l'emulatore viene eseguito sulla macchina locale, dipende dall'ambiente locale per applicazioni, programmi e utilità integrati.

Tieni presente che il tuo ambiente locale per lo sviluppo di Cloud Functions potrebbe differire dall'ambiente di produzione di Google:

  • Le applicazioni che installi localmente per simulare l'ambiente di produzione (ad es. ImageMagick da questo tutorial) potrebbero avere un comportamento diverso dalla produzione, soprattutto se richiedi versioni diverse o sviluppi in un ambiente non Linux. Valuta la possibilità di eseguire il deployment della tua copia binaria del programma mancante insieme al deployment della funzione.

  • Allo stesso modo, le utilità integrate (ad es. i comandi della shell come ls, mkdir) potrebbero differire dalle versioni disponibili in produzione, soprattutto se sviluppi in un ambiente non Linux (ad es. macOS). Puoi risolvere questo problema utilizzando alternative solo per Node ai comandi nativi o creando file binari Linux da raggruppare con la tua implementazione.

Nuovo tentativo in corso…

L'emulatore Cloud Functions non supporta i nuovi tentativi delle funzioni in caso di errore.

Che cosa succede ora?