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