本頁面由 Cloud Translation API 翻譯而成。

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

使用者可透過參數自訂擴充功能的每個已安裝例項。參數類似於擴充功能的環境變數。參數值可以自動填入 (由 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 值區名稱	一般格式： `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
(required if parameter type is select or multiSelect)

list

使用者可選取的值清單

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

label (字串)：可選選項的簡短說明
value (字串)：可選取選項的實際值
請務必在這些字串周圍加上引號，以免發生非預期的型別轉換。

options 欄位必須填寫 value 欄位。
如果省略 label，清單選項預設會顯示 value。

語法範例

options:
  - label:
    value:
  - label:
    value:
  - label:
    value:

resourceType
(required if parameter type is selectResource)

字串

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

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

系統會忽略不明的 resourceType 值，並在 UI 中將參數算繪為任意形式的 string 輸入欄位。

example
(選填)

字串

參數值範例

validationRegex
(選用)
(僅適用於參數 type 為 string 的情況)

字串

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

系統會使用 Go 程式庫 (RE2) 編譯規則運算式

如要瞭解驗證詳情，請參閱下方的「驗證和錯誤訊息」。

validationErrorMessage
(選填)

字串

如果 validationRegex 失敗，要顯示的錯誤訊息

如要瞭解錯誤訊息的詳細資訊，請參閱下方的「驗證和錯誤訊息」。

default
(選填)

字串

如果使用者將參數值留空，系統會使用的參數預設值

如適用，您可以為 default 值指定自動填入的參數值 (如需範例，請參閱「調整圖片大小」擴充功能的 IMG_BUCKET 參數)。

required
(選填)

布林值

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

如果省略 required，這個值預設為 true (即必要參數)。

immutable
(選填)

布林值

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

如未填寫此欄位，則預設值為 false。 immutable

注意：如果您為擴充功能的已部署函式定義「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 連線至指定的虛擬私有雲連接器。
firebaseextensions.v1beta.function/minInstances	函式執行個體數量下限	`minInstances`	一次執行的函式執行個體數量下限
firebaseextensions.v1beta.function/maxInstances	函式執行個體上限	`maxInstances`	可同時執行的函式執行個體數量上限
firebaseextensions.v1beta.function/ingressSettings	輸入設定	`ingressSettings`	控管接受連入流量的來源
firebaseextensions.v1beta.function/labels	標籤	`labels`	要套用至擴充功能中所有資源的標籤