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

參數是使用者用來自訂擴充功能每個已安裝例項的機制。參數就像擴充功能的環境變數。參數的值可以自動填入 (安裝後由 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 專案的預設值 (例如預設儲存體系別)，也可能是擴充功能專屬值 (例如擴充功能的執行個體 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 值區名稱

一般格式：
project-id.appspot.com

範例值：
project-123.appspot.com

參數：擴充功能安裝程序的預設值
EXT_INSTANCE_ID

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

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

第一個已安裝例項的一般格式 (由 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 儲存桶)。

    指定這類參數時，使用者會在安裝 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 個值區支援資源選取器：

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

系統會忽略不明的 resourceType 值，且 UI 會將參數顯示為自由格式 string 輸入欄位。
example
(選填) 		字串

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

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

規則運算式使用 Go 程式庫編譯：RE2

如需驗證詳細資訊，請參閱下方的「驗證和錯誤訊息」。
validationErrorMessage
(選填) 		字串

如果 validationRegex 失敗，系統會顯示這則錯誤訊息

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

如果使用者將參數值留空，則該參數的預設值

如適用，您可以為 default 值指定自動填入的參數值 (例如，請參閱 Resize Images 擴充功能的 IMG_BUCKET 參數)。
required
(選填) 		布林值

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

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

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

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

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

針對使用者設定的值提供驗證和錯誤訊息

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

此外，對於許多擴充資料，常見的參數值要求是資料庫路徑或 Cloud Storage 值區。請注意，在安裝、重新設定或更新期間，Extensions 服務不會在參數值輸入時驗證下列項目：

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

但是，當擴充功能實際部署其資源時，如果參照的資料庫或 Cloud Storage 值區尚未在專案中設定，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 虛擬私有雲連接器輸出 vpcConnectorEgressSettings 在設定 VPC 連接器時控管傳出流量
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 要套用至擴充功能中所有資源的標籤