Tệp thông số kỹ thuật của tiện ích (extension.yaml) chứa siêu dữ liệu của tiện ích, khai báo các tài nguyên do tiện ích tạo ra cũng như các API và quyền truy cập mà tiện ích yêu cầu, đồng thời xác định mọi tham số do người dùng định cấu hình mà tiện ích 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à 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/
| Các trường cơ bản | |||||||||
|---|---|---|---|---|---|---|---|---|---|
namechuỗi (bắt buộc) |
Giá trị nhận dạng cho tiện ích. Chỉ được chứa chữ cái viết thường, số và dấu gạch ngang; giới hạn 40 ký tự. Lưu ý: Giá trị này được dùng để tạo mã nhận dạng thực thể của tiện ích (sau đó được dùng để tạo tên của 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). |
||||||||
Chuỗi version(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). |
||||||||
specVersionchuỗ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: |
||||||||
licensechuỗ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 bằng |
||||||||
billingRequiredboolean (không bắt buộc) |
Liệu các dịch vụ mà tiện ích sử dụng có yêu cầu tài khoản thanh toán Firebase cấp trả phí hay không. Luôn đặt thành |
||||||||
displayNamechuỗi (không bắt buộc) |
Tên hiển thị dễ nhớ cho tiện ích (3-5 từ). Giới hạn 40 ký tự. |
||||||||
descriptionchuỗi (không bắt buộc) |
Nội dung mô tả ngắn gọn về tác vụ mà tiện ích của bạn thực hiện (~1 câu). | ||||||||
iconchuỗi (không bắt buộc) |
Tệp dùng làm biểu tượng của tiện ích trên Tệp này phải là tệp 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 tiện ích:
|
||||||||
tagsdanh sách chuỗi (không bắt buộ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 đến các danh mục trên Trung tâm tiện ích:
marketing,
messaging,
payments,
search,
shipping,
social,
utilities,
ai
|
||||||||
sourceUrlchuỗ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. | ||||||||
releaseNotesUrlchuỗi (không bắt buộc) |
URL công khai nơi có thể truy cập vào ghi chú phát hành của tiện ích. | ||||||||
authormộ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/
|
||||||||
contributorsdanh 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 cài đặt tiện ích, người dùng 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 | |
|---|---|
apiNamechuỗi (bắt buộc) |
Tên của API Google Phải tương ứng với trường Tên dịch vụ được liệt kê trên trang tổng quan của từng API (ví dụ) trong Thư viện API Google Cloud |
Chuỗi reason(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 |
Vai trò trong IAM
Các trường này chỉ định các vai trò Cloud IAM mà tiện ích yêu cầu. Tài khoản dịch vụ được cấp cho tiện ích 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ò | |
|---|---|
Chuỗi role(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ợ |
Chuỗi reason(bắt buộc) |
Nội dung mô tả ngắn gọn về lý do tiện ích cần quyền truy cập do vai trò này cấp |
resourcechuỗ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ạn bỏ qua thuộc tính này, 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 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 thức nào để tự động bật hoặc thực hiện uỷ 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
| Các trường dịch vụ bên ngoài | |
|---|---|
namechuỗ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 |
Chuỗi pricingUri(bắt buộc) |
URI đến thông tin về 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 thông 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ố | |
|---|---|
paramchuỗi (bắt buộc) |
Tên của thông số. Bạn sử dụng tên này để tham chiếu giá trị tham số trong mã. |
labelchuỗi (bắt buộc) |
Nội dung mô tả ngắn về thông số này. Hiển thị cho người dùng khi họ được nhắc nhập giá trị của tham số. |
descriptionchuỗi (không bắt buộc) |
Nội dung mô tả chi tiết về tham số. Hiển thị cho người dùng khi họ được nhắc nhập giá trị của tham số. Hỗ trợ Markdown. |
examplechuỗi (không bắt buộc) |
Giá trị mẫu cho tham số. |
defaultchuỗi (không bắt buộc) |
Giá trị mặc định của thông số nếu người dùng để trống giá trị của thông số đó. |
validationRegexchuỗi (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 RE2 của Google. |
validationErrorMessagechuỗ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. |
requiredboolean (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 được nhắc nhập giá trị của tham số hay không. Giá trị mặc định là true.
|
immutableboolean (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). Giá trị mặc định là Lưu ý: Nếu bạn xác định tham số "vị trí" cho các hàm đã triển khai của tiện ích, hãy đặt trường này thành |
typechuỗi (không bắt buộc) |
Loại tham số. Các loại tham số đặc biệt có thể có thêm yêu cầu hoặc cách trình bày giao diện người dùng khác. Hãy xem các phần sau. |
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 lựa 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
| Trường tham số có nhiều lựa chọn | |||||||
|---|---|---|---|---|---|---|---|
typechuỗi |
Chỉ định rằng tham số có thể là một giá trị ( |
||||||
optionsdanh sách các tuỳ chọn (bắt buộc) |
Các lựa chọn mà người dùng có thể chọn
|
||||||
Thông số tài nguyên có thể chọn
Các tham số tài nguyên có thể chọn sẽ nhắc người dùng chọn một tài nguyên (phiên bản cơ sở dữ liệu, 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 tham số tài nguyên | |
|---|---|
Chuỗi type |
Chỉ định rằng tham số này đại diện cho tài nguyên dự án |
Chuỗi resourceType(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 trên 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 tuỳ ý). |
Tham số bí mật
Các 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:
- Các giá trị bí mật được lưu trữ bằng Trình quản lý bí mật trên đám mây. Chỉ các ứng dụng được uỷ quyền (chẳng hạn như một phiên bản đã cài đặt của tiện ích) mới có thể truy cập vào các giá trị này.
- Khi người dùng được nhắc cung cấp các giá trị này, dữ liệu đầu vào của họ 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 tham số bí mật | |
|---|---|
Chuỗi type |
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 trên đám mây có trong một tiện ích. Cú pháp khai báo tài nguyên có vẻ hơi khác giữa các hàm thế hệ 1 và thế hệ 2, các hàm này có thể cùng tồn tại trong một tiện ích.
Cloud Functions 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 | |||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
namechuỗi (bắt buộc) |
Tên thân thiện với người dùng cho hàm được xuất. Nếu bạn không chỉ định thuộc tính Tên cuối cùng của hàm đã triển khai sẽ có định dạng sau: |
||||||||||||||||
typechuỗi (bắt buộc) |
Đối với tài nguyên hàm thế hệ 1:
firebaseextensions.v1beta.function
|
||||||||||||||||
descriptionchuỗ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) |
Các thuộc tính của Cloud Functions 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 về Chức năng đám mây.
|
||||||||||||||||
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 | |||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
namechuỗi (bắt buộc) |
Tên thân thiện với người dùng cho hàm được xuất. Nếu bạn không chỉ định thuộc tính Tên cuối cùng của hàm đã triển khai sẽ có định dạng sau: |
||||||||||||||||||||||||||||
typechuỗi (bắt buộc) |
Đối với tài nguyên hàm thế hệ 2:
firebaseextensions.v1beta.v2function
|
||||||||||||||||||||||||||||
Chuỗi description(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) |
Các thuộc tính của Cloud Functions thế hệ 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 về Chức năng đám mây.
Ngoài ra, còn có 3 trường loại đối tượng có các thuộc tính riêng:
|
||||||||||||||||||||||||||||
Sự kiện trong vòng đời
Sự kiện 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 thực thể của tiện ích. Xem phần 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
| Các trường sự kiện trong vòng đời | |||||||
|---|---|---|---|---|---|---|---|
onInstall(không bắt buộc) |
Chỉ định một hàm 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 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 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 tuỳ chỉnh là các sự kiện mà tiện ích 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. Xem phần Eventarc trong bài viết Thêm trình bổ trợ 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 | |
|---|---|
Chuỗi type(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ừ các trường được phân tách bằng 3 đến 4 dấu chấm: bắt buộc phải nhập mã nhà xuất bản, tên tiện ích và trường tên sự kiện; nên nhập trường phiên bản. Chọn một tên sự kiện duy nhất và mô tả cho từng loại sự kiện mà bạn phát hành. |
Chuỗi description(bắt buộc) |
Nội dung mô tả về sự kiện. |