此页面由 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 项目的唯一标识符	通用格式： `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`	已安装的扩展程序实例的唯一标识符此值由 `extension.yaml` 文件中指定的 `name` 字段生成。	第 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 存储桶）。
如果您指定此类型的参数，系统会在安装界面中为用户提供更便于使用的选择小组件；因此，请尽可能使用 selectResource 参数。

如果您指定此值，则还必须定义 resourceType 字段。
secret：允许存储敏感字符串，例如用于第三方服务的 API 密钥。这些值将存储在 Cloud Secret Manager 中。
Cloud Secret Manager 是一项付费服务，安装您的扩展程序的用户若使用该服务，则需要支付相应费用。如果您使用 secret 参数类型，请务必在 PREINSTALL 文件中明确记载您的扩展程序会使用 Cloud Secret Manager。

如果省略此字段，则该参数默认为 string type。

options
（如果参数 type 为 select 或 multiSelect，则必须提供）

列表

用户可以从中进行选择的值的列表

在 options 字段中包含 label 和 value 字段：

label（字符串）：可选选项的简短说明
value（字符串）：可选选项的实际值
请务必用引号含括这些字符串，以防止意外类型转换。

options 字段是 value 字段的必填项。
如果省略 label，则列表选项默认为显示 value。

示例语法

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

resourceType
（如果参数type为 selectResource，则必须选择该字段）

字符串

提示用户选择的 Firebase 资源类型。目前，只有 Cloud Storage 存储桶支持资源选择器：

资源类型	类型 ID
Cloud Storage 个存储桶	`storage.googleapis.com/Bucket`

系统会忽略未知的 resourceType 值，并且界面会将该参数呈现为自由格式的 string 输入字段。

example
（选填）

字符串

参数的示例值

validationRegex
（选填）
（仅在参数 type 为 string 时适用）

字符串

用于验证用户配置的值的正则表达式字符串

正则表达式使用 Go 库 RE2 进行编译

如需了解验证的详细信息，请参阅下面的验证和错误消息传递。

validationErrorMessage
（选填）

字符串

validationRegex 失败时显示的错误消息

如需了解错误消息传递的详细信息，请参阅下面的验证和错误消息传递。

default
（选填）

字符串

用户将参数的值留空时该参数的默认值

如果适用，您可以为 default 值指定自动填充的参数值（如需查看示例，请参阅 Resize Images 扩展程序的 IMG_BUCKET 参数）。

required
（选填）

布尔值

定义当系统提示用户输入参数值时，用户是否可以提交空字符串

如果省略 required，则此值默认为 true（即必填参数）。

immutable
（选填）

布尔值

定义用户能否在安装后更改参数值（例如，如果用户重新配置扩展程序）

如果省略 immutable，则此值默认为 false。

注意：如果您要为已部署的扩展程序函数定义“location”参数，则应在其参数对象中包含此 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`	应为每个函数分配多少兆字节的内存？
firebaseextensions.v1beta.function/timeoutSeconds	函数超时	`timeout`	函数在运行多少秒后便会超时？
firebaseextensions.v1beta.function/vpcConnectorEgressSettings	VPC 连接器出站流量	`vpcConnectorEgressSettings`	配置 VPC 连接器后，控制出站流量
firebaseextensions.v1beta.function/vpcConnector	VPC 连接器	`vpcConnector`	将 Cloud Functions 函数连接到指定的 VPC 连接器。
firebaseextensions.v1beta.function/minInstances	函数实例数下限	`minInstances`	此函数一次要运行的实例数下限
firebaseextensions.v1beta.function/maxInstances	函数实例数上限	`maxInstances`	此函数一次可运行的实例数上限
firebaseextensions.v1beta.function/ingressSettings	入站流量设置	`ingressSettings`	控制从何处接受传入流量
firebaseextensions.v1beta.function/labels	标签	`labels`	要应用于扩展程序中所有资源的标签