Catch up on highlights from Firebase at Google I/O 2023. Learn more

Inizia: scrivi, testa e distribuisci le tue prime funzioni


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

Abbiamo scelto Cloud Firestore e le funzioni JavaScript 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, PubSub, Auth e trigger richiamabili HTTP. Altri tipi di trigger in background come i trigger Remote Config, TestLab e Analytics possono essere tutti testati in modo interattivo utilizzando set di strumenti non descritti in questa pagina.

Le sezioni seguenti di questa esercitazione descrivono in dettaglio i passaggi necessari per compilare, testare e distribuire l'esempio. Se preferisci semplicemente eseguire il codice e ispezionarlo, passa a Review complete sample code .

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 del progetto desiderato. Facoltativamente, puoi anche modificare l'ID progetto visualizzato sotto il nome del progetto.

  2. Se richiesto, rivedi e accetta i termini di Firebase .

  3. Fare clic su Continua .

  4. (Facoltativo) Imposta Google Analytics per il tuo progetto, che ti consente di avere un'esperienza ottimale utilizzando uno dei seguenti prodotti Firebase:

    Seleziona un account Google Analytics esistente o creane uno nuovo.

    Se crei un nuovo account, seleziona la posizione dei rapporti di Analytics , quindi accetta le impostazioni di condivisione dei dati e i termini di Google Analytics per il tuo progetto.

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

Firebase esegue automaticamente il provisioning delle risorse per il tuo progetto Firebase. Al termine del processo, verrai indirizzato alla pagina di panoramica del tuo progetto Firebase nella console Firebase.

Configura Node.js e l'interfaccia a riga di comando di Firebase

Avrai bisogno di un ambiente Node.js per scrivere le funzioni e avrai bisogno dell'interfaccia a riga di comando di Firebase per distribuire le funzioni nel runtime di Cloud Functions. Per l'installazione di Node.js e npm , si consiglia Node Version Manager .

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

npm install -g firebase-tools

Questo installa il comando firebase disponibile a livello globale. Se il comando fallisce, potrebbe essere necessario modificare npm permissions . Per eseguire l'aggiornamento all'ultima versione di firebase-tools , eseguire nuovamente lo stesso comando.

Inizializza il tuo progetto

Quando inizializzi Firebase SDK for Cloud Functions, crei un progetto vuoto contenente dipendenze e codice di esempio minimo e scegli TypeScript o JavaScript per la composizione delle funzioni. Ai fini di questo tutorial, dovrai anche inizializzare Cloud Firestore.

Per inizializzare il tuo progetto:

  1. Esegui firebase login per accedere tramite il browser e autenticare l'interfaccia a riga di comando di Firebase.
  2. Vai alla directory del tuo progetto Firebase.
  3. Esegui firebase init firestore . Per questo tutorial, puoi accettare i valori predefiniti quando ti vengono richieste le regole Firestore e i file di indice. Se non hai ancora utilizzato Cloud Firestore in questo progetto, dovrai anche selezionare una modalità e una posizione di avvio per Firestore come descritto in Introduzione a Cloud Firestore .
  4. Esegui firebase init functions . L'interfaccia a riga di comando richiede di scegliere una codebase esistente o di inizializzarne e nominarne una nuova. Quando hai appena iniziato, una singola base di codice nella posizione predefinita è adeguata; in seguito, man mano che la tua implementazione si espande, potresti voler organizzare le funzioni in codebases .

  5. La CLI offre due opzioni per il supporto linguistico:

    Per questo tutorial, seleziona JavaScript .

  6. La CLI offre un'opzione per installare le dipendenze con npm. È sicuro rifiutare se desideri gestire le dipendenze in un altro modo, anche se se rifiuti dovrai eseguire npm install prima di emulare o distribuire le tue funzioni.

Dopo che questi comandi sono stati completati correttamente, la struttura del progetto è simile a questa:

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

Il file package.json creato durante l'inizializzazione contiene una chiave importante: "engines": {"node": "16"} . Questo specifica la tua versione di Node.js per la scrittura e la distribuzione delle funzioni. È possibile selezionare altre versioni supportate .

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 tuo progetto deve importare i moduli Cloud Functions e Admin SDK utilizzando le istruzioni Node require . Aggiungi righe come le seguenti al tuo file index.js :

// The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
const functions = require("firebase-functions");

// The Firebase Admin SDK to access Firestore.
const admin = require("firebase-admin");
admin.initializeApp();
index.js

Queste righe caricano i moduli firebase-functions e firebase-admin e inizializzano un'istanza dell'app admin da cui è possibile apportare modifiche a Cloud Firestore. Ovunque sia disponibile il supporto Admin SDK , come per FCM, Authentication e Firebase Realtime Database, fornisce un modo efficace per integrare Firebase utilizzando Cloud Functions.

L'interfaccia a riga di comando di Firebase installa automaticamente i moduli Firebase e Firebase SDK for Cloud Functions Node quando inizializzi il tuo progetto. Per aggiungere librerie di terze parti al tuo progetto, puoi modificare package.json ed eseguire npm install . Per ulteriori informazioni, consulta Gestire le dipendenze .

Aggiungere la funzione addMessage()

Per la funzione addMessage() , aggiungi queste righe a index.js :

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addMessage = functions.https.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 admin
    .firestore()
    .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

La funzione addMessage() è un endpoint HTTP. Qualsiasi richiesta all'endpoint risulta in oggetti Request e Response in stile ExpressJS passati al callback onRequest() .

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

Aggiungere la funzione makeUppercase()

Per la funzione makeUppercase() , aggiungi queste righe a index.js :

// Listens for new messages added to /messages/:documentId/original and creates an
// uppercase version of the message to /messages/:documentId/uppercase
exports.makeUppercase = functions.firestore
  .document("/messages/{documentId}")
  .onCreate((snap, context) => {
    // Grab the current value of what was written to Firestore.
    const original = snap.data().original;

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

    const uppercase = original.toUpperCase();

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

La funzione makeUppercase() viene eseguita quando viene scritto su Cloud Firestore. La funzione ref.set definisce il documento su cui ascoltare. Per motivi di prestazioni, dovresti essere il più specifico possibile.

Le parentesi graffe, ad esempio {documentId} racchiudono i "parametri", i caratteri jolly che espongono i dati corrispondenti nel callback.

Cloud Firestore attiva la richiamata onCreate() ogni volta che vengono aggiunti nuovi messaggi.

Le funzioni basate su eventi come gli eventi di Cloud Firestore sono asincrone. La funzione di callback deve restituire null , Object o Promise . Se non si restituisce nulla, la funzione va in timeout, segnalando un errore e viene ritentata. Consulta Sync, Async e Promises .

Emula l'esecuzione delle tue funzioni

Firebase Local Emulator Suite ti consente di creare e testare app sulla tua macchina locale invece di distribuirle a 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 ciclo infinito).

Per emulare le tue funzioni:

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

  2. Controlla l'output degli firebase emulators:start per l'URL della funzione HTTP addMessage() . Sembrerà simile a http://localhost:5001/MY_PROJECT/us-central1/addMessage , tranne per il fatto che:

    1. MY_PROJECT verrà sostituito con il tuo 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 essere simile a: 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 nel tuo browser.

  5. Visualizza gli effetti delle funzioni nell'interfaccia utente di Emulator Suite:

    1. Nella scheda Registri , dovresti vedere nuovi registri che indicano che le funzioni addMessage() e makeUppercase() sono state eseguite:

      i functions: Beginning execution of "addMessage"

      i functions: Beginning execution of "makeUppercase"

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

Distribuire le funzioni in un ambiente di produzione

Una volta che le tue funzioni funzionano come desiderato nell'emulatore, puoi procedere alla distribuzione, al test e all'esecuzione nell'ambiente di produzione. Tieni presente che per eseguire il deployment nell'ambiente di runtime Node.js 14 consigliato, il tuo progetto deve essere nel piano tariffario di Blaze . Consulta i prezzi di Cloud Functions .

Per completare il tutorial, distribuisci le tue funzioni e quindi esegui addMessage() per attivare makeUppercase() .

  1. Esegui questo comando per distribuire le tue funzioni:

     firebase deploy --only functions

    Dopo aver eseguito questo comando, l'interfaccia a riga di comando di Firebase restituisce l'URL per tutti gli endpoint della funzione HTTP. Nel tuo terminale, dovresti vedere una riga come la seguente:

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

    L'URL contiene l'ID del progetto e una regione per la funzione HTTP. Sebbene non sia necessario preoccuparsene ora, alcune funzioni HTTP di produzione dovrebbero specificare una posizione 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 tuo progetto .

  2. Utilizzando l'output dell'URL addMessage() dalla CLI, aggiungi un parametro di query di testo 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 makeUppercase() , che scrive una versione maiuscola della stringa.

Dopo aver distribuito ed eseguito le funzioni, puoi visualizzare i log in Google Cloud Console . Se devi eliminare funzioni in fase di sviluppo o produzione, utilizza l'interfaccia a riga di comando di 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 ulteriori informazioni su queste opzioni di runtime, consulta Comportamento del ridimensionamento dei controlli .

Esaminare il codice di esempio completo

Ecco le functions/index.js completate contenenti le funzioni addMessage() e makeUppercase() . Queste funzioni ti consentono di passare un parametro a un endpoint HTTP che scrive un valore in Cloud Firestore e poi lo trasforma trasformando in maiuscolo tutti i caratteri nella stringa.

// The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
const functions = require("firebase-functions");

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

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addMessage = functions.https.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 admin
    .firestore()
    .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 creates an
// uppercase version of the message to /messages/:documentId/uppercase
exports.makeUppercase = functions.firestore
  .document("/messages/{documentId}")
  .onCreate((snap, context) => {
    // Grab the current value of what was written to Firestore.
    const original = snap.data().original;

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

    const uppercase = original.toUpperCase();

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

Prossimi passi

In questa documentazione, puoi ottenere ulteriori informazioni 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 procedere come segue: