擴充功能的規格檔案 (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 規格的版本。 目前的值： |
||||||||
licensestring (選填) |
擴充功能的授權。 您的擴充功能必須使用 |
||||||||
billingRequiredboolean (選用) |
擴充功能所使用的服務是否需要付費層級的 Firebase 帳單帳戶。 一律設為 |
||||||||
displayNamestring (選填) |
擴充功能的友善顯示名稱 (3 到 5 個字詞)。 長度上限為 40 個半形字元。 |
||||||||
descriptionstring (選填) |
簡要說明擴充功能執行的工作 (約 1 句話)。 | ||||||||
iconstring (選填) |
在 這個檔案必須是正方形 PNG，大小介於 512x512 和 1024x1024 像素之間。
將檔案放在 設計擴充功能圖示時，請遵守下列規範：
|
||||||||
tags字串清單 (選用) |
標記可協助使用者發現擴充功能。
下列標記會對應至擴充功能中心的類別：marketing、messaging、payments、search、shipping、social、utilities、ai
|
||||||||
sourceUrlstring (選填) |
可存取擴充功能目錄的公開網址。 | ||||||||
releaseNotesUrlstring (選填) |
可存取擴充功能版本資訊的公開網址。 | ||||||||
author一個作者物件 (選用) |
擴充功能的主要作者和聯絡窗口。 author: authorName: Your Company email: extensions@example.com url: https://example.com/
|
||||||||
contributors作者物件清單 (選用) |
擴充功能的其他作者。 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
| API 欄位 | |
|---|---|
apiName字串 (必要) |
Google API 名稱 必須與 Google Cloud API 程式庫 中各個 API 總覽頁面 (示例) 所列的「Service name」欄位相符 |
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字串 (必要) |
簡要說明擴充功能為何需要由此角色授予的存取權 |
resourcestring (選填) |
將角色的範圍限制在這項資源。 如果省略此屬性，系統會預設為 |
外部服務
這些欄位會指定擴充功能使用的非 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
| 外部服務欄位 | |
|---|---|
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字串 (必要) |
參數的簡短說明。當系統提示使用者輸入參數值時，會向使用者顯示這項資訊。 |
descriptionstring (選填) |
參數的詳細說明。當系統提示使用者輸入參數值時，會向使用者顯示這項資訊。 支援 Markdown。 |
examplestring (選填) |
參數值範例。 |
defaultstring (選填) |
如果使用者將參數值留空，則該參數的預設值。 |
validationRegexstring (選填) |
用於驗證參數的使用者設定值的規則運算式。Google RE2 語法。 |
validationErrorMessagestring (選填) |
如果規則運算式驗證失敗，系統會顯示這項錯誤訊息。 |
requiredboolean (選用) |
定義使用者在系統提示輸入參數值時，是否可以提交空字串。預設值為 true。 |
immutableboolean (選用) |
定義使用者是否可以在安裝後變更參數值 (例如重新設定擴充功能)。預設值為 注意：如果您為擴充功能的已部署函式定義「位置」參數，請將這個欄位設為 |
typestring (選填) |
參數類型。特殊參數類型可能會有額外規定或不同的 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字串 |
指定參數可從一組預先定義的選項中選取一個值 ( |
||||||
options選項清單 (必填) |
使用者可選擇的選項
|
||||||
可選取的資源參數
可選取的資源參數會提示使用者從專案中選取資源 (資料庫執行個體、儲存空間 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
| 資源參數欄位 | |
|---|---|
type字串 |
指定參數代表專案資源 |
resourceType字串 (必要) |
系統要提示使用者選取的資源類型。 有效值：
不過，目前只有 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字串 |
指定參數為密鑰值 |
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字串 (必要) |
匯出函式的使用者友善名稱。 如果您未指定 部署函式的最終名稱會採用以下格式： |
||||||||||||||||
type字串 (必要) |
第 1 代函式資源：
firebaseextensions.v1beta.function
|
||||||||||||||||
description字串 (必要) |
簡要說明函式為擴充功能執行的任務。 |
||||||||||||||||
properties(必要) |
第 1 代 Cloud Functions 資源。以下列出最重要的屬性，但您可以在 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字串 (必要) |
匯出函式的使用者友善名稱。 如果您未指定 部署函式的最終名稱會採用以下格式： |
||||||||||||||||||||||||||||
type字串 (必要) |
第 2 代函式資源：
firebaseextensions.v1beta.v2function
|
||||||||||||||||||||||||||||
description字串 (必要) |
簡要說明函式為擴充功能執行的任務。 |
||||||||||||||||||||||||||||
properties(必要) |
第 2 代 Cloud Functions 屬性。以下列出最重要的屬性，但您可以在 Cloud Functions 參考資料中找到完整清單。
另外還有三個物件類型欄位，各自具有以下屬性：
|
||||||||||||||||||||||||||||
生命週期事件
生命週期事件可讓您指定在使用者安裝、更新或設定擴充功能的例項時執行的函式。請參閱「處理擴充功能的生命週期事件」。
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(選填) |
指定使用者安裝擴充功能時執行的函式。
|
||||||
onUpdate(選填) |
指定使用者更新擴充功能時執行的函式。
|
||||||
onConfigure(選填) |
指定使用者重新設定擴充功能時要執行的函式。
|
||||||
自訂事件 (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字串 (必要) |
事件的類型 ID。使用 3 到 4 個以點號分隔的欄位建立 ID：發布商 ID、擴充功能名稱和事件名稱欄位為必填欄位；建議使用版本欄位。請為每個發布的事件類型選擇不重複且具描述性的事件名稱。 |
description字串 (必要) |
事件的說明。 |