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

使用者可透過參數自訂擴充功能的每個已安裝例項。參數類似於擴充功能的環境變數。參數值可以自動填入 (由 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 儲存空間)，或是擴充功能專屬值 (例如擴充功能的執行個體 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 欄位產生。

首次安裝例項的一般格式 (由 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。

如果省略這個欄位，參數預設為 type 的 string。

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 值，並在使用者介面中將參數顯示為任意形式的 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 欄位定義適當的 regex 驗證。

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

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

不過，當擴充功能實際部署資源時，如果專案中尚未設定參照的資料庫或 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 設定虛擬私有雲連接器時，控管輸出流量
firebaseextensions.v1beta.function/vpcConnector 虛擬私有雲連接器 vpcConnector 將 Cloud Functions 連線至指定的 VPC 連接器。
firebaseextensions.v1beta.function/minInstances 函式執行個體數量下限 minInstances 一次執行的函式執行個體數量下限
firebaseextensions.v1beta.function/maxInstances 函式執行個體上限 maxInstances 可同時執行的函式執行個體數量上限
firebaseextensions.v1beta.function/ingressSettings 輸入設定 ingressSettings 控管接受連入流量的來源
firebaseextensions.v1beta.function/labels 標籤 labels 要套用至擴充功能中所有資源的標籤