安裝 Firebase 擴充功能

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

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


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

這個自動產生的 SDK 包含：

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

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

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


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

如要安裝擴充功能，專案必須採用 Blaze (即付即用) 方案。安裝擴充功能不會產生費用，但如果 Firebase 服務或 Cloud Secret Manager 等 Cloud 服務的用量超出免費方案配額，您可能需要支付相關費用。

事前準備

  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。

這個指令會建立 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 指令列印的陳述式匯入建構函式。

    TypeScriptJavaScript

    舉例來說，如果您為 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";

    舉例來說，如果您為 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，只能包含小寫英文字母、數字和連字號。

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

    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。如果擴充功能發布事件，您可以編寫函式，透過自訂邏輯回應這些事件。舉例來說，這項功能可用於在長時間執行的工作完成時通知使用者，或是後續處理擴充功能函式的輸出內容。

如要為擴充功能發出的任何事件定義處理常式，可以使用每個例項的觸發方法：

TypeScriptJavaScript 
export const firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });

export const emailErrorHandler = firestoreSendEmail_1.onError((event) => {
  // Handle mail errors.
});

exports.firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });

exports.emailErrorHandler = exports.firestoreSendEmail_1.onError((event) => {
  // Handle mail errors.
});

您必須匯出事件處理常式和擴充功能例項。

定義事件處理常式後，每次變更時，請重新部署擴充功能和處理常式。

安裝多個擴充功能執行個體

您可以在同一個專案中多次安裝相同的擴充功能。 每個已安裝的執行個體都可以有專屬的自訂設定和擴充功能資源。您可以使用執行個體 ID 識別及參照每個已安裝的執行個體，這個 ID 在專案中是獨一無二的。

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

後續步驟