Inizia: scrivi, testa e distribuisci le tue prime funzioni


Per iniziare a utilizzare 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 su Cloud Firestore.
  • Una funzione "rendi maiuscolo" che si attiva su una scrittura 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 attivatori in background possono essere testati approfonditamente 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 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 ed esaminarlo, passa a Revisione del codice di esempio completo .

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, esamina 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 report 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. Una volta completato il processo, verrai indirizzato alla pagina di panoramica del tuo progetto Firebase nella console Firebase.

Configura Node.js e la CLI Firebase

Avrai bisogno di un ambiente Node.js per scrivere funzioni e della CLI Firebase per distribuire funzioni nel runtime Cloud Functions. Per installare Node.js e npm , si consiglia Node Version Manager .

Dopo aver installato Node.js e npm, installa la CLI 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 le autorizzazioni npm . Per aggiornare all'ultima versione di firebase-tools , esegui nuovamente lo stesso comando.

Inizializza il tuo progetto

Quando inizializzi Firebase SDK for Cloud Functions, crei un progetto vuoto contenente le 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 la CLI 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 Iniziare con Cloud Firestore .
  4. Esegui firebase init functions . La CLI richiede di scegliere una codebase esistente o di inizializzarne e denominarne una nuova. Quando hai appena iniziato, è adeguata una singola base di codice nella posizione predefinita; in seguito, man mano che la tua implementazione si espande, potresti voler organizzare le funzioni in codebase .

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

    Per questo tutorial, seleziona JavaScript .

  6. La CLI ti offre la possibilità di installare le dipendenze con npm. È sicuro rifiutare se desideri gestire le dipendenze in un altro modo, tuttavia se rifiuti dovrai eseguire npm install prima di emulare o distribuire le tue funzioni.

Una volta completati correttamente questi comandi, la struttura del progetto avrà il seguente aspetto:

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

La CLI Firebase installa automaticamente i moduli Firebase e Firebase SDK for Cloud Functions Node quando inizializzi il 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 .

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 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 rinviare 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 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 "parametri", caratteri jolly che espongono i dati corrispondenti nel callback.

Cloud Firestore attiva il callback onCreate() ogni volta che vengono aggiunti nuovi messaggi.

Le funzioni guidate dagli eventi come gli eventi Cloud Firestore sono asincrone. La funzione di callback dovrebbe restituire un null , un Object o una Promise . Se non si restituisce nulla, la funzione va in timeout, segnalando un errore, e viene ritentata. Consulta 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 su 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 comportare costi in un ambiente di produzione (ad esempio, un ciclo infinito).

Per emulare le tue funzioni:

  1. Esegui firebase emulators:start e controlla nell'output 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 l'URL nel tuo browser per aprire l'interfaccia utente di Emulator Suite.

  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 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, è possibile modificare 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 l'esecuzione delle funzioni addMessage() e makeUppercase() :

      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 tuo messaggio (se originariamente era "uppercaseme", vedrai "UPPERCASEME").

Distribuire le funzioni in un ambiente di produzione

Una volta che le funzioni funzionano come desiderato nell'emulatore, puoi procedere alla loro distribuzione, test ed esecuzione nell'ambiente di produzione. Tieni presente che per eseguire la distribuzione nell'ambiente runtime Node.js 14 consigliato, il tuo progetto deve rientrare 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, la CLI di Firebase restituisce l'URL per qualsiasi 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 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 in maiuscolo della stringa.

Dopo aver distribuito ed eseguito le funzioni, puoi visualizzare i log nella console Google Cloud . Se devi eliminare funzioni in fase di sviluppo o produzione, utilizza la CLI Firebase.

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

Esaminare il codice di esempio completo

Ecco il file functions/index.js completato contenente le funzioni addMessage() e makeUppercase() . Queste funzioni ti consentono di passare un parametro a un endpoint HTTP che scrive un valore su 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/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

Prossimi passi

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 ulteriori informazioni su Cloud Functions, puoi anche procedere come segue: