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

Tệp kê khai tiện ích là danh sách các phiên bản tiện ích 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 tiện ích của bạn với người khác
  • Sao chép cấu hình tiện ích giữa các dự án (chẳng hạn như từ dự án thử nghiệm sang dự án chính thức)
  • Triển khai tất cả tiện ích cùng một lúc
  • Kiểm thử cách các tiện ích hoạt động với ứng dụng của bạn bằng Firebase Local Emulator Suite
  • Đưa cấu hình tiện ích vào hệ thống kiểm soát nguồn
  • Đưa tiện ích vào quy trình CI/CD

Tệp kê khai tiện ích có hai phần:

  • Phần extensions của firebase.json, là bản đồ mã thực thể cho tham chiếu phiên bản tiện ích. Ví dụ:

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

  • Các tệp .env chứa cấu hình cho từng phiên bản tiện ích, 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 tiện ích

Có 3 cách để tạo tệp kê khai tiện ích:

  • Quản lý tệp kê khai tiện ích bằng Giao diện dòng lệnh (CLI) của Firebase
  • Xuất cấu hình tiện ích 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 tiện ích 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 tiện ích 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 tiện ích 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 cho 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 tiện ích:

# 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 tiện ích của dự án

Để lưu cấu hình tiện ích 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 thực hiện, hãy thiết lập Giao diện dòng lệnh (CLI) của Firebase
  2. Từ lời nhắc shell, 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 một phần extensions vào tệp firebase.json. Ngoài ra, lệnh ext:export sẽ tạo một thư mục extensions chứa tệp .env cho mỗi phiên bản tiện ích mà bạn đã cài đặt. Các tệp này chứa tham số cấu hình cho từng thực thể.

Kiểm thử cấu hình tiện ích bằng Firebase Local Emulator Suite

Sau khi thêm một số thực thể tiện ích vào tệp kê khai tiện ích, 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. Bắt đầu Local Emulator Suite:

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

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

Triển khai cấu hình tiện ích cho một dự án

Sau khi thêm một số phiên bản tiện ích vào tệp kê khai tiện ích, bạn có thể triển khai tiện ích đó cho một 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 tiện ích, bạn sẽ cài đặt, cập nhật và định cấu hình tất cả các phiên bản tiện ích 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 tiện ích:

  1. Từ lời nhắc shell, hãy chuyển sang thư mục chứa cấu hình tiện ích đã lưu. (Đây là thư mục chứa firebase.json. Nếu 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 tiện ích cho một dự án khác với dự án hiện tại, hãy chỉ định --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ể tiện ích nào khỏi dự án đích không có trong firebase.json hay không, sau đó triển khai tất cả thực thể tiện ích của bạn.

Cấu hình tiện ích theo dự án

Bạn có thể dùng cấu hình tiện ích đã lưu để triển khai cho nhiều dự án khác nhau, chẳng hạn như dự án thử nghiệm và dự án chính thức. Khi làm việc này, một số giá trị tham số có thể cần phải khác nhau cho mỗi dự án. Các tệp .env dành riêng cho dự án giúp 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ố dùng chung vào 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 tiện ích: ví dụ: bạn có thể muốn cung cấp khoá API thử nghiệm thay vì khoá API chính thức. Đặt các tham số này vào tệp .local:

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