Sau khi di chuyển từ Firebase Extensions sang một bộ công cụ chức năng, bạn sẽ quản lý các phiên bản bộ công cụ của mình dưới dạng Cloud Functions thế hệ thứ 2 tiêu chuẩn trong dự án Firebase. Hướng dẫn này trình bày cách cài đặt các bộ chức năng mới trực tiếp từ npm mà không cần di chuyển tiện ích hiện có, cập nhật các tham số và lựa chọn chung của bộ công cụ, nâng cấp phiên bản gói npm khi nhà xuất bản phát hành bản cập nhật và khôi phục quá trình di chuyển nếu cần.
Sử dụng một bộ hàm từ gói npm mà không cần di chuyển
Nếu bạn không di chuyển từ một tiện ích, thì việc sử dụng bộ công cụ chức năng sẽ bao gồm 2 phần:
Lắp đặt bộ dụng cụ
Bạn có thể cài đặt một bộ chức năng bằng lệnh CLI sau:
firebase functions:kits:install --package <npm-package-name>
Ví dụ minh hoạ:
firebase functions:kits:install --package @firebase-function-kits/firestore-bigquery-export --project my-project
✔ What would you like to name this kit? firestore-bigquery-export
✔ What would you like to name this instance? firestore-bigquery-export
i function-kits/firestore-bigquery-export/source/package.json is unchanged
i function-kits/firestore-bigquery-export/source/tsconfig.json is unchanged
i function-kits/firestore-bigquery-export/source/.gitignore is unchanged
i functions: Running npm install @firebase-function-kits/firestore-bigquery-export@next --save-prefix=^...
i functions: Building TypeScript source...
✔ Wrote configuration info to firebase.json
i functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project
Prompting for parameters for codebase firestore-bigquery-export:
✔ Enter a string value for FUNCTION_DEFAULT_REGION:
(Global default region where functions should be deployed. Can be overridden per-function.) us-east1
✔ Enter a string value for BigQuery Project ID:
(Override the default project for BigQuery instance. This can allow updates to be directed to a BigQuery
instance on another GCP project.) my-bigquery-project
✔ Enter a string value for Firestore Instance ID:
(The Firestore database to use. Use "(default)" for the default database. You can view your available
Firestore databases at https://console.cloud.google.com/firestore/databases.) eu-testing
# Omitting many more parameters for brevity
✔ Wrote configuration info to firebase.json
✔ functions: Function kit firestore-bigquery-export successfully installed.
i functions: At the first deploy, the following functions will be created in your project:
- kit-firestore-bigquery-export-fsexportbigquery
- kit-firestore-bigquery-export-initBigQuerySync
- kit-firestore-bigquery-export-setupBigQuerySync
i functions: At the first deploy, the following Task Queues will be created in your project:
- kit-firestore-bigquery-export-initBigQuerySync
- kit-firestore-bigquery-export-setupBigQuerySync
i functions: At the first deploy, the following APIs will be enabled in your project:
- bigquery.googleapis.com
- cloudtasks.googleapis.com
i functions: At the first deploy, the following roles will be granted to the kit service account:
- BigQuery Data Editor
- BigQuery User
- Cloud Datastore User
- Eventarc Event Receiver
- roles/run.invoker
⚠ functions: Please review the changes above. If you do not want them applied to your project, uninstall this kit before running firebase deploy.
Thay đổi các lựa chọn mặc định trên toàn cầu
Để định cấu hình các lựa chọn chung cho phiên bản bộ công cụ, hãy sửa đổi tệp index.ts nằm tại function-kits/<your-kit-id>/source/src/index.ts.
Nếu bạn muốn chia sẻ các giá trị mặc định trên tất cả các phiên bản của bộ công cụ, hãy đặt các giá trị đó trực tiếp trong index.ts. Nếu không, hãy tạo các tham số được đặt cho mỗi phiên bản, theo các ví dụ và hướng dẫn được ghi lại trong index.ts.
Triển khai bộ công cụ
Để triển khai bộ hàm, hãy chạy:
firebase deploy --only functions:<kit-instance-id>
Ví dụ minh hoạ:
firebase deploy --only functions:firestore-bigquery-export --project my-project
Đầu ra:
=== Deploying to 'my-project'...
i deploying functions
i functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project
i functions: ensuring required API bigquery.googleapis.com is enabled...
i functions: ensuring required API cloudtasks.googleapis.com is enabled...
✔ functions: required APIs are enabled
i functions: granting declarative IAM roles to managed service account:
- BigQuery Data Editor
- BigQuery User
- Cloud Datastore User
- Eventarc Event Receiver
- roles/run.invoker
✔ functions: successfully granted IAM roles
i functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-fsexportbigquery(us-central1)...
i functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-initBigQuerySync(us-central1)...
i functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-setupBigQuerySync(us-central1)...
✔ functions[kit-firestore-bigquery-export-fsexportbigquery(us-central1)] Successful create operation.
✔ functions[kit-firestore-bigquery-export-initBigQuerySync(us-central1)] Successful create operation.
✔ functions[kit-firestore-bigquery-export-setupBigQuerySync(us-central1)] Successful create operation.
i functions: Executing afterFirstDeploy lifecycle hook targeting: kit-firestore-bigquery-export-initBigQuerySync...
✔ functions: Successfully queued task for lifecycle hook kit-firestore-bigquery-export-initBigQuerySync in queue projects/my-project/locations/us-central1/queues/kit-firestore-bigquery-export-initBigQuerySync.
✔ Deploy complete!
Việc cài đặt và triển khai bộ công cụ này sẽ thực hiện các thao tác sau:
- Tạo
function-kits/firestore-bigquery-export/source, chứa nguồn của bộ công cụ, bao gồm một tệpindex.tscơ bản nhập và xuất gói bộ công cụ trong khi thiết lập một tham số cho phép bạn chọn một vị trí khác cho mỗi phiên bản của bộ công cụ. - Tạo
function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.<project-id>và điền sẵn dữ liệu cấu hình đã nhập cho hàm. Nếu các bản cập nhật trong tương lai thêm tham số mới, bạn sẽ được nhắc trong lần triển khai tiếp theo. - Tạo các tài nguyên Google Cloud cần thiết để chạy bộ công cụ này, bao gồm cả tài khoản dịch vụ có các vai trò IAM cụ thể, các hàm, trình kích hoạt Eventarc và hàng đợi Cloud Tasks.
Nếu có nhiều phiên bản của bộ công cụ trong cùng một dự án, bạn có thể lặp lại các lệnh này để tạo và triển khai các phiên bản mới của cùng một bộ công cụ. Bạn cũng có thể triển khai một phiên bản bộ công cụ duy nhất cho nhiều dự án Firebase với các cấu hình khác nhau (ví dụ: dự án dàn dựng và dự án phát hành công khai). Để tìm hiểu thêm về các chế độ thiết lập nâng cao, hãy xem bài viết Di chuyển nâng cao.
Gỡ cài đặt bộ dụng cụ
Để xoá bộ công cụ và tất cả các phiên bản của bộ công cụ đó, hãy chạy lệnh:
firebase functions:kits:uninstall --kit <kit-id>
Thao tác này sẽ xoá tất cả các phiên bản và cấu hình của chúng, đồng thời xoá nguồn của bộ công cụ khỏi ổ đĩa.
Để chỉ xoá một phiên bản của bộ công cụ, hãy chạy lệnh:
firebase functions:kits:uninstall --instance <kit-instance-id>
Nếu bạn chỉ có một phiên bản của bộ công cụ, thì thao tác này sẽ gỡ cài đặt toàn bộ bộ công cụ.
Cập nhật cấu hình bộ công cụ
Trong quá trình cài đặt hoặc triển khai lần đầu, bạn sẽ được nhắc định cấu hình tất cả các tham số cho bộ công cụ (trừ phi bạn đã di chuyển cấu hình từ một tiện ích).
Các tham số này được lưu trữ trong tệp .env trong thư mục cấu hình của phiên bản bộ công cụ. Ví dụ: nếu bạn có một thực thể của bộ công cụ tên là firestore-bigquery-export trong dự án my-project, thì tệp .env sẽ nằm tại function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project.
Dòng đó có dạng như sau:
DATASET_LOCATION=us
BIGQUERY_PROJECT_ID=my-project
DATABASE=eu-testing
DATABASE_REGION=eur3
COLLECTION_PATH=posts
WILDCARD_IDS=false
DATASET_ID=firestore_export
TABLE_ID=posts
TABLE_PARTITIONING=NONE
TIME_PARTITIONING_FIELD=
TIME_PARTITIONING_FIRESTORE_FIELD=
TIME_PARTITIONING_FIELD_TYPE=omit
CLUSTERING=
MAX_DISPATCHES_PER_SECOND=100
VIEW_TYPE=view
MAX_STALENESS=
REFRESH_INTERVAL_MINUTES=
BACKUP_COLLECTION=
TRANSFORM_FUNCTION=
USE_NEW_SNAPSHOT_QUERY_SYNTAX=no
EXCLUDE_OLD_DATA=no
KMS_KEY_NAME=
MAX_ENQUEUE_ATTEMPTS=3
LOG_LEVEL=info
FUNCTION_DEFAULT_REGION=us-west1
Nếu biết giá trị cấu hình mà bạn muốn thay đổi, bạn có thể chỉnh sửa trực tiếp giá trị đó trong tệp .env. Nếu bạn muốn sử dụng lời nhắc tương tác chạy trong quá trình cài đặt và triển khai, hãy xoá các tham số mà bạn muốn thay đổi khỏi tệp .env rồi triển khai lại phiên bản bộ công cụ. Bạn sẽ được nhắc nhập các tham số đó trong quá trình triển khai.
Ví dụ: nếu xoá dòng COLLECTION_PATH=posts và triển khai, bạn sẽ được nhắc nhập dòng này trong quá trình triển khai:
i functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export-d9cd/.env.ajp-testing
Prompting for parameters for codebase firestore-bigquery-export:
Collection path: What is the path of the collection that you would like to export? You may use {wildcard} notation to match a subcollection of all documents in a collection (for example: chatrooms/{chatid}/posts). Parent Firestore Document IDs from {wildcards} can be returned in path_params as a JSON formatted string.
? Enter a string value for Collection path: (posts)
Duy trì và nâng cấp bộ chức năng
Nhà xuất bản có thể cập nhật các gói npm theo thời gian để sửa lỗi, thêm tính năng, cập nhật các phần phụ thuộc hoặc giải quyết các lỗ hổng bảo mật. Bạn nên cập nhật những bản phát hành này và cài đặt các bản cập nhật, đặc biệt là những bản cập nhật giải quyết các lỗ hổng bảo mật.
Lệnh functions:kits:install tạo một toàn bộ mã nguồn cài đặt một bộ công cụ dưới dạng một gói npm và xuất tất cả các hàm của bộ công cụ đó cho từng thực thể của bộ công cụ.
Để nâng cấp một bộ công cụ, hãy cập nhật phiên bản gói rồi triển khai lại từng phiên bản của bộ công cụ để áp dụng các thay đổi.
Xác định xem một bộ công cụ có bản cập nhật hay không
Chuyển đến thư mục source của bộ công cụ tại function-kits/<your-kit-id>/source. Từ thư mục source này, hãy chạy lệnh sau để nhận báo cáo về tất cả các gói npm lỗi thời, bao gồm cả bộ công cụ chức năng và SDK Cloud Functions:
npm outdated
Nếu đã sử dụng một công cụ để xác định các phần phụ thuộc cần cập nhật, chẳng hạn như Dependabot cho GitHub, bạn nên tích hợp thư mục bộ công cụ vào quy trình đó.
Cập nhật bộ dụng cụ
Để cập nhật bộ công cụ và các phần phụ thuộc của bộ công cụ này lên phiên bản mới nhất không có thay đổi gây lỗi (ngoại trừ các bản cập nhật phiên bản lớn có thể chứa các thay đổi gây lỗi), hãy chạy:
npm update --save
Nếu bạn chỉ muốn cập nhật gói bộ công cụ chức năng và không có gói nào khác, hãy truyền tên gói đến npm update:
npm update <package-name> --save
Để nâng cấp một gói lên phiên bản lớn mới nhất (có thể gây ra các thay đổi có thể gây lỗi), hãy chạy:
npm update --save <npm-package-name>@latest
Xem tài liệu về gói và ghi chú phát hành để biết những thay đổi và liệu bạn có cần thực hiện thêm bước nào trước hoặc sau khi triển khai để ngăn chặn các thay đổi gây lỗi hay không.
Triển khai các phiên bản đã cập nhật
Việc chạy npm update chỉ cập nhật mã nguồn cục bộ. Để cập nhật các hàm đang chạy trên đám mây, hãy triển khai lại các hàm đó. Bạn có thể triển khai lại tất cả các hàm trong dự án, bao gồm cả mọi bộ hàm, bằng cách chạy:
firebase deploy --only functions
Huỷ quy trình di chuyển
Để huỷ di chuyển, trước tiên hãy cài đặt lại tiện ích. Bạn có thể dùng tệp .env của bộ công cụ để tìm các giá trị cấu hình cần thiết trong quá trình cài đặt.
Sau khi triển khai tiện ích, hãy gỡ cài đặt phiên bản của bộ công cụ (thao tác này sẽ gỡ cài đặt toàn bộ bộ công cụ nếu đây là phiên bản còn lại cuối cùng):
firebase functions:kits:uninstall --instance <kit-instance-id> --project <project-id>
Lưu cấu hình tiện ích cho quá trình di chuyển trong tương lai
Sau ngày 31 tháng 3 năm 2027, bạn sẽ không thể tìm nạp cấu hình tiện ích hiện có. Nếu không thể di chuyển trước ngày 31 tháng 3 năm 2027, bạn nên lưu tiện ích phòng trường hợp bạn quyết định di chuyển sau ngày này.
Lấy danh sách mã nhận dạng phiên bản tiện ích:
Bạn có thể dùng lệnh CLI
ext:listđể lấy danh sách tất cả các thực thể tiện ích trong dự án Firebase của mình:firebase ext:list --project <project-id>Ví dụ minh hoạ:
firebase ext:list --project my-project» firebaselocal ext:list i extensions: ensuring required API firebaseextensions.googleapis.com is enabled... i extensions: list of extensions installed in ajp-testing: ┌────────────────────────────────────┬───────────┬────────────────────────────────┬────────┬─────────┬─────────────────────┬───────────────────────────────────────────────────┐ │ Extension │ Publisher │ Instance ID │ State │ Version │ Your last update │ Replacement Kit │ ├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤ │ firebase/firestore-bigquery-export │ firebase │ firestore-bigquery-export-zbrp │ ACTIVE │ 0.3.3 │ 2026-09-06 22:31:04 │ @firebase-function-kits/firestore-bigquery-export │ ├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤ │ firebase/firestore-bigquery-export │ firebase │ firestore-bigquery-export │ ACTIVE │ 0.3.2 │ 2026-06-03 17:41:24 │ @firebase-function-kits/firestore-bigquery-export │ └────────────────────────────────────┴───────────┴────────────────────────────────┴────────┴─────────┴─────────────────────┴───────────────────────────────────────────────────┘ ⚠ Notice: Firebase Extensions will shut down on March 31, 2027. Learn more: https://firebase.google.com/docs/extensions/faq-and-troubleshootingLệnh
ext:listcũng có định dạng đầu ra JSON và nếu đã cài đặt tiện ích jq, bạn có thể dùng tiện ích này để lấy danh sách tất cả mã nhận dạng phiên bản cho một dự án:firebase ext:list --json --project <project-id> | jq -r '.result[].instanceId'Ví dụ minh hoạ:
firebase ext:list --json --project my-project | jq -r '.result[].instanceId'Đầu ra:
firestore-bigquery-export-zbrp firestore-bigquery-exportXuất cấu hình cho từng phiên bản:
Đối với mỗi phiên bản, bạn có thể lưu cấu hình của phiên bản đó trên đĩa bằng cách thực thi lệnh xuất sau:
firebase ext:export --mode functions --project <project-id> --instance <your-instance-id>Ví dụ minh hoạ:
firebase ext:export --mode functions --project my-project --instance firestore-bigquery-exportĐầu ra:
i extensions: ensuring required API firebaseextensions.googleapis.com is enabled... i functions: Saving exported extensions config as a Function Kits .env file i functions: Created new local file firestore-bigquery-export/.env.testing to store param values. We suggest explicitly adding or excluding this file from version control. i functions: Loaded environment variables from firestore-bigquery-export/.env.testing i functions: Loaded environment variables from firestore-bigquery-export/.env.testing i functions: Writing new parameter values to disk: firestore-bigquery-export/.env.testingTrên ổ đĩa, bạn sẽ thấy một bản xuất của phiên bản tiện ích này tại một vị trí như
<instance-id>/.env.<project-id>. Trong ví dụ này, tệp nằm ởfirestore-bigquery-export/.env.my-project.Bạn có thể lặp lại quy trình này một lần cho mỗi phiên bản và quy trình này sẽ tạo một tập hợp các tệp
.envcó tất cả cấu hình phiên bản tiện ích mà bạn có thể sử dụng lại sau này trong quá trình di chuyển.Di chuyển các tệp
.envđã xuất đến một vị trí phù hợp hơn:Các tệp
.envđược xuất từ các tiện ích của bạn sẽ được đặt trực tiếp vào dự án Firebase, nhưng không cần thiết hằng ngày nếu bạn chưa di chuyển sang bộ công cụ chức năng. Bạn có thể di chuyển các tệp này từ dự án của mình đến bất kỳ vị trí lưu trữ thích hợp nào khác cho đến khi cần dùng hoặc chọn xoá chúng.