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

Thông số là cơ chế mà qua đó người dùng tuỳ chỉnh từng thông tin được cài đặt bản sao của một tiện ích. Các thông số giống như các biến môi trường cho tiện ích. Giá trị cho các 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 thông số này trong hàm mã nguồn, tệp extension.yamlPOSTINSTALL.md của bạn . Dưới đâ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ặc process.env.PARAMETER_NAME.

  • Trong extension.yamlPOSTINSTALL.md, hãy sử dụng ${param:PARAMETER_NAME}.

    Sau khi cài đặt, bảng điều khiển Firebase sẽ hiện nội dung của POSTINSTALL.md và điền sẵn mọi tham chiếu tham số bằng phương thức giá trị thực tế cho phiên bản đã cài đặt.

Thông số được điền tự động

Mỗi bản sao tiện ích đã cài đặt sẽ tự động có quyền truy cập vào một số thông số tự động điền mặc định do Firebase cung cấp (tham khảo bảng bên dưới). Các giá trị thông số này là giá trị mặc định cho Firebase dự án (như bộ chứa Storage mặc định) hoặc dành riêng cho tiện ích (như mã bản sao của tiện ích).

Tất cả các giá trị thông số được tự động điề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ị 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 kết và phù hợp 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. Bạn nên thông báo cho người dùng về những yêu cầu này trong PREINSTALL.md .

Tài liệu tham khảo về thông số được tự động điề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 có tiện ích đã cài đặt

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

Giá trị mẫu:
project-123

DATABASE_URL URL 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
(các phiên bản ở Hoa Kỳ)
hoặc
https://project-id-default-rtdb.region-code.firebasedatabase.app
(các phiên bản không phả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 chung:
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 chung:
project-id.appspot.com

Giá trị mẫu:
project-123.appspot.com

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ừ name trường được chỉ định trong tệp extension.yaml.

Định dạng chung cho phiên bản được cài đặt đầu tiên (được tự động chỉ định của Firebase; không thể sửa đổi người dùng trong khi cài đặt):
name-from-extension.yaml

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


Định dạng chung cho phiên bản cài đặt thứ 2 trở lên (do Firebase chỉ định tự động; có thể do người dùng sửa đổi trong khi 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 bản sao đã cài đặt của tiện ích, bạn có thể hãy yêu cầu người dùng chỉ định các giá trị thông số trong quá trình cài đặt. Để yêu cầu những thông tin này các giá trị bạn thiết lập trong phần params của extension.yaml .

Sau đây là ví dụ về phần params, theo sau là bảng mô tả tất cả các mục có sẵn các trường thông số.

# 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 cung cấp thông số giá trị

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 cung cấp thông số giá trị

Hỗ trợ Markdown

type
(không bắt buộc)
chuỗi

Cơ chế nhập cho cách người dùng đặt giá trị của thông số (cho ví dụ: nhập văn bản trực tiếp hoặc chọn từ danh sách thả xuống)

Sau đây là các giá trị hợp lệ:

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

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

    Nếu chỉ định giá trị này, bạn cũng phải xác định 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ụ 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ể sẽ phải trả phí cho người dùng cài đặt tiện ích của bạn. 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 Trình quản lý bí mật trên đám mây.

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

options
(bắt buộc nếu tham số typeselect hoặc multiSelect)
list

Danh sách giá trị mà người dùng có thể chọn

Bao gồm các trường labelvalue trong Trường options:

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

Trường value là trường bắt buộc cho options .
Nếu bạn bỏ qua label, lựa chọn danh sách sẽ hiển thị theo mặc định value.

resourceType
(bắt buộc nếu tham số typeselectResource)
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:

Loại tài nguyên ID 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ị thông số dưới dạng đầu vào string dạng tự do .

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ố typestring)
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 thông 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 Xác thực và lỗi nhắn tin 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 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, bạn có thể chỉ định giá trị thông số tự động điền cho giá trị default (ví dụ: tham khảo IMG_BUCKET của Đổi kích thước hình ảnh).

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 mặc định là true (tức là một 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 thông số sau khi (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 một "vị trí" tham số cho các chức năng được triển khai của tiện ích, thì bạn nên đưa trường immutable này vào tham số củ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ố bằng type của string, bạn cần xác định xác thực biểu thức chính quy phù hợp thông qua Trường validationRegex.

Ngoài ra, đối với nhiều tiện ích, giá trị thông số thường được yêu cầu là đường dẫn cơ sở dữ liệu hoặc bộ chứa Cloud Storage. Hãy lưu ý rằng trong quá trình cài đặt, định cấu hình lại, hoặc thì dịch vụ Extensions sẽ không xác thực những thông tin sau tại thời gian của giá trị tham số mục nhập:

  • Liệu cơ sở dữ liệu đã chỉ định hoặc bộ chứa Cloud Storage có được thiết lập trong dự án Firebase của người dù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 đang thực sự triển khai các tài nguyên, Bảng điều khiển của Firebase hoặc giao diện dòng lệnh (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, 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ì chúng kiểm soát cấu hình tài nguyên, chúng không thể truy cập dưới dạng biến môi trường từ bên trong mã hàm của bạn.

Thông thường, bạn không cần khai báo bất cứ thông tin nào cho các tham số này trong extension.yaml. Chúng được tự động xác định cho mọi phiên bản tiện ích, và người dùng có cơ hội đặt giá trị tuỳ chỉnh khi họ 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 đè tiện ích của người dùng chế độ cài đặt cho toàn bộ thực thể. 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 Cloud Functions nên được triển khai cho khu vực nào?
firebaseextensions.v1beta.function/memory Bộ nhớ hàm memory Nên phân bổ bao nhiêu megabyte bộ nhớ cho mỗi hàm?
firebaseextensions.v1beta.function/timeoutSeconds Hết thời gian chờ hàm timeout Các hàm phải chạy trong bao nhiêu giây trước khi hết thời gian chờ?
firebaseextensions.v1beta.function/vpcconnectorEgressSettings Đầu ra trình kết nối VPC vpcConnectorEgressSettings Kiểm soát lưu lượng đi khi định cấu hình trình kết nối VPC
firebaseextensions.v1beta.function/vpcconnector Đầu nối VPC vpcConnector Kết nối Chức năng đám mây với trình kết nối VPC được chỉ định.
firebaseextensions.v1beta.function/minInstances Số bản sao hàm tối thiểu minInstances Số lượng thực thể tối thiểu của hàm này có thể 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 lưu lượng vào ingressSettings Kiểm soát nơi bắt nguồn lưu lượng truy cập đến được chấp nhận
firebaseextensions.v1beta.function/labels Nhãn labels Các nhãn để áp dụng cho tất cả tài nguyên trong tiện ích