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

Per iniziare a utilizzare Cloud Functions, prova a seguire questo tutorial, che inizia con le attività di configurazione richieste e illustra la creazione, il test, e il deployment 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 "trasforma in maiuscolo" che si attiva in caso di scrittura in Cloud Firestore e trasforma il testo in maiuscolo.

Ecco il codice campione 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/https");
const {onDocumentCreated} = require("firebase-functions/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 le funzioni attivate da HTTP per questo esempio, in parte perché questi trigger in background possono essere testati a fondo tramite Firebase Local Emulator Suite. Questo set di strumenti supporta anche Realtime Database, Cloud Storage, Pub/Sub, Auth e i trigger HTTP chiamabili. Altri tipi di trigger in background come Remote Config e i trigger di Test Lab possono essere testati in modo interattivo utilizzando set di strumenti non descritti in questa pagina.

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

Creare un progetto Firebase

Non hai mai utilizzato Firebase o Cloud

Segui questi passaggi se non hai mai utilizzato Firebase o Google Cloud.
Puoi seguire questi passaggi anche se vuoi creare un progetto Firebase completamente nuovo (e il progetto sottostante Google Cloud ).

Accedi alla Firebase console.
Fai clic sul pulsante per creare un nuovo progetto Firebase.
Nel campo di testo, inserisci un nome progetto.

Se fai parte di un'organizzazione Google Cloud, puoi facoltativamente selezionare la cartella in cui creare il progetto.

Il nome del progetto viene utilizzato come nome visualizzato nelle interfacce Firebase e Firebase crea automaticamente un ID progetto univoco basato su questo nome. Tieni presente che puoi facoltativamente fare clic sull' icona Modifica ora per impostare l'ID progetto che preferisci, ma non puoi modificare questo ID dopo la creazione del progetto. Scopri come Firebase utilizza l'ID progetto.
Se ti viene richiesto, esamina e accetta i Termini di Firebase, quindi fai clic su Continua.
(Facoltativo) Abilita l'assistenza AI nella console Firebase (denominata "Gemini in Firebase"), che può aiutarti a iniziare e semplificare il processo di sviluppo.
(Facoltativo) Configura Google Analytics per il tuo progetto, che consente un'esperienza ottimale utilizzando questi prodotti Firebase: Firebase A/B Testing, Cloud Messaging, Crashlytics, In-App Messaging e Remote Config (inclusa la personalizzazione).

Seleziona un account Google Analytics esistente o creane uno nuovo. Se crei un nuovo account, seleziona la località di generazione dei report Analytics, quindi accetta le impostazioni di condivisione dei dati e i Google Analytics termini per il tuo progetto.

Puoi configurare Google Analytics in un secondo momento nella scheda Integrazioni delle Impostazioni progetto.
Fai clic su Crea progetto.

Firebase crea il progetto, esegue il provisioning di alcune risorse iniziali e abilita le API importanti. Al termine della procedura, verrà visualizzata la pagina Panoramica del progetto Firebase nella console Firebase.

Progetto Cloud esistente

Segui questi passaggi se vuoi iniziare a utilizzare Firebase con un progetto esistente Google Cloud Scopri di più e risolvi i problemi relativi all'aggiunta di Firebase a un progetto esistente.Google Cloud

Accedi alla Firebase console con l'account che ti dà accesso al progetto esistente Google Cloud.
Fai clic sul pulsante per creare un nuovo progetto Firebase.
Nella parte inferiore della pagina, fai clic su Aggiungi Firebase al progetto Google Cloud.
Nel campo di testo, inizia a inserire il nome progetto del progetto esistente, quindi seleziona il progetto dall'elenco visualizzato.
Fai clic su Apri progetto.
Se ti viene richiesto, esamina e accetta i Termini di Firebase, quindi fai clic su Continua.
(Facoltativo) Abilita l'assistenza AI nella console Firebase (denominata "Gemini in Firebase"), che può aiutarti a iniziare e semplificare il processo di sviluppo.
(Facoltativo) Configura Google Analytics per il tuo progetto, che consente un'esperienza ottimale utilizzando questi prodotti Firebase: Firebase A/B Testing, Cloud Messaging, Crashlytics, In-App Messaging e Remote Config (inclusa la personalizzazione).

Seleziona un account Google Analytics esistente o creane uno nuovo. Se crei un nuovo account, seleziona la località di generazione dei report Analytics, quindi accetta le impostazioni di condivisione dei dati e i Google Analytics termini per il tuo progetto.

Puoi configurare Google Analytics in un secondo momento nella scheda Integrazioni delle Impostazioni progetto.
Fai clic su Aggiungi Firebase.

Firebase aggiunge Firebase al progetto esistente. Al termine della procedura, verrà visualizzata la pagina di riepilogo del progetto Firebase nella Firebase console.

Configurare 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 dell'interfaccia a riga di comando Firebase per eseguire il deployment delle funzioni nel runtime Cloud Functions. Per l'installazione di Node.js e npm, Node Version Manager è consigliabile.

Una volta installati Node.js e npm, installa la CLI Firebase utilizzando il metodo che preferisci. Per installare l'interfaccia a riga di comando tramite npm, utilizza:

npm install -g firebase-tools

In questo modo viene installato il comando firebase disponibile a livello globale. Se il comando non riesce, potresti dover modificare le autorizzazioni npm. Per eseguire l'aggiornamento all'ultima versione di firebase-tools, esegui di nuovo lo stesso comando.

Python

Avrai bisogno di un ambiente Python per scrivere le funzioni e dell'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 di Python da 3.10 a 3.13, con 3.13 come runtime predefinito.

Una volta installato Python, installa l'interfaccia a riga di comandoFirebase utilizzando il metodo che preferisci.

Inizializzare il progetto

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

Per inizializzare il progetto:

Esegui firebase login per accedere tramite il browser e autenticare la Firebase CLI.
Vai alla directory del progetto Firebase.
Esegui firebase init firestore. Per questo tutorial, puoi accettare i valori predefiniti quando ti viene richiesto di inserire i file di regole e indici di Firestore. Se non hai ancora utilizzato Cloud Firestore in questo progetto, dovrai anche selezionare una modalità di avvio e una località per Firestore come descritto in Iniziare a utilizzare Cloud Firestore.
Esegui firebase init functions. L'interfaccia a riga di comando ti chiede di scegliere una codebase esistente o di inizializzarne e denominarne una nuova. Quando inizi a utilizzare il prodotto, una singola codebase nella località predefinita è sufficiente; in seguito, man mano che l'implementazione si espande, potresti voler organizzare le funzioni nelle codebase.
L'interfaccia a riga di comando offre le seguenti opzioni per il supporto linguistico:
- JavaScript
- TypeScript
- Python
Per questo tutorial, seleziona JavaScript o Python. Per la creazione in TypeScript, consulta Scrivere funzioni con TypeScript.
L'interfaccia a riga di comando offre un'opzione per installare le dipendenze. Puoi rifiutare questa opzione se vuoi gestire le dipendenze in un altro modo.

Al termine di questi comandi, la struttura del progetto sarà simile alla seguente:

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"}. Questa specifica la versione di Node.js per la scrittura e 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

Importare i moduli richiesti e inizializzare 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 Cloud Functions e i moduli SDK Admin. Aggiungi righe simili alle 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/https");
const {onDocumentCreated} = require("firebase-functions/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. Ovunque sia disponibile il supporto dell'SDK Admin, come lo è per FCM, Authentication e Firebase Realtime Database, fornisce un modo efficace per integrare Firebase utilizzando Cloud Functions.

L'Firebase CLI installa automaticamente i moduli dell'SDK Firebase Admin e dell'Firebase SDK per Cloud Functions quando inizializzi il progetto. Per ulteriori informazioni sull'aggiunta di librerie di terze parti al progetto, consulta Gestire le dipendenze.

Aggiungere la funzione "aggiungi messaggio"

Per la funzione "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 genera oggetti di richiesta e risposta passati al gestore delle richieste per la tua piattaforma (onRequest() o on_request).

Le funzioni HTTP sono sincrone (simili alle funzioni chiamabili), 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 nel percorso /messages/:documentId/original.

Aggiungere la funzione "trasforma in maiuscolo"

Per la funzione "trasforma in 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 "trasforma in maiuscolo" viene eseguita quando viene scritta in Cloud Firestore, definendo il documento da monitorare. Per motivi di prestazioni, devi essere il più specifico possibile.

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

In Node.js, le funzioni basate su eventi, come gli eventi Cloud Firestore, sono asincrone. La funzione di callback deve restituire null un oggetto, o una promessa. Se non restituisci nulla, la funzione va in timeout, segnala un errore e viene ritentata. Consulta Sincrono, asincrono e promesse.

Emulare l'esecuzione delle funzioni

Firebase Local Emulator Suite ti consente di creare e testare le app sulla tua macchina locale anziché eseguirne il deployment in un progetto Firebase. Il test locale durante lo sviluppo è fortemente consigliato, in parte perché riduce il rischio di errori di codifica che potrebbero potenzialmente comportare costi in un ambiente di produzione (ad esempio, un loop infinito).

Per emulare le funzioni:

Esegui firebase emulators:start e controlla l'output per l'URL di Emulator Suite UI. Per impostazione predefinita è localhost:4000, ma potrebbe essere ospitato su una porta diversa sulla tua macchina. Inserisci l'URL nel browser per aprire il Emulator Suite UI.
Controlla 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 progetto.
2. La porta potrebbe essere diversa sulla tua macchina locale.
Aggiungi la stringa di query ?text=uppercaseme alla fine dell'URL della funzione. Dovrebbe essere simile a: http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme. Se vuoi, puoi modificare il messaggio "uppercaseme" in un messaggio personalizzato messaggio.
Crea un nuovo messaggio aprendo l'URL in una nuova scheda del browser.
Visualizza gli effetti delle funzioni nel Emulator Suite UI:
1. Nella scheda Log dovresti visualizzare 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 visualizzare un documento contenente il messaggio originale e la versione in maiuscolo del messaggio (se originariamente era "uppercaseme", vedrai "UPPERCASEME").

Eseguire il deployment delle funzioni in un ambiente di produzione

Una volta che 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 incluso nel piano tariffario Blaze. Consulta i prezzi Cloud Functions.

Per completare il tutorial, esegui il deployment delle funzioni e poi eseguile.

Esegui questo comando per eseguire il deployment delle funzioni:
```
 firebase deploy --only functions
 
```
Dopo aver eseguito questo comando, l'Firebase CLI restituisce l'URL per tutti gli endpoint delle funzioni HTTP. Nel terminale, dovresti visualizzare una riga simile alla seguente:
```
Function URL (addMessage): https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage
```
L'URL contiene l'ID progetto e una regione per la funzione HTTP. Anche se non devi preoccuparti ora, alcune funzioni HTTP di produzione devono specificare una località per ridurre al minimo la latenza di rete.

Se riscontri errori di accesso come "Impossibile autorizzare l'accesso a progetto," prova a controllare l'aliasing del progetto.
Utilizzando l'output dell'URL dell'interfaccia a riga di comando, aggiungi un parametro di query di testo, e aprilo in un browser:
```
https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage?text=uppercasemetoo
```
La funzione viene eseguita e reindirizza il browser alla Firebase console nella località del database in cui è archiviata la stringa di testo. Questo evento di scrittura attiva la funzione "trasforma in maiuscolo", che scrive una versione in maiuscolo della stringa.

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

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

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 saperne di più su Cloud Functions, puoi anche:

Leggere i casi d'uso di Cloud Functions.
Provare il Cloud Functions codelab.
Esaminare ed eseguire esempi di codice su GitHub

Per iniziare: scrivi, testa ed esegui il deployment delle tue prime funzioni Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Node.js

Python

Informazioni su questo tutorial

Creare un progetto Firebase

Non hai mai utilizzato Firebase o Cloud

Progetto Cloud esistente

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

Node.js

Python

Inizializzare il progetto

Node.js

Python

Importare i moduli richiesti e inizializzare un'app

Node.js

Python

Aggiungere la funzione "aggiungi messaggio"

Node.js

Python

Aggiungere la funzione "trasforma in maiuscolo"

Node.js

Python

Emulare l'esecuzione delle funzioni

Eseguire il deployment delle funzioni in un ambiente di produzione

Passaggi successivi

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