extension.yaml 参考文档

您的扩展程序的规范文件 (extension.yaml) 包含扩展程序的元数据，声明了扩展程序创建的资源以及扩展程序所需的 API 和访问权限，并且定义了扩展程序提供的可由用户配置的所有参数。

本页中的各表描述了 extension.yaml 文件的可用字段。

基本信息和标识信息

name: your-extension-name
version: 1.0.0         # Semantic versioning (semver)
specVersion: v1beta    # Always "v1beta"
license: Apache-2.0    # Always "Apache-2.0" (required to publish on extensions.dev)
billingRequired: true  # Always "true"

displayName: Your extension name
description: >-
  Description of the extension. (One or two
  sentences.)
icon: icon.png
tags: [tag, anothertag]

sourceUrl: https://github.com/your-org/your-repo   # GitHub repo URL
releaseNotesUrl: https://github.com/your-org/your-repo/blob/main/CHANGELOG.md

author:
  authorName: Your Company
  email: extensions@example.com
  url: https://example.com/
contributors:
  - authorName: Your Name
  - authorName: Another Contributor
    email: colleague@example.net
    url: https://github.com/their-org/
基本字段
name
字符串
（必填）

扩展程序的标识符。

只能包含小写字母、数字和短划线；不能超过 40 个字符。

注意：此值用于生成扩展程序的实例 ID（该 ID 稍后用于生成扩展程序的服务账号及特定于扩展程序的资源的名称）。

version
字符串
（必填）

扩展程序的版本。

必须遵循 semver 版本控制（例如 1.2.0）。
specVersion
字符串
（必填）

Firebase Extensions 扩展程序规范的版本。

当前值：v1beta
license
字符串
（选填）

扩展程序的许可。

您的扩展程序必须遵循 Apache-2.0 许可条款。
billingRequired
布尔值
（选填）

扩展程序使用的服务是否需要付费层级 Firebase 结算账号。

一律设置为 true
displayName
字符串
（选填）

扩展程序的易记显示名（3-5 个字词）。

不能超过 40 个字符。
description
字符串
（选填） 		扩展程序执行的任务的简要说明（约 1 个句子）。
icon
字符串
（选填）

用作 extensions.dev 和 Firebase 控制台中的扩展程序图标的文件。

必须是大小介于 512x512 与 1024x1024 像素之间的方形 PNG 文件。请将该文件放在 extension.yaml 所在的目录中；不能指定子目录。

为扩展程序设计图标时，请遵循以下准则：

  • 选择适合您品牌的背景颜色和图形颜色。
  • 保持图标颜色简洁，请仅使用 2 种颜色。使用过多颜色可能会导致您的图标的视觉冲击力过强。
  • 出于同样的原因，请勿在图标中使用渐变色。渐变色会导致尺寸较小的图片难以辨别，并会使图标看起来很复杂。
  • 使用简明独特的图形来传达您的扩展程序的功能。
  • 如果贵公司构建了多个扩展程序，请不要将您的徽标用作图标；因为这样会导致用户很难区分您的扩展程序。
  • 使用形象醒目的图形。请勿使用过于精细或精致的图片，因为这类图片在尺寸较小时无法很好地呈现。
  • 请勿在图片中使用文字来说明您的扩展程序的用途；因为文字在较小尺寸的图片中通常难以辨认。
tags
字符串列表
（选填） 		可帮助用户发现您的扩展程序的标签。以下标签与 Extensions Hub 上的类别相对应：marketing、messaging、payments、search、shipping、social、utilities、ai
sourceUrl
字符串
（选填） 		可访问扩展程序目录的公开网址。
releaseNotesUrl
字符串
（选填） 		可访问扩展程序版本说明的公开网址。
author
一个 author 对象
（选填）

扩展程序的主要作者和联系人。

author:
  authorName: Your Company
  email: extensions@example.com
  url: https://example.com/
作者相关字段
authorName
字符串
（必填）

作者的姓名。

可以是个人、公司、组织等。
email
字符串
（选填） 		作者的电子邮件地址。
url
字符串
（选填） 		可访问作者信息的公开网址。
contributors
author 对象的列表
（选填）

扩展程序的任何其他创作贡献作者。

contributors:
  - authorName: Your Name
  - authorName: Another Contributor
    email: colleague@example.net
    url: https://github.com/their-org/
作者相关字段
authorName
字符串
（必填）

作者的姓名。

可以是个人、公司、组织等。
email
字符串
（选填） 		作者的电子邮件地址。
url
字符串
（选填） 		可访问作者信息的公开网址。

Firebase 和 Google Cloud API

这些字段指定扩展程序使用的 Firebase 和 Google API。用户安装扩展程序时，可以选择在项目中自动启用这些 API。

apis:
  - apiName: apiname.googleapis.com
    reason: Explanation of why the extension uses this API
  - apiName: anotherapiname.googleapis.com
    reason: Explanation of why the extension uses this API
API 相关字段
apiName
字符串
（必填）

Google API 的名称

必须与 Google Cloud API 库中每个 API 的概览页面（示例）中列出的“服务名称”字段相对应
reason
字符串
（必填） 		有关扩展程序为何需要使用此 API 的简要说明

IAM 角色

这些字段指定扩展程序所需的 Cloud IAM 角色。为扩展程序预配的服务账号将被授予这些角色。

您只能指定某个受支持的角色。

roles:
  - role: product.role
    reason: Explanation of why the extension needs this level of access
  - role: anotherproduct.role
    resource: projects/${project_id}/resource_type/*
    reason: Explanation of why the extension needs this level of access
角色相关字段
role
字符串
（必填）

运行扩展程序所需的 IAM 角色的名称

必须是某个受支持的角色
reason
字符串
（必填） 		有关扩展程序为何需要此角色授予的访问权限的简要说明
resource
字符串
（选填）

将角色权限范围限定在此资源。

如果省略，则默认为 projects/${project_id}。请参阅缩小角色授予的权限范围。

外部服务

这些字段指定扩展程序使用的非 Firebase 及非 Google 服务（通常是 REST API）。Firebase Extensions 平台不会提供任何自动启用这些服务或是为它们执行授权的方法。

externalServices:
  - name: Example API
    pricingUri: https://developers.example.com/pricing
  - name: Another Example API
    pricingUri: https://developers.example.com/pricing
外部服务相关字段
name
字符串
（必填） 		运行扩展程序所需的外部服务的名称
pricingUri
字符串
（必填） 		可访问服务价格信息的 URI

用户可配置的参数

这些字段定义了扩展程序可供用户配置的参数。

params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      What do you want to set PARAM_ID to?
      This is a longer description of the parameter, often phrased as a prompt
      to the user.
  - param: ANOTHER_PARAM_ID
    label: Short description of the parameter
    description: >
      What do you want to set ANOTHER_PARAM_ID to?
      This is a longer description of the parameter.
    example: example-input
    validationRegex: "^[a-zA-Z][a-zA-Z-]*[a-zA-Z]?$"
    validationErrorMessage:
      Must be a hyphen-delimited string of alphabetic characters
    default: default-value
    required: false
    immutable: true
参数相关字段
param
字符串
（必填） 		参数的名称。您可以在代码中使用此名称来引用参数值。
label
字符串
（必填） 		参数的简短说明。当系统提示用户输入参数值时向用户显示。
description
字符串
（选填）

参数的详细说明。当系统提示用户输入参数值时向用户显示。

支持 Markdown。
example
字符串
（选填） 		参数的示例值。
default
字符串
（选填） 		用户将参数的值留空时该参数的默认值。
validationRegex
字符串
（选填） 		用于验证参数的用户配置值的正则表达式。Google RE2 语法。
validationErrorMessage
字符串
（选填） 		正则表达式验证失败时显示的错误消息。
required
布尔值
（选填） 		定义当系统提示用户输入参数值时，用户是否可以提交空字符串。默认为 true。
immutable
布尔值
（选填）

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

注意：如果您要为已部署的扩展程序函数定义“location”参数，请将此字段设为 true。
type
字符串
（选填） 		参数类型。特殊参数类型可能有额外的要求或是有不同的界面呈现方式。详情请参阅以下各部分。

可选择的参数和可多选的参数

可选择的参数和可多选的参数会提示用户从预定义的选项列表中进行选择。

params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      Do you want to enable the option?
    type: select
    options:
      - label: Yes
        value: true
      - label: No
        value: false
  - param: ANOTHER_PARAM_ID
    label: Short description of the parameter
    description: >-
      Which options do you want to enable?
    type: multiselect
    options:
      - value: red
      - value: green
      - value: blue
参数选择相关字段
type
字符串

select 或 multiselect

指定该参数可以是从一组预定义的选项中选择的一个值 (select) 或多个值 (multiselect)
options
选项列表
（必填）

可供用户选择的选项

选项相关字段
value
字符串
（必填） 		用户可以选择的其中一个值。这是您在代码中读取参数值时将获得的值。
label
字符串
（选填） 		可供选择的选项的简短说明。如果省略，则默认为 value。

可选择的资源参数

可选择的资源参数会提示用户从其项目中选择资源（数据库实例、存储桶等）。

params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      Which resource do you want to use?
    type: selectresource
    resourceType: product.googleapis.com/ResourceType
资源参数相关字段
type
字符串

selectresource

指定参数代表项目资源
resourceType
字符串
（必填）

提示用户选择的资源类型。

有效值：

  • storage.googleapis.com/Bucket
  • firestore.googleapis.com/Database
  • firebasedatabase.googleapis.com/DatabaseInstance

不过，目前只有 Cloud Storage 存储桶有专用选择界面（其他资源类型显示为自由格式文本输入字段）。

Secret 参数

用户提供的 Secret 值（例如 API 密钥）的处理方式有所不同：

  • Secret 值使用 Cloud Secret Manager 进行存储。只有已获授权的客户端（例如已安装的扩展程序实例）才能访问这些值。
  • 当系统提示用户提供这些值时，他们的输入不会显示出来。
params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      What is the secret value?
    type: secret
Secret 参数相关字段
type
字符串

secret

指定参数是 Secret 值

Cloud Functions 函数资源

这些字段声明扩展程序中包含的 Cloud Functions 函数。第 1 代和第 2 代函数的资源声明语法看起来略有不同，但它们可以在一个扩展程序中共存。

第 1 代 Cloud Functions 函数

resources:
  - name: functionName
    type: firebaseextensions.v1beta.function
    description: >-
      Description of what the function does. (One or two
      sentences.)
    properties:
      runtime: runtime-version
      eventTrigger:
        eventType: google.product.event
        resource: projects/_/resource/specifier
资源相关字段
name
字符串
（必填）

导出的函数的易记名称。

如果您未指定 entryPoint 属性（请参阅下文），则此值必须与函数源代码中函数的名称匹配。

已部署函数的最终名称将采用以下格式：ext-extension-instance-id-name。
type
字符串
（必填） 		对于第 1 代函数资源：firebaseextensions.v1beta.function
description
字符串
（必填）

简要说明函数对扩展程序执行的任务。
properties
（必填）

第 1 代 Cloud Functions 函数的属性。下面列出了一些最重要的属性，不过，您也可以在 Cloud Functions 参考文档中找到完整列表。

属性
location
（选填）

部署函数的位置。默认为 us-central1
entryPoint
（选填） 		扩展程序应在函数源代码中查找的已导出函数的名称。默认为前面 name 的值。
sourceDirectory
（选填）

在根目录下包含 package.json 的目录。函数源代码文件必须位于此目录中。默认为 functions

注意：package.json 的 main 字段指定函数源代码文件（如 index.js）。
timeout
（选填）

函数的执行时长上限。

  • 默认值：60s
  • 最大值：540s
availableMemoryMb
（选填）

可供此函数使用的内存量（以 MB 为单位）。

  • 默认值：256
  • 有效值：128、256、512、1024 和 2048
runtime
（推荐使用）

函数的运行时环境。
httpsTrigger
、
eventTrigger
、
scheduleTrigger
或
taskQueueTrigger
（必须为其中一种函数触发器类型） 		如需详细了解每种触发器类型，请参阅为扩展程序编写 Cloud Functions 函数。

第 2 代 Cloud Functions 函数

resources:
  - name: functionName
    type: firebaseextensions.v1beta.v2function
    description: >-
      Description of what the function does. (One or two
      sentences.)
    properties:
      buildConfig:
        runtime: nodejs16
      serviceConfig:
        availableMemory: 512M
      eventTrigger:
        eventType: google.firebase.firebasealerts.alerts.v1.published
        triggerRegion: global
        eventFilters:
          - attribute: alerttype
            value: crashlytics.newFatalIssue
资源相关字段
name
字符串
（必填）

导出的函数的易记名称。

如果您未指定 entryPoint 属性（请参阅下文），则此值必须与函数源代码中函数的名称匹配。

已部署函数的最终名称将采用以下格式：ext-extension-instance-id-name。
type
字符串
（必填） 		对于第 2 代函数资源：firebaseextensions.v1beta.v2function
description
字符串
（必填）

简要说明函数对扩展程序执行的任务。
properties
（必填）

第 2 代 Cloud Functions 函数的属性。下面列出了一些最重要的属性，不过，您也可以在 Cloud Functions 参考文档中找到完整列表。

属性
location
（选填）

部署函数的位置。默认为 us-central1
sourceDirectory
（选填）

在根目录下包含 package.json 的目录。函数源代码文件必须位于此目录中。默认为 functions

注意：package.json 的 main 字段指定函数源代码文件（如 index.js）。

此外，还有三个对象类型字段有自己专用的属性：

buildConfig 属性
buildConfig.runtime
（推荐使用）

函数的运行时环境。
buildConfig.entryPoint
（选填） 		扩展程序应在函数源代码中查找的已导出函数的名称。默认为前面 name 的值。
serviceConfig 属性
serviceConfig.timeoutSeconds
（选填）

函数的执行时长上限。

  • 默认值：60
  • 最大值：540
serviceConfig.availableMemory
（选填） 		可供函数使用的内存量。默认为 256M。支持的单位包括 k、M、G、Mi、Gi。如果未提供单位，则值默认以字节为单位。
eventTrigger 属性
eventTrigger.eventType
（必填） 		要监听的事件的类型。如需了解每种产品可用的事件类型，请参阅为扩展程序编写 Cloud Functions 函数。
eventTrigger.eventFilters
（选填） 		进一步限制要监听的事件的过滤条件。例如，您可以仅监听与特定资源模式匹配的事件。如需了解如何过滤每种类型的事件，请参阅为扩展程序编写 Cloud Functions 函数。
eventTrigger.channel
（选填） 		与触发器关联的渠道的名称，采用 projects/{project}/locations/{location}/channels/{channel} 格式。如果省略此属性，函数将监听项目默认渠道上的事件。
eventTrigger.triggerRegion
（选填） 		触发器将仅接收源自此区域的事件。该区域可以是函数所在区域，也可以是其他区域，甚至是多区域或全球区域。如果未提供，则默认为函数所在区域。

生命周期事件

借助生命周期事件，您可以指定在用户安装、更新或配置扩展程序实例时运行的函数。 请参阅处理扩展程序的生命周期事件。

lifecycleEvents:
  onInstall:
    function: myTaskFunction
    processingMessage: Describes the task being completed
  onUpdate:
    function: myOtherTaskFunction
    processingMessage: Describes the task being completed
  onConfigure:
    function: myOtherTaskFunction
    processingMessage: Describes the task being completed
生命周期事件相关字段
onInstall
（选填）

指定在用户安装扩展程序时运行的函数。

函数规范
function
字符串
（必填）

负责处理事件的任务队列触发的函数的名称。

必须在 resources 部分声明该函数，并定义 taskQueue。
processingMessage
字符串
（必填） 		任务执行期间，显示在 Firebase 控制台中的消息。
onUpdate
（选填）

指定在用户更新扩展程序时运行的函数。

函数规范
function
字符串
（必填）

负责处理事件的任务队列触发的函数的名称。

必须在 resources 部分声明该函数，并定义 taskQueue。
processingMessage
字符串
（必填） 		任务执行期间，显示在 Firebase 控制台中的消息。
onConfigure
（选填）

指定在用户重新配置扩展程序时运行的函数。

函数规范
function
字符串
（必填）

负责处理事件的任务队列触发的函数的名称。

必须在 resources 部分声明该函数，并定义 taskQueue。
processingMessage
字符串
（必填） 		任务执行期间，显示在 Firebase 控制台中的消息。

自定义事件 (Eventarc)

自定义事件是您的扩展程序发出的事件，让用户可以将自己的逻辑插入到您的扩展程序中。请参阅向扩展程序添加用户钩子中的 Eventarc 部分。

events:
  - type: publisher-id.extension-name.version.event-name
    description: Description of the event
  - type: publisher-id.extension-name.version.another-event-name
    description: Description of the other event
自定义事件相关字段
type
字符串
（必填） 		事件的类型标识符。使用 3-4 个由英文句点分隔的字段来构建标识符：发布商 ID、扩展程序名称和事件名称字段是必选项；另外建议选用版本字段。为您发布的每种事件类型选择一个唯一的描述性事件名称。
description
字符串
（必填） 		事件说明。