Các phương pháp hay nhất sau khi di chuyển

Sau khi di chuyển từ Firebase Extensions sang một bộ hàm, bạn sẽ quản lý các thực thể của bộ hàm 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 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 tham số bộ chức năng và tuỳ chọn chung, 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 bộ hàm từ một gói npm mà không 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ộ hàm sẽ bao gồm hai phần:

Lắp đặt bộ dụng cụ

Bạn có thể cài đặt bộ hàm 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 chung mặc định

Để định cấu hình các tuỳ chọn chung cho thực thể 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 tham số được đặt cho mỗi thực thể, 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 lệnh:

firebase deploy --only functions:<kit-instance-id>

Ví dụ minh hoạ:

firebase deploy --only functions:firestore-bigquery-export --project my-project

Kết quả:

=== 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ụ sẽ thực hiện các thao tác sau:

  • Tạo function-kits/firestore-bigquery-export/source, chứa nguồn bộ công cụ, bao gồm cả tệp index.ts cơ bản nhập và xuất gói bộ công cụ trong khi thiết lập tham số cho phép bạn chọn một vị trí khác cho mỗi thực thể của bộ công cụ.
  • Tạo function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.<project-id> và điền dữ liệu cấu hình đã nhập cho hàm vào tệp này. 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, hàm, điều kiện kích hoạt Eventarc và hàng đợi tác vụ Cloud Tasks cụ thể.

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ụ cho nhiều dự án Firebase có cấu hình khác nhau (ví dụ: một dự án thử nghiệm và một dự án chính thức). Để tìm hiểu thêm về cá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ộ cô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:

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 bộ công cụ khỏi ổ đĩa.

Để chỉ xoá một thực thể của bộ công cụ, hãy chạy:

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ả 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 thực thể bộ công cụ. Ví dụ: nếu bạn có một phiên bản 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.

Nó 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ố 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 bạn 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.my-project
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 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 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 bộ công cụ dưới dạng gói npm và xuất tất cả hàm của bộ công cụ đó cho mỗi 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. Trong 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ộ hàm và SDK Cloud Functions:

npm outdated

Nếu bạn đã 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ông việc đó.

Cập nhật bộ công cụ

Để cập nhật bộ công cụ và các phần phụ thuộc của bộ công cụ lên phiên bản mới nhất không gây lỗi (không bao gồm các bản cập nhật phiên bản lớn có thể chứa các thay đổi có thể gây lỗi), hãy chạy lệnh:

npm update --save

Nếu bạn chỉ muốn cập nhật gói bộ công cụ hàm mà không cập nhật các gói khác, hãy truyền tên gói vào 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 thay đổi có thể gây lỗi), hãy chạy:

npm update --save <npm-package-name>@latest

Xem lại 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 có thể gây lỗi hay không.

Đang 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ủa bạn. Để 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ả hàm trong dự án, bao gồm cả tất cả bộ hàm, bằng cách chạy:

firebase deploy --only functions

Huỷ quá trình di chuyển

Để huỷ quá trình di chuyển, trước tiên hãy cài đặt lại tiện ích. Bạn có thể sử 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 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 cuối cùng còn lại):

firebase functions:kits:uninstall --instance <kit-instance-id> --project <project-id>

Lưu cấu hình tiện ích để 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 của mình phòng trường hợp bạn quyết định di chuyển sau ngày này.

  1. Lấy danh sách mã nhận dạng thực thể tiện ích:

    Bạn có thể dùng lệnh CLI ext:list để lấy danh sách tất cả các phiên bản 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

    » firebase ext:list
i  extensions: ensuring required API firebaseextensions.googleapis.com is enabled...
i  extensions: list of extensions installed in my-project:
┌────────────────────────────────────┬───────────┬────────────────────────────────┬────────┬─────────┬─────────────────────┬───────────────────────────────────────────────────┐
│ 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-troubleshooting

    Lệnh ext:list cũng có định dạng đầu ra JSON và nếu đã cài đặt tiện ích jq, bạn có thể sử dụng tiện ích này để lấy danh sách tất cả mã thực thể 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'

    Kết quả:

    firestore-bigquery-export-zbrp
firestore-bigquery-export

  2. Xuấ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

    Kết quả:

    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.testing

    Trên ổ đĩa, bạn sẽ thấy một bản xuất của thực thể 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 .env có 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.

  3. Di chuyển các tệp .env đã xuất sang một vị trí phù hợp hơn:

    Các tệp .env được xuất từ tiện ích của bạn đã đượ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ộ hàm. Bạn có thể di chuyển các tệp này từ dự án của mình sang bất kỳ vị trí lưu trữ thích hợp nào khác cho đến khi cần dùng trong tương lai hoặc chọn xoá các tệp này.