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/
基本欄位
name
字串
(必填)

擴充功能的 ID。

只能由小寫英文字母、數字和破折號組成；40 個半形字元 我們會自動向帳單帳戶扣款 並每月或在您達到用量上限時發送帳單

注意：這個值用於產生擴充功能的 執行個體 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 控制台。

此檔案必須是介於 512 x 512 至 1024 x 1024 像素之間的正方形 PNG。 將檔案放在與 extension.yaml 相同的目錄中。你 無法指定子目錄。

為您的 副檔名：

  • 選取合適的背景和藝術作品顏色 品牌
  • 僅使用 2 種顏色，讓圖示顏色保持精簡。多種顏色 讓您的圖示在視覺上看起來吃力
  • 基於相同理由，請勿在圖示中使用漸層。漸層 使圖示難以辨識 複雜的
  • 使用簡單獨特的圖像傳達擴充功能的 功能。
  • 要是貴公司建立了多項額外資訊，請不要將標誌 圖示。使用者無法區分您的 。
  • 將圖片設為粗體。請勿使用細緻或精細的商標 因為如果圖片較小 可能無法在較小的螢幕上順利顯示
  • 不要加入能說明擴充功能用途的字詞。文字為 因為較小的尺寸往往難以辨識
tags
字串清單
(選答) 		協助使用者找到您的擴充功能的標籤。 以下標記會對應至 Extensions Hub 中的類別： marketing, messaging, payments, search, shipping, social, utilities, ai
sourceUrl
字串
(選答) 		可以存取擴充功能目錄的公開網址。
releaseNotesUrl
字串
(選答) 		公開網址，使用者可以存取擴充功能的版本資訊。
author
1 個作者物件
(選答)

擴充功能的主要作者和聯絡窗口。

author:
  authorName: Your Company
  email: extensions@example.com
  url: https://example.com/
作者欄位
authorName
字串
(必填)

作者的名稱。

可以是個人、公司或機構等。
email
字串
(選答) 		作者的電子郵件地址。
url
字串
(選答) 		可供存取作者資訊的公開網址。
contributors
作者物件清單
(選答)

其他提供擴充功能的作者。

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。當使用者 安裝擴充功能後，他們就可以在 他們的專案

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 的名稱

必須與每個「服務名稱」欄位 (如每個欄位所示) API 的總覽頁面 (範例) 的 Google Cloud 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。

注意：如果定義「位置」要部署的 函式，請將這個欄位設為 true。
type
字串
(選答) 		參數類型。特殊參數類型可能有 或是不同的 UI 呈現方式請參閱下列各節。

可選取和可選取的參數

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

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。

可選取的資源參數

可選取的資源參數會提示使用者選取資源 (資料庫) 和 Storage 值區等)

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 值區提供選項 UI (其他資源類型會顯示為任意形式的文字輸入欄位)。

密鑰參數

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

  • 密鑰值使用 Cloud Secret Manager 儲存。僅限獲得授權的用戶端 (例如擴充功能已安裝的執行個體) 可以存取這些值。
  • 當使用者提示你提供這些值時，系統不會顯示他們的輸入內容。
params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      What is the secret value?
    type: secret
密鑰參數欄位
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
資源欄位
name
字串
(必填)

匯出函式易記的名稱。

如果未指定 entryPoint 屬性 (請參閱 )，此值必須與您 函式原始碼。

deployed 函式的最終名稱會在 格式如下： ext-extension-instance-id-name。
type
字串
(必填) 		第 1 代函式資源： firebaseextensions.v1beta.function
description
字串
(必填)

簡短說明函式會對 。
properties
(必填)

第 1 代 Cloud Functions 屬性最重要的屬性 完整政策列於下方 雲端 函式參考資料。

資源
location
(選答)

部署函式的位置。預設為 us-central1
entryPoint
(選答) 		在函式原始碼中匯出的函式名稱 所有內容預設值為 name (上方)。
sourceDirectory
(選答)

內含您的 package.json 的目錄 根目錄。函式原始碼的檔案必須放在 目錄。預設為 functions

注意：main package.json 會指定 函式原始碼 (例如 index.js)。
timeout
(選答)

函式的執行時間上限。

  • 預設：60s
  • 最大值：540s
availableMemoryMb
(選答)

函式可用的記憶體量 (以 MB 為單位)。

  • 預設：256
  • 有效值：128、256、 512、1024 和 2048
runtime
(建議)

函式的執行階段環境。
httpsTrigger
或
eventTrigger
或
scheduleTrigger
或
taskQueueTrigger
(必須提供以下其中一種函式觸發條件類型) 		請參閱 Write 適用於擴充功能的 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 屬性 (請參閱 )，此值必須與您 函式原始碼。

deployed 函式的最終名稱會在 格式如下： ext-extension-instance-id-name。
type
字串
(必填) 		第 2 代函式資源： firebaseextensions.v1beta.v2function
description
字串
(必填)

簡短說明函式會對 。
properties
(必填)

第 2 代 Cloud Functions 屬性最重要的屬性 完整政策列於下方 雲端 函式參考資料。

資源
location
(選答)

部署函式的位置。預設為 us-central1
sourceDirectory
(選答)

內含您的 package.json 的目錄 根目錄。函式原始碼的檔案必須放在 目錄。預設為 functions

注意：main package.json 會指定 函式原始碼 (例如 index.js)。

此外還有三個物件類型欄位，具有各自的屬性：

buildConfig 屬性
buildConfig.runtime
(建議)

函式的執行階段環境。
buildConfig.entryPoint
(選答) 		在函式原始碼中匯出的函式名稱 所有內容預設值為 name (上方)。
serviceConfig 屬性
serviceConfig.timeoutSeconds
(選答)

函式的執行時間上限。

  • 預設：60
  • 最大值：540
serviceConfig.availableMemory
(選答) 		函式可用的記憶體量。預設為 256M。支援的單位為 k。 M、G、Mi、 Gi。 如未提供單位，系統會將值解讀為位元組。
eventTrigger 屬性
eventTrigger.eventType
(必填) 		要監聽的事件類型。詳情請見 寫入雲端 適用於擴充功能的事件類型函式 每項產品
eventTrigger.eventFilters
(選答) 		進一步限制監聽事件的篩選器。例如： 您只能監聽與特定資源相符的事件 。詳情請見 寫入雲端 適用於擴充功能的函式，用於篩選各個擴充功能 事件類型。
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)

自訂事件是指擴充功能引發的事件，能讓使用者插入 自己的擴充功能請參閱 將使用者掛鉤新增至擴充功能。

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
字串
(必填) 		事件類型 ID。以 3-4 的格式建立 ID 以點分隔的欄位：發布商 ID、擴充功能名稱和事件名稱 必填欄位；建議版本欄位選擇不重複的名稱 並為發布的每種事件類型提供描述性的事件名稱
description
字串
(必填) 		活動說明。