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

參數是使用者用來自訂擴充功能每個已安裝例項的機制。參數就像擴充功能的環境變數。參數的值可以自動填入 (安裝後由 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 檔案中通知使用者這些規定。

使用者設定的參數

如要讓使用者自訂每個已安裝的擴充功能例項，您可以在安裝期間要求使用者指定參數值。如要要求這些值，請在 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 區段中，使用下列欄位定義使用者設定的參數：

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

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

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

此外，對於許多擴充資料，常見的參數值要求是資料庫路徑或 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

可用的系統參數如下：