擴充功能的規格檔案 (extension.yaml) 包含擴充功能的 metadata，宣告擴充功能建立的資源，以及擴充功能所需的 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字串 (必要) |
擴充功能版本。 必須遵循語意化版本控管 (例如 1.2.0)。 |
||||||||
specVersion字串 (必要) |
Firebase Extensions 規格版本。 目前值： |
||||||||
license字串 (選填) |
擴充功能的授權。 擴充功能必須使用 |
||||||||
billingRequired布林值 (選填) |
擴充功能使用的服務是否需要付費層級的 Firebase 帳單帳戶。 一律設為 |
||||||||
displayName字串 (選填) |
擴充功能的友善顯示名稱 (3 到 5 個字)。 長度上限為 40 個半形字元。 |
||||||||
description字串 (選填) |
擴充功能執行的工作簡短說明 (約 1 句話)。 | ||||||||
icon字串 (選填) |
在 這個檔案必須是正方形 PNG，大小介於 512x512 至 1024x1024 像素。
將檔案放在與 設計擴充功能的圖示時，請遵守下列規範：
|
||||||||
tags字串清單 (選用) |
標記，協助使用者探索擴充功能。
下列標記會對應至擴充功能中心上的類別：
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 名稱 必須與每個 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字串 (選填) |
將角色的範圍限制為這項資源。 如果省略此屬性，系統會預設為 |
外部服務
這些欄位會指定擴充功能使用的非 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字串 (選填) |
如果 regex 驗證失敗，要顯示的錯誤訊息。 |
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選項清單 (必填) |
使用者可選擇的選項
|
||||||
可選取的資源參數
可選取的資源參數會提示使用者從專案中選取資源 (資料庫執行個體、儲存空間 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字串 (必要) |
活動說明。 |