擴充功能的規格檔案 (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 規格的版本。 目前的值： |
||||||||
license字串 (選用) |
擴充功能的授權。 你的擴充功能必須使用 |
||||||||
billingRequired布林值 (選用) |
擴充功能使用的服務是否需要付費層級的 Firebase 帳單帳戶。 一律設為 |
||||||||
displayName字串 (選用) |
方便使用的擴充功能顯示名稱 (3 到 5 個字)。 長度上限為 40 個半形字元。 |
||||||||
description字串 (選用) |
擴充功能所執行工作工作的簡短說明 (約 1 句)。 | ||||||||
icon字串 (選用) |
要在 此檔案必須是介於 512 x 512 至 1024 x 1024 像素之間的正方形 PNG。將檔案放在與 為擴充功能設計圖示時，請謹記下列規範：
|
||||||||
tags字串清單 (選用) |
協助使用者找到擴充功能的標記。以下標記會對應至 Extensions Hub 中的類別：marketing、messaging、payments、search、shipping、social、utilities、ai |
||||||||
sourceUrl字串 (選用) |
可以存取擴充功能目錄的公開網址。 | ||||||||
releaseNotesUrl字串 (選用) |
公開網址，可以存取擴充功能的版本資訊。 | ||||||||
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 總覽頁面 (範例) 中列出的「服務名稱」欄位一致 |
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字串 (選用) |
限制這個資源的角色範圍。 省略時，會預設為 |
外部服務
這些欄位會指定擴充功能使用的非 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布林值 (選用) |
定義使用者在安裝後是否可以變更參數值 (例如使用者重新設定擴充功能時)。預設值為 注意：如果要為已部署的擴充功能函式定義「location」參數，請將這個欄位設為 |
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字串 |
指定參數可以是單一值 ( |
||||||
options選項清單 (必填) |
可供使用者選擇的選項
|
||||||
可選取的資源參數
可選取的資源參數會提示使用者從專案中選取資源 (資料庫執行個體、儲存值區等)。
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字串 (必填) |
事件說明。 |