Installare un'estensione Firebase

Puoi installare (e gestire) una qualsiasi delle estensioni Firebase ufficiali utilizzando la console Firebase, l'interfaccia a riga di comando (CLI) di Firebase o un SDK generato automaticamente.

Assicurati di esaminare le differenze nelle azioni supportate per ogni metodo di installazione.


L'installazione tramite un SDK generato automaticamente è una nuova opzione per installare e gestire le estensioni. Con questa opzione, utilizzi la CLI per generare automaticamente un SDK Node per una versione specifica dell'estensione, che puoi importare come dipendenza ordinaria nelle tue Cloud Functions JavaScript o TypeScript.

Questo SDK generato automaticamente contiene:

  • Un'interfaccia che rappresenta i parametri dell'estensione e le dichiarazioni di tipo per la maggior parte dei tipi di parametri non primitivi.
  • Una funzione costruttore che inizializza un'istanza dell'estensione
  • Una classe di estensione che contiene trigger Eventarc per tutti gli eventi emessi dall'estensione.

Una volta generato un SDK di estensione, tutta la configurazione dell'estensione avviene nel codice.

L'utilizzo di questa opzione di installazione può semplificare notevolmente la gestione di più istanze di estensione, in particolare nei progetti che contengono funzioni Cloud definite al di fuori delle estensioni.


Per installare o gestire le estensioni, devi disporre di uno dei seguenti ruoli: Proprietario o Editor oppure Amministratore Firebase.

Per installare un'estensione, il progetto deve essere nel piano Blaze (pagamento a consumo). Sebbene l'installazione di un'estensione non comporti costi, potresti dover pagare per l'utilizzo dei servizi Firebase o Cloud come Cloud Secret Manager, se il tuo utilizzo supera il livello senza costi dei servizi.

Prima di iniziare

  1. Se non l'hai già fatto, aggiungi Firebase al tuo progetto.

  2. Se non l'hai ancora fatto, esegui l'upgrade del progetto al piano Blaze (pagamento a consumo).

  3. Installa o esegui l'aggiornamento all'ultima versione della CLI Firebase.

  4. Prendi nota dell'ID progetto Firebase o dell'alias del progetto configurato in precedenza.

    • ID progetto: esegui firebase projects:list da qualsiasi posizione del computer.
    • Alias progetto: esegui firebase use dalla directory dell'app locale.

Passaggio 1: visualizza informazioni dettagliate su un'estensione

Questo passaggio è facoltativo, ma vivamente consigliato.

Prima di installare un Firebase Extension, ti consigliamo di esaminare le informazioni dettagliate sull'estensione, tra cui:

  • Come funziona l'estensione, eventuali attività di preinstallazione e dettagli sull'estensione
  • Informazioni identificative generali e descrizione
  • Se le attività dell'estensione richiedono un account di fatturazione
  • Servizi Google (API) e ruoli di accesso necessari per il funzionamento
  • Risorse create per l'estensione (ad esempio le funzioni)
  • Descrizioni dei parametri configurabili dall'utente

Per visualizzare le informazioni dettagliate di un'estensione:

  1. Assicurati di aver configurato il tuo ambiente e selezionato un' estensione.

  2. Esegui il comando extension-info da qualsiasi posizione del computer:

    firebase ext:info publisher-id/extension-id

    Gli argomenti publisher-id e extension-id sono obbligatori e sono disponibili nella pagina dei dettagli di preinstallazione dell'estensione.

Passaggio 2: installa un'estensione

Prima dell'installazione, rivedi le specifiche di base dell'estensione (ad esempio API abilitate, risorse create, accesso concesso e così via) e i relativi requisiti di fatturazione.

Prima di continuare, assicurati di aver configurato l'ambiente e di aver selezionato un'estensione.

Inizializzare Cloud Functions for Firebase

Se stai iniziando un nuovo progetto o se il tuo progetto non utilizza già Cloud Functions for Firebase, esegui init functions:

cd your-project
firebase init functions

Scegli TypeScript o JavaScript come linguaggio delle funzioni.

Se il progetto ha già inizializzato Cloud Functions, assicurati di utilizzare la versione 5.1.0 o successive del pacchetto firebase-functions:

cd your-project/functions
npm upgrade --save firebase-functions

Se utilizzi ESLint, potresti anche escludere gli SDK generati dalla tua configurazione (.eslintrc.js):

ignorePatterns: [
  "/generated/**/*", // Ignore generated files.
  // ...
],

Genera un SDK di estensione

Dalla directory Firebase locale, esegui il comando ext:sdk:install.

firebase ext:sdk:install publisher-id/extension-id@version

Ad esempio, per installare la versione 0.1.34 dell'estensione firestore-send-email:

firebase ext:sdk:install firebase/firestore-send-email@0.1.34

publisher-id e extension-id sono obbligatori e si trovano nella pagina dei dettagli di preinstallazione dell'estensione su extensions.dev. La parte @version è facoltativa; se la ometti, lo strumento installa l'ultima versione.

Puoi specificare due opzioni:

  • --force: Esegui tutte le seguenti operazioni senza ulteriore conferma:

    • Genera automaticamente l'SDK anche se ne è già stato generato uno per la stessa estensione e versione.
    • Installa il pacchetto SDK generato automaticamente nel progetto Node di Cloud Functions.

  • --codebase: il nome della codebase a cui aggiungere l'SDK. Se non specificato, il comando aggiunge l'SDK al codebase predefinito, functions.

Questo comando crea un pacchetto Node contenente un SDK generato automaticamente per l'estensione e lo aggiunge a una delle basi di codice Cloud Functions del progetto. Nel codebase predefinito (functions), l'SDK viene salvato nella seguente posizione: 

functions/generated/extensions/publisher-id/extension-id/version

Dopo aver generato l'SDK, il comando ti chiederà se vuoi installare l'SDK anche nel tuo progetto Node di Cloud Functions. Rispondi Sì a questa richiesta.

Configurare le istanze delle estensioni

Per configurare l'estensione, importa l'SDK e, per ogni istanza dell'estensione che vuoi installare, chiama la funzione costruttore, passando un ID istanza univoco per il progetto e i parametri di configurazione richiesti dall'estensione.

  1. Nel codice sorgente di Cloud Functions, importa il costruttore utilizzando l'istruzione stampata dal comando ext:sdk:install.

    TypeScript

    Ad esempio, se hai generato un SDK per l'estensione firestore-send-email, l'istruzione import avrà un aspetto simile al seguente:

    import { firestoreSendEmail } from "@firebase-extensions/firebase-firestore-send-email-sdk";

    Se l'estensione richiede valori segreti come le password, devi utilizzare anche la funzione defineSecret dell'SDK Cloud Functions:

    import { defineSecret } from "firebase-functions/params";

    JavaScript

    Ad esempio, se hai generato un SDK per l'estensione firestore-send-email, l'istruzione require avrà un aspetto simile al seguente:

    const { firestoreSendEmail } = require("@firebase-extensions/firebase-firestore-send-email-sdk");

    Se l'estensione richiede valori segreti come le password, devi utilizzare anche la funzione defineSecret dell'SDK Cloud Functions:

    const { defineSecret } = require('firebase-functions/params');

  2. Per ogni istanza che vuoi configurare, chiama la funzione costruttore ed esporta il risultato.

    Assegna a ogni istanza un ID univoco contenente solo lettere minuscole, numeri e trattini.

    TypeScript

    export const firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", {
    SMTP_CONNECTION_URI: "smtps://username@example.com@smtp.example.com:465",
    SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"),
    MAIL_COLLECTION: "mail",
    DEFAULT_FROM: "ExampleCo <username@example.com>",
    TTL_EXPIRE_VALUE: "1",
    TTL_EXPIRE_TYPE: "day",
});

    JavaScript

    exports.firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", {
    SMTP_CONNECTION_URI: "smtps://username@example.com@smtp.example.com:465",
    SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"),
    MAIL_COLLECTION: "mail",
    DEFAULT_FROM: "ExampleCo <username@example.com>",
    TTL_EXPIRE_VALUE: "1",
    TTL_EXPIRE_TYPE: "day",
});

    Tieni presente che i valori secret devono essere specificati utilizzando la funzione defineSecret.

  3. Poi, per eseguire il deployment delle estensioni che hai configurato, esegui: 

    firebase deploy --only functions --project=projectId-or-alias

    Si applicano tutte le solite opzioni di deployment di Cloud Functions. Ad esempio, per eseguire il deployment di una singola istanza di estensione da un basecode specifica: 

    firebase deploy --only functions:codebase:extension-instance-id --project=projectId-or-alias

Passaggio 3: completa la configurazione post-installazione

Alcune estensioni prevedono passaggi obbligatori o facoltativi da completare prima di poterle utilizzare. Trova queste istruzioni nella pagina dei dettagli post-installazione dell'estensione nella dashboard Extensions della console Firebase (il link specifico alla dashboard viene visualizzato nel terminale dopo l'installazione).

Puoi trovare queste istruzioni anche nel file POSTINSTALL.md incluso nella directory di origine dell'estensione.

Crea risorse Firebase

Se hai configurato l'estensione in modo che utilizzi risorse Firebase (raccolte Cloud Firestore, percorsi Realtime Database, bucket Cloud Storage) che non esistono ancora, creale prima di utilizzare l'estensione.

Crea gestori di eventi Eventarc

Alcune estensioni pubblicano su Eventarc quando si verificano eventi importanti durante l'esecuzione. Se un'estensione pubblica eventi, puoi scrivere funzioni che reagiscono a questi eventi con la tua logica personalizzata. Questo può essere utile, ad esempio, per notificare agli utenti il completamento di attività di lunga durata o per post-elaborare l'output di una funzione di estensione.

Se vuoi definire i gestori per uno qualsiasi degli eventi emessi dall'estensione, puoi farlo utilizzando i metodi di attivazione di ogni istanza:

TypeScript

export const firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });

export const emailErrorHandler = firestoreSendEmail_1.onError((event) => {
  // Handle mail errors.
});

JavaScript

exports.firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });

exports.emailErrorHandler = exports.firestoreSendEmail_1.onError((event) => {
  // Handle mail errors.
});

Devi esportare il gestore eventi insieme all'istanza dell'estensione.

Dopo aver definito un gestore di eventi e ogni volta che ne modifichi uno, esegui nuovamente il deployment dell'estensione e del gestore.

Installare più istanze di estensione

Puoi installare la stessa estensione più di una volta nello stesso progetto. Ogni istanza installata può avere la propria configurazione personalizzata e le proprie risorse di estensione. Identifichi e fai riferimento a ogni istanza installata utilizzando il relativo ID istanza, che è univoco all'interno del progetto.

Chiama la funzione di costruzione dell'SDK generato automaticamente una volta per ogni istanza che vuoi installare e configurare.

Passaggi successivi