Installer une extension Firebase

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

Veillez à examiner 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 déclarations de type pour la plupart des types de paramètres non primitifs.
  • Une fonction de constructeur qui initialise une instance de l'extension
  • Classe d'extension contenant des 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 produit dans le code.

L'utilisation de cette option d'installation peut grandement simplifier la gestion de plusieurs instances d'extension, en particulier dans les projets contenant 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é au forfait Blaze (paiement à l'usage). Bien que l'installation d'une extension ne soit pas facturée, 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 encore fait, ajoutez Firebase à votre projet.

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

  3. Installez ou mettez à jour la dernière version de la CLI Firebase.

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

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

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

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

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

  • Fonctionnement de l'extension, tâches de préinstallation et informations sur l'extension
  • Informations générales permettant d'identifier l'application 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 les informations détaillées d'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 quelle partie de votre ordinateur:

    firebase ext:info publisher-id/extension-id

    Les arguments publisher-id et extension-id sont obligatoires et se trouvent sur la page d'informations sur la préinstallation de l'extension.

Étape 2: Installez une extension

Avant l'installation, examinez les spécifications de base de l'extension (API activées, ressources créées, accès accordé, 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 de 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 éléments publisher-id et extension-id sont obligatoires et se trouvent sur la page d'informations 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 opérations suivantes sans confirmation:

    • Générez 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 de SDK généré automatiquement dans le projet Node de Cloud Functions.

  • --codebase: nom du codebase auquel ajouter le SDK. Si cette valeur n'est pas spécifiée, la commande ajoute le SDK au 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'un des codebases Cloud Functions de votre projet. Dans le codebase par défaut (functions), le SDK est enregistré à l'emplacement suivant: 

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

Une fois le SDK généré, la commande vous demande si vous souhaitez également l'installer dans votre projet Node Cloud Functions. Répondez Yes (Oui) à cette invite.

Configurer des 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 propre au projet et les paramètres de configuration requis par l'extension.

  1. Dans votre 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 se présente comme 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ésente 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, contenant uniquement 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. 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'un codebase spécifique: 

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

Étape 3: Finaliser la configuration post-installation

Certaines extensions nécessitent des étapes obligatoires ou facultatives avant de pouvoir 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 données dans Eventarc lorsque des événements importants se produisent pendant 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 de l'extension.

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

Installer plusieurs instances d'une 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 et faites référence à chaque instance installée à l'aide de son ID d'instance, qui est unique dans votre projet.

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

Étapes suivantes