安裝 Firebase 擴充功能

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

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

Firebase 控制台 Firebase CLI 自動產生的 SDK

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

這個自動產生的 SDK 包含：

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

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

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

如要首次試用 Firebase Extension，建議您在測試或開發專案中安裝擴充功能。

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

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

事前準備

1. 如果您尚未將 Firebase 新增至專案，請先完成這項操作。

2. 如果您尚未將專案升級至 Blaze (即付即用) 方案，請先完成這項作業。

3. 安裝或更新至最新版 Firebase CLI。

4. 請記下 Firebase 專案 ID 或先前設定的專案別名。

   • 專案 ID：從電腦上的任何位置執行 firebase projects:list。
   • 專案別名：從本機應用程式目錄執行 firebase use。
   注意： 如要使用 CLI 指令安裝及管理擴充功能，您必須擁有與本機應用程式目錄相關聯的 Firebase 專案。如果您尚未設定，請執行 firebase init 來設定本機 Firebase 目錄。

步驟 1：查看擴充功能的詳細資訊

這是選用步驟，但強烈建議執行。

安裝 Firebase Extension 前，建議您詳閱擴充功能的相關資訊，包括：

• 擴充功能的運作方式、任何預先安裝工作，以及擴充功能的詳細資料
• 一般識別資訊和說明
• 擴充功能的作業是否需要帳單帳戶
• 作業所需的 Google 服務 (API) 和存取權角色
• 為擴充功能建立的資源 (例如函式)
• 使用者可設定參數的說明

如要查看擴充功能的詳細資訊：

1. 請確認您已設定環境，並選取擴充功能。

2. 您可以在電腦上的任何位置執行 extension-info 指令：

   firebase ext:info publisher-id/extension-id

   必須使用 publisher-id 和 extension-id 引數，您可以在擴充功能的預先安裝詳細資料頁面中找到這些引數。

注意： 您也可以在擴充功能目錄中，查看包含 README 的詳細資訊。

步驟 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，可能也要從設定中排除產生的 SDK (.eslintrc.js)：

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 專案。請在系統提示時回答「是」。

設定擴充功能執行個體

如要設定擴充功能，請匯入 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://[e-mail]@smtp.example.com:465",
       SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"),
       MAIL_COLLECTION: "mail",
       DEFAULT_FROM: "ExampleCo <[e-mail]>",
       TTL_EXPIRE_VALUE: "1",
       TTL_EXPIRE_TYPE: "day",
   });
   

   JavaScript

   exports.firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", {
       SMTP_CONNECTION_URI: "smtps://[e-mail]@smtp.example.com:465",
       SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"),
       MAIL_COLLECTION: "mail",
       DEFAULT_FROM: "ExampleCo <[e-mail]>",
       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 到 5 分鐘的時間。

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

您必須將事件處理常式與擴充功能例項一併匯出。

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

重要事項： 如果您啟用事件，且超過免費配額，系統就會向您收費。請參閱 Eventarc 定價。

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

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

針對每個要安裝及設定的例項，分別呼叫自動產生的 SDK 建構函式一次。

後續步驟

• 在 Firebase 主控台中查看已安裝擴充功能的詳細資料和設定。

• 監控已安裝擴充功能的活動，包括檢查其健康狀態、使用情形和記錄。

• 使用 Firebase 主控台管理已安裝的擴充功能。對於官方 Firebase 擴充功能，您可以重新設定或解除安裝擴充功能，以及將擴充功能更新至最新版本。

• 為確保所有專案都能順利運作，請務必為專案設定預算快訊，並在 Firebase 控制台中監控用量和帳單資訊主頁。