Thông số là cơ chế mà qua đó người dùng tuỳ chỉnh từng phiên bản đã cài đặt của một tiện ích. Thông số giống như biến môi trường cho một tiện ích. Các giá trị của thông số có thể được tự động điền (do Firebase cung cấp sau khi cài đặt) hoặc do người dùng định cấu hình (do người dùng chỉ định trong quá trình cài đặt).
Bạn có thể tham khảo các tham số này trong mã nguồn hàm của tiện ích, tệp extension.yaml và tệp POSTINSTALL.md. Dưới đây là cú pháp để tham chiếu một tham số có tên là PARAMETER_NAME:
Trong mã nguồn của hàm, hãy sử dụng mô-đun
params(ví dụ:params.defineInt("PARAMETER_NAME")) hoặcprocess.env.PARAMETER_NAME.Trong
extension.yamlvàPOSTINSTALL.md, hãy sử dụng${param:PARAMETER_NAME}.Sau khi cài đặt, bảng điều khiển Firebase sẽ hiển thị nội dung của tệp
POSTINSTALL.mdvà điền sẵn mọi tham chiếu tham số bằng giá trị thực tế cho thực thể đã cài đặt.
Thông số được điền tự động
Mỗi phiên bản đã cài đặt của một tiện ích sẽ tự động có quyền truy cập vào một số tham số mặc định được tự động điền do Firebase cung cấp (tham khảo bảng bên dưới). Các giá trị tham số này là giá trị mặc định cho dự án Firebase (chẳng hạn như bộ nhớ mặc định) hoặc là giá trị dành riêng cho tiện ích (chẳng hạn như mã phiên bản của tiện ích).
Tất cả giá trị thông số được tự động điền đều không thể thay đổi. Các giá trị này được đặt tại thời điểm tạo dự án hoặc cài đặt tiện ích.
Mặc dù Firebase tự động điền các giá trị thông số này cho tiện ích, nhưng Firebase không tự động cấp phép các sản phẩm được liên kết cho người dùng trong quá trình cài đặt. Người dùng cài đặt tiện ích phải bật(các) sản phẩm liên quan và thích hợp trong dự án trước khi cài đặt. Ví dụ: nếu tiện ích của bạn liên quan đến Cloud Firestore, thì người dùng phải thiết lập Cloud Firestore trong dự án của họ. Bạn nên thông báo cho người dùng về các yêu cầu này trong tệp PREINSTALL.md.
| Tài liệu tham khảo về thông số được điền tự động | Nội dung mô tả | Giá trị thông số (do Firebase cung cấp) |
|---|---|---|
| Các tham số có giá trị mặc định từ dự án Firebase | ||
PROJECT_ID |
Giá trị nhận dạng duy nhất của dự án Firebase mà tiện ích được cài đặt |
Định dạng tổng quát:
Giá trị mẫu: |
DATABASE_URL |
URL thực thể Realtime Database mặc định của dự án Firebase |
Định dạng tổng quát:
Giá trị mẫu: |
DATABASE_INSTANCE |
Tên thực thể Realtime Database mặc định của dự án Firebase Thông thường, giá trị này giống với mã dự án hoặc kết thúc bằng |
Định dạng chung:
Giá trị mẫu: |
STORAGE_BUCKET |
Tên bộ chứa Cloud Storage mặc định của dự án Firebase |
Định dạng tổng quát:
Giá trị mẫu: |
| Tham số có giá trị mặc định từ quá trình cài đặt tiện ích | ||
EXT_INSTANCE_ID |
Giá trị nhận dạng duy nhất của thực thể tiện ích đã cài đặt Giá trị này được tạo từ trường |
Định dạng tổng quát cho phiên bản cài đặt đầu tiên (do Firebase tự động chỉ định; người dùng không thể sửa đổi trong quá trình cài đặt):
Giá trị mẫu: Định dạng tổng quát cho phiên bản cài đặt thứ 2 trở lên
(do Firebase tự động chỉ định; có thể được người dùng sửa đổi
trong quá trình cài đặt):
Giá trị mẫu: |
Thông số do người dùng định cấu hình
Để cho phép người dùng tuỳ chỉnh từng phiên bản đã cài đặt của một tiện ích, bạn có thể yêu cầu người dùng chỉ định giá trị thông số trong quá trình cài đặt. Để yêu cầu các giá trị này, bạn cần thiết lập lời nhắc trong phần params của tệp extension.yaml.
Dưới đây là ví dụ về phần params, theo sau là bảng mô tả tất cả các trường tham số có sẵn.
# extension.yaml
...
# Parameters (environment variables) for which the user specifies values during installation
params:
- param: DB_PATH
label: Realtime Database path
description: >-
What is the Realtime Database path where you will write new text
for sentiment analysis?
type: string
validationRegex: ^\S+$
validationErrorMessage: Realtime Database path cannot contain spaces.
example: path/to/posts
required: true
- param: TEXT_KEY
label: Key for text
description: What is the name of the key that will contain text to be analyzed?
type: string
default: textToAnalyze
required: true
Trong phần params của tệp extension.yaml, hãy sử dụng các trường sau để xác định tham số do người dùng định cấu hình:
| Trường | Loại | Nội dung mô tả | ||||
|---|---|---|---|---|---|---|
param(bắt buộc) |
chuỗi | Tên của thông số | ||||
label(bắt buộc) |
chuỗi |
Nội dung mô tả ngắn về thông số Hiển thị cho người dùng khi họ được nhắc nhập giá trị của tham số |
||||
description(không bắt buộc) |
chuỗi |
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 | ||||
type(không bắt buộc) |
chuỗi |
Cơ chế nhập dữ liệu cho cách người dùng đặt giá trị cho thông số (ví dụ: nhập văn bản trực tiếp hoặc chọn trong danh sách thả xuống) Sau đây là các giá trị hợp lệ:
Nếu bạn bỏ qua trường này, tham số mặc định sẽ là |
||||
options(bắt buộc nếu tham số type
là select hoặc multiSelect)
|
list |
Danh sách giá trị mà người dùng có thể chọn Thêm các trường
Trường |
||||
resourceType(bắt buộc nếu tham số type
là selectResource)
|
chuỗi |
Loại tài nguyên Firebase để nhắc người dùng chọn. Hiện tại, chỉ có bộ chứa Cloud Storage hỗ trợ bộ chọn tài nguyên:
Các giá trị |
||||
example(không bắt buộc) |
chuỗi |
Giá trị mẫu cho thông số |
||||
validationRegex(không bắt buộc) (chỉ áp dụng khi tham số type là
string)
|
chuỗi |
Chuỗi Regex để xác thực giá trị do người dùng định cấu hình của tham số Regex được biên dịch bằng thư viện go: RE2 Để biết thông tin chi tiết về việc xác thực, hãy tham khảo phần Xác thực và thông báo lỗi bên dưới. |
||||
validationErrorMessage(không bắt buộc) |
chuỗi |
Thông báo lỗi sẽ hiển thị nếu Để biết thông tin chi tiết về thông báo lỗi, hãy tham khảo phần Xác thực và thông báo lỗi bên dưới. |
||||
default(không bắt buộc) |
chuỗi |
Giá trị mặc định cho thông số nếu người dùng để trống giá trị của thông số Nếu có thể, bạn có thể chỉ định giá trị thông số được tự động điền cho giá trị |
||||
required(không bắt buộc) |
boolean |
Xác định xem người dùng có thể gửi một chuỗi trống hay không khi được nhắc về giá trị của tham số Nếu bạn bỏ qua |
||||
immutable(không bắt buộc) |
boolean |
Xác định xem người dùng có thể thay đổi giá trị của thông số sau khi cài đặt hay không (ví dụ: nếu họ định cấu hình lại tiện ích) Nếu bạn bỏ qua
Lưu ý: Nếu xác định tham số "vị trí" cho các hàm đã triển khai của tiện ích, thì bạn nên đưa trường |
Xác thực và thông báo lỗi cho các giá trị do người dùng định cấu hình
Khi thiết lập một thông số có type của string, bạn cần xác định phương thức xác thực biểu thức chính quy phù hợp thông qua trường validationRegex của tham số đó.
Ngoài ra, đối với nhiều tiện ích, giá trị tham số thường được yêu cầu là đường dẫn cơ sở dữ liệu hoặc bộ chứa Cloud Storage. Xin lưu ý rằng trong quá trình cài đặt, định cấu hình lại hoặc cập nhật, dịch vụ Extensions không xác thực các nội dung sau tại thời điểm nhập giá trị tham số:
- Liệu cơ sở dữ liệu hoặc bộ chứa Cloud Storage đã chỉ định có được thiết lập trong dự án Firebase của người dùng hay không
- Đường dẫn cơ sở dữ liệu được chỉ định có tồn tại trong cơ sở dữ liệu của người dùng hay không
Tuy nhiên, khi tiện ích thực sự triển khai tài nguyên, bảng điều khiển Firebase hoặc CLI Firebase sẽ hiển thị thông báo lỗi nếu cơ sở dữ liệu được tham chiếu hoặc bộ chứa Cloud Storage chưa được thiết lập trong dự án.
Bạn nên thông báo cho người dùng trong tệp PREINSTALL về những yêu cầu này để khi họ cài đặt tiện ích của bạn, tiện ích đó sẽ cài đặt thành công và hoạt động như dự kiến.
Tham số hệ thống
Các thông số hệ thống kiểm soát cấu hình cơ bản của tài nguyên của một tiện ích. Vì các biến này dùng để kiểm soát cấu hình tài nguyên, nên bạn không thể truy cập các biến này dưới dạng biến môi trường từ trong mã hàm.
Thông thường, bạn không cần khai báo bất kỳ nội dung gì cho các tham số này trong extension.yaml.
Các giá trị này được tự động xác định cho mọi thực thể tiện ích và người dùng có thể đặt giá trị tuỳ chỉnh khi cài đặt tiện ích.
Tuy nhiên, nếu tiện ích của bạn có các yêu cầu đặc biệt về tài nguyên, bạn có thể đặt các giá trị cụ thể theo cấp tài nguyên trong extension.yaml.
Các chế độ cài đặt cấu hình cho mỗi tài nguyên này sẽ ghi đè các chế độ cài đặt trên toàn phiên bản tiện ích của người dùng.
Ví dụ:
resources:
- name: high_memory_function
type: firebaseextensions.v1beta.function
description: >-
This function needs at least 1GB of memory!
properties:
httpsTrigger: {}
runtime: nodejs18
availableMemoryMb: 1024
- name: normal_function
type: firebaseextensions.v1beta.function
description: >-
This function has no special memory requirements. It will use the
default value, or the value of `firebaseextension.v1beta.function/memory`
properties:
httpsTrigger: {}
runtime: nodejs18
Sau đây là các tham số hệ thống có sẵn:
| Tên | Nhãn (thân thiện với con người) | Trường tương ứng trong properties |
Mô tả |
|---|---|---|---|
| firebaseextensions.v1beta.function/location | Vị trí | location |
Bạn nên triển khai Cloud Functions ở khu vực nào? |
| firebaseextensions.v1beta.function/memory | Bộ nhớ hàm | memory |
Mỗi hàm nên được phân bổ bao nhiêu megabyte bộ nhớ? |
| firebaseextensions.v1beta.function/timeoutSeconds | Hết thời gian chờ hàm | timeout |
Các hàm nên chạy trong bao nhiêu giây trước khi hết thời gian chờ? |
| firebaseextensions.v1beta.function/vpcConnectorEgressSettings | Lưu lượng ra của trình kết nối VPC | vpcConnectorEgressSettings |
Kiểm soát lưu lượng truy cập đi khi định cấu hình trình kết nối VPC |
| firebaseextensions.v1beta.function/vpcConnector | Trình kết nối VPC | vpcConnector |
Kết nối Cloud Functions với trình kết nối VPC đã chỉ định. |
| firebaseextensions.v1beta.function/minInstances | Số thực thể hàm tối thiểu | minInstances |
Số lượng thực thể tối thiểu của hàm này để chạy cùng một lúc |
| firebaseextensions.v1beta.function/maxInstances | Số thực thể hàm tối đa | maxInstances |
Số lượng thực thể tối đa của hàm này để chạy cùng một lúc |
| firebaseextensions.v1beta.function/ingressSettings | Cài đặt Ingress | ingressSettings |
Kiểm soát nơi lưu lượng truy cập đến được chấp nhận |
| firebaseextensions.v1beta.function/labels | Nhãn | labels |
Nhãn để áp dụng cho tất cả tài nguyên trong tiện ích |