Per iniziare: scrivi, testa ed esegui il deployment delle tue prime funzioni

2ª gen. 1ª gen.

Per iniziare a utilizzare Cloud Functions, prova a seguire questo tutorial, che inizia con le attività di configurazione richieste e prosegue con la creazione, il test e l'implementazione di due funzioni correlate:

• Una funzione "Aggiungi messaggio" che espone un URL che accetta un valore di testo e lo scrive in Cloud Firestore.
• Una funzione "make maiuscolo" che si attiva in caso di scrittura Cloud Firestore e trasforma il testo in maiuscolo.

Ecco il codice di esempio completo contenente le funzioni:

Node.js

// The Cloud Functions for Firebase SDK to create Cloud Functions and triggers.
const {logger} = require("firebase-functions");
const {onRequest} = require("firebase-functions/v2/https");
const {onDocumentCreated} = require("firebase-functions/v2/firestore");

// The Firebase Admin SDK to access Firestore.
const {initializeApp} = require("firebase-admin/app");
const {getFirestore} = require("firebase-admin/firestore");

initializeApp();

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addmessage = onRequest(async (req, res) => {
  // Grab the text parameter.
  const original = req.query.text;
  // Push the new message into Firestore using the Firebase Admin SDK.
  const writeResult = await getFirestore()
      .collection("messages")
      .add({original: original});
  // Send back a message that we've successfully written the message
  res.json({result: `Message with ID: ${writeResult.id} added.`});
});

// Listens for new messages added to /messages/:documentId/original
// and saves an uppercased version of the message
// to /messages/:documentId/uppercase
exports.makeuppercase = onDocumentCreated("/messages/{documentId}", (event) => {
  // Grab the current value of what was written to Firestore.
  const original = event.data.data().original;

  // Access the parameter `{documentId}` with `event.params`
  logger.log("Uppercasing", event.params.documentId, original);

  const uppercase = original.toUpperCase();

  // You must return a Promise when performing
  // asynchronous tasks inside a function
  // such as writing to Firestore.
  // Setting an 'uppercase' field in Firestore document returns a Promise.
  return event.data.ref.set({uppercase}, {merge: true});
});
index.js

Python

# The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
from firebase_functions import firestore_fn, https_fn

# The Firebase Admin SDK to access Cloud Firestore.
from firebase_admin import initialize_app, firestore
import google.cloud.firestore

app = initialize_app()


@https_fn.on_request()
def addmessage(req: https_fn.Request) -> https_fn.Response:
    """Take the text parameter passed to this HTTP endpoint and insert it into
    a new document in the messages collection."""
    # Grab the text parameter.
    original = req.args.get("text")
    if original is None:
        return https_fn.Response("No text parameter provided", status=400)

    firestore_client: google.cloud.firestore.Client = firestore.client()

    # Push the new message into Cloud Firestore using the Firebase Admin SDK.
    _, doc_ref = firestore_client.collection("messages").add({"original": original})

    # Send back a message that we've successfully written the message
    return https_fn.Response(f"Message with ID {doc_ref.id} added.")


@firestore_fn.on_document_created(document="messages/{pushId}")
def makeuppercase(event: firestore_fn.Event[firestore_fn.DocumentSnapshot | None]) -> None:
    """Listens for new documents to be added to /messages. If the document has
    an "original" field, creates an "uppercase" field containg the contents of
    "original" in upper case."""

    # Get the value of "original" if it exists.
    if event.data is None:
        return
    try:
        original = event.data.get("original")
    except KeyError:
        # No "original" field, so do nothing.
        return

    # Set the "uppercase" field.
    print(f"Uppercasing {event.params['pushId']}: {original}")
    upper = original.upper()
    event.data.reference.update({"uppercase": upper})
main.py

Informazioni su questo tutorial

Abbiamo scelto Cloud Firestore e funzioni attivate da HTTP per questo esempio in parte perché questi trigger in background possono essere testati con attenzione tramite Firebase Local Emulator Suite. Questo set di strumenti supporta anche gli trigger chiamabili Realtime Database, Cloud Storage, PubSub, Auth e HTTP. Altri tipi di attivatori in background, come gli attivatori Remote Config e TestLab, possono essere testati in modo interattivo utilizzando set di strumenti non descritti in questa pagina.

Nota: puoi emulare funzioni in qualsiasi progetto Firebase, ma per eseguire il deployment delle funzioni, il progetto deve rientrare nel piano tariffario Blaze. Consulta i prezzi di Cloud Functions.

Le seguenti sezioni di questo tutorial spiegano in dettaglio i passaggi necessari per creare, testare ed eseguire il deployment dell'esempio.

Crea un progetto Firebase

1. Nella console Firebase, fai clic su Aggiungi progetto.

   • Per aggiungere risorse Firebase a un progetto Google Cloud esistente, inserisci il nome del progetto o selezionalo dal menu a discesa.

   • Per creare un nuovo progetto, inserisci il nome desiderato. Facoltativamente, puoi anche modificare l'ID progetto visualizzato sotto il nome del progetto.

     Firebase genera un ID univoco per il tuo progetto Firebase in base al nome che gli assegni. Se vuoi modificare questo ID progetto, devi farlo ora, poiché non può essere modificato dopo che Firebase ha eseguito il provisioning delle risorse per il tuo progetto. Visita la pagina Informazioni sui progetti Firebase per scoprire come Firebase utilizza l'ID progetto.

2. Se richiesto, leggi e accetta i Termini di Firebase.

3. Fai clic su Continua.

4. (Facoltativo) Configura Google Analytics per il tuo progetto, al fine di avere un'esperienza ottimale utilizzando i seguenti prodotti Firebase:

   Firebase Crashlytics Firebase Cloud Messaging

   Firebase In-App Messaging Firebase Remote Config

   Personalizzazione Remote Config Firebase A/B Testing

   Seleziona un account Google Analytics esistente o creane uno nuovo.

   Se crei un nuovo account, seleziona la località del report di Analytics, poi accetta le impostazioni di condivisione dei dati e i termini di Google Analytics per il tuo progetto.

   Puoi sempre configurare Google Analytics in un secondo momento nella scheda Integrazioni delle Impostazioni progetto di .

5. Fai clic su Crea progetto (o su Aggiungi Firebase, se utilizzi un progetto Google Cloud esistente).

Firebase esegue automaticamente il provisioning delle risorse per il tuo progetto Firebase. Al termine del processo, verrà visualizzata la pagina Panoramica del progetto Firebase nella console Firebase.

Configura l'ambiente e l'interfaccia a riga di comando di Firebase

Node.js

Avrai bisogno di un ambiente Node.js per scrivere le funzioni e avrai bisogno dell'interfaccia a riga di comando Firebase per eseguire il deployment delle funzioni nel runtime Cloud Functions. Per installare Node.js e npm, è consigliato Node Version Manager.

Importante: Cloud Functions e l'interfaccia a riga di comando Firebase supportano completamente le versioni di Node.js 18 e 20, con supporto a livello di anteprima per la versione 22. Le versioni 14 e 16 sono ritirate e verranno ritirate all'inizio del 2025 (al momento, il deployment con queste versioni ritirate è disattivato). Consulta Impostare le opzioni di runtime per informazioni importanti sull'assistenza continua per queste versioni di Node.js.

Dopo aver installato Node.js e npm, installa l'interfaccia a riga di comando Firebase con il tuo metodo preferito. Per installare l'interfaccia a riga di comando tramite npm, utilizza:

npm install -g firebase-tools

Viene installato il comando firebase disponibile a livello globale. Se il comando non riesce, potrebbe essere necessario modificare le autorizzazioni npm. Per eseguire l'aggiornamento alla versione più recente di firebase-tools, esegui di nuovo lo stesso comando.

In molti casi, nuove funzionalità e correzioni di bug sono disponibili solo con la versione più recente dell'interfaccia a riga di comando di Firebase e dell'SDK firebase-functions. È buona norma aggiornare frequentemente sia l'interfaccia a riga di comando di Firebase sia l'SDK con questi comandi nella cartella functions del progetto Firebase:

npm install firebase-functions@latest firebase-admin@latest --save
npm install -g firebase-tools

Python

Avrai bisogno di un ambiente Python per scrivere funzioni e l'interfaccia a riga di comando Firebase per eseguire il deployment delle funzioni nel runtime Cloud Functions. Ti consigliamo di utilizzare venv per isolare le dipendenze. Sono supportate le versioni Python 3.10 e 3.11.

Dopo aver installato Python, installa l'interfaccia a riga di comando Firebase con il tuo metodo preferito.

In molti casi, nuove funzionalità e correzioni di bug sono disponibili solo con la versione più recente dell'interfaccia a riga di comando di Firebase e dell'SDK firebase-functions. È buona norma aggiornare frequentemente sia l'interfaccia a riga di comando di Firebase sia l'SDK all'interno della cartella functions del tuo progetto Firebase.

Inizializza il progetto

Quando inizili l'SDK Firebase per Cloud Functions, crei un progetto vuoto contenente dipendenze e un codice di esempio minimo. Se utilizzi Node.js, puoi scegliere tra TypeScript o JavaScript per comporre le funzioni. Ai fini di questo tutorial, dovrai anche inizializzare Cloud Firestore.

Per inizializzare il progetto:

1. Esegui firebase login per accedere tramite il browser e autenticare l'interfaccia a riga di comando Firebase.
2. Vai alla directory del progetto Firebase.
3. Esegui firebase init firestore. Per questo tutorial, puoi accettare i valori predefiniti quando ti viene chiesto di specificare le regole e i file di indicizzazione di Firestore. Se non hai ancora utilizzato Cloud Firestore in questo progetto, dovrai anche selezionare una modalità di partenza e una località per Firestore, come descritto in Iniziare a utilizzare Cloud Firestore.
4. Esegui firebase init functions. L'interfaccia a riga di comando ti chiede di scegliere un codebase esistente o di inizializzarne uno nuovo. All'inizio, è sufficiente un singolo codebase nella località predefinita; in seguito, man mano che l'implementazione si espande, potresti voler organizzare le funzioni nei codebase.

5. La CLI offre le seguenti opzioni per il supporto della lingua:

   • JavaScript
   • TypeScript
   • Python

   Per questo tutorial, seleziona JavaScript o Python. Per la creazione di script in TypeScript, consulta Scrivere funzioni con TypeScript.

6. L'interfaccia a riga di comando ti offre la possibilità di installare le dipendenze. Puoi rifiutare in tutta sicurezza se vuoi gestire le dipendenze in un altro modo.

Una volta completati questi comandi, la struttura del progetto sarà simile a questa:

Node.js

myproject
+- .firebaserc    # Hidden file that helps you quickly switch between
|                 # projects with `firebase use`
|
+- firebase.json  # Describes properties for your project
|
+- functions/     # Directory containing all your functions code
      |
      +- .eslintrc.json  # Optional file containing rules for JavaScript linting.
      |
      +- package.json  # npm package file describing your Cloud Functions code
      |
      +- index.js      # Main source file for your Cloud Functions code
      |
      +- node_modules/ # Directory where your dependencies (declared in
                        # package.json) are installed

Per Node.js, il file package.json creato durante l'inizializzazione contiene una chiave importante: "engines": {"node": "18"}. Specifica la versione di Node.js per scrivere ed eseguire il deployment delle funzioni. Puoi selezionare altre versioni supportate.

Python

myproject
+- .firebaserc    # Hidden file that helps you quickly switch between
|                 # projects with `firebase use`
|
+- firebase.json  # Describes properties for your project
|
+- functions/     # Directory containing all your functions code
      |
      +- main.py      # Main source file for your Cloud Functions code
      |
      +- requirements.txt  #  List of the project's modules and packages 
      |
      +- venv/ # Directory where your dependencies are installed

Importa i moduli richiesti e inizializza un'app

Dopo aver completato le attività di configurazione, puoi aprire la directory di origine e iniziare ad aggiungere codice come descritto nelle sezioni seguenti. Per questo esempio, il progetto deve importare i moduli Cloud Functions e SDK Admin. Aggiungi righe come le seguenti al file di origine:

Node.js

// The Cloud Functions for Firebase SDK to create Cloud Functions and triggers.
const {logger} = require("firebase-functions");
const {onRequest} = require("firebase-functions/v2/https");
const {onDocumentCreated} = require("firebase-functions/v2/firestore");

// The Firebase Admin SDK to access Firestore.
const {initializeApp} = require("firebase-admin/app");
const {getFirestore} = require("firebase-admin/firestore");

initializeApp();
index.js

Python

# The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
from firebase_functions import firestore_fn, https_fn

# The Firebase Admin SDK to access Cloud Firestore.
from firebase_admin import initialize_app, firestore
import google.cloud.firestore

app = initialize_app()
main.py

Queste righe caricano i moduli richiesti e inizializzano un'istanza dell'app admin da cui è possibile apportare modifiche a Cloud Firestore. Ogni volta che è disponibile il supporto degli SDK Admin, come per FCM, Authentication e Firebase Realtime Database, offre un modo efficace per integrare Firebase utilizzando Cloud Functions.

L'interfaccia a riga di comando Firebase installa automaticamente l'SDK Admin Firebase e l'SDK Firebase per i moduli Cloud Functions quando inizializza il progetto. Per ulteriori informazioni sull'aggiunta di librerie di terze parti al progetto, consulta Gestire le dipendenze.

Aggiungi la funzione "Aggiungi messaggio"

Per la funzione "add message" (aggiungi messaggio), aggiungi queste righe al file di origine:

Node.js

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addmessage = onRequest(async (req, res) => {
  // Grab the text parameter.
  const original = req.query.text;
  // Push the new message into Firestore using the Firebase Admin SDK.
  const writeResult = await getFirestore()
      .collection("messages")
      .add({original: original});
  // Send back a message that we've successfully written the message
  res.json({result: `Message with ID: ${writeResult.id} added.`});
});
index.js

Python

@https_fn.on_request()
def addmessage(req: https_fn.Request) -> https_fn.Response:
    """Take the text parameter passed to this HTTP endpoint and insert it into
    a new document in the messages collection."""
    # Grab the text parameter.
    original = req.args.get("text")
    if original is None:
        return https_fn.Response("No text parameter provided", status=400)

    firestore_client: google.cloud.firestore.Client = firestore.client()

    # Push the new message into Cloud Firestore using the Firebase Admin SDK.
    _, doc_ref = firestore_client.collection("messages").add({"original": original})

    # Send back a message that we've successfully written the message
    return https_fn.Response(f"Message with ID {doc_ref.id} added.")
main.py

La funzione "aggiungi messaggio" è un endpoint HTTP. Qualsiasi richiesta all'endpoint restituisce oggetti di richiesta e risposta passati al gestore di richieste per la tua piattaforma (onRequest() o on_request).

Le funzioni HTTP sono sincrone (simili alle funzioni richiamabili), quindi devi inviare una risposta il più rapidamente possibile e rimandare il lavoro utilizzando Cloud Firestore. La funzione HTTP "aggiungi messaggio" passa un valore di testo all'endpoint HTTP e lo inserisce nel database sotto il percorso /messages/:documentId/original.

Aggiungi la funzione "Rendi maiuscola"

Per la funzione "make maiuscolo", aggiungi queste righe al file di origine:

Node.js

// Listens for new messages added to /messages/:documentId/original
// and saves an uppercased version of the message
// to /messages/:documentId/uppercase
exports.makeuppercase = onDocumentCreated("/messages/{documentId}", (event) => {
  // Grab the current value of what was written to Firestore.
  const original = event.data.data().original;

  // Access the parameter `{documentId}` with `event.params`
  logger.log("Uppercasing", event.params.documentId, original);

  const uppercase = original.toUpperCase();

  // You must return a Promise when performing
  // asynchronous tasks inside a function
  // such as writing to Firestore.
  // Setting an 'uppercase' field in Firestore document returns a Promise.
  return event.data.ref.set({uppercase}, {merge: true});
});
index.js

Python

@firestore_fn.on_document_created(document="messages/{pushId}")
def makeuppercase(event: firestore_fn.Event[firestore_fn.DocumentSnapshot | None]) -> None:
    """Listens for new documents to be added to /messages. If the document has
    an "original" field, creates an "uppercase" field containg the contents of
    "original" in upper case."""

    # Get the value of "original" if it exists.
    if event.data is None:
        return
    try:
        original = event.data.get("original")
    except KeyError:
        # No "original" field, so do nothing.
        return

    # Set the "uppercase" field.
    print(f"Uppercasing {event.params['pushId']}: {original}")
    upper = original.upper()
    event.data.reference.update({"uppercase": upper})
main.py

La funzione "make maiuscolo" viene eseguita quando viene scritto Cloud Firestore, che definisce il documento da ascoltare. Per migliorare le prestazioni, dovresti essere il più specifico possibile.

Le parentesi graffe, ad esempio {documentId}, contengono i "parametri", ovvero i caratteri jolly che espongono i dati corrispondenti nel callback. Cloud Firestore attiva il callback ogni volta che vengono aggiunti nuovi messaggi.

Attenzione: fai attenzione a evitare situazioni in cui il risultato della funzione riattivi effettivamente la funzione, creando un ciclo infinito, ad esempio una funzione attivata da scritture in un documento Cloud Firestore specifico che termina scrivendo nello stesso percorso. Assicurati inoltre di scrivere le funzioni in modo idempotente, in modo che producano lo stesso risultato se vengono eseguite più volte per un singolo evento.

In Node.js, le funzioni basate su eventi come gli eventi Cloud Firestore sono asincrone. La funzione di callback deve restituire un null, un oggetto o una Promessa. Se non restituisci nulla, la funzione scade, segnala un errore e viene eseguito nuovamente il tentativo. Vedi Sincronizzazione, Asinc e Promesse.

Emula l'esecuzione delle tue funzioni

Firebase Local Emulator Suite ti consente di creare e testare app sul tuo computer locale anziché eseguirne il deployment in un progetto Firebase. Ti consigliamo vivamente di eseguire test locali durante lo sviluppo, in parte perché riduce il rischio di errori di programmazione che potrebbero comportare costi in un ambiente di produzione (ad esempio un loop infinito).

Per emulare le tue funzioni:

1. Esegui firebase emulators:start e controlla l'output per l'URL del Emulator Suite UI. Il valore predefinito è localhost:4000, ma potrebbe essere ospitato su una porta diversa della tua macchina. Inserisci l'URL nel browser per aprire Emulator Suite UI.

2. Verifica l'output del comando firebase emulators:start per l'URL della funzione HTTP. Sarà simile a http://localhost:5001/MY_PROJECT/us-central1/addMessage, tranne che:

   1. MY_PROJECT verrà sostituito con l'ID del tuo progetto.
   2. La porta potrebbe essere diversa sulla macchina locale.

3. Aggiungi la stringa di query ?text=uppercaseme alla fine dell'URL della funzione. Dovrebbe avere il seguente aspetto: http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme. Facoltativamente, puoi modificare il messaggio "uppercaseme" in un messaggio personalizzato.

4. Crea un nuovo messaggio aprendo l'URL in una nuova scheda del browser.

5. Visualizza gli effetti delle funzioni in Emulator Suite UI:

   1. Nella scheda Log vengono visualizzati i nuovi log che indicano che le funzioni HTTP sono state eseguite correttamente:

      i functions: Beginning execution of "addMessage"

      i functions: Beginning execution of "makeUppercase"

   2. Nella scheda Firestore, dovresti vedere un documento contenente il messaggio originale e la versione in maiuscolo del messaggio (se originariamente era "maiuscole", vedrai "MAIUSCOLE").

Esegui il deployment delle funzioni in un ambiente di produzione

Quando le funzioni funzionano come previsto nell'emulatore, puoi procedere con il deployment, il test e l'esecuzione nell'ambiente di produzione. Tieni presente che per eseguire il deployment in produzione, il progetto deve essere nel piano tariffario Blaze. Consulta i prezzi di Cloud Functions.

Per completare il tutorial, esegui il deployment delle funzioni ed eseguile.

1. Esegui questo comando per eseguire il deployment delle funzioni:

    firebase deploy --only functions
    

   Dopo che hai eseguito il comando, l'interfaccia a riga di comando Firebase restituisce l'URL per qualsiasi endpoint della funzione HTTP. Nel terminale dovresti vedere una riga simile alla seguente:

   Function URL (addMessage): https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage
   

   L'URL contiene il tuo ID progetto e una regione per la funzione HTTP. Anche se non devi preoccuparti ora, alcune funzioni HTTP di produzione dovrebbero specificare una località per ridurre al minimo la latenza di rete.

   Se riscontri errori di accesso come "Impossibile autorizzare l'accesso al progetto", prova a controllare l'alias del progetto.

2. Utilizzando l'URL generato dall'interfaccia a riga di comando, aggiungi un parametro di query testuale e aprilo in un browser:

   https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage?text=uppercasemetoo
   

   La funzione esegue e reindirizza il browser alla console Firebase nella posizione del database in cui è archiviata la stringa di testo. Questo evento di scrittura attiva la funzione "make uppercase", che scrive una versione in lettere uppercase della stringa.

Dopo aver eseguito il deployment ed eseguito le funzioni, puoi visualizzare i log nella console Google Cloud. Se devi eliminare funzioni in fase di sviluppo o produzione, utilizza l'interfaccia a riga di comando Firebase.

In produzione, ti consigliamo di ottimizzare le prestazioni delle funzioni e di controllare i costi impostando il numero minimo e massimo di istanze da eseguire. Per ulteriori informazioni su queste opzioni di runtime, consulta Controllare il comportamento di scalabilità.

Nota: il deployment delle funzioni dall'interfaccia a riga di comando Firebase è soggetto a limiti di frequenza. Consulta la sezione Limiti di quota per l'implementazione della CLI Firebase.

Passaggi successivi

In questa documentazione puoi scoprire di più su come gestire le funzioni per Cloud Functions e su come gestire tutti i tipi di eventi supportati da Cloud Functions.

Per scoprire di più su Cloud Functions, puoi anche:

• Leggi i casi d'uso di Cloud Functions.
• Prova il codelab Cloud Functions.
• Rivedi ed esegui esempi di codice su GitHub