Quản lý cấu hình dự án bằng tệp kê khai tiện ích

Tệp kê khai phần mở rộng là danh sách các thực thể phần mở rộng và cấu hình của chúng. Với tệp kê khai, bạn có thể:

  • Chia sẻ cấu hình phần mở rộng với người khác
  • Sao chép cấu hình phần mở rộng giữa các dự án (chẳng hạn như từ dự án dàn dựng sang dự án phát hành công khai)
  • Triển khai tất cả phần mở rộng cùng một lúc
  • Kiểm thử cách các phần mở rộng hoạt động với ứng dụng của bạn bằng Firebase Local Emulator Suite
  • Cam kết cấu hình phần mở rộng của bạn để kiểm soát nguồn
  • Đưa các phần mở rộng vào quy trình CI/CD

Tệp kê khai phần mở rộng có 2 phần:

  • Phần extensions của firebase.json, là bản đồ của mã nhận dạng thực thể đến tham chiếu phiên bản phần mở rộng. Ví dụ:

    {
 "extensions": {
   "my-bigquery-extension": "firebase/firestore-bigquery-export@^0.1.18",
   "my-image-resizer": "firebase/storage-resize-images@^0.1.22",
 }
}

  • Tệp .env chứa cấu hình cho từng thực thể phần mở rộng của bạn, trong thư mục con extensions/ của thư mục dự án Firebase. Ví dụ: một thực thể của storage-resize-images có thể có tệp .env như sau:

    IMAGE_TYPE=jpeg
LOCATION=us-central1
IMG_BUCKET=${param:PROJECT_ID}.firebasestorage.app
IMG_SIZES=100x100
DELETE_ORIGINAL_FILE=false

Tạo tệp kê khai phần mở rộng

Có 3 cách để tạo tệp kê khai phần mở rộng:

  • Quản lý tệp kê khai phần mở rộng bằng Giao diện dòng lệnh (CLI) của Firebase
  • Xuất cấu hình phần mở rộng của dự án
  • Chỉnh sửa tệp kê khai theo cách thủ công

Hai phương thức đầu tiên được giải thích bên dưới.

Quản lý tệp kê khai phần mở rộng bằng Giao diện dòng lệnh (CLI) của Firebase

Bạn có thể chạy hầu hết các lệnh ext: của Giao diện dòng lệnh (CLI) của Firebase bằng tuỳ chọn --local để cập nhật tệp kê khai phần mở rộng mà không thực sự thay đổi cấu hình hiện tại của dự án.

Ví dụ:

firebase ext:install --local firebase/firestore-bigquery-export

Khi chạy lệnh trên, bạn sẽ được nhắc định cấu hình phiên bản mới nhất của phần mở rộng firebase/firestore-bigquery-export và lưu cấu hình vào tệp kê khai, nhưng lệnh này sẽ không triển khai cấu hình vào dự án của bạn.

Sau đây là một số ví dụ khác về các lệnh sửa đổi tệp kê khai phần mở rộng:

# ext:configure changes the params for an extension instance in your extensions manifest
$ firebase ext:configure my-bigquery-extension --local

# ext:update --local updates an instance in your extensions manifest
# to the latest version of that extension
$ firebase ext:update my-bigquery-extension --local

# You can also specify a version if you don't want to update to the latest version
$ firebase ext:update my-bigquery-extension firebase/firestore-bigquery-export@0.1.10 --local 

# ext:uninstall --local removes an instance from your extensions manifest
$ firebase ext:uninstall my-bigquery-extension --local

Xuất cấu hình phần mở rộng của dự án

Để lưu cấu hình phần mở rộng hiện tại của dự án vào tệp kê khai, hãy làm như sau:

  1. Nếu bạn chưa làm như vậy, hãy thiết lập Giao diện dòng lệnh (CLI) của Firebase
  2. Từ dấu nhắc lệnh, hãy chuyển sang thư mục dự án. (Thư mục dự án của bạn chứa tệp firebase.json).
  3. Chạy lệnh ext:export: 
    firebase ext:export

Lệnh ext:export sẽ thêm phần extensions vào tệp firebase.json. Ngoài ra, lệnh ext:export sẽ tạo thư mục extensions chứa tệp .env cho từng thực thể phần mở rộng mà bạn đã cài đặt. Các tệp này chứa các tham số cấu hình cho từng thực thể.

Kiểm thử cấu hình phần mở rộng bằng Firebase Local Emulator Suite

Sau khi thêm một số thực thể phần mở rộng vào tệp kê khai phần mở rộng, bạn có thể kiểm thử các thực thể đó bằng Local Emulator Suite.

  1. Cài đặt và định cấu hình Local Emulator Suite.

  2. Khởi động Local Emulator Suite:

    • Để chạy Bộ mô phỏng cục bộ một cách tương tác, hãy chạy: firebase emulators:start
    • Để chạy Bộ mô phỏng cục bộ và thực thi tập lệnh kiểm thử, hãy chạy: firebase emulators:exec my-test.sh

Giờ đây, nếu bạn có các thực thể phần mở rộng được liệt kê trong tệp kê khai, Local Emulator Suite sẽ tải mã nguồn của các phần mở rộng đó xuống ~/.cache/firebase/extensions. Sau khi tải xuống, Local Emulator Suite sẽ khởi động và bạn có thể kích hoạt bất kỳ hàm nào được kích hoạt ở chế độ nền của các phần mở rộng và kết nối ứng dụng của bạn với Bộ mô phỏng để kiểm thử khả năng tích hợp của các hàm đó với ứng dụng của bạn.

Triển khai cấu hình phần mở rộng vào dự án

Sau khi thêm một số thực thể phần mở rộng vào tệp kê khai phần mở rộng, bạn có thể triển khai tệp kê khai đó vào dự án bằng Giao diện dòng lệnh (CLI) của Firebase. Khi triển khai bằng tệp kê khai phần mở rộng, bạn sẽ cài đặt, cập nhật và định cấu hình tất cả thực thể phần mở rộng trong tệp kê khai vào một dự án cùng một lúc.

Cách triển khai tệp kê khai phần mở rộng:

  1. Từ dấu nhắc lệnh, hãy chuyển sang thư mục chứa cấu hình phần mở rộng đã lưu. (Đây là thư mục chứa firebase.json. Nếu bạn vừa chạy ext:export, thì bạn đã ở đúng thư mục.)
  2. Chạy lệnh deploy. Nếu bạn muốn triển khai các phần mở rộng vào một dự án khác với dự án hiện tại, hãy chỉ định thêm --project=: 
    firebase deploy --only extensions –-project=YOUR_PROJECT_ID

Lệnh deploy sẽ xác thực từng cấu hình thực thể, hỏi xem bạn có muốn xoá bất kỳ thực thể phần mở rộng nào khỏi dự án đích không được liệt kê trong firebase.json hay không, sau đó triển khai tất cả thực thể phần mở rộng của bạn.

Cấu hình phần mở rộng dành riêng cho dự án

Bạn có thể dùng cấu hình phần mở rộng đã lưu để triển khai vào nhiều dự án khác nhau: ví dụ: dự án dàn dựng và dự án phát hành công khai. Khi thực hiện việc này, một số giá trị tham số có thể cần khác nhau đối với từng dự án. Tệp .env dành riêng cho dự án giúp bạn thực hiện việc này:

  • Đặt các giá trị tham số khác nhau giữa các dự án trong extensions/EXTENSION_INSTANCE_ID.env.YOUR_PROJECT_ID
  • Đặt các giá trị tham số được chia sẻ trong extensions/EXTENSION_INSTANCE_ID.env.

Đôi khi, bạn có thể muốn sử dụng một giá trị tham số khác khi mô phỏng các phần mở rộng: ví dụ: bạn có thể muốn cung cấp khoá API kiểm thử thay vì khoá API phát hành công khai. Đặt các tham số này trong tệp .local:

  • Đặt các tham số không phải là bí mật mà bạn muốn sử dụng trong quá trình mô phỏng trong extensions/EXTENSION_INSTANCE_ID.env.local
  • Đặt các giá trị tham số bí mật trong extensions/EXTENSION_INSTANCE_ID.secret.local