Tệp đặc tả (extension.yaml) của tiện ích 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 thông 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ả những trường có trong 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 | |||||||||
|---|---|---|---|---|---|---|---|---|---|
namestring (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; giới hạn 40 ký tự. Lưu ý: Giá trị này được dùng để tạo mã nhận dạng phiên bản 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à các tài nguyên dành riêng cho tiện ích). |
||||||||
versionstring (bắt buộc) |
Phiên bản của tiện ích. Phải tuân theo quy tắc đặt phiên bản semver (ví dụ: 1.2.0). |
||||||||
specVersionstring (bắt buộc) |
Phiên bản của quy cách Tiện ích Firebase. Giá trị hiện tại: |
||||||||
licensestring (không bắt buộc) |
Giấy phép cho 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) |
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 thuộc cấp trả phí hay không. Luôn đặt thành |
||||||||
displayNamestring (không bắt buộc) |
Tên hiển thị thân thiện cho tiện ích (3 đến 5 từ). Giới hạn 40 ký tự. |
||||||||
descriptionstring (không bắt buộc) |
Nội dung mô tả ngắn gọn về nhiệm vụ mà tiện ích của bạn thực hiện (khoảng 1 câu). | ||||||||
iconstring (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 trong 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 của bạn:
|
||||||||
tagsdanh 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 của bạn.
Các thẻ sau đây được ánh xạ đến các danh mục trên Extensions Hub:
marketing,
messaging,
payments,
search,
shipping,
social,
utilities,
ai
|
||||||||
sourceUrlstring (không bắt buộc) |
URL công khai mà bạn có thể truy cập vào thư mục tiện ích. | ||||||||
releaseNotesUrlstring (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 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ệ của tiện ích. author: authorName: Your Company email: extensions@example.com url: https://example.com/
|
||||||||
contributorsdanh sách các đối tượng tác giả (không bắt buộc) |
Mọi tác giả đóng góp bổ sung 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 Firebase và API 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
| Các trường API | |
|---|---|
apiNamestring (bắt buộc) |
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 của Google Cloud |
reasonstring (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ò IAM
Các trường này chỉ định những vai trò Cloud IAM mà tiện ích yêu cầu. Tài khoản dịch vụ được cung 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ò | |
|---|---|
rolestring (bắt buộc) |
Tên của vai trò IAM cần thiết để tiện ích hoạt động Phải là một trong những vai trò được hỗ trợ |
reasonstring (bắt buộc) |
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 |
resourcestring (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 những 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 nào để tự động bật hoặc thực hiện việc 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 | |
|---|---|
namestring (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 |
pricingUristring (bắt buộc) |
URI đến thông tin về giá của dịch vụ |
Tham số do người dùng định cấu hình
Các trường này xác định những 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 tham số | |
|---|---|
paramstring (bắt buộc) |
Tên của thông số. Bạn dùng tên này để tham chiếu giá trị tham số trong mã. |
labelstring (bắt buộc) |
Nội dung mô tả ngắn về tham số. Hiển thị cho người dùng khi họ được nhắc nhập giá trị của tham số. |
descriptionstring (không bắt buộc) |
Nội dung mô tả chi tiết cho 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. |
examplestring (không bắt buộc) |
Giá trị mẫu cho tham số. |
defaultstring (không bắt buộc) |
Giá trị mặc định cho thông số nếu người dùng để trống giá trị của thông số. |
validationRegexstring (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. |
validationErrorMessagestring (không bắt buộc) |
Thông báo lỗi sẽ xuất hiện nếu quá trình xác thực bằng 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 hay không khi họ được nhắc nhập giá trị của tham số. 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 một tham số "location" cho các hàm đã triển khai của tiện ích, hãy đặt trường này thành |
typestring (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 khác trong giao diện người dùng. Hãy xem các phần sau. |
Các thông số có thể chọn và chọn nhiều
Các thông số có thể chọn và có thể chọn nhiều mục 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ố trắc nghiệm | |||||||
|---|---|---|---|---|---|---|---|
typechuỗi |
Chỉ định rằng tham số có thể là một giá trị ( |
||||||
optionsdanh sách các lựa chọn (bắt buộc) |
Các lựa chọn mà người dùng có thể chọn
|
||||||
Các thông số tài nguyên có thể chọn
Các tham số tài nguyên có thể chọn nhắc người dùng chọn một tài nguyên (ví dụ: phiên bản cơ sở dữ liệu, vùng lưu trữ, v.v.) trong 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 | |
|---|---|
typechuỗi |
Chỉ định rằng tham số này đại diện cho một tài nguyên dự án |
resourceTypestring (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 chỉ có bộ chứa Cloud Storage có giao diện người dùng để chọn (các loại tài nguyên khác được trình bày dưới dạng các trường nhập văn bản 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 Cloud Secret Manager. Chỉ những ứ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, 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 tham số bí mật | |
|---|---|
typechuỗi |
Chỉ định rằng tham số là một giá trị bí mật |
Tài nguyên Cloud Functions
Các trường này khai báo Cloud Functions có trong một tiện ích. Cú pháp khai báo tài nguyên có một chút khác biệt giữa các hàm thế hệ thứ nhất và thế hệ thứ hai, có thể cùng tồn tại trong một tiện ích.
Cloud Functions 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 | |||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
namestring (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: |
||||||||||||||||
typestring (bắt buộc) |
Đối với tài nguyên hàm thế hệ thứ nhất:
firebaseextensions.v1beta.function
|
||||||||||||||||
descriptionstring (bắt buộc) |
Nội dung mô tả ngắn gọn về nhiệm 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 Tài liệu tham khảo về Chức năng đám mây.
|
||||||||||||||||
Cloud Functions 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 | |||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
namestring (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: |
||||||||||||||||||||||||||||
typestring (bắt buộc) |
Đối với tài nguyên hàm thế hệ thứ 2:
firebaseextensions.v1beta.v2function
|
||||||||||||||||||||||||||||
descriptionstring (bắt buộc) |
Nội dung mô tả ngắn gọn về nhiệm 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 Tài liệu tham khảo về Chức năng đám mây.
Ngoài ra, còn có 3 trường kiểu đối tượng có các thuộc tính riêng:
|
||||||||||||||||||||||||||||
Sự kiện trong vòng đời
Các sự kiện vòng đời cho phép bạn chỉ định những 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 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à những 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. Hãy xem phần Eventarc trong bài viết Thêm các lệnh gọi của người dùng vào một 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 | |
|---|---|
typestring (bắt buộc) |
Giá trị nhận dạng loại của sự kiện. Tạo mã nhận dạng từ 3 đến 4 trường được phân tách bằng dấu chấm: bạn phải điền trường mã nhận dạng nhà xuất bản, tên tiện ích và tên sự kiện; bạn nên điền trường phiên bản. Chọn một tên sự kiện duy nhất và mang tính mô tả cho mỗi loại sự kiện mà bạn xuất bản. |
descriptionstring (bắt buộc) |
Nội dung mô tả về sự kiện. |