Join us in person and online for Firebase Summit on October 18, 2022. Learn how Firebase can help you accelerate app development, release your app with confidence, and scale with ease. Register now

Inizia: scrivi, testa e distribuisci le tue prime funzioni

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

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:

  • addMessage() , che espone un URL che accetta un valore di testo e lo scrive su Cloud Firestore.
  • makeUppercase() , che attiva la scrittura su 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 i trigger richiamabili Realtime Database, PubSub, Auth e HTTP. Altri tipi di trigger in background come Remote Config, TestLab e Analytics possono essere 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 creare, 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. Puoi anche modificare facoltativamente 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) Configura 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 crea un nuovo account.

    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 effettua 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 la CLI di Firebase

Avrai bisogno di un ambiente Node.js per scrivere funzioni e avrai bisogno della CLI Firebase per distribuire le funzioni al 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 Firebase CLI 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 non riesce, potrebbe essere necessario modificare le autorizzazioni npm . Per eseguire l'aggiornamento all'ultima versione di firebase-tools , esegui nuovamente lo stesso comando.

Inizializza il tuo progetto

Quando inizializzi Firebase SDK per Cloud Functions, crei un progetto vuoto contenente dipendenze e un codice di esempio minimo e scegli TypeScript o JavaScript per comporre le 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 lo strumento Firebase.
  2. Vai alla directory del tuo progetto Firebase.
  3. Esegui firebase init firestore . Per questo tutorial, puoi accettare i valori predefiniti quando richiesto per le regole Firestore e i file di indice. Se non hai ancora utilizzato Cloud Firestore in questo progetto, dovrai anche selezionare una modalità di avvio e una posizione per Firestore come descritto in Introduzione a Cloud Firestore .
  4. Esegui firebase init functions . Lo strumento offre un'opzione per installare le dipendenze con npm. È sicuro rifiutare se vuoi gestire le dipendenze in un altro modo, anche se se rifiuti dovrai eseguire npm install prima di emulare o distribuire le tue funzioni.
  5. Lo strumento offre due opzioni per il supporto della lingua:

    Per questo tutorial, seleziona JavaScript .

Dopo che questi comandi sono stati completati con successo, la struttura del tuo progetto sarà 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": "10"} . Questo specifica la tua versione di Node.js per la scrittura e la distribuzione di funzioni. È possibile selezionare altre versioni supportate .

Importa i moduli richiesti e inizializza un'app

Dopo aver completato le attività di configurazione, è possibile 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();

Queste righe caricano le firebase-functions firebase e i moduli firebase-admin e inizializzano un'istanza dell'app di 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 potente 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 si inizializza il progetto. Per aggiungere librerie di terze parti al tuo progetto, puoi modificare package.json ed eseguire npm install . Per ulteriori informazioni, vedere Gestire le dipendenze .

Aggiungi 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.`});
});

La funzione addMessage() è un endpoint HTTP. Qualsiasi richiesta all'endpoint genera 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 posticipare 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 .

Aggiungi 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});
    });

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

Parentesi graffe, ad esempio {documentId} , racchiudono "parametri", caratteri jolly che espongono i dati corrispondenti nella richiamata.

Cloud Firestore attiva il callback onWrite() ogni volta che i dati vengono scritti o aggiornati sul documento specificato.

Le funzioni basate su eventi come gli eventi di Cloud Firestore sono asincrone. La funzione di callback dovrebbe restituire un null , un Object o un Promise . Se non si restituisce nulla, la funzione va in timeout, segnalando un errore, e viene riprovata. Vedere Sincronizzazione, Asincrono e Promesse .

Emula l'esecuzione delle tue funzioni

Firebase Local Emulator Suite ti consente di creare e testare app sul tuo computer locale invece di distribuirle in un progetto Firebase. Si consiglia vivamente di eseguire test locali durante lo sviluppo, 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 sul tuo computer. Inserisci quell'URL nel tuo browser per aprire l'interfaccia utente di Emulator Suite.

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

    1. MY_PROJECT verrà sostituito con il tuo ID progetto.
    2. La porta potrebbe essere diversa sul tuo computer 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 cambiare il messaggio "maiuscolo" 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 Log , dovresti vedere nuovi log che indicano che le funzioni addMessage() e makeUppercase() sono state eseguite:

      i funzioni: Inizio dell'esecuzione di "addMessage"

      i functions: Inizio dell'esecuzione di "makeUppercase"

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

Distribuire funzioni in un ambiente di produzione

Una volta che le funzioni funzionano come desiderato nell'emulatore, puoi procedere alla distribuzione, al test e all'esecuzione nell'ambiente di produzione. Tieni presente che per eseguire la distribuzione nell'ambiente di runtime Node.js 14 consigliato, il tuo progetto deve essere nel piano tariffario 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 della riga di comando di Firebase restituisce l'URL per qualsiasi endpoint della funzione HTTP. Nel tuo terminale, dovresti vedere una linea come la 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 preoccupartene 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' alias del tuo progetto .

  2. Usando l'URL addMessage() emesso 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 è necessario eliminare funzioni in fase di sviluppo o produzione, utilizzare 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. Vedere Controllo del comportamento di ridimensionamento per ulteriori informazioni su queste opzioni di runtime.

Esamina il codice di esempio completo

Ecco il functions/index.js completato contenente le funzioni addMessage() e makeUppercase() . Queste funzioni consentono di passare un parametro a un endpoint HTTP che scrive un valore in Cloud Firestore e quindi lo trasforma mettendo 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});
    });

Prossimi passi

In questa documentazione puoi trovare maggiori informazioni sui concetti generali per Cloud Functions, nonché guide per la scrittura di funzioni per gestire i tipi di eventi supportati da Cloud Functions.

Per saperne di più su Cloud Functions, puoi anche fare quanto segue:

Videotutorial

Puoi saperne di più sulle Funzioni Cloud guardando i tutorial video. In questo video troverai una guida dettagliata su come iniziare a utilizzare Cloud Functions, inclusi Node.js e la configurazione della CLI.