Gestire le funzioni (1ª gen.)

Puoi eseguire il deployment, eliminare e modificare le funzioni utilizzando i comandi dell'interfaccia a riga di comando Firebase o impostando le opzioni di runtime nel codice sorgente delle funzioni.

Eseguire il deployment delle funzioni

Per eseguire il deployment delle funzioni, esegui questo comando dell'interfaccia a riga di comando Firebase:

firebase deploy --only functions

Per impostazione predefinita, l'Firebase CLI esegue il deployment di tutte le funzioni all'interno dell'origine contemporaneamente. Se il progetto contiene più di 5 funzioni, ti consigliamo di utilizzare il flag --only con nomi di funzioni specifici per eseguire il deployment solo delle funzioni che hai modificato. L'esecuzione del deployment di funzioni specifiche in questo modo velocizza il processo di deployment e ti aiuta a evitare di raggiungere le quote di deployment. Ad esempio:

firebase deploy --only functions:addMessage,functions:makeUppercase

Quando esegui il deployment di un numero elevato di funzioni, potresti superare la quota standard e ricevere messaggi di errore HTTP 429 o 500. Per risolvere il problema, esegui il deployment delle funzioni in gruppi di massimo 10.

Per l'elenco completo dei comandi disponibili, consulta la documentazione di riferimento dell'interfaccia a riga di comando Firebase di Firebase.

Per impostazione predefinita, l'Firebase CLI cerca il codice sorgente nella cartella functions/ per il. Se preferisci, puoi organizzare le funzioni in codebase o in più set di file.

Eliminare le funzioni

Puoi eliminare le funzioni di cui è stato eseguito il deployment in precedenza nei seguenti modi:

  • esplicitamente nell'interfaccia a riga di comando con Firebasefunctions:delete
  • esplicitamente nella Google Cloud console.
  • Implicitamente rimuovendo la funzione dall'origine prima del deployment.

Tutte le operazioni di eliminazione ti chiedono di confermare prima di rimuovere la funzione dalla produzione.

L'eliminazione esplicita delle funzioni nell'interfaccia a riga di comando Firebase supporta più argomenti e gruppi di funzioni e ti consente di specificare una funzione in esecuzione in una regione specifica. Inoltre, puoi ignorare la richiesta di conferma.

  • Elimina tutte le funzioni che corrispondono al nome specificato in tutte le regioni: 

    firebase functions:delete FUNCTION-1_NAME

  • Elimina una funzione specificata in esecuzione in una regione non predefinita: 

    firebase functions:delete FUNCTION-1_NAME --region REGION_NAME

  • Elimina più di una funzione: 

    firebase functions:delete FUNCTION-1_NAME FUNCTION-2_NAME

  • Elimina un gruppo di funzioni specificato: 

    firebase functions:delete GROUP_NAME

  • Ignora la richiesta di conferma: 

    firebase functions:delete FUNCTION-1_NAME --force

Con l'eliminazione implicita delle funzioni, firebase deploy analizza l'origine e rimuove dalla produzione tutte le funzioni che sono state rimosse dal file.

Modificare il nome, la regione o il trigger di una funzione

Se stai rinominando o modificando le regioni o il trigger per le funzioni che gestiscono il traffico di produzione, segui i passaggi descritti in questa sezione per evitare di perdere eventi durante la modifica. Prima di seguire questi passaggi, assicurati che la tua funzione sia idempotente, poiché sia la nuova versione sia quella precedente della funzione verranno eseguite contemporaneamente durante la modifica.

Rinominare una funzione

Per rinominare una funzione, crea una nuova versione rinominata della funzione nell'origine, quindi esegui due comandi di deployment separati. Il primo comando esegue il deployment della funzione con il nuovo nome, mentre il secondo rimuove la versione di cui è stato eseguito il deployment in precedenza. Ad esempio, se hai una funzione Node.js chiamata webhook che vuoi modificare in webhookNew, rivedi il codice come segue:

// before
const functions = require('firebase-functions/v1');

exports.webhook = functions.https.onRequest((req, res) => {
    res.send("Hello");
});

// after
const functions = require('firebase-functions/v1');

exports.webhookNew = functions.https.onRequest((req, res) => {
    res.send("Hello");
});

Quindi esegui i seguenti comandi per eseguire il deployment della nuova funzione:

# Deploy new function called webhookNew
firebase deploy --only functions:webhookNew

# Wait until deployment is done; now both webhookNew and webhook are running

# Delete webhook
firebase functions:delete webhook

Modificare la regione o le regioni di una funzione

Se stai modificando le regioni specificate per una funzione che gestisce il traffico di produzione, puoi evitare la perdita di eventi eseguendo questi passaggi in ordine:

  1. Rinomina la funzione e modifica la regione o le regioni come preferisci.
  2. Esegui il deployment della funzione rinominata, che comporta l'esecuzione temporanea dello stesso codice in entrambi i set di regioni.
  3. Elimina la funzione precedente.

Ad esempio, se hai una funzione chiamata webhook che si trova attualmente nella regione predefinita delle funzioni us-central1 e vuoi eseguirne la migrazione a asia-northeast1, devi prima modificare il codice sorgente per rinominare la funzione e rivedere la regione.

// before
const functions = require('firebase-functions/v1');

exports.webhook = functions
    .https.onRequest((req, res) => {
            res.send("Hello");
    });

// after
const functions = require('firebase-functions/v1');

exports.webhookAsia = functions
    .region('asia-northeast1')
    .https.onRequest((req, res) => {
            res.send("Hello");
    });

Quindi esegui il deployment eseguendo:

firebase deploy --only functions:webhookAsia

Ora sono in esecuzione due funzioni identiche: webhook in esecuzione in us-central1, e webhookAsia in esecuzione in asia-northeast1.

Quindi, elimina webhook:

firebase functions:delete webhook

Ora è presente una sola funzione, webhookAsia, in esecuzione in asia-northeast1.

Modificare il tipo di trigger di una funzione

Man mano che sviluppi il deployment di Cloud Functions for Firebase nel tempo, potresti dover modificare il tipo di trigger di una funzione per vari motivi. Ad esempio, potresti voler passare da un tipo di Firebase Realtime Database o Cloud Firestore evento a un altro.

Non è possibile modificare il tipo di evento di una funzione semplicemente modificando il codice sorgente ed eseguendo firebase deploy. Per evitare errori, modifica il tipo di trigger di una funzione seguendo questa procedura:

  1. Modifica il codice sorgente in modo da includere una nuova funzione con il tipo di trigger desiderato.
  2. Esegui il deployment della funzione, che comporta l'esecuzione temporanea sia della funzione precedente sia di quella nuova.
  3. Elimina esplicitamente la funzione precedente dalla produzione utilizzando la CLI Firebase.

Ad esempio, se avevi una funzione Node.js denominata objectChanged con il tipo di evento legacy onChange e vuoi modificarla in onFinalize, rinomina prima la funzione e modificala in modo che abbia il tipo di evento onFinalize.

// before
const functions = require('firebase-functions/v1');

exports.objectChanged = functions.storage.object().onChange((object) => {
    return console.log('File name is: ', object.name);
});

// after
const functions = require('firebase-functions/v1');

exports.objectFinalized = functions.storage.object().onFinalize((object) => {
    return console.log('File name is: ', object.name);
});

Quindi esegui i seguenti comandi per creare prima la nuova funzione, prima di eliminare quella precedente:

# Create new function objectFinalized
firebase deploy --only functions:objectFinalized

# Wait until deployment is done; now both objectChanged and objectFinalized are running

# Delete objectChanged
firebase functions:delete objectChanged

Impostare le opzioni di runtime

Cloud Functions for Firebase ti consente di selezionare le opzioni di runtime, come la versione del runtime Node.js e il timeout per funzione, l'allocazione della memoria e le istanze di funzione minime/massime.

Come best practice, queste opzioni (ad eccezione della versione di Node.js) devono essere impostate in un oggetto di configurazione all'interno del codice della funzione. Questo RuntimeOptions oggetto è l'origine attendibile per le opzioni di runtime della funzione e sostituirà le opzioni impostate utilizzando qualsiasi altro metodo (ad esempio la Google Cloud console o gcloud CLI).

Se il flusso di lavoro di sviluppo prevede l'impostazione manuale delle opzioni di runtime utilizzando la Google Cloud console o gcloud CLI e non vuoi che questi valori vengano sostituiti a ogni deployment, imposta l'opzione preserveExternalChanges su true. Se questa opzione è impostata su true, Firebase unisce le opzioni di runtime impostate nel codice con le impostazioni della versione di cui è stato eseguito il deployment della funzione con la seguente priorità:

  1. L'opzione è impostata nel codice delle funzioni: sostituisci le modifiche esterne.
  2. L'opzione è impostata su RESET_VALUE nel codice delle funzioni: sostituisci le modifiche esterne con il valore predefinito.
  3. L'opzione non è impostata nel codice delle funzioni, ma è impostata nella funzione di cui è stato eseguito il deployment: utilizza l'opzione specificata nella funzione di cui è stato eseguito il deployment.

L'utilizzo dell'opzione preserveExternalChanges: true non è consigliato per la maggior parte degli scenari, perché il codice non sarà più l'origine attendibile completa per le opzioni di runtime delle funzioni. Se la utilizzi, controlla la console Google Cloud o utilizza gcloud CLI per visualizzare la configurazione completa di una funzione.

Impostare la versione di Node.js

L'Firebase SDK per Cloud Functions consente di selezionare il runtime Node.js. Puoi scegliere di eseguire tutte le funzioni di un progetto esclusivamente nell'ambiente di runtime corrispondente a una di queste versioni di Node.js supportate:

  • Node.js 22
  • Node.js 20
  • Node.js 18 (ritirato)

Consulta la pianificazione dell'assistenza per informazioni importanti sull'assistenza continua per queste versioni di Node.js.

Per impostare la versione di Node.js:

Puoi impostare la versione nel campo engines del file package.json creato nella directory functions/ durante l'inizializzazione. Ad esempio, per utilizzare solo la versione 20, modifica questa riga in package.json:

  "engines": {"node": "22"}

Se utilizzi il gestore di pacchetti Yarn o hai altri requisiti specifici per il campo engines, puoi impostare il runtime per l'SDK Firebase per Cloud Functions in firebase.json:

  {
    "functions": {
      "runtime": "nodejs22"
    }
  }

L'interfaccia a riga di comando utilizza il valore impostato in firebase.json preferibilmente a qualsiasi valore o intervallo impostato separatamente in package.json.

Eseguire l'upgrade del runtime Node.js

Per eseguire l'upgrade del runtime Node.js:

  1. Assicurati che il tuo progetto utilizzi il piano tariffario Blaze.
  2. Assicurati di utilizzare Firebase CLI v11.18.0 o versioni successive.
  3. Modifica il valore engines nel file package.json creato nella directory functions/ durante l'inizializzazione. Ad esempio, se esegui l'upgrade dalla versione 16 alla versione 18, la voce dovrebbe essere simile a questa: "engines": {"node": "18"}
  4. (Facoltativo) Testa le modifiche utilizzando la Firebase Local Emulator Suite.
  5. Esegui di nuovo il deployment di tutte le funzioni.

Scegliere un sistema di moduli Node.js

Il sistema di moduli predefinito in Node.js è CommonJS (CJS), ma le versioni attuali di Node.js supportano anche i moduli ECMAScript (ESM). Cloud Functions supporta entrambi.

Per impostazione predefinita, le funzioni utilizzano CommonJS. Ciò significa che le importazioni e le esportazioni sono simili a queste:

const functions = require("firebase-functions/v1");

exports.helloWorld = functions.https.onRequest(async (req, res) => res.send("Hello from Firebase!"));

Per utilizzare ESM, imposta il campo "type": "module" nel file package.json :

  {
   ...
   "type": "module",
   ...
  }

Una volta impostato, utilizza la sintassi import ed export di ESM:

import functions from "firebase-functions/v1";

export const helloWorld = functions.https.onRequest(async (req, res) => res.send("Hello from Firebase!"));

Entrambi i sistemi di moduli sono completamente supportati. Puoi scegliere quello più adatto al tuo progetto. Scopri di più nella documentazione di Node.js sui moduli.

Controllare il comportamento di scalabilità

Per impostazione predefinita, Cloud Functions for Firebase adatta il numero di istanze in esecuzione in base al numero di richieste in entrata, con una potenziale riduzione a zero istanze in caso di traffico ridotto. Tuttavia, se la tua app richiede una latenza ridotta e vuoi limitare il numero di avvii a freddo, puoi modificare questo comportamento predefinito specificando un numero minimo di istanze di container da mantenere in uso e pronte per gestire le richieste.

Allo stesso modo, puoi impostare un numero massimo per limitare la scalabilità delle istanze in risposta alle richieste in entrata. Utilizza questa impostazione per controllare i costi o limitare il numero di connessioni a un servizio di backend, ad esempio a un database.

Ridurre il numero di avvii a freddo

Per impostare il numero minimo di istanze per una funzione nel codice sorgente, utilizza il runWith metodo. Questo metodo accetta un oggetto JSON conforme all' RuntimeOptions interfaccia, che definisce il valore di minInstances. Ad esempio, questa funzione imposta un minimo di 5 istanze da mantenere in uso:

exports.getAutocompleteResponse = functions
    .runWith({
      // Keep 5 instances warm for this latency-critical function
      minInstances: 5,
    })
    .https.onCall((data, context) => {
      // Autocomplete a user's search term
    });
index.js

Di seguito sono riportati alcuni aspetti da considerare quando imposti un valore per minInstances:

  • Se Cloud Functions for Firebase adatta la scalabilità della tua app al di sopra dell'impostazione minInstances, si verificherà un avvio a freddo per ogni istanza al di sopra di questa soglia.
  • Gli avvii a freddo hanno l'effetto più grave sulle app con traffico irregolare. Se la tua app ha un traffico irregolare e imposti un valore minInstances sufficientemente alto da ridurre gli avvii a freddo a ogni aumento del traffico, noterai una latenza notevolmente ridotta. Per le app con traffico costante, è improbabile che gli avvii a freddo influiscano gravemente sulle prestazioni.

  • L'impostazione delle istanze minime può essere utile per gli ambienti di produzione, ma in genere deve essere evitata negli ambienti di test. Per eseguire lo scale down a zero nel progetto di test, ma ridurre comunque gli avvii a freddo nel progetto di produzione, puoi impostare minInstances in base alla variabile di ambiente FIREBASE_CONFIG:

    // Get Firebase project id from `FIREBASE_CONFIG` environment variable
const envProjectId = JSON.parse(process.env.FIREBASE_CONFIG).projectId;

exports.renderProfilePage = functions
    .runWith({
      // Keep 5 instances warm for this latency-critical function
      // in production only. Default to 0 for test projects.
      minInstances: envProjectId === "my-production-project" ? 5 : 0,
    })
    .https.onRequest((req, res) => {
      // render some html
    });
    index.js

Limitare il numero massimo di istanze per una funzione

Per impostare il numero massimo di istanze nel codice sorgente della funzione, utilizza il runWith metodo. Questo metodo accetta un oggetto JSON conforme all' RuntimeOptions interfaccia, che definisce i valori di maxInstances. Ad esempio, questa funzione imposta un limite di 100 istanze per non sovraccaricare un database legacy ipotetico:

exports.mirrorOrdersToLegacyDatabase = functions
    .runWith({
      // Legacy database only supports 100 simultaneous connections
      maxInstances: 100,
    })
    .firestore.document("orders/{orderId}")
    .onWrite((change, context) => {
      // Connect to legacy database
    });
index.js

Se viene eseguito lo scale up di una funzione HTTP fino al limite maxInstances, le nuove richieste vengono messe in coda per 30 secondi e poi rifiutate con un codice di risposta 429 Too Many Requests se non è disponibile alcuna istanza entro quel momento.

Per scoprire di più sulle best practice per l'utilizzo delle impostazioni del numero massimo di istanze, consulta queste best practice per l'utilizzo di maxInstances.

Impostare un service account

Il service account predefinito per le funzioni di 1ª gen., PROJECT_ID@appspot.gserviceaccount.com (denominato App Engine default service account), dispone di un ampio set di autorizzazioni che ti consentono di interagire con altri servizi Firebase e Google Cloud.

Potresti voler sostituire il service account predefinito e limitare una funzione alle risorse esatte necessarie. Puoi farlo creando un service account personalizzato e assegnandolo alla funzione appropriata utilizzando il metodo .runWith(). Questo metodo accetta un oggetto con opzioni di configurazione, inclusa la proprietà serviceAccount.

const functions = require("firebase-functions/v1");

exports.helloWorld = functions
    .runWith({
        // This function doesn't access other Firebase project resources, so it uses a limited service account.
        serviceAccount:
            "my-limited-access-sa@", // or prefer the full form: "my-limited-access-sa@my-project.iam.gserviceaccount.com"
    })
    .https.onRequest((request, response) => {
        response.send("Hello from Firebase!");
    });

Impostare il timeout e l'allocazione della memoria

In alcuni casi, le funzioni potrebbero avere requisiti speciali per un valore di timeout lungo o un'allocazione di memoria elevata. Puoi impostare questi valori nella console Google Cloud o nel codice sorgente della funzione (solo Firebase).

Per impostare l'allocazione della memoria e il timeout nel codice sorgente delle funzioni, utilizza il runWith parametro introdotto nell'SDK Firebase per Cloud Functions 2.0.0. Questa opzione di runtime accetta un oggetto JSON conforme all' RuntimeOptions interfaccia, che definisce i valori di timeoutSeconds e memory. Ad esempio, questa funzione di archiviazione utilizza 1 GB di memoria e va in timeout dopo 300 secondi:

exports.convertLargeFile = functions
    .runWith({
      // Ensure the function has enough memory and time
      // to process large files
      timeoutSeconds: 300,
      memory: "1GB",
    })
    .storage.object()
    .onFinalize((object) => {
      // Do some complicated things that take a lot of memory and time
    });
index.js

Il valore massimo per timeoutSeconds è 540, ovvero 9 minuti. La quantità di memoria concessa a una funzione corrisponde alla CPU allocata per la funzione, come descritto in questo elenco di valori validi per memory:

  • 128MB — 200MHz
  • 256MB — 400MHz
  • 512MB — 800MHz
  • 1GB — 1,4 GHz
  • 2GB — 2,4 GHz
  • 4GB — 4,8 GHz
  • 8GB — 4,8 GHz

Per impostare l'allocazione della memoria e il timeout nella console Google Cloud:

  1. Nella Google Cloud console, seleziona Cloud Functions dal menu a sinistra.
  2. Seleziona una funzione facendo clic sul relativo nome nell'elenco delle funzioni.
  3. Fai clic sull'icona Modifica nel menu in alto.
  4. Seleziona un'allocazione della memoria dal menu a discesa con l'etichetta Memoria allocata.
  5. Fai clic su Altro per visualizzare le opzioni avanzate e inserisci un numero di secondi nella casella di testo Timeout.
  6. Fai clic su Salva per aggiornare la funzione.