Installare un'estensione Firebase

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

Assicurati di esaminare le differenze tra le azioni supportate per ciascun metodo di installazione.


L'installazione utilizzando 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 funzioni Cloud 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 di costruttore che inizializza un'istanza dell'estensione
  • Un'estensione di classe che contiene gli attivatori Eventarc per tutti gli eventi emessi dall'estensione.

Dopo aver 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 estensioni, 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 o Amministratore Firebase.

Per installare un'estensione, il progetto deve essere nel piano Blaze (pagamento a consumo). Sebbene l'installazione di un'estensione non sia a pagamento, ti potrebbe essere addebitato 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 lo 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 alla versione più recente dell'interfaccia a riga di comando Firebase.

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

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

Passaggio 1: visualizza le 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 generali di identificazione e descrizione
  • Indica 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 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 della preinstallazione dell'estensione.

Passaggio 2: installa un'estensione

Prima dell'installazione, esamina 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 per Firebase, esegui init functions:

cd your-project
firebase init functions

Scegli TypeScript o JavaScript come linguaggio delle funzioni.

Se nel progetto sono già state inizializzate le funzioni Cloud, 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, ti consigliamo di escludere anche gli SDK generati dalla configurazione (.eslintrc.js):

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

Generare 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 sono disponibili nella pagina dei dettagli della preinstallazione dell'estensione su extensions.dev. La parte @version è facoltativa; se la ometti, lo strumento installerà la versione più recente.

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 base di codice a cui aggiungere l'SDK. Se non specificato, il comando aggiunge l'SDK al codice di base 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 di Cloud Functions del progetto. Nel codice di base 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 installarlo anche nel progetto Node di Cloud Functions. Rispondi Sì a questa richiesta.

Configura le istanze dell'estensione

Per configurare l'estensione, importa l'SDK e, per ogni istanza dell'estensione che vuoi installare, chiama la funzione di costruttore, passando un ID istanza univoco del 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, la dichiarazione import avrà il seguente aspetto:

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

    Se l'estensione richiede valori segreti come le password, hai bisogno anche della 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, la dichiarazione require avrà il seguente aspetto:

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

    Se l'estensione richiede valori segreti come le password, hai bisogno anche della funzione defineSecret dell'SDK Cloud Functions:

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

  2. Per ogni istanza da configurare, chiama la funzione del 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 dei secret devono essere specificati utilizzando la funzione defineSecret.

  3. Per eseguire il deployment delle estensioni configurate, esegui: 

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

    Si applicano tutte le opzioni di implementazione di Cloud Functions. Ad esempio, per eseguire il deployment di una singola istanza dell'estensione da un codebase specifico: 

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

Passaggio 3: completa la configurazione post-installazione

Per alcune estensioni devi completare passaggi obbligatori o facoltativi prima di poterle utilizzare. Trova queste istruzioni nella pagina dei dettagli post-installazione dell'estensione nella dashboard di 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.

Creare risorse Firebase

Se hai configurato l'estensione in modo che utilizzi risorse Firebase (Cloud Firestorecollezioni, Realtime Databasepercorsi, Cloud Storagebucket) che non esistono già, creale prima di utilizzare l'estensione.

Crea gestori di eventi Eventarc

Alcune estensioni pubblicano in 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 informare gli utenti al termine di attività che richiedono molto tempo o per eseguire il post-trattamento dell'output di una funzione di estensione.

Se vuoi definire gestori per uno 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 eventi e ogni volta che apporti modifiche a uno, esegui il redeployment sia dell'estensione sia del gestore.

Installare più istanze di estensioni

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. Identifica e fai riferimento a ogni istanza installata utilizzando il suo ID istanza, che è univoco all'interno del progetto.

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

Passaggi successivi