Installer une extension Firebase

Vous pouvez installer (et gérer) n'importe quelle extension Firebase officielle à l'aide de la console Firebase, de la Firebase CLI (interface de ligne de commande) ou d'un SDK généré automatiquement.

Veillez à consulter les différences entre les actions compatibles pour chaque méthode d'installation.


L'installation à l'aide d'un SDK généré automatiquement est une nouvelle option pour installer et gérer les extensions. Avec cette option, vous utilisez la CLI pour générer automatiquement un SDK Node pour une version d'extension spécifique, que vous pouvez importer en tant que dépendance ordinaire dans vos fonctions Cloud JavaScript ou TypeScript.

Ce SDK généré automatiquement contient :

  • Interface représentant les paramètres de l'extension et les déclarations de type pour la plupart des types de paramètres non primitifs.
  • Fonction de constructeur qui initialise une instance de l'extension
  • Classe d'extension contenant les déclencheurs Eventarc pour tous les événements émis par l'extension.

Une fois que vous avez généré un SDK d'extension, toute la configuration de l'extension se fait dans le code.

Cette option d'installation peut simplifier considérablement la gestion de plusieurs instances d'extension, en particulier dans les projets qui contiennent des fonctions Cloud définies en dehors des extensions.


Pour installer ou gérer des extensions, vous devez disposer de l'un des rôles suivants : Propriétaire ou Éditeur ou Administrateur Firebase.

Pour installer une extension, votre projet doit être associé à la formule Blaze (avec paiement à l'usage). Bien que l'installation d'une extension soit sans frais, vous pouvez être facturé pour votre utilisation des services Firebase ou des services Cloud tels que Cloud Secret Manager, si votre utilisation dépasse le niveau sans frais des services.

Avant de commencer

  1. Si ce n'est pas déjà fait, ajoutez Firebase à votre projet.

  2. Si ce n'est pas déjà fait, passez votre projet au forfait Blaze (paiement à l'usage).

  3. Installez la dernière version de la CLI Firebase ou appliquez la mise à jour correspondante.

  4. Notez l'ID de votre projet Firebase ou l'alias de projet configuré précédemment.

    • ID du projet : exécutez firebase projects:list depuis n'importe quel emplacement de votre ordinateur.
    • Alias du projet : exécutez firebase use à partir du répertoire de votre application locale.

Étape 1 : Afficher des informations détaillées sur une extension

Cette étape est facultative, mais vivement recommandée.

Avant d'installer un Firebase Extension, nous vous recommandons de consulter des informations détaillées sur l'extension, y compris :

  • Fonctionnement de l'extension, tâches de pré-installation et informations la concernant
  • Informations générales d'identification et description
  • Indique si les tâches de l'extension nécessitent un compte de facturation.
  • Services Google (API) et rôles d'accès requis pour le fonctionnement
  • Ressources créées pour l'extension (comme les fonctions)
  • Descriptions des paramètres configurables par l'utilisateur

Pour afficher des informations détaillées sur une extension :

  1. Assurez-vous d'avoir configuré votre environnement et sélectionné une extension.

  2. Exécutez la commande extension-info depuis n'importe quel emplacement de votre ordinateur :

    firebase ext:info publisher-id/extension-id

    Les arguments publisher-id et extension-id sont obligatoires et sont disponibles sur la page des détails de préinstallation de l'extension.

Étape 2 : Installez une extension

Avant l'installation, examinez les spécifications de base de l'extension (telles que les API activées, les ressources créées, les accès accordés, etc.) et ses exigences de facturation.

Avant de continuer, assurez-vous d'avoir configuré votre environnement et sélectionné une extension.

Initialiser Cloud Functions for Firebase

Si vous démarrez un nouveau projet ou si votre projet n'utilise pas encore Cloud Functions for Firebase, exécutez init functions :

cd your-project
firebase init functions

Choisissez TypeScript ou JavaScript comme langage pour vos fonctions.

Si Cloud Functions est déjà initialisé dans votre projet, assurez-vous d'utiliser la version 5.1.0 ou ultérieure du package firebase-functions :

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

Si vous utilisez ESLint, vous pouvez également exclure les SDK générés de votre configuration (.eslintrc.js) :

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

Générer un SDK d'extension

Depuis votre répertoire Firebase local, exécutez la commande ext:sdk:install.

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

Par exemple, pour installer la version 0.1.34 de l'extension firestore-send-email :

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

Les publisher-id et extension-id sont obligatoires et se trouvent sur la page des détails de préinstallation de l'extension sur extensions.dev. La partie @version est facultative. Si vous l'omettez, l'outil installe la dernière version.

Vous pouvez spécifier deux options :

  • --force : effectuez toutes les actions suivantes sans autre confirmation :

    • Génère automatiquement le SDK, même si un SDK a déjà été généré pour la même extension et la même version.
    • Installez le package SDK généré automatiquement dans le projet Node de Cloud Functions.

  • --codebase : nom de la codebase à laquelle ajouter le SDK. Si aucune n'est spécifiée, la commande ajoute le SDK à la codebase par défaut, functions.

Cette commande crée un package Node contenant un SDK généré automatiquement pour l'extension et l'ajoute à l'une des bases de code Cloud Functions de votre projet. Dans la codebase par défaut (functions), le SDK est enregistré à l'emplacement suivant : 

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

Après avoir généré le SDK, la commande vous demandera si vous souhaitez également l'installer dans votre projet Node Cloud Functions. Répondez Oui à cette invite.

Configurer les instances d'extension

Pour configurer l'extension, importez le SDK et, pour chaque instance d'extension que vous souhaitez installer, appelez la fonction de constructeur en lui transmettant un ID d'instance unique au projet et les paramètres de configuration requis par l'extension.

  1. Dans la source Cloud Functions, importez le constructeur à l'aide de l'instruction imprimée par la commande ext:sdk:install.

    TypeScript

    Par exemple, si vous avez généré un SDK pour l'extension firestore-send-email, l'instruction import ressemblerait à ce qui suit :

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

    Si l'extension nécessite des valeurs secrètes telles que des mots de passe, vous avez également besoin de la fonction defineSecret du SDK Cloud Functions :

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

    JavaScript

    Par exemple, si vous avez généré un SDK pour l'extension firestore-send-email, l'instruction require se présentera comme suit :

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

    Si l'extension nécessite des valeurs secrètes telles que des mots de passe, vous avez également besoin de la fonction defineSecret du SDK Cloud Functions :

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

  2. Pour chaque instance que vous souhaitez configurer, appelez la fonction de constructeur et exportez le résultat.

    Attribuez à chaque instance un ID unique, qui ne doit contenir que des lettres minuscules, des chiffres et des traits d'union.

    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",
});

    Notez que les valeurs secrètes doivent être spécifiées à l'aide de la fonction defineSecret.

  3. Ensuite, pour déployer les extensions que vous avez configurées, exécutez la commande suivante : 

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

    Toutes les options de déploiement de Cloud Functions habituelles s'appliquent. Par exemple, pour déployer une seule instance d'extension à partir d'une base de code spécifique : 

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

Étape 3 : Terminer la configuration post-installation

Certaines extensions nécessitent que vous effectuiez des étapes obligatoires ou facultatives avant de les utiliser. Vous trouverez ces instructions sur la page d'informations post-installation de votre extension dans le tableau de bord Extensions de la console Firebase (le lien spécifique vers le tableau de bord s'affiche dans le terminal après l'installation).

Vous trouverez également ces instructions dans le fichier POSTINSTALL.md inclus dans le répertoire source de l'extension.

Créer des ressources Firebase

Si vous avez configuré l'extension pour qu'elle utilise des ressources Firebase (collections Cloud Firestore, chemins Realtime Database, buckets Cloud Storage) qui n'existent pas encore, créez-les avant d'utiliser l'extension.

Créer des gestionnaires d'événements Eventarc

Certaines extensions publient des événements dans Eventarc lorsque des événements importants se produisent lors de l'exécution. Si une extension publie des événements, vous pouvez écrire des fonctions qui réagissent à ces événements avec votre propre logique personnalisée. Cela peut être utile, par exemple, pour avertir les utilisateurs lorsque des tâches de longue durée sont terminées ou pour post-traiter la sortie d'une fonction d'extension.

Si vous souhaitez définir des gestionnaires pour l'un des événements émis par l'extension, vous pouvez le faire à l'aide des méthodes de déclenchement de chaque instance :

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.
});

Vous devez exporter le gestionnaire d'événements avec l'instance d'extension.

Après avoir défini un gestionnaire d'événements, et chaque fois que vous en modifiez un, redéployez l'extension et le gestionnaire.

Installer plusieurs instances d'extension

Vous pouvez installer la même extension plusieurs fois dans le même projet. Chaque instance installée peut avoir sa propre configuration personnalisée et ses propres ressources d'extension. Vous identifiez chaque instance installée et y faites référence à l'aide de son ID d'instance, qui est unique dans votre projet.

Appelez la fonction de constructeur du SDK autogénéré une fois pour chaque instance que vous souhaitez installer et configurer.

Étapes suivantes

  • Affichez les détails et la configuration de votre extension installée dans la console Firebase.

  • Surveillez l'activité de votre extension installée, y compris son état, son utilisation et ses journaux.

  • À l'aide de la console Firebase, gérez votre extension installée. Pour les extensions Firebase officielles, vous pouvez reconfigurer ou désinstaller votre extension, ainsi que la mettre à jour vers la dernière version.

  • Nous vous recommandons de configurer des alertes budgétaires pour votre projet et de surveiller le tableau de bord Utilisation et facturation dans la console Firebase.