Extensions.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/

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/

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

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

外部服務

這些欄位會指定擴充功能使用的非 Firebase 和非 Google 服務 (通常為 REST API)。Firebase 擴充功能平台並未提供任何方法，可自動啟用或執行這些服務的授權。

externalServices:
  - name: Example API
    pricingUri: https://developers.example.com/pricing
  - name: Another Example API
    pricingUri: https://developers.example.com/pricing

使用者可設定的參數

這些欄位會定義擴充功能可供使用者設定的參數。

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

可選取和可多選參數

可選取和多選參數會提示使用者從預先定義的選項清單中選擇。

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

可選取的資源參數

可選取的資源參數會提示使用者從專案中選取資源 (資料庫執行個體、儲存空間 bucket 等)。

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

密鑰參數

使用者提供的機密值 (例如 API 金鑰) 會以不同的方式處理：

• 密鑰值會使用 Cloud Secret Manager 儲存。只有經過授權的用戶端 (例如已安裝的擴充功能例項) 可以存取這些值。
• 當系統提示使用者提供這些值時，系統不會顯示使用者輸入的內容。

params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      What is the secret value?
    type: secret

Cloud 函式資源

這些欄位會宣告擴充功能中包含的 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

第 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

生命週期事件

生命週期事件可讓您指定在使用者安裝、更新或設定擴充功能的例項時執行的函式。請參閱「處理擴充功能的生命週期事件」。

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

自訂事件 (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