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 tài nguyên do tiện ích tạo và API cũng như 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 do 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/
| Trường cơ bản | |||||||||
|---|---|---|---|---|---|---|---|---|---|
Chuỗi name(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; tối đa 40 ký tự. Lưu ý: Giá trị này được dùng để tạo mã thực thể của tiện ích (sau đó, mã này sẽ đượ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). |
||||||||
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). |
||||||||
Chuỗi specVersion(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 sử dụng |
||||||||
billingRequiredboolean (không bắt buộc) |
Liệu các dịch vụ mà tiện ích sử dụng có bắt buộc phải có 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ễ hiểu cho phần mở rộng (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ề việc mà tiện ích thực hiện (khoảng 1 câu). | ||||||||
iconchuỗi (không bắt buộc) |
Tệp mà bạn dùng làm biểu tượng cho 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 này 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) |
Các thẻ giúp người dùng khám phá tiện ích của bạn.
Các thẻ sau 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
|
||||||||
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 bạn có thể truy cập vào ghi chú phát hành cho 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 này, người dùng 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 | |
|---|---|
Chuỗi apiName(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ư 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 |
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. 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ò | |
|---|---|
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 vai trò này cần cấp quyền truy cập cho tiện ích |
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ỏ 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 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
| Trường dịch vụ bên ngoài | |
|---|---|
Chuỗi name(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 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ố | |
|---|---|
Chuỗi param(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ã. |
Chuỗi label(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ố. |
descriptionchuỗ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 họ được nhắc nhập giá trị của thông số. Hỗ trợ Markdown. |
examplechuỗi (không bắt buộc) |
Giá trị mẫu cho thông 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 thông 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 về 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ư họ có định cấu hình lại tiện ích hay không). Giá trị mặc định là Lưu ý: Nếu bạn xác định 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 |
typechuỗi (không bắt buộc) |
Loại thông 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. 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 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 thông số trắc nghiệm | |||||||
|---|---|---|---|---|---|---|---|
Chuỗi type |
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 tuỳ chọn mà người dùng có thể chọn
|
||||||
Tham 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 thông số tài nguyên | |
|---|---|
Chuỗi type |
Chỉ định rằng tham số đại diện cho một 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 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ạ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 ứng dụng được uỷ quyền (chẳng hạn như bản sao đã cài đặt của một 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 thông 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 đám mây có trong tiện ích. Cú pháp khai báo tài nguyên có vẻ hơi khác nhau giữa hàm thế hệ 1 và thế hệ 2, 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 | |||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Chuỗi name(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 triển khai sẽ có
định dạng sau:
|
||||||||||||||||
Chuỗi type(bắt buộc) |
Đối với tài nguyên hàm thế hệ 1: firebaseextensions.v1beta.function
|
||||||||||||||||
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) |
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ề Hàm đá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 | |||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Chuỗi name(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 triển khai sẽ có
định dạng sau:
|
||||||||||||||||||||||||||||
Chuỗi type(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) |
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ề Hàm đám mây.
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 của tiện ích. 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 tuỳ 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 họ vào tiện ích. Hãy xem phần Eventarc trong bài viết Thêm nội dung hấp dẫn 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 | |
|---|---|
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 riêng biệt và có tính mô tả cho từng loại sự kiện mà bạn xuất bản. |
Chuỗi description(bắt buộc) |
Nội dung mô tả về sự kiện. |