Per iniziare: scrivi, testa ed esegui il deployment delle tue prime funzioni


Per iniziare a usare Cloud Functions, prova a seguire questo tutorial, che inizia con le attività di configurazione richieste e si conclude con la creazione, il test e il deployment di due funzioni correlate:

  • Un messaggio di aggiunta funzione che espone un URL che accetta un valore di testo e lo scrive a Cloud Firestore.
  • La formula "make up" (in maiuscolo) funzione che si attiva su una scrittura Cloud Firestore e trasforma il testo in maiuscolo.

Per questo abbiamo scelto Cloud Firestore e funzioni JavaScript attivate da HTTP il campione in parte perché questi fattori scatenanti in background possono essere testati tramite Firebase Local Emulator Suite. Questo set di strumenti supporta anche Realtime Database, Trigger richiamabili HTTP, PubSub e Auth. Altri tipi di trigger in background come Remote Config, TestLab e gli attivatori di 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 compilare, testare e implementare il sample. Se preferisci eseguire il codice e ispezionarlo, passa a Esamina il codice campione 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 relativo il nome del progetto o selezionarlo dal menu a discesa.

    • Per creare un nuovo progetto, inserisci il nome del progetto che ti interessa. Se vuoi, puoi anche modificare l'ID progetto visualizzato sotto il nome del progetto.

  2. Se richiesto, leggi e accetta i Termini di Firebase.

  3. Fai clic su Continua.

  4. (Facoltativo) Configura Google Analytics per il tuo progetto, che ti consente per un'esperienza ottimale con i seguenti prodotti Firebase:

    Seleziona un'opzione esistente Account Google Analytics o creare un nuovo account.

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

  5. Fai clic su Crea progetto (o su Aggiungi Firebase, se utilizzi una progetto Google Cloud esistente).

Firebase esegue automaticamente il provisioning delle risorse per il tuo progetto Firebase. Quando Completata la procedura, verrà visualizzata la pagina Panoramica di Firebase progetto nella console Firebase.

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

Per scrivere le funzioni, hai bisogno di un ambiente Node.js e dell'interfaccia a riga di comando Firebase per eseguire il deployment delle funzioni nel runtime Cloud Functions. Per installare Node.js e npm, Gestore delle versioni dei nodi è consigliato.

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

npm install -g firebase-tools

Questa operazione installa il comando firebase disponibile a livello globale. Se non va a buon fine, potresti dover modificare le autorizzazioni npm. Per eseguire l'aggiornamento alla versione più recente di firebase-tools, esegui nuovamente lo stesso comando.

Inizializza il progetto

Quando inizili l'SDK Firebase 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 del presente documento dovrai inizializzare anche 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 viene chiesto di specificare le regole e i file di indicizzazione di Firestore. Se non hai utilizzato Cloud Firestore in questo progetto, lo farai anche devi selezionare una modalità iniziale e una posizione 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 nominarne uno nuovo. Quando sei solo all'inizio, sia sufficiente un singolo codebase nella posizione predefinita; in seguito, man mano che la tua implementazione si espande, vuoi organizzare le funzioni nei codebase.

  5. L'interfaccia a riga di comando offre due opzioni per il supporto delle lingue:

    Per questo tutorial, seleziona JavaScript.

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

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

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 un'importante chiave: "engines": {"node": "16"}. Questa operazione specifica la tua versione Node.js la scrittura e il deployment delle funzioni. Puoi seleziona altre versioni supportate.

Importa i moduli richiesti e inizializza un'app

Una volta completate le attività di configurazione, puoi apri la directory del codice sorgente e inizia ad aggiungere codice come descritto le sezioni seguenti. Per questo esempio, il progetto deve importare Cloud Functions e moduli SDK Admin che utilizzano il nodo require istruzioni. Aggiungi righe nel seguente modo 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 inizializza un'istanza dell'app admin da cui è possibile apportare modifiche Cloud Firestore. Ovunque sia disponibile il supporto degli SDK amministrativi, così com'è per FCM, Authentication e Firebase Realtime Database, fornisce un un modo efficace per integrare Firebase utilizzando Cloud Functions.

L'interfaccia a riga di comando Firebase automaticamente installa l'SDK Firebase e Firebase per Cloud Functions moduli di nodo al momento dell'inizializzazione del progetto. Per aggiungere librerie di terze parti al tuo progetto, puoi modificare package.json ed eseguire npm install. Per ulteriori informazioni, vedi 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 risultati in stile ExpressJS Richiesta e risposta di oggetti passati onRequest().

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. addMessage() La funzione HTTP passa un valore di testo all'endpoint HTTP e lo inserisce nel 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 rimanere in ascolto. Per motivi di rendimento, devi essere il più specifico possibile.

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

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

Le funzioni basate su eventi, come gli eventi Cloud Firestore, vengono asincrone. La funzione di callback deve restituire un null, un oggetto o una Promessa. Se non restituisci nulla, la funzione scade, segnalando un errore un nuovo tentativo. Vedi Sincronizzazione, Asinc e Promesse.

Emula l'esecuzione delle tue funzioni

La Firebase Local Emulator Suite consente di creare e testare app sul computer locale anziché eseguirne il deployment di un progetto Firebase. È vivamente consigliato eseguire test locali durante lo sviluppo, anche perché riduce il rischio di errori di programmazione 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 l'output dell'URL di Emulator Suite UI. Per impostazione predefinita, localhost:4000, ma potrebbe essere ospitato su un'istanza sulla macchina. Inserisci l'URL nel browser per aprire lo Emulator Suite UI.

  2. Controlla l'output di firebase emulators:start per l'URL della funzione HTTP addMessage(). Sarà simile a: http://localhost:5001/MY_PROJECT/us-central1/addMessage, fatta eccezione per:

    1. Il campo 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 avere il seguente aspetto: http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme. Se vuoi, puoi modificare il messaggio in maiuscolo a un modello per creare un nuovo messaggio email.

  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 vengono visualizzati i nuovi log che indicano che le funzioni addMessage() e makeUppercase() hanno eseguito:

      i functions: Beginning execution of "addMessage"

      i functions: Beginning execution of "makeUppercase"

    2. Nella scheda Firestore dovresti vedere un documento contenente la tua e la versione maiuscola del messaggio (se è originariamente "maiuscole", vedrai "MAIUSCOLE").

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 consigliato, il tuo progetto deve essere nel piano tariffario Blaze. Consulta Prezzi di Cloud Functions.

Per completare il tutorial, esegui il deployment delle funzioni ed 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'interfaccia a riga di comando Firebase restituisce l'URL per qualsiasi Funzione HTTP endpoint. 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, nonché una regione per il traffico HTTP personalizzata. Anche se ora non devi preoccuparti di nulla, alcune richieste HTTP devono specificare una location 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 progetto.

  2. Usando l'output URL addMessage() 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 l'evento di scrittura attiva makeUppercase(), che scrive una lettera maiuscola della stringa.

Dopo aver eseguito il deployment e l'esecuzione delle funzioni, puoi visualizza i log nella console Google Cloud. Se hai bisogno di eliminare funzioni in fase di sviluppo o di produzione, usa l'interfaccia a riga di comando Firebase.

In produzione, potresti voler ottimizzare le prestazioni e il controllo delle funzioni impostando il numero minimo e massimo di istanze da eseguire. Consulta Controllare il comportamento di scalabilità per ulteriori informazioni su queste opzioni di runtime.

Rivedi il codice campione completo

Ecco i campi functions/index.js completati contenenti le funzioni addMessage() e makeUppercase(). Queste funzioni ti consentono di passare a un endpoint HTTP che scrive un valore in Cloud Firestore e che poi lo trasforma utilizzando le maiuscole e minuscole per 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, nonché su come gestire tutti i tipi di eventi supportati da Cloud Functions.

Per scoprire di più su Cloud Functions, potrebbe anche fare quanto segue: