安装 Firebase Extensions 扩展程序

您可以使用 Firebase 控制台、Firebase CLI（命令行界面）或自动生成的 SDK 安装（和管理）任何官方 Firebase 扩展程序。

请务必查看每种安装方法支持的操作之间的差异。


使用自动生成的 SDK 进行安装是安装和管理扩展程序的新选项。使用此选项时，您可以使用 CLI 为特定扩展版本自动生成 Node SDK，并将其作为普通依赖项导入到 JavaScript 或 TypeScript Cloud Functions 中。

此自动生成的 SDK 包含：

  • 一个接口，表示扩展程序的参数，以及大多数非基本参数类型的类型声明。
  • 用于初始化扩展程序实例的构造函数
  • 一个扩展程序类，其中包含扩展程序发出的所有事件的 Eventarc 触发器。

生成扩展程序 SDK 后，扩展程序的所有配置都将在代码中进行。

使用此安装选项可以极大地简化对多个扩展程序实例的管理，尤其是在包含在扩展程序之外定义的 Cloud Functions 函数的项目中。


如需安装或管理扩展程序，您必须拥有以下某个角色：Owner 或 Editor 或 Firebase Admin。

如需安装扩展程序，您的项目必须采用 Blaze（随用随付）方案。虽然扩展程序可以免费安装，但如果超出 Firebase 服务或 Cloud 服务（例如 Cloud Secret Manager）的免费层级，您可能就需要支付相应的费用。

准备工作

  1. 将 Firebase 添加到您的项目（如果尚未添加）。

  2. 将项目升级为 Blaze（随用随付）方案（如果尚未升级）。

  3. 安装或更新到 Firebase CLI 的最新版本。

  4. 记下您的 Firebase 项目 ID 或之前配置的项目别名。

    • 项目 ID - 从计算机上的任意位置运行 firebase projects:list。
    • 项目别名 - 从本地应用目录运行 firebase use。

第 1 步：查看扩展程序的相关详情

这是可选步骤，但我们强烈建议您执行此操作。

在安装 Firebase Extension 扩展程序之前，我们建议您先查看该扩展程序的详细信息，包括：

  • 扩展程序的工作方式、任何预安装任务以及扩展程序的相关详情
  • 一般标识信息和说明
  • 扩展程序的任务是否需要结算账号
  • 执行操作所需的 Google 服务 (API) 和访问角色
  • 为扩展程序创建的资源（如函数）
  • 用户可配置参数的说明

如需查看扩展程序的详细信息，请执行以下操作：

  1. 确保您已设置环境并选择了某个扩展程序。

  2. 从计算机上的任意位置运行 extension-info 命令：

    firebase ext:info publisher-id/extension-id

    publisher-id 和 extension-id 参数是必需的，可以在扩展程序的预安装详情页面上找到。

第 2 步：安装扩展程序

在安装之前，请查看扩展程序的基本规范（例如启用的 API、创建的资源、授予的访问权限等）及其结算要求。

在继续操作之前，请确保您已设置环境并选择了扩展程序。

初始化 Cloud Functions for Firebase

如果您要开始一个新项目，或者您的项目尚未使用 Cloud Functions for Firebase，请运行 init functions：

cd your-project
firebase init functions

选择 TypeScript 或 JavaScript 作为函数语言。

如果您的项目已初始化 Cloud Functions，请确保您使用的是 firebase-functions 软件包 5.1.0 版或更高版本：

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

如果您使用 ESLint，可能还需要从配置 (.eslintrc.js) 中排除生成的 SDK：

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

生成扩展程序 SDK

在本地 Firebase 目录中，运行 ext:sdk:install 命令。

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

例如，如需安装 firestore-send-email 扩展程序 0.1.34 版，请运行以下命令：

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

publisher-id 和 extension-id 是必需的，可以在 extensions.dev 上的扩展程序预安装详情页面上找到。@version 部分是可选的；如果您省略该部分，该工具会安装最新版本。

您可以指定以下两个选项：

  • --force：执行以下所有操作，而无需进一步确认：

    • 自动生成 SDK，即使已为同一扩展程序和版本生成 SDK 也是如此。
    • 在 Cloud Functions Node 项目中安装自动生成的 SDK 软件包。

  • --codebase：要将 SDK 添加到的代码库的名称。如果未指定，该命令会将 SDK 添加到默认代码库 functions。

此命令会创建一个包含为扩展程序自动生成的 SDK 的 Node 软件包，并将其添加到项目的某个 Cloud Functions 代码库中。在默认代码库 (functions) 中，SDK 会保存到以下位置： 

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

生成 SDK 后，该命令会询问您是否要将 SDK 也安装到 Cloud Functions Node 项目中。对此提示回答 Yes。

配置扩展程序实例

如需配置扩展程序，请导入 SDK，然后针对要安装的每个扩展程序实例调用构造函数，并将项目专有的实例 ID 和扩展程序所需的配置参数传递给该函数。

  1. 在 Cloud Functions 源代码中，使用 ext:sdk:install 命令输出的语句导入构造函数。

    TypeScript

    例如，如果您为 firestore-send-email 扩展程序生成了 SDK，则 import 语句将如下所示：

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

    如果扩展程序需要任何 Secret 值（例如密码），您还需要 Cloud Functions SDK 中的 defineSecret 函数：

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

    JavaScript

    例如，如果您为 firestore-send-email 扩展程序生成了 SDK，则 require 语句将如下所示：

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

    如果扩展程序需要任何 Secret 值（例如密码），您还需要 Cloud Functions SDK 中的 defineSecret 函数：

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

  2. 对于要配置的每个实例，调用构造函数并导出结果。

    为每个实例分配一个唯一 ID，该 ID 只能包含小写字母、数字和连字符。

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

    请注意，必须使用 defineSecret 函数指定密钥值。

  3. 然后，如需部署您配置的扩展程序，请运行以下命令： 

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

    所有常规的 Cloud Functions 部署选项都适用。例如，如需从特定代码库部署单个扩展程序实例，请运行以下命令：

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

第 3 步：完成安装后设置

对于某些扩展程序，您需要完成必需或可选步骤，然后才能使用。在 Firebase 控制台上 Extensions 信息中心内扩展程序的安装后详情页面中可以找到这些说明（安装后，终端会显示指向信息中心的特定链接）。

您还可以在扩展程序的源目录中包含的 POSTINSTALL.md 文件内找到这些说明。

创建 Firebase 资源

如果您将扩展程序配置为使用尚不存在的 Firebase 资源（Cloud Firestore 集合、Realtime Database 路径、Cloud Storage 存储桶），请先创建这些资源，然后再使用该扩展程序。

创建 Eventarc 事件处理脚本

如果执行期间发生重要事件，某些扩展程序会向 Eventarc 发布事件。如果扩展程序发布了事件，则您可以编写函数，使用自己的自定义逻辑对这些事件进行响应。这一功能非常有用。例如，在长时间运行的任务完成时通知用户，或对扩展程序函数的输出进行后处理。

如果您想为扩展程序发出的任何事件定义处理脚本，可以使用每个实例的触发器方法来实现：

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

您必须将事件处理程序与扩展程序实例一起导出。

定义事件处理脚本后，以及每次对事件处理脚本进行更改后，请重新部署扩展程序和处理脚本。

安装多个扩展程序实例

注意：您可以在同一项目中多次安装同一扩展程序。 每个已安装的实例都可以拥有自己的自定义配置和扩展程序资源。您可以使用项目中唯一的实例 ID 来标识和引用每个已安装的实例。

针对您要安装和配置的每个实例调用自动生成的 SDK 的构造函数一次。

后续步骤