Tệp kê khai tiện ích là một danh sách các thực thể tiện ích và cấu hình của các thực thể đó. 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 khác nhau (chẳng hạn như từ dự án thử nghiệm sang dự án chính thức)
- Triển khai tất cả các tiện ích cùng một lúc
- Kiểm thử cách tiện ích hoạt động với ứng dụng bằng Bộ công cụ mô phỏng cục bộ Firebase
- Xác nhận cấu hình tiện ích cho quyền 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
trongfirebase.json
, là bản đồ ánh xạ mã thực thể với tệp 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 conextensions/
của thư mục dự án Firebase. Ví dụ: một thực thể củastorage-resize-images
có thể có tệp.env
như sau:IMAGE_TYPE=jpeg LOCATION=us-central1 IMG_BUCKET=${param:PROJECT_ID}.appspot.com 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 của bạn 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 pháp đầu tiên sẽ được giải thích ở bên dưới.
Quản lý tệp kê khai tiện ích của bạn 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
Việc chạy lệnh trên sẽ nhắc bạn đị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 của 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 một dự án
Để lưu cấu hình tiện ích hiện tại của một dự án vào tệp kê khai, hãy làm như sau:
- Hãy thiết lập Giao diện dòng lệnh (CLI) của Firebase nếu bạn chưa thực hiện
- Từ lời nhắc shell, hãy thay đổi sang thư mục dự án. (Thư mục dự án của bạn chứa tệp
firebase.json
). - 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 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 tiện ích bằng Bộ mô phỏng cục bộ của Firebase
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 Bộ công cụ mô phỏng cục bộ.
-
- Để chạy Bộ mô phỏng theo cách có tính tương tác, hãy chạy:
firebase emulators:start
- Để chạy Bộ mô phỏng và thực thi tập lệnh kiểm thử, hãy chạy:
firebase emulators:exec my-test.sh
- Để chạy Bộ mô phỏng theo cách có tính tương tác, hãy chạy:
Giờ đây, nếu bạn đã liệt kê các thực thể tiện ích trong tệp kê khai, thì Bộ công cụ mô phỏng cục bộ sẽ tải mã nguồn của các tiện ích đó xuống ~/.cache/firebase/extensions
. Sau khi tải xuống, Bộ mô phỏng cục bộ 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 trong nền của tiện ích, đồng thời kết nối ứng dụng của bạn với bộ Trình mô phỏng để kiểm thử quá trình tích hợp với ứng dụng của bạn.
Triển khai cấu hình tiện ích cho một dự án
Sau khi thêm một số bản sao 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 cách sử dụ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 mọi 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:
- Từ lời nhắc shell, hãy thay đổi 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ạyext:export
, thì bạn đã ở đúng thư mục.) - Chạy lệnh
deploy
. Nếu bạn muốn triển khai các 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 của thực thể, hỏi xem bạn có muốn xoá bất kỳ phiên bản tiện ích 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ả các phiên bản tiện ích.
Cấu hình phần mở rộng dành riêng cho dự án
Bạn có thể sử dụng các cấu hình tiện ích đã lưu để triển khai cho nhiều dự án, ví dụ: dự án thử nghiệm và dự án chính thức. Khi thực hiện việc này, một số giá trị tham số có thể cần phải khác nhau cho từng dự án.
Các tệp .env
dành riêng cho dự án giúp thực hiện điều này:
- Đặt các giá trị tham số khác nhau giữa các dự án vào
extensions/EXTENSION_INSTANCE_ID.env.YOUR_PROJECT_ID
- Đặt các giá trị thông số dùng chung 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 tiện ích: ví dụ: bạn có thể muốn cung cấp khoá API kiểm thử 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 trong
extensions/EXTENSION_INSTANCE_ID.env.local
- Đặt các giá trị thông số bí mật trong
extensions/EXTENSION_INSTANCE_ID.secret.local