Inizia: scrivi, testa ed esegui il deployment delle tue prime funzioni (1ª gen.)

Per iniziare a utilizzare Cloud Functions, prova a seguire questo tutorial, che inizia con le attività di configurazione richieste e spiega come creare, testare, ed eseguire 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.

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, i trigger richiamabili HTTP, di autenticazione e Pub/Sub. Altri tipi di trigger in background come Remote Config, Test Lab e Analytics 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. Se preferisci semplicemente eseguire il codice ed esaminarlo, vai a Esamina il codice campione completo.

Crea un progetto Firebase

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

Per scrivere le funzioni, ti servirà un ambiente Node.js, e per eseguirne il deployment nel runtime Cloud Functions, ti servirà l'interfaccia a riga di comando Firebase. Per l'installazione di Node.js e npm, è consigliabile utilizzare Node Version Manager.

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.

Inizializza il progetto

Quando inizializzi Firebase SDK per Cloud Functions, crei un progetto vuoto contenente dipendenze e un codice campione minimo e scegli 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 la Firebase CLI.

2. Vai alla directory del progetto Firebase.

3. 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 Inizia a utilizzare Cloud Firestore.

4. 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 servizio, una singola codebase nella località predefinita è sufficiente; in seguito, man mano che l'implementazione si espande, potresti voler organizzare le funzioni nelle codebase.

5. L'interfaccia a riga di comando offre le seguenti opzioni per il supporto linguistico:

   • JavaScript
   • Python
   • TypeScript Per saperne di più, consulta Scrivi funzioni con TypeScript.

   Per questo tutorial, seleziona JavaScript.

6. L'interfaccia a riga di comando offre la possibilità di installare le dipendenze con npm. Puoi rifiutare in sicurezza se vuoi gestire le dipendenze in un altro modo, anche se in questo caso dovrai eseguire npm install prima di emulare o eseguire il deployment delle funzioni.

Al termine di questi comandi, la struttura del progetto sarà la 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

Il file package.json creato durante l'inizializzazione contiene una chiave importante: "engines": {"node": "16"}. Questa specifica la versione di Node.js per la scrittura e il deployment delle funzioni. Puoi 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 progetto deve importare i Cloud Functions e i moduli dell'SDK Admin utilizzando lerequire istruzioni di Node. Aggiungi righe come le seguenti al file index.js:

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

// 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. Laddove è 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 Node di Firebase e dell'Firebase SDK per Cloud Functions quando inizializzi il progetto. Per aggiungere librerie di terze parti al progetto, puoi modificare package.json ed eseguire npm install. Per saperne di più, consulta Gestisci 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.` });
});
index.js

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

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 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 });
  });
index.js

La funzione makeUppercase() viene eseguita quando viene scritto in Cloud Firestore. La funzione ref.set definisce 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 onCreate() callback ogni volta che vengono aggiunti nuovi messaggi.

Le funzioni basate su eventi, come gli eventi Cloud Firestore, sono asincrone. La funzione di callback deve restituire un valore null, un oggetto, o una promessa. Se non restituisci nulla, la funzione va in timeout, segnala un errore e viene ritentata. Consulta Sincronizzazione, asincronizzazione e promesse.

Emula 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 è vivamente consigliato, in parte perché riduce il rischio di errori di codifica che potrebbero comportare costi in un ambiente di produzione (ad esempio, un loop infinito).

Per emulare le funzioni:

1. 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.

2. Controlla l'output del comando firebase emulators:start per l'URL della funzione HTTP addMessage(). 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.

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 messaggio.

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

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

   1. Nella scheda Log dovresti vedere nuovi log 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 messaggio originale e la versione in maiuscolo del messaggio (se originariamente 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 nell'ambiente di runtime Node.js 14, il progetto deve essere incluso nel piano tariffario Blaze. Consulta i prezzi Cloud Functions.

Per completare il tutorial, esegui il deployment delle funzioni, quindi esegui addMessage() per attivare makeUppercase().

1. 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 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 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.

2. Utilizzando l'URL addMessage() 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 Firebase console nella località del database in cui è memorizzata la stringa di testo. Questo evento di scrittura attiva makeUppercase(), 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 saperne di più su queste opzioni di runtime, consulta Controlla il comportamento di scalabilità.

Esamina il codice campione completo

Ecco il file functions/index.js completo contenente le funzioni addMessage() e makeUppercase(). Queste funzioni ti consentono di passare un parametro a un endpoint HTTP che scrive un valore in Cloud Firestoree poi lo trasforma mettendo in maiuscolo tutti i caratteri della stringa.

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

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

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:

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