Tệp thông số tiện ích mở rộng của bạn ( extension.yaml
) chứa siêu dữ liệu của tiện ích mở rộng của bạn, khai báo các tài nguyên được tạo bởi tiện ích mở rộng và các API cũng như quyền truy cập mà tiện ích mở rộng yêu cầu, đồng thời xác định mọi tham số do người dùng định cấu hình do tiện ích mở rộng cung cấp.
Các bảng trên trang này mô tả các trường có sẵn cho tệp extension.yaml
.
Thông tin cơ bản và nhận dạng
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/
Các trường cơ bản | |||||||||
---|---|---|---|---|---|---|---|---|---|
name sợi dây (yêu cầu) | Mã định danh cho phần mở rộng. Chỉ có thể chứa chữ thường, số và dấu gạch ngang; Giới hạn 40 ký tự. Lưu ý: Giá trị này được sử dụng để tạo ID phiên bản của tiện ích mở rộng (sau đó được sử dụng để tạo tên tài khoản dịch vụ của tiện ích mở rộng và tài nguyên dành riêng cho tiện ích mở rộng). | ||||||||
version sợi dây (yêu cầu) | Phiên bản của phần mở rộng. Phải tuân theo phiên bản học kỳ (ví dụ: 1.2.0). | ||||||||
specVersion sợi dây (yêu cầu) | Phiên bản đặc tả Tiện ích mở rộng Firebase. Giá trị hiện tại: | ||||||||
license sợi dây (không bắt buộc) | Giấy phép cho phần mở rộng. Tiện ích mở rộng của bạn phải được cấp phép sử dụng | ||||||||
billingRequired boolean (không bắt buộc) | Liệu các dịch vụ mà tiện ích mở rộng sử dụng có yêu cầu tài khoản thanh toán Firebase trả phí hay không. Luôn được đặt thành | ||||||||
displayName sợi dây (không bắt buộc) | Tên hiển thị thân thiện cho tiện ích mở rộng (3-5 từ). Giới hạn 40 ký tự. | ||||||||
description sợi dây (không bắt buộc) | Mô tả ngắn gọn về nhiệm vụ mà tiện ích mở rộng của bạn thực hiện (~1 câu). | ||||||||
icon sợi dây (không bắt buộc) | Tệp để sử dụng làm biểu tượng tiện ích mở rộng của bạn trên Tệp này phải là hình vuông PNG có kích thước từ 512x512 đến 1024x1024 pixel. Đặt tệp vào cùng thư mục với Hãy ghi nhớ các nguyên tắc sau khi thiết kế biểu tượng cho tiện ích mở rộng của bạn:
| ||||||||
tags danh sách các chuỗi (không bắt buộc) | Thẻ để giúp người dùng khám phá tiện ích mở rộng của bạn. Các thẻ sau ánh xạ tới các danh mục trên Trung tâm tiện ích mở rộng: marketing , messaging , payments , search , shipping , social , utilities , ai | ||||||||
sourceUrl sợi dây (không bắt buộc) | URL công khai nơi thư mục tiện ích mở rộng có thể được truy cập. | ||||||||
releaseNotesUrl sợi dây (không bắt buộc) | URL công khai nơi có thể truy cập ghi chú phát hành của tiện ích mở rộng. | ||||||||
author một đối tượng tác giả (không bắt buộc) | Tác giả chính và người liên hệ cho phần mở rộng. author: authorName: Your Company email: extensions@example.com url: https://example.com/
| ||||||||
contributors danh sách đối tượng tác giả (không bắt buộc) | Bất kỳ tác giả đóng góp bổ sung nào cho phần mở rộng. contributors: - authorName: Your Name - authorName: Another Contributor email: colleague@example.net url: https://github.com/their-org/
|
API Firebase và Google Cloud
Các trường này chỉ định API Firebase và Google mà tiện ích mở rộng sử dụng. Khi người dùng cài đặt tiện ích mở rộng, họ có thể chọn tự động bật các API này trong dự án của mình.
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
trường API | |
---|---|
apiName sợi dây (yêu cầu) | Tên của API Google Phải tương ứng với trường Tên dịch vụ như được liệt kê trên trang tổng quan của từng API ( ví dụ ) trong Thư viện API Google Cloud |
reason sợi dây (yêu cầu) | Mô tả ngắn gọn lý do tiện ích mở rộng cần sử dụng API này |
Vai trò IAM
Các trường này chỉ định vai trò Cloud IAM mà tiện ích mở rộng yêu cầu. Tài khoản dịch vụ được cung cấp cho tiện ích mở rộng sẽ được cấp các vai trò này.
Bạn chỉ có thể chỉ định một trong các vai trò được hỗ trợ .
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
Các trường vai trò | |
---|---|
role sợi dây (yêu cầu) | Tên của vai trò IAM cần thiết để tiện ích mở rộng hoạt động Phải là một trong những vai trò được hỗ trợ |
reason sợi dây (yêu cầu) | Mô tả ngắn gọn lý do tại sao tiện ích mở rộng cần quyền truy cập do vai trò này cấp |
resource sợi dây (không bắt buộc) | Giới hạn phạm vi của vai trò đối với tài nguyên này. Nếu bị bỏ qua, mặc định là |
Dịch vụ bên ngoài
Các trường này chỉ định các dịch vụ không phải của Firebase và không phải của Google mà tiện ích mở rộng sử dụng (thường là API REST). Nền tảng Tiện ích mở rộng Firebase không cung cấp bất kỳ phương tiện nào để tự động bật hoặc thực hiện ủy quyền cho các dịch vụ này.
externalServices:
- name: Example API
pricingUri: https://developers.example.com/pricing
- name: Another Example API
pricingUri: https://developers.example.com/pricing
Lĩnh vực dịch vụ bên ngoài | |
---|---|
name sợi dây (yêu cầu) | Tên của dịch vụ bên ngoài cần thiết để tiện ích mở rộng hoạt động |
pricingUri sợi dây (yêu cầu) | URI tới thông tin về giá của dịch vụ |
Các thông số do người dùng cấu hình
Các trường này xác định các tham số mà tiện ích mở rộng cung cấp cho người dùng định cấu hình.
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
Các trường thông số | |
---|---|
param sợi dây (yêu cầu) | Tên của tham số. Bạn sử dụng tên này để tham chiếu giá trị tham số trong mã. |
label sợi dây (yêu cầu) | Mô tả ngắn gọn cho tham số. Hiển thị cho người dùng khi họ được nhắc về giá trị của tham số. |
description sợi dây (không bắt buộc) | Mô tả chi tiết cho tham số. Hiển thị cho người dùng khi họ được nhắc về giá trị của tham số. Hỗ trợ Markdown. |
example sợi dây (không bắt buộc) | Giá trị ví dụ cho tham số. |
default sợi dây (không bắt buộc) | Giá trị mặc định cho tham số nếu người dùng để trống giá trị của tham số. |
validationRegex sợi dây (không bắt buộc) | Biểu thức chính quy để xác thực giá trị do người dùng định cấu hình của tham số. Cú pháp Google RE2 . |
validationErrorMessage sợi dây (không bắt buộc) | Thông báo lỗi hiển thị nếu xác thực biểu thức chính quy không thành công. |
required boolean (không bắt buộc) | Xác định xem người dùng có thể gửi chuỗi trống hay không khi họ được nhắc nhập giá trị của tham số. Mặc định là true . |
immutable boolean (không bắt buộc) | Xác định xem người dùng có thể thay đổi giá trị của tham số sau khi cài đặt hay không (chẳng hạn như nếu họ định cấu hình lại tiện ích mở rộng). Mặc định là Lưu ý: Nếu bạn xác định tham số "vị trí" cho các chức năng được triển khai của tiện ích mở rộng của mình, hãy đặt trường này thành |
type sợi dây (không bắt buộc) | Kiểu tham số. Các loại tham số đặc biệt có thể có các yêu cầu bổ sung hoặc cách trình bày giao diện người dùng khác nhau. Xem các phần sau. |
Các thông số có thể lựa chọn và đa lựa chọn
Các tham số có thể lựa chọn và nhiều lựa chọn sẽ nhắc người dùng chọn từ danh sách các tùy chọn được xác định trước.
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
Các trường tham số trắc nghiệm | |||||||
---|---|---|---|---|---|---|---|
type sợi dây | Chỉ định rằng tham số có thể là một giá trị ( | ||||||
options danh sách các lựa chọn (yêu cầu) | Các tùy chọn mà người dùng có thể chọn
|
Các tham số tài nguyên có thể lựa chọn
Các tham số tài nguyên có thể lựa chọn sẽ nhắc người dùng chọn tài nguyên (phiên bản cơ sở dữ liệu, nhóm lưu trữ, v.v.) từ dự án của họ.
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
Các trường tham số tài nguyên | |
---|---|
type sợi dây | Chỉ định rằng tham số đại diện cho tài nguyên dự án |
resourceType sợi dây (yêu cầu) | Loại tài nguyên để nhắc người dùng chọn. Giá trị hợp lệ:
Tuy nhiên, hiện chỉ có các nhóm Cloud Storage mới có giao diện người dùng lựa chọn (các loại tài nguyên khác được trình bày dưới dạng trường nhập văn bản dạng tự do). |
Thông số bí mật
Các giá trị bí mật do người dùng cung cấp (chẳng hạn như khóa API) được xử lý khác nhau:
- Các giá trị bí mật được lưu trữ bằng Cloud Secret Manager. Chỉ những khách hàng được ủy quyền (chẳng hạn như phiên bản đã cài đặt của tiện ích mở rộng) mới có thể truy cập các giá trị này.
- Khi người dùng được nhắc cung cấp các giá trị này, thông tin đầu vào của họ sẽ không được hiển thị.
params:
- param: PARAM_ID
label: Short description of the parameter
description: >-
What is the secret value?
type: secret
Trường tham số bí mật | |
---|---|
type sợi dây | Chỉ định rằng tham số là một giá trị bí mật |
Tài nguyên chức năng đám mây
Các trường này khai báo các Chức năng đám mây có trong tiện ích mở rộng. Cú pháp khai báo tài nguyên có vẻ hơi khác một chút giữa các hàm thế hệ 1 và thế hệ 2, những hàm này có thể cùng tồn tại trong một phần mở rộng.
Chức năng đám mây thế hệ 1
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
Trường tài nguyên | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
name sợi dây (yêu cầu) | Tên thân thiện với người dùng cho chức năng xuất. Nếu bạn không chỉ định thuộc tính Tên cuối cùng của chức năng được triển khai sẽ có định dạng sau: | ||||||||||||||||
type sợi dây (yêu cầu) | Đối với tài nguyên hàm thế hệ 1: firebaseextensions.v1beta.function | ||||||||||||||||
description sợi dây (yêu cầu) | Mô tả ngắn gọn về nhiệm vụ mà hàm thực hiện cho tiện ích mở rộng. | ||||||||||||||||
properties (yêu cầu) | Thuộc tính Chức năng đám mây thế hệ 1. Các thuộc tính quan trọng nhất được liệt kê bên dưới, nhưng bạn có thể tìm thấy danh sách đầy đủ trong tài liệu tham khảo Chức năng đám mây .
|
Chức năng đám mây thế hệ thứ 2
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
Trường tài nguyên | |||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
name sợi dây (yêu cầu) | Tên thân thiện với người dùng cho chức năng xuất. Nếu bạn không chỉ định thuộc tính Tên cuối cùng của chức năng được triển khai sẽ có định dạng sau: | ||||||||||||||||||||||||||||
type sợi dây (yêu cầu) | Đối với tài nguyên hàm thế hệ thứ 2: firebaseextensions.v1beta.v2function | ||||||||||||||||||||||||||||
description sợi dây (yêu cầu) | Mô tả ngắn gọn về nhiệm vụ mà hàm thực hiện cho tiện ích mở rộng. | ||||||||||||||||||||||||||||
properties (yêu cầu) | Thuộc tính Chức năng đám mây thế hệ thứ 2. Các thuộc tính quan trọng nhất được liệt kê bên dưới, nhưng bạn có thể tìm thấy danh sách đầy đủ trong tài liệu tham khảo Chức năng đám mây .
Ngoài ra còn có ba trường loại đối tượng có thuộc tính riêng:
|
Sự kiện vòng đời
Sự kiện vòng đời cho phép bạn chỉ định các chức năng sẽ chạy khi người dùng cài đặt, cập nhật hoặc định cấu hình phiên bản tiện ích mở rộng của bạn. Xem Xử lý các sự kiện trong vòng đời của tiện ích mở rộng của bạn .
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
Các trường sự kiện vòng đời | |||||||
---|---|---|---|---|---|---|---|
onInstall (không bắt buộc) | Chỉ định một chức năng sẽ chạy khi người dùng cài đặt tiện ích mở rộng.
| ||||||
onUpdate (không bắt buộc) | Chỉ định một chức năng sẽ chạy khi người dùng cập nhật tiện ích mở rộng.
| ||||||
onConfigure (không bắt buộc) | Chỉ định một chức năng sẽ chạy khi người dùng định cấu hình lại tiện ích mở rộng.
|
Sự kiện tùy chỉnh (Eventarc)
Sự kiện tùy chỉnh là các sự kiện mà tiện ích mở rộng của bạn phát ra để cho phép người dùng chèn logic của riêng họ vào tiện ích mở rộng của bạn. Xem phần Eventarc trong Thêm móc người dùng vào tiện ích mở rộng .
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
Trường sự kiện tùy chỉnh | |
---|---|
type sợi dây (yêu cầu) | Mã định danh loại của sự kiện. Tạo mã nhận dạng từ các trường được phân cách bằng 3-4 dấu chấm: bắt buộc phải có ID nhà xuất bản, tên tiện ích mở rộng và tên sự kiện; trường phiên bản được khuyến nghị. Chọn tên sự kiện duy nhất và mang tính mô tả cho từng loại sự kiện bạn xuất bản. |
description sợi dây (yêu cầu) | Mô tả sự kiện. |