安裝 Firebase 擴充功能

您可以使用 Firebase 控制台、Firebase CLI (指令列介面) 或自動產生的 SDK，安裝 (和管理) 任何官方 Firebase 擴充功能。

請務必查看各安裝方法支援動作的差異。


使用自動產生的 SDK 安裝擴充功能是新的安裝和管理方式。使用這個選項時，您可以使用 CLI 自動產生特定擴充功能版本的 Node SDK，並在 JavaScript 或 TypeScript Cloud Functions 中匯入為一般依附元件。

這個自動產生的 SDK 包含：

  • 代表擴充功能參數的介面，以及大多數非原始參數類型的型別宣告。
  • 初始化擴充功能例項的建構函式
  • 擴充功能類別，其中包含擴充功能發出的所有事件的 Eventarc 觸發條件。

產生擴充功能 SDK 後，所有擴充功能設定都會在程式碼中進行。

使用這個安裝選項可大幅簡化多個擴充功能執行個體的管理作業，尤其是在包含擴充功能外部定義的 Cloud Functions 的專案中。


如要安裝或管理擴充功能，您必須獲派下列任一角色：擁有者或編輯者，或是 Firebase 管理員。

如要安裝擴充功能，專案必須採用 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

如果您要開始新專案，或專案目前未使用 Firebase 專用的 Cloud Functions，請執行 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。

這個指令會建立 Node 套件，其中包含為擴充功能自動產生的 SDK，並將其新增至專案的其中一個 Cloud Functions 程式碼庫。在預設程式碼庫 (functions) 中，SDK 會儲存至下列位置：

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

產生 SDK 後，指令會詢問您是否要將 SDK 安裝到 Cloud Functions Node.js 專案中。對這項提示回答「是」。

設定擴充功能執行個體

如要設定擴充功能，請匯入 SDK，並針對要安裝的每個擴充功能例項呼叫建構函式，然後將專案專屬的例項 ID 和擴充功能所需的設定參數傳遞至該函式。

  1. 在 Cloud Functions 來源中，使用 ext:sdk:install 指令列印的陳述式匯入建構函式。

    TypeScript

    舉例來說，如果您為 firestore-send-email 擴充功能產生 SDK，import 陳述式會如下所示：

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

    如果擴充功能需要任何密碼等私密值，您也需要 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");

    如果擴充功能需要任何密碼等私密值，您也需要 Cloud Functions SDK 中的 defineSecret 函式：

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

  2. 針對要設定的每個執行個體，呼叫建構函式並匯出結果。

    為每個執行個體提供專屬 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 bucket)，請先建立這些資源，再使用擴充功能。

建立 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 識別及參照每個已安裝的執行個體，這個 ID 在專案中是唯一的。

針對要安裝及設定的每個執行個體，呼叫一次自動產生的 SDK 建構函式。

後續步驟