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

使用者可透過參數這種機制，逐一為安裝 。參數就像是 。參數值可以是 自動填入 (由 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 的預設值 專案 (例如 default Storage 值區) 或特定副檔名 (例如 擴充功能的執行個體 ID)。

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

雖然 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

這個值會產生 name 欄位 在 extension.yaml 檔案中指定

第 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 值區)。

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

    如果您指定此值，也必須定義 resourceType敬上 ] 欄位。

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

    Cloud Secret Manager 是付費服務，用於 因此必須向安裝擴充功能的使用者收取費用。如果您使用 secret 參數類型，請務必在 PREINSTALL 檔案中記錄擴充功能使用 Cloud Secret Manager。

如果省略這個欄位，參數會預設為 type (共 string 個)。

options
(如果參數 type 則為必要欄位) 是 select 或 multiSelect) 		list

使用者可以選取的值清單

將 label 和 value 欄位加入 options 欄位：

  • label (字串)： 可選取的選項
  • value (字串)： 可選取的選項

「value」為「options」為必填欄位 ] 欄位。
如果省略 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。

注意：如果您定義了 「位置」 已部署函式的參數 您應該在參數中加入這個 immutable 欄位 物件。

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

使用 string 的 type 設定參數時，必須定義 透過參數的 validationRegex 欄位中填入資料。

此外，許多擴充功能的常見要求參數值是資料庫 路徑或 Cloud Storage 值區。在安裝、重新設定或 更新後，Extensions 服務「不會」驗證以下項目： 參數值 entry 的時間：

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

然而，當擴充功能實際部署其資源時 Firebase 控制台或 Firebase CLI 會在下列情況顯示錯誤訊息 參照的資料庫或 Cloud Storage 值區尚未在專案中設定。

強烈建議您通知使用 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 函式連線至指定的 VPC 連接器。
firebaseextensions.v1beta.function/minInstances 函式執行個體數量下限 minInstances 此函式同時執行的最低執行個體數量下限
firebaseextensions.v1beta.function/maxInstances 函式執行個體上限 maxInstances 一次執行的此函式例項數量上限
firebaseextensions.v1beta.function/ingressSettings 輸入設定 ingressSettings 控管接收下列來源的流量
firebaseextensions.v1beta.function/labels 標籤 labels 要套用至擴充功能中所有資源的標籤