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 prosegue con la creazione, il test e il deployment di due funzioni correlate:

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

Ecco il codice campione completo contenente le funzioni:

// 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

# 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

Per questo esempio abbiamo scelto Cloud Firestore e le funzioni attivate da HTTP in parte perché questi trigger in background possono essere testati accuratamente tramite Firebase Local Emulator Suite. Questo set di strumenti supporta anche i trigger richiamabili Realtime Database, Cloud Storage, Pub/Sub, Auth e HTTP. Altri tipi di trigger in background, come i trigger Remote Config e TestLab, 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.

Crea un progetto Firebase

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

Inizializza il progetto

Quando inizializzi l'SDK Firebase per Cloud Functions, crei un progetto vuoto contenente le dipendenze e un codice campione minimo. Se utilizzi Node.js, puoi scegliere TypeScript o JavaScript per la composizione delle 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 vengono richiesti 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 Inizia a utilizzare Cloud Firestore.
4. Esegui firebase init functions. La CLI ti chiede di scegliere un codebase esistente o di inizializzarne e assegnare un nome a uno nuovo. Quando inizi, un singolo codebase nella località predefinita è sufficiente; 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 delle lingue:

   • JavaScript
   • TypeScript
   • Python

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

6. La CLI ti offre la possibilità di installare le dipendenze. Puoi rifiutare questa opzione se vuoi gestire le dipendenze in un altro modo.

Una volta completati questi comandi, la struttura del progetto sarà simile alla seguente:

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

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:

// 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

# 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 nel caso di FCM, Authentication e Firebase Realtime Database, viene fornito un modo efficace per integrare Firebase utilizzando Cloud Functions.

L'interfaccia a riga di comando Firebase installa automaticamente l'SDK Firebase Admin e l'SDK Firebase per i moduli Cloud Functions quando inizializzi il progetto. Per saperne di più sull'aggiunta di librerie di terze parti al tuo progetto, consulta Gestisci le dipendenze.

Aggiungi la funzione "add message"

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

// 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

@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 "add message" è 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 richiamabili), quindi devi inviare una risposta il più rapidamente possibile e rimandare il lavoro utilizzando Cloud Firestore. La funzione HTTP "add message" passa un valore di testo all'endpoint HTTP e lo inserisce nel database nel percorso /messages/:documentId/original.

Aggiungi la funzione "make uppercase"

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

// 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

@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 uppercase" viene eseguita quando viene scritto 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", ovvero i 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 un null, un oggetto o una promessa. Se non restituisci nulla, la funzione va in timeout, segnala un errore e viene eseguito un nuovo tentativo. Consulta Sincronizzazione, asincronia e promesse.

Emula l'esecuzione delle tue funzioni

Firebase Local Emulator Suite ti consente di creare e testare app sulla tua macchina locale anziché eseguirne il deployment in un progetto Firebase. I test locali durante lo sviluppo sono vivamente consigliati, in parte perché riducono il rischio di errori di programmazione che potrebbero potenzialmente 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 di 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. 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, con le seguenti eccezioni:

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

3. Aggiungi la stringa di query ?text=uppercaseme alla fine dell'URL della funzione. Dovrebbe avere un aspetto simile a questo: http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme. Se vuoi, 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, dovresti vedere nuovi log che indicano che le tue 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 lettere maiuscole del messaggio (se in origine era "uppercaseme", vedrai "UPPERCASEME").

Esegui 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 tuo progetto deve essere associato al piano tariffario Blaze. Visualizza i prezzi di Cloud Functions.

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

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

    firebase deploy --only functions
    

   Dopo aver eseguito questo comando, l'interfaccia a riga di comando Firebase restituisce l'URL di tutti gli endpoint delle funzioni HTTP. Nel terminale dovresti vedere 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 preoccupartene 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 al progetto", prova a controllare l'aliasing del progetto.

2. Utilizzando l'URL restituito dall'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 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 maiuscolo della stringa.

Dopo aver eseguito il deployment e l'esecuzione delle funzioni, puoi visualizzare i log nella consoleGoogle Cloud. Se devi eliminare 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 il numero minimo e massimo di istanze da eseguire. Per saperne di più su queste opzioni di runtime, consulta Controlla 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 scoprire di più su Cloud Functions, puoi anche procedere nel seguente modo:

• Scopri di più sui casi d'uso di Cloud Functions.
• Prova il codelab Cloud Functions.
• Esamina ed esegui esempi di codice su GitHub