Google is committed to advancing racial equity for Black communities. See how.
Questa pagina è stata tradotta dall'API Cloud Translation.
Switch to English

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 funziona 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 in 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 attivatori in background possono essere testati a fondo tramite Firebase Local Emulator Suite . Questo set di strumenti supporta anche i trigger chiamabili Realtime Database, PubSub, Auth e HTTP. Altri tipi di trigger in background come i trigger 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 Rivedi il codice di esempio completo .

Crea un progetto Firebase

  1. Nella console Firebase , fai clic su Aggiungi progetto , quindi seleziona o inserisci un nome per il progetto .

    Se hai un progetto Google Cloud Platform (GCP) esistente, puoi selezionare il progetto dal menu a discesa per aggiungere le risorse Firebase a quel progetto.

  2. (Facoltativo) Se stai creando un nuovo progetto, puoi modificare l' ID progetto .

    Firebase assegna automaticamente un ID univoco al tuo progetto Firebase. Visita Comprendere i progetti Firebase per scoprire come Firebase utilizza l'ID progetto.

  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:

    Quando richiesto, seleziona per utilizzare un account Google Analytics esistente o per creare un nuovo account.
    Se scegli di creare 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 su Aggiungi Firebase , se stai utilizzando un progetto GCP esistente).

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

Configura Node.js e la Firebase CLI

Avrai bisogno di un ambiente Node.js per scrivere funzioni e avrai bisogno della CLI di Firebase per distribuire le funzioni al runtime di Cloud Functions. Per l'installazione di Node.js e npm , si consiglia di utilizzare 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 fallisce, potrebbe essere necessario modificare le autorizzazioni npm . Per aggiornare all'ultima versione di firebase-tools , riesegui lo stesso comando.

Inizializza il tuo progetto

Quando si inizializza Firebase SDK per Cloud Functions, si crea un progetto vuoto contenente dipendenze e un codice di esempio minimo e si sceglie TypeScript o JavaScript per le funzioni di composizione. 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 Guida introduttiva a Cloud Firestore .
  4. Esegui le firebase init functions . Lo strumento ti offre un'opzione per installare le dipendenze con npm. È sicuro rifiutare se si desidera gestire le dipendenze in un altro modo, anche se in caso di npm install sarà necessario eseguire npm install prima di emulare o distribuire le funzioni.
  5. Lo strumento offre due opzioni per il supporto della lingua:

    Per questo tutorial, seleziona JavaScript .

Dopo che questi comandi sono stati completati correttamente, la struttura del progetto avrà questo 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": "10"} . Specifica la versione di Node.js per la scrittura e la distribuzione delle funzioni. Puoi 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 setup triggers.
const functions = require('firebase-functions');

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

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

La CLI di Firebase installa automaticamente i moduli Firebase e Firebase SDK per 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 
// Cloud 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 Cloud Firestore using the Firebase Admin SDK.
  const writeResult = await admin.firestore().collection('messages').add({original: original});
  // Send back a message that we've succesfully written the message
  res.json({result: `Message with ID: ${writeResult.id} added.`});
});

La funzione addMessage() è un endpoint HTTP. Qualsiasi richiesta all'endpoint produce 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 sotto il 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 Cloud 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 Cloud Firestore.
      // Setting an 'uppercase' field in Cloud Firestore document returns a Promise.
      return snap.ref.set({uppercase}, {merge: true});
    });

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.

Parentesi graffe, ad esempio {documentId} "parametri" surround, caratteri jolly che espongono i dati corrispondenti nel callback.

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

Le funzioni guidate dagli eventi come gli eventi di Cloud Firestore sono asincrone. La funzione di callback dovrebbe restituire un null , un oggetto o una promessa . Se non si restituisce nulla, la funzione scade, segnalando un errore e viene ritentata. Vedi Sincronizzazione, Asincronizzazione 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 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 incorrere in 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. Immettere l'URL nel browser per aprire l'interfaccia utente di Emulator Suite.

  2. Controlla l'output degli firebase emulators:start 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 sulla 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 cambiare 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 Log , dovresti vedere nuovi log che indicano che le funzioni addMessage() e makeUppercase() eseguite:

      Funzioni i: inizio dell'esecuzione di "addMessage"

      funzioni i: inizio dell'esecuzione di "makeUppercase"

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

Distribuire le funzioni in un ambiente di produzione

Una volta che le funzioni funzionano come desiderato nell'emulatore, è possibile 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 10 consigliato, il tuo progetto deve essere nel piano di fatturazione con pagamento in base al consumo di Blaze. Vedi i prezzi di Cloud Functions .

Per completare il tutorial, distribuire le funzioni e quindi eseguire 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 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' alias 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 Firebase per Cloud Functions . Se devi eliminare funzioni in fase di sviluppo o produzione, utilizza la CLI di Firebase.

Rivedi il codice di esempio completo

Ecco le functions/index.js completate contenenti 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 inserendo in maiuscolo tutti i caratteri nella stringa.

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

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

// Take the text parameter passed to this HTTP endpoint and insert it into 
// Cloud 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 Cloud Firestore using the Firebase Admin SDK.
  const writeResult = await admin.firestore().collection('messages').add({original: original});
  // Send back a message that we've succesfully 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 Cloud 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 Cloud Firestore.
      // Setting an 'uppercase' field in Cloud Firestore document returns a Promise.
      return snap.ref.set({uppercase}, {merge: true});
    });

Prossimi passi

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

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

Video tutorial

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