Join us for Firebase Summit on November 10, 2021. Tune in to learn how Firebase can help you accelerate app development, release with confidence, and scale with ease. Register

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 passa attraverso la creazione, il test e l'implementazione di due funzioni correlate:

  • addMessage() , che espone un URL che accetta un valore di testo e lo scrive a Cloud FireStore.
  • makeUppercase() , che innesca su Cloud FireStore scrittura e trasforma il testo in lettere maiuscole.

Abbiamo scelto cloud FireStore e funzioni JavaScript HTTP-triggered per questo campione in parte perché questi trigger di fondo possono essere testati attraverso la Firebase locale emulatore Suite . Questo set di strumenti supporta anche Realtime Database, PubSub, Auth e trigger richiamabili HTTP. Altri tipi di sfondo trigger come Configurazione remota, TestLab e trigger Analytics possono essere testati in modo interattivo usando set di strumenti non descritte in questa pagina.

Le sezioni seguenti di questa esercitazione descrivono in dettaglio i passaggi necessari per compilare, testare e distribuire l'esempio. Se si preferisce basta eseguire il codice e ispezionarlo, salto per la revisione del codice di esempio completo .

Crea un progetto Firebase

  1. Nella console Firebase , scegliere Aggiungi progetto.

    • Per aggiungere le risorse Firebase ad un progetto di Google Cloud esistente, inserire il nome del progetto o selezionarlo 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, rivedere e accettare i termini Firebase .

  3. Fare clic su Continua.

  4. (Opzionale) Impostazione di Google Analytics per il progetto, che vi permette di avere un'esperienza ottimale utilizzando uno dei seguenti prodotti Firebase:

    O selezionare un esistente account Google Analytics o per creare un nuovo account.

    Se si crea un nuovo account, selezionare le Analytics posizione di segnalazione , quindi accettare le impostazioni di condivisione dei dati e condizioni di Google Analytics per il vostro progetto.

  5. Fare clic su Crea progetto (o Aggiungi Firebase, se si sta utilizzando un progetto Google Cloud esistente).

Firebase fornisce automaticamente le risorse per il tuo progetto Firebase. Al termine del processo, verrai indirizzato alla pagina di panoramica per il tuo progetto Firebase nella console Firebase.

Configura Node.js e Firebase CLI

Avrete bisogno di un Node.js ambiente a funzioni di scrittura, e avrete bisogno la Firebase CLI per le funzioni di distribuzione su funzioni cloud runtime. Per l'installazione Node.js e NPM , Node Manager versione è raccomandata.

Una volta che avete Node.js e NPM installato, installare il Firebase CLI tramite il 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 aggiornare alla versione più recente di firebase-tools , eseguire nuovamente lo stesso comando.

Inizializza il tuo progetto

Quando inizializzi Firebase SDK for Cloud Functions, crei un progetto vuoto contenente dipendenze e codice di esempio minimo e scegli TypeScript o JavaScript per la composizione delle funzioni. Ai fini di questo tutorial, dovrai anche inizializzare Cloud Firestore.

Per inizializzare il tuo progetto:

  1. Eseguire firebase login effettuare il login 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 ti vengono richieste le regole Firestore e i file di indice. Se non avete ancora utilizzato cloud Firestore in questo progetto, avrete anche bisogno di selezionare una modalità di partenza e un percorso per Firestore come descritto in Inizia con Cloud Firestore .
  4. Esegui firebase init functions . Lo strumento offre un'opzione per installare le dipendenze con npm. E 'sicuro di rifiutare se si desidera gestire le dipendenze in un altro modo, anche se si fa declinare sarà necessario eseguire npm install prima di emulare o distribuzione delle funzioni.
  5. Lo strumento offre due opzioni per il supporto linguistico:

    Per questo tutorial, selezionare JavaScript.

Dopo che questi comandi sono stati completati con successo, la struttura del tuo progetto è 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 package.json file 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 progetto deve importare le funzioni cloud e moduli Admin SDK utilizzando Nodo require dichiarazioni. Aggiungere le linee come la seguente al index.js del file:

// 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 linee caricare le firebase-functions e firebase-admin moduli, e inizializzare un admin istanza dell'applicazione da cui cambiamenti cloud Firestore possono essere fatte. Ovunque Admin SDK supporto è disponibile, come lo è per FCM, l'autenticazione, e Firebase in tempo reale del database, fornisce un potente strumento per integrare Firebase utilizzando funzioni cloud.

La Firebase CLI installa automaticamente i moduli Firebase e Firebase SDK for Cloud Functions Node quando inizializzi il progetto. Per aggiungere le librerie 3a parte al progetto, è possibile modificare package.json ed eseguire npm install . Per ulteriori informazioni, vedere Dipendenze Maniglia .

Aggiungere addMessage() funzione

Per addMessage() la funzione, aggiungere queste righe al 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.`});
});

addMessage() funzione è un endpoint HTTP. Qualsiasi richiesta ai risultati degli endpoint in ExpressJS stile Richiesta e risposta oggetti passato al onRequest() callback.

Funzioni di HTTP sono sincroni (simile a funzioni richiamabili ), così si dovrebbe inviare una risposta nel più breve tempo possibile e rinviare attività utilizzando cloud Firestore. addMessage() HTTP funzione passa un valore di testo per l'HTTP endpoint e l'inserisce nel database nel percorso /messages/:documentId/original .

Aggiungere il makeUppercase() funzione

Per la makeUppercase() la funzione, aggiungere queste righe al 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});
    });

I makeUppercase() esegue la funzione quando cloud FireStore viene scritto. La ref.set funzione definisce il documento per l'ascolto su. Per motivi di prestazioni, dovresti essere il più specifico possibile.

Bretelle, ad esempio {documentId} -surround "parametri", i caratteri jolly che espongono i loro dati appaiati nel callback.

Nuvola Firestore innesca onWrite() richiamata ogni volta che i dati vengono scritti o aggiornati sul documento dato.

Le funzioni basate sugli eventi come gli eventi di Cloud Firestore sono asincrone. La funzione di callback deve restituire un null , un oggetto o una promessa . Se non si restituisce nulla, la funzione va in timeout, segnalando un errore, e viene ritentata. Vedere Sync, Async e promesse .

Emula l'esecuzione delle tue funzioni

Il Firebase locale emulatore Suite consente di creare applicazioni di test e sul computer locale invece di distribuire ad 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. Eseguire firebase emulators:start e controllare l'uscita per l'URL del Emulator Suite UI. Il valore predefinito è localhost: 4000 , ma possono essere ospitati su una porta diversa sulla vostra macchina. Inserisci quell'URL nel tuo browser per aprire l'interfaccia utente di Emulator Suite.

  2. Controllare l'uscita dei firebase emulators:start il comando per l'URL della funzione HTTP addMessage() . Essa sarà simile a http://localhost:5001/MY_PROJECT/us-central1/addMessage , salvo che:

    1. MY_PROJECT sarà sostituito con il tuo ID progetto.
    2. La porta potrebbe essere diversa sul tuo computer locale.
  3. Aggiungere la stringa di query ?text=uppercaseme alla fine dell'URL della funzione. Questo dovrebbe essere simile a: http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme . Facoltativamente, puoi modificare il messaggio "maiuscolo" in un messaggio personalizzato.

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

  5. Visualizza gli effetti delle funzioni nell'interfaccia utente di Emulator Suite:

    1. Nella scheda Registri, si dovrebbe vedere nuovi registri indicare che le funzioni addMessage() e makeUppercase() Ran:

      funzioni i: inizio dell'esecuzione di "addMessage"

      funzioni i: inizio dell'esecuzione di "makeUppercase"

    2. Nella scheda FireStore, si dovrebbe vedere un documento contenente il messaggio originale così come la versione in maiuscolo del messaggio (se era in origine "uppercaseme", vedrete "UPPERCASEME").

Distribuire le 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. Tenete a mente che per la distribuzione su ambiente consigliato Node.js 14 runtime, il progetto deve essere sul piano tariffario Blaze . Vedere cloud funzioni di pricing .

Per completare il tutorial, implementare le funzioni e quindi eseguire addMessage() per innescare 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 riga 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 c'è bisogno di preoccuparsi ora, alcune funzioni di produzione HTTP dovrebbero specificare un percorso per ridurre al minimo la latenza di rete.

    Se si verificano errori di accesso come ad esempio "in grado di autorizzare l'accesso al progetto", provare a controllare il vostro aliasing del progetto .

  2. Utilizzando addMessage() in uscita URL dalla CLI, aggiungere un parametro di query di testo, e aprirlo 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 fa scattare scrittura makeUppercase() , che scrive una versione maiuscola della stringa.

Dopo la distribuzione e l'esecuzione di funzioni, è possibile visualizzare i registri nella console Firebase per le funzioni cloud . Se avete bisogno di eliminare le funzioni in fase di sviluppo o di produzione, utilizzare la Firebase CLI.

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

Rivedi il codice di esempio completo

Ecco le completati functions/index.js contenenti 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 inserendo tutte le lettere maiuscole 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, è possibile trovare ulteriori informazioni sui concetti generali per le funzioni cloud così come guide per le funzioni di scrittura per gestire i tipi di evento supportati da funzioni cloud.

Per saperne di più su Cloud Functions, puoi 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.