Thiết lập và sử dụng các thông số trong phần mở rộng

Tham số là cơ chế mà người dùng sử dụng để tuỳ chỉnh từng phiên bản đã cài đặt của một tiện ích. Tham số giống như các biến môi trường cho một tiện ích. Giá trị cho các tham 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 của hàm, hãy sử dụng mô-đun params (ví dụ: params.defineInt("PARAMETER_NAME")) hoặc process.env.PARAMETER_NAME.

  • Trong extension.yaml và 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.md và điền sẵn mọi tham chiếu tham số bằng các giá trị thực tế cho thực thể đã cài đặt.

Tham số được điền sẵ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 điền sẵ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 (như bộ chứa Storage mặc định) hoặc là giá trị dành riêng cho tiện ích (như mã thực thể của tiện ích).

Tất cả giá trị tham số được điền sẵn tự động đều không thể thay đổi. Các biến 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 sẵ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 quan 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à á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.

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)
Thông số có giá trị mặc định từ dự án Firebase
PROJECT_ID Giá trị nhận dạng riêng biệt của dự án Firebase mà tiện ích được cài đặt

Định dạng tổng quát:
project-id

Giá trị mẫu:
project-123

DATABASE_URL URL của thực thể Realtime Database mặc định của dự án Firebase

Định dạng tổng quát:
https://project-id-default-rtdb.firebaseio.com
(phiên bản tại Hoa Kỳ)
hoặc
https://project-id-default-rtdb.region-code.firebasedatabase.app
(phiên bản bên ngoài Hoa Kỳ)

Giá trị mẫu:
https://project-123-default-rtdb.firebaseio.com

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 -default-rtdb.

Định dạng tổng quát:
project-id

Giá trị mẫu:
project-123

STORAGE_BUCKET Tên bộ chứa Cloud Storage mặc định của dự án Firebase

Định dạng tổng quát:
PROJECT_ID.firebasestorage.app

Giá trị mẫu:
project-123.firebasestorage.app

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 riêng biệt của phiên bản tiện ích đã cài đặt

Giá trị này được tạo từ trường name được chỉ định trong tệp extension.yaml.

Đị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):
name-from-extension.yaml

Giá trị mẫu:
my-awesome-extension


Định dạng tổng quát cho phiên bản được 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):
name-from-extension.yaml-4-digit-alphanumeric-hash

Giá trị mẫu:
my-awesome-extension-6m31

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ị 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, theo sau là bảng mô tả tất cả các trường tham số hiện có.

# 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 tham 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 văn bản trực tiếp hoặc chọn trong danh sách thả xuống)

Các giá trị hợp lệ bao gồm:

  • string: cho phép nhập văn bản dạng tự do (theo giới hạn của validationRegex)
  • select: cho phép chọn một mục trong danh sách các lựa chọn được xác định trước. Nếu chỉ định giá trị này, bạn cũng phải xác định trường options.
  • multiSelect: cho phép chọn một hoặc nhiều mục trong danh sách các lựa chọn được xác định trước. Nếu chỉ định giá trị này, bạn cũng phải xác định trường options.
  • selectResource: cho phép chọn một loại tài nguyên Firebase cụ thể (chẳng hạn như bộ chứa Cloud Storage) trong dự án của người dùng.

    Khi bạn chỉ định một tham số thuộc loại này, người dùng sẽ nhận được một tiện ích lựa chọn thân thiện hơn với người dùng trong giao diện người dùng cài đặt; vì lý do này, hãy sử dụng các tham số selectResource bất cứ khi nào có thể.

    Nếu chỉ định giá trị này, bạn cũng phải xác định trường resourceType.

  • secret: cho phép lưu trữ các chuỗi nhạy cảm, chẳng hạn như khoá API cho các dịch vụ của bên thứ ba. Các giá trị này sẽ được lưu trữ trong Cloud Secret Manager.

    Cloud Secret Manager là một dịch vụ có tính phí, việc sử dụng dịch vụ này có thể khiến người dùng cài đặt tiện ích của bạn phải trả phí. Nếu bạn sử dụng loại tham số secret, hãy nhớ ghi lại trong tệp PREINSTALL rằng tiện ích của bạn sử dụng Cloud Secret Manager.

Nếu bạn bỏ qua trường này, tham số sẽ mặc định là type của string.

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 label và value vào trường options:

  • label (chuỗi): nội dung mô tả ngắn về lựa chọn có thể chọn
  • value (chuỗi): giá trị thực tế của lựa chọn có thể chọn

Trường value là bắt buộc đối với trường options.
Nếu bạn bỏ qua label, thì tuỳ chọn danh sách sẽ mặc định hiển thị value.

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 bộ chứa Cloud Storage mới hỗ trợ bộ chọn tài nguyên:

Loại tài nguyên Mã loại
Cloud Storage bộ chứa storage.googleapis.com/Bucket

Các giá trị resourceType không xác định sẽ bị bỏ qua và giao diện người dùng sẽ hiển thị tham số dưới dạng trường nhập dữ liệu string dạng tuỳ ý.

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ẽ hiển thị nếu validationRegex không thành công

Để biết thông tin chi tiết về thông báo lỗi, hãy tham khảo phần Thông báo lỗi và xác thực 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 một giá trị tham số được điền sẵn tự động cho giá trị default (ví dụ: tham khảo tham số IMG_BUCKET của tiện ích Resize Images).

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 khi được nhắc nhập giá trị của tham số hay không

Nếu bạn bỏ qua required, giá trị này sẽ mặc định là true (tức là tham số bắt buộc).

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 immutable, giá trị này sẽ mặc định là false.

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, thì bạn nên đưa trường immutable này vào đối tượng tham số của tiện ích.

Thông báo 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ố có type là 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 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 những thông tin 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 được chỉ định có được thiết lập trong dự án Firebase của người dùng hay không
  • Liệu đườ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 hoặc bộ chứa Cloud Storage được tham chiếu 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 cài đặt thành công và hoạt động như mong đợi.

Tham số hệ thống

Tham số hệ thống kiểm soát cấu hình cơ bản của tài nguyên của 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 vào các biến này dưới dạng 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 kỳ nội dung nào cho các tham số này trong extension.yaml. Các tham số này được xác định tự động cho mọi phiên bản tiện ích và người dùng có thể đặt 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 đè chế độ cài đặt trên toàn phiên bản của 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 tham số hệ thống hiện có là:

Tên Nhãn (dễ hiểu) Trường tương ứng trong properties Mô tả
firebaseextensions.v1beta.function/location Vị trí location 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 Hàm sẽ 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 truy cập đi của trình kết nối VPC vpcConnectorEgressSettings Kiểm soát lưu lượng truy cập đi khi trình kết nối VPC được định cấu hình
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 được chỉ định.
firebaseextensions.v1beta.function/minInstances Số lượng 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 có thể chạy cùng một lúc
firebaseextensions.v1beta.function/ingressSettings Cài đặt lưu lượng truy cập vào ingressSettings Kiểm soát nguồn 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