在擴充功能中設定並使用參數

使用者可透過參數自訂每個已安裝的擴充功能執行個體。參數就像是擴充功能的環境變數。參數值可以自動填入 (由 Firebase 在安裝後提供)，或由使用者設定 (由使用者在安裝期間指定)。

您可以在擴充功能的函式原始碼、extension.yaml 檔案和 POSTINSTALL.md 檔案中參照這些參數。以下是參照 PARAMETER_NAME 參數的語法：

  • 在函式原始碼中，使用 params 模組 (例如 params.defineInt("PARAMETER_NAME")) 或 process.env.PARAMETER_NAME。

  • 在 extension.yaml 和 POSTINSTALL.md 中，使用 ${param:PARAMETER_NAME}。

    安裝完成後，Firebase 控制台會顯示 POSTINSTALL.md 檔案的內容，並在所有參數參照中填入已安裝執行個體的「實際」值。

自動填入的參數

每個安裝的擴充功能執行個體，都會自動存取 Firebase 提供的多個預設自動填入參數 (請參閱下表)。這些參數值可能是 Firebase 專案的預設值 (例如預設 Storage bucket)，也可能是擴充功能專屬的值 (例如擴充功能的執行個體 ID)。

所有自動填入的參數值都無法變更。這些變數會在建立專案或安裝擴充功能時設定。

雖然 Firebase 會自動為擴充功能填入這些參數值，但Firebase 不會在安裝期間自動為使用者佈建相關聯的產品。安裝擴充功能的使用者必須先在專案中啟用相關且適用的產品，才能安裝擴充功能。舉例來說，如果擴充功能涉及 Cloud Firestore，使用者就必須在專案中設定 Cloud Firestore。建議您在 PREINSTALL.md 檔案中向使用者說明這些規定。

自動填入參數參考資料 說明 參數值 (由 Firebase 提供)
Firebase 專案中具有預設值的參數
PROJECT_ID 擴充功能安裝所在 Firebase 專案的專屬 ID

一般格式：
project-id

範例值：
project-123

DATABASE_URL Firebase 專案的預設 Realtime Database 執行個體網址

一般格式：
https://project-id-default-rtdb.firebaseio.com
(美國執行個體)
或
https://project-id-default-rtdb.region-code.firebasedatabase.app
(非美國執行個體)

範例值：
https://project-123-default-rtdb.firebaseio.com

DATABASE_INSTANCE

Firebase 專案的「預設」Realtime Database 執行個體名稱

這個值通常與專案 ID 相同，或結尾為 -default-rtdb。

一般格式：
project-id

範例值：
project-123

STORAGE_BUCKET Firebase 專案的預設 Cloud Storage bucket 名稱

一般格式：
PROJECT_ID.firebasestorage.app

範例值：
project-123.firebasestorage.app

擴充功能安裝時預設值的參數
EXT_INSTANCE_ID

已安裝擴充功能執行個體的專屬 ID

這個值是根據 extension.yaml 檔案中指定的 name 欄位產生。

第 1 個安裝執行個體的一般格式 (由 Firebase 自動指派，無法在安裝期間由使用者修改)：
name-from-extension.yaml

範例值：
my-awesome-extension


第 2 個及後續安裝執行個體的一般格式 (由 Firebase 自動指派，使用者可以在安裝期間修改)：
name-from-extension.yaml-4-digit-alphanumeric-hash

範例值：
my-awesome-extension-6m31

使用者設定的參數

如要讓使用者自訂擴充功能的每個安裝執行個體，可以在安裝期間要求使用者指定參數值。如要要求這些值，請在 extension.yaml 檔案的 params 區段中設定提示。

以下是 params 區段範例，以及說明所有可用參數欄位的表格。

# extension.yaml
...

# Parameters (environment variables) for which the user specifies values during installation
params:
  - param: DB_PATH
    label: Realtime Database path
    description: >-
      What is the Realtime Database path where you will write new text
      for sentiment analysis?
    type: string
    validationRegex: ^\S+$
    validationErrorMessage: Realtime Database path cannot contain spaces.
    example: path/to/posts
    required: true

  - param: TEXT_KEY
    label: Key for text
    description: What is the name of the key that will contain text to be analyzed?
    type: string
    default: textToAnalyze
    required: true

在 extension.yaml 檔案的 params 區段中，使用下列欄位定義使用者設定的參數：

欄位 類型 說明
param
(必要) 		字串 參數名稱
label
(必要) 		字串

參數簡短說明

系統提示使用者輸入參數值時，會顯示這段文字
description
(選填) 		字串

參數的詳細說明

系統提示使用者輸入參數值時，會顯示這段文字

支援 Markdown

type
(選填) 		字串

使用者設定參數值的方式 (例如直接輸入文字或從下拉式選單中選取)

有效值包括：

  • string：允許輸入任意形式的文字 (受 validationRegex 限制)
  • select：可從預先定義的選項清單中選取一個項目。如果指定這個值，也必須定義 options 欄位。
  • multiSelect：可從預先定義的選項清單中選取一或多個項目。如果指定這個值，也必須定義 options 欄位。
  • selectResource：可從使用者的專案中選取特定類型的 Firebase 資源 (例如 Cloud Storage bucket)。

    指定這種類型的參數時，使用者會在安裝 UI 中看到更方便使用的選取小工具，因此請盡可能使用 selectResource 參數。

    如果指定這個值，也必須定義 resourceType 欄位。

  • secret：允許儲存機密字串，例如第三方服務的 API 金鑰。這些值會儲存在 Cloud Secret Manager。

    Cloud Secret Manager 是付費服務，使用者安裝擴充功能後，可能需要支付相關費用。如果使用 secret 參數類型，請務必在 PREINSTALL 檔案中記錄擴充功能使用 Cloud Secret Manager。

如果省略這個欄位，參數會預設為 string 的 type。
options
(如果參數 type 為 select 或 multiSelect，則為必要) 		list

使用者可選取的值清單

在 options 欄位中加入 label 和 value 欄位：

  • label (字串)：可選選項的簡短說明
  • value (字串)：可選選項的實際值。

options 欄位必須填寫 value 欄位。
如果省略 label，清單選項預設會顯示 value。
resourceType
(如果參數 type 為 selectResource，則為必要) 		字串

提示使用者選取的 Firebase 資源類型。目前只有 Cloud Storage bucket 支援資源選取器：

資源類型 類型 ID
Cloud Storage 個 Bucket storage.googleapis.com/Bucket

系統會忽略不明的 resourceType 值，並在使用者介面中將參數算繪為任意形式的 string 輸入欄位。
example
(選填) 		字串

參數範例值
validationRegex
(選用)
(僅適用於 type 參數為 string 時) 		字串

用於驗證參數使用者設定值的規則運算式字串

規則運算式是使用 Go 程式庫 RE2 編譯而成

如要進一步瞭解驗證，請參閱下方的「驗證和錯誤訊息」。
validationErrorMessage
(選填) 		字串

validationRegex 失敗時顯示的錯誤訊息

如要進一步瞭解錯誤訊息，請參閱下方的「驗證和錯誤訊息」一節。
default
(選填) 		字串

使用者將參數值留空時，參數的預設值

在適用情況下，您可以為 default 值指定自動填入的參數值 (例如，請參閱調整圖片大小擴充功能的 IMG_BUCKET 參數)。
required
(選填) 		布林值

定義系統提示使用者輸入參數值時，使用者是否能提交空白字串

如果省略 required，這個值會預設為 true (即必要參數)。
immutable
(選填) 		布林值

定義使用者是否能在安裝後變更參數值 (例如重新設定擴充功能)

如果省略 immutable，這個值會預設為 false。

注意：如果您為擴充功能部署的函式定義「location」參數，則應在其 param 物件中加入這個 immutable 欄位。

使用者設定值的驗證和錯誤訊息

使用 string 的 type 設定參數時，您需要透過參數的 validationRegex 欄位定義適當的規則運算式驗證。

此外，許多擴充功能通常會要求提供資料庫路徑或 Cloud Storage bucket 做為參數值。請注意，在安裝、重新設定或更新期間，Extensions 服務不會在輸入參數值時驗證下列項目：

  • 是否已在使用者 Firebase 專案中設定指定的資料庫或 Cloud Storage bucket
  • 指定資料庫路徑是否存在於使用者的資料庫中

不過，如果專案尚未設定參照的資料庫或 Cloud Storage bucket，擴充功能實際部署資源時，Firebase 控制台或 Firebase CLI 就會顯示錯誤訊息。

強烈建議您在 PREINSTALL 檔案中通知使用者這些需求條件，確保他們安裝擴充功能時，能順利安裝並正常運作。

系統參數

系統參數可控管擴充功能資源的基本設定。由於這些變數是用來控管資源設定，因此無法從函式程式碼中以環境變數的形式存取。

您通常不需要在 extension.yaml 中為這些參數宣告任何內容。系統會自動為每個擴充功能執行個體定義這些參數，使用者在安裝擴充功能時可以設定自訂值。

不過，如果擴充功能有特殊資源需求，您可以在 extension.yaml 中，為每項資源設定特定值。這些個別資源設定會覆寫使用者在擴充功能執行個體層級的設定。例如：

resources:
- name: high_memory_function
  type: firebaseextensions.v1beta.function
  description: >-
    This function needs at least 1GB of memory!
  properties:
    httpsTrigger: {}
    runtime: nodejs18
    availableMemoryMb: 1024
- name: normal_function
  type: firebaseextensions.v1beta.function
  description: >-
    This function has no special memory requirements. It will use the
    default value, or the value of `firebaseextension.v1beta.function/memory`
  properties:
    httpsTrigger: {}
    runtime: nodejs18

可用的系統參數如下：

名稱 標籤 (一般人可判讀) properties中的對應欄位 說明
firebaseextensions.v1beta.function/location 位置 location Cloud Functions 應部署至哪個區域？
firebaseextensions.v1beta.function/memory 函式記憶體 memory 每個函式應分配多少 MB 的記憶體？
firebaseextensions.v1beta.function/timeoutSeconds 函式逾時 timeout 函式應執行多少秒後逾時？
firebaseextensions.v1beta.function/vpcConnectorEgressSettings VPC 連接器輸出 vpcConnectorEgressSettings 設定虛擬私有雲連接器時，控管傳出流量
firebaseextensions.v1beta.function/vpcConnector 虛擬私有雲連接器 vpcConnector 將 Cloud Functions 連結至指定的虛擬私有雲連接器。
firebaseextensions.v1beta.function/minInstances 函式執行個體數量下限 minInstances 一次執行的函式執行個體數量下限
firebaseextensions.v1beta.function/maxInstances 函式執行個體上限 maxInstances 這個函式一次可執行的執行個體數量上限
firebaseextensions.v1beta.function/ingressSettings 輸入設定 ingressSettings 控管接受傳入流量的來源
firebaseextensions.v1beta.function/labels 標籤 labels 要套用至擴充功能中所有資源的標籤