您的擴充功能的規格檔案 ( 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 細繩 (必需的) | 擴展名的標識符。 只能包含小寫字母、數字和破折號; 40 個字元限制。 注意:此值用於產生擴充功能的實例 ID(然後用於產生擴充功能的服務帳戶和特定於擴充功能的資源的名稱)。 | ||||||||
version 細繩 (必需的) | 擴充的版本。 必須遵循 semver 版本控制(例如 1.2.0)。 | ||||||||
specVersion 細繩 (必需的) | Firebase 擴充規範的版本。 目前值: | ||||||||
license 細繩 (選修的) | 擴展許可。 您的擴充功能必須使用 | ||||||||
billingRequired 布林值 (選修的) | 擴充功能使用的服務是否需要付費 Firebase 計費帳戶。 始終設定為 | ||||||||
displayName 細繩 (選修的) | 擴充功能的友善顯示名稱(3-5 個單字)。 40 個字元限制。 | ||||||||
description 細繩 (選修的) | 您的擴充程式執行的任務的簡要描述(約 1 句話)。 | ||||||||
icon 細繩 (選修的) | 用作 此檔案必須是 512x512 到 1024x1024 像素之間的方形 PNG。將檔案放在與 為您的擴充功能設計圖示時,請記住以下準則:
| ||||||||
tags 字串列表 (選修的) | 幫助用戶發現您的擴充功能的標籤。以下標籤對應到擴展中心上的類別: marketing 、 messaging 、 payments 、 search 、 shipping 、 social 、實用utilities 、 ai | ||||||||
sourceUrl 細繩 (選修的) | 可以存取擴充目錄的公共 URL。 | ||||||||
releaseNotesUrl 細繩 (選修的) | 可以存取擴充的發行說明的公共 URL。 | ||||||||
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 細繩 (選修的) | 用於驗證參數的使用者配置值的正規表示式。谷歌 RE2 語法。 |
validationErrorMessage 細繩 (選修的) | 如果正規表示式驗證失敗則顯示錯誤訊息。 |
required 布林值 (選修的) | 定義當提示使用者輸入參數值時是否可以提交空字串。預設為true 。 |
immutable 布林值 (選修的) | 定義使用者是否可以在安裝後更改參數的值(例如,如果他們重新配置擴充功能)。預設為 注意:如果您為擴充功能的已部署功能定義「位置」參數,請將此欄位設為 |
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 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 細繩 (必需的) | 對於第一代函數資源: firebaseextensions.v1beta.function | ||||||||||||||||
description 細繩 (必需的) | 簡要描述函數為擴展執行什麼任務。 | ||||||||||||||||
properties (必需的) | 第一代 Cloud Functions 屬性。下面列出了最重要的屬性,但您可以在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 細繩 (必需的) | 對於第二代函數資源: firebaseextensions.v1beta.v2function | ||||||||||||||||||||||||||||
description 細繩 (必需的) | 函數為擴展執行什麼任務的簡要描述。 | ||||||||||||||||||||||||||||
properties (必需的) | 第二代 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 細繩 (必需的) | 事件的類型標識符。以 3-4 個點分隔的欄位建構標識符:發布者 ID、副檔名和事件名稱欄位是必需的;建議使用版本字段。為您發佈的每種事件類型選擇一個唯一且具有描述性的事件名稱。 |
description 細繩 (必需的) | 事件描述。 |