Tham số là cơ chế mà người dùng tuỳ chỉnh từng phiên bản đã cài đặt của một tiện ích. Các tham số giống như biến môi trường cho một tiện ích. Các giá trị cho thông số có thể được tự động điền sẵ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 chiếu các tham số này trong mã nguồn của các hàm trong tiện ích, tệp extension.yaml và tệp POSTINSTALL.md. Sau đây là cú pháp để tham chiếu một tham số có tên là PARAMETER_NAME:
Trong mã nguồn 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 giá trị tham chiếu tham số bằng các giá trị thực tế cho phiên bản đã cài đặt.
Thông số được điền sẵn
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 điền sẵn do Firebase cung cấp (xem 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ư vùng chứa lưu trữ mặc định) hoặc là giá trị dành riêng cho tiện ích (chẳng hạn như mã nhận dạng phiên bản của tiện ích).
Tất cả giá trị thông số được điền sẵn đều không thể thay đổi. Chúng đượ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ị tham số này cho tiện ích, nhưng Firebase không tự động cung cấp các sản phẩm 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 được liên kết và áp dụng trong dự án của họ 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ề những yêu cầu này trong tệp PREINSTALL.md.
| Thông tin tham khảo về thông số được điền sẵn | Nội dung mô tả | Giá trị thông số (do Firebase cung cấp) |
|---|---|---|
| Các thông 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 của phiên bản mặc định Realtime Database của dự án Firebase |
Định dạng chung:
Giá trị mẫu: |
DATABASE_INSTANCE |
Tên phiên bản mặc định Realtime Database 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 tổng quát:
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 phiên bản tiện ích đã cài đặt Giá trị này được tạo từ trường |
Định dạng chung cho phiên bản được cài đặt lần đầu tiên (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 cài đặt lần thứ 2 trở lên (do Firebase tự động chỉ định; người dùng có thể sửa đổi trong quá trình cài đặt):
Giá trị mẫu: |
Tham 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 các giá trị tham số trong quá trình cài đặt. Để yêu cầu các giá trị này, bạn thiết lập lời nhắc trong phần params của tệp extension.yaml.
Sau đây là ví dụ về phần params, tiếp theo 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 dùng các trường sau để xác định một 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ề tham 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 để người dùng đặt giá trị của tham số (ví dụ: nhập trực tiếp văn bản hoặc chọn trong danh sách thả xuống) Các giá trị hợp lệ bao gồm:
Nếu bạn bỏ qua trường này, tham số sẽ mặc định là |
||||
options(bắt buộc nếu tham số type là select hoặc multiSelect)
|
list |
Danh sách các giá trị mà người dùng có thể chọn Thêm các trường
Bạn bắt buộc phải điền vào 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ác nhóm Cloud Storage mới 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 tham số |
||||
validationRegex(không bắt buộc) (chỉ áp dụng khi tham số type là string)
|
chuỗi |
Chuỗi 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ố Biểu thức chính quy được biên dịch bằng thư viện go: RE2 Để biết thông tin chi tiết về quy trình 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ẽ xuất hiện 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 tham số nếu người dùng để trống giá trị của tham số Nếu có thể, bạn có thể chỉ định giá trị tham số được điền sẵn tự động 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 họ được nhắc nhập 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 tham 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 một tham số "location" cho các hàm đã triển khai của tiện ích, thì bạn nên thêm 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 tham số bằng type của string, bạn cần xác định quy trình xác thực biểu thức chính quy thích 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 vùng 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 những nội dung sau tại thời điểm nhập giá trị tham số:
- Cho dù cơ sở dữ liệu hoặc vùng chứa Cloud Storage được 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 đã 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 Firebase CLI sẽ hiển thị thông báo lỗi nếu cơ sở dữ liệu được tham chiếu hoặc vùng 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ề các 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ư mong đợi.
Thông số hệ thống
Các tham số hệ thống kiểm soát cấu hình cơ bản của tài nguyên trong một tiện ích. Vì chúng được dùng để kiểm soát cấu hình tài nguyên, nên bạn không thể truy cập vào chúng dưới dạng các biến môi trường trong mã hàm.
Thông thường, bạn không cần khai báo bất cứ điều gì cho các tham số này trong extension.yaml.
Chúng được xác định tự động cho mọi phiên bản tiện ích và người dùng có cơ hội đặt các giá trị tuỳ chỉnh khi cài đặt tiện ích của bạn.
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ể ở cấp độ từng tài nguyên trong extension.yaml.
Các chế độ cài đặt cấu hình theo tài nguyên này sẽ ghi đè các chế độ cài đặt trên toàn bộ 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
Các thông số hệ thống có sẵn là:
| Tên | Nhãn (dễ hiểu) | Trường tương ứng trong properties |
Mô tả |
|---|---|---|---|
| firebaseextensions.v1beta.function/location | Vị trí | location |
Cloud Functions nên được triển khai ở 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ờ của 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 bạn định cấu hình một trình kết nối VPC |
| firebaseextensions.v1beta.function/vpcConnector | VPC Connector | vpcConnector |
Kết nối Cloud Functions với trình kết nối VPC được chỉ định. |
| firebaseextensions.v1beta.function/minInstances | Số lượng tối thiểu các phiên bản hàm | minInstances |
Số lượng tối thiểu các phiên bản của hàm này sẽ chạy cùng một lúc |
| firebaseextensions.v1beta.function/maxInstances | Số lượng phiên bản hàm tối đa | maxInstances |
Số lượng tối đa các phiên bản của hàm này có thể chạy cùng một lúc |
| firebaseextensions.v1beta.function/ingressSettings | Cài đặt Ingress | ingressSettings |
Kiểm soát nguồn chấp nhận lưu lượng truy cập đế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 |