Di chuyển Tiện ích Firebase sang bộ công cụ hàm

Hướng dẫn này trình bày cách di chuyển tiện ích từ môi trường Firebase Extensions ngừng hoạt động sang một bộ hàm mà bạn có thể cài đặt và triển khai trong toàn bộ mã nguồn Cloud Functions cho Firebase (thế hệ thứ 2) của riêng mình.

Firebase Extensions quản lý tất cả các khía cạnh của việc tạo, cập nhật và xoá phần mở rộng. Bộ chức năng đóng gói các chức năng của tiện ích dưới dạng Cloud Functions for Firebase thế hệ thứ 2 thông thường. Vì bộ hàm là Cloud Functions tiêu chuẩn, nên bạn có thể tạo, cập nhật, xoá và khắc phục sự cố bằng CLI Firebase trong dự án Firebase. Hướng dẫn này giúp bạn chuẩn bị quản lý các hàm ngay bây giờ và áp dụng các bản cập nhật khi có.

Trong suốt hướng dẫn này, tiện ích Stream Cloud Firestore to BigQuery (firestore-bigquery-export) được dùng làm ví dụ cho bạn thấy các lệnh và kết quả lệnh cho từng bước di chuyển.

Xác định đường dẫn di chuyển

Firebase khuyến khích tất cả nhà xuất bản Firebase Extensions tạo các bản thay thế cho tiện ích của họ dưới dạng bộ hàm được xuất bản trên npm. Bạn có thể kiểm tra xem có bộ hàm thay thế cho tiện ích của mình hay không bằng một vài cách sau:

  • Chuyển đến trang Tiện ích của bảng điều khiển Firebase cho dự án của bạn. Mỗi tiện ích bạn đã cài đặt đều cho biết liệu tiện ích đó có bộ chức năng thay thế hay không.

  • Chạy firebase ext:list bên trong dự án Firebase của bạn trong một dòng lệnh để cho biết tiện ích nào bạn đã cài đặt có tiện ích thay thế chính thức:

    firebase ext:list --project my-project

    i  extensions: ensuring required API firebaseextensions.googleapis.com is enabled...
✔  extensions: 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.2   │ 2026-06-10 18:35:03 │ @firebase-function-kits/firestore-bigquery-export │
├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤
│ firebase/storage-resize-images     │ firebase  │ storage-resize-images          │ ACTIVE │ 0.3.6   │ 2026-06-03 17:41:24 │                                                   │
└────────────────────────────────────┴───────────┴────────────────────────────────┴────────┴─────────┴─────────────────────┴───────────────────────────────────────────────────┘
⚠ Notice: Firebase Extensions will shut down on March 31, 2027. Learn more: https://firebase.google.com/docs/extensions/faq-and-troubleshooting

Nếu có một bộ hàm thay thế chính thức cho tiện ích của bạn, thì bạn có thể di chuyển tiện ích đó bằng cách sử dụng phần Di chuyển sang bộ hàm trên npm.

Nếu không tìm thấy tiện ích thay thế đã xuất bản, bạn có thể phân nhánh mã tiện ích và tạo tiện ích thay thế của riêng mình vì tất cả tiện ích đều là nguồn mở. Để làm việc này, hãy làm theo hướng dẫn Di chuyển sang bộ hàm tự tạo.

Chọn cách thức di chuyển: Di chuyển sang bộ hàm trên npm Di chuyển sang bộ hàm tự tạo

Di chuyển sang bộ hàm trên npm

Kiểm tra các hạn chế đã biết khi di chuyển

Trước khi bắt đầu di chuyển một phiên bản tiện ích, hãy kiểm tra xem chế độ thiết lập của bạn có sử dụng bất kỳ tính năng nào sau đây cần có giải pháp thay thế hoặc chưa được hỗ trợ trong bộ hàm hay không:

  • Kho lưu trữ Docker tuỳ chỉnh và khoá KMS yêu cầu giải pháp thủ công Cloud Functions for Firebase không hỗ trợ các tham số hệ thống thay thế để định cấu hình kho lưu trữ Docker tuỳ chỉnh hoặc Khoá mã hoá do khách hàng quản lý (khoá KMS). Nếu tiện ích của bạn định cấu hình một trong hai tham số này, hãy tham khảo giải pháp trong phần Câu hỏi thường gặp.

Trước khi bắt đầu

Bạn cần thiết lập CLI Firebase và khởi động một dự án Firebase. Khi sử dụng CLI, hãy đảm bảo bạn đang dùng firebase-tools phiên bản >= 15.32.0, có các lệnh di chuyển và bộ hàm mới.

Các quyền và vai trò bắt buộc đối với tài khoản

Tuỳ thuộc vào những gì cần được tạo và định cấu hình bằng CLI Firebase trong quá trình di chuyển, tài khoản bạn đang dùng để xác thực bằng Firebase và Google Cloud phải có các vai trò sau:

  • roles/firebaseextensions.editor
  • roles/cloudbuild.builds.editor
  • roles/artifactregistry.writer
  • roles/run.developer
  • roles/iam.serviceAccountUser
  • roles/iam.serviceAccountCreator
  • roles/cloudfunctions.admin (nếu bạn cần thực hiện setIamPermissions cho các điểm cuối công khai)
  • roles/secretmanager.admin (nếu sử dụng bí mật)
  • roles/serviceusage.serviceUsageAdmin (nếu bạn cần bật các API mới)

Bạn nên sử dụng một tài khoản đã cài đặt tiện ích và triển khai các hàm trước đó, vì hầu hết các quyền này đều đã được cấp. Nếu tài khoản di chuyển của bạn cần thêm vai trò, hãy làm theo Google Cloud hướng dẫn về IAM để thêm vai trò.

Chọn quy trình CLI

Để di chuyển từ một phiên bản tiện ích sang một bộ hàm có trên npm, hãy chọn một trong các phương án sau:

  • (Nên dùng) Di chuyển bằng lệnh CLI ext:migrate. Lệnh này sẽ triển khai bộ hàm thay thế trước khi gỡ cài đặt tiện ích mà bộ hàm này thay thế.
  • Di chuyển bằng lệnh CLI của bộ hàm. Bạn có thể sử dụng các lệnh riêng biệt để cập nhật tiện ích, cài đặt bộ hàm, định cấu hình bộ hàm như tiện ích, triển khai bộ hàm và gỡ cài đặt tiện ích. Điều này giúp bạn linh hoạt hơn trong việc sắp xếp lại các lệnh hoặc thực hiện thêm công việc giữa các bước.

Di chuyển bằng ext:migrate

Mỗi phiên bản tiện ích chỉ cần bắt đầu di chuyển một lần bằng cách chạy:

firebase ext:migrate --project <project-id>

Lệnh này sẽ hướng dẫn bạn:

  1. Chọn một tiện ích để di chuyển có sẵn bộ chức năng chính thức thay thế.
  2. Chọn một phiên bản cụ thể của tiện ích đó.
  3. Cập nhật tiện ích lên phiên bản mới nhất nếu cần.
  4. Cài đặt bộ hàm, định cấu hình một thực thể giống hệt với cách định cấu hình thực thể tiện ích.
  5. Đang triển khai bộ hàm.
  6. Xác minh rằng bộ hàm đã triển khai thành công và tất cả các hook vòng đời (nếu có) đều đã chạy.
  7. Đang gỡ cài đặt phiên bản tiện ích.

Nếu bạn biết tiện ích hoặc phiên bản tiện ích cụ thể mà bạn muốn di chuyển, hãy chỉ định tiện ích đó bằng các cờ dòng lệnh sau:

firebase ext:migrate --extension firebase/firestore-bigquery-export --project <project-id>

# or

firebase ext:migrate --ext-instance firestore-bigquery-export-abcd --project <project-id>

Nếu bạn biết gói cụ thể mà mình muốn di chuyển, đặc biệt là nếu đó không phải là gói thay thế chính thức do Google liệt kê, hãy chỉ định gói đó bằng cờ --package:

firebase ext:migrate --ext-instance firestore-bigquery-export-abcd --package @firebase-function-kits/firestore-bigquery-export --project <project-id>

Xác minh quá trình triển khai bộ hàm

Để xác minh rằng firebase deploy của bộ công cụ không có lỗi, hãy kiểm tra nhật ký triển khai để xem có trình kích hoạt vòng đời nào được kích hoạt hay không. Các tiện ích phổ biến, chẳng hạn như Stream Cloud Firestore to BigQuery, sử dụng hook vòng đời. Sau đây là ví dụ về giao diện của một hook vòng đời khi được kích hoạt:

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/europe-west1/queues/kit-firestore-bigquery-export-initBigQuerySync.
i  functions: View logs for afterFirstDeploy at: https://console.cloud.google.com/logs/query;query=resource.type%3D%22cloud_run_revision%22%0Aresource.labels.service_name%3D%22kit-firestore-bigquery-export--initbigquerysync%22%0Aresource.labels.location%3D%22europe-west1%22;project=my-project

Các thông điệp nhật ký này xác nhận những điều sau:

  • Đã tìm thấy và thực thi một hook vòng đời.
  • Một tác vụ đã được đưa vào hàng đợi trong hàng đợi tác vụ liên kết với trình nối vòng đời.
  • Đường liên kết đến Cloud Logging được cung cấp để bạn có thể xác thực rằng tác vụ đã hoàn tất mà không có lỗi.

Hãy nhấp vào đường liên kết đến nhật ký trong bảng điều khiển Google Cloud để xác thực rằng không có lỗi nào trong nhật ký và sự kiện hàng đợi tác vụ của bạn đã được xử lý thành công. Nếu sự kiện trong vòng đời không thực thi thành công, bạn có thể kích hoạt lại sự kiện đó bằng cách chạy:

firebase functions:lifecycle:run <hook-name> <codebase>

Nếu bạn triển khai một thực thể bộ hàm lần đầu tiên, hãy chạy lệnh:

firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id>

Nếu tại bất kỳ thời điểm nào trong quá trình xác thực, bạn quyết định muốn dừng hoặc huỷ quá trình di chuyển này, bạn có thể gỡ cài đặt bộ công cụ theo hướng dẫn trong phần Gỡ cài đặt tiện ích.

Sau khi xác minh rằng quá trình triển khai ban đầu của bộ hàm đã hoàn tất thành công, bạn cần xác thực rằng chức năng của bộ hàm thực sự hoạt động như mong đợi. Vì bản thân tiện ích vẫn đang chạy, bạn cần cẩn thận để đảm bảo rằng những gì bạn đang kiểm tra không chỉ là một trong hai đã hoạt động, vì tiện ích đã và sẽ tiếp tục hoạt động.

Trong trường hợp quá trình xử lý không thay đổi và bạn không thấy kết quả trùng lặp từ tiện ích và bộ công cụ, thì cách tốt nhất là trực tiếp kiểm tra nhật ký của bộ công cụ sau khi kích hoạt chức năng của bộ công cụ.

Ví dụ thực tế: Chuyển đổi luồng Cloud Firestore thành BigQuery

Với tiện ích Stream Cloud Firestore to BigQuery, các lượt ghi vào cả Bảng nhật ký thay đổi thô (*_raw_changelog) và bảng chế độ xem mới nhất (*_raw_latest) sẽ loại bỏ trùng lặp nếu cùng một sự kiện được phân phối đến bộ công cụ và tiện ích. Vì vậy, bạn không thể sử dụng sự hiện diện của bất kỳ hàng hoặc hàng trùng lặp nào trong BigQuery để xác thực bộ công cụ đang hoạt động.

Bạn có thể xem nhật ký hàm ngay sau khi ghi vào tập hợp Firestore bằng firebase functions:logs và tìm một mục nhập nhật ký cho biết hàm đã xử lý thành công một thao tác ghi. Đối với bộ công cụ này, mã thực thể mặc định firestore-bigquery-export sẽ có dạng như sau:

2026-09-25T19:52:46.328612Z I kit-firestore-bigquery-export-fsexportbigquery: Started execution of extension
2026-09-25T19:52:46.328644Z I kit-firestore-bigquery-export-fsexportbigquery: {"message":"Firestore event received by onDocumentWritten trigger","document_name":"projects/extensions-eventarc-testing/databases/(default)/documents/exported-messages/cmGP6XLyksqGdw2OgTOq","operation":0,"event_id":"9f59a2a4-1a5e-4c41-a32d-561e3c734502"}
2026-09-25T19:52:46.616064Z I kit-firestore-bigquery-export-fsexportbigquery: Completed execution of extension
2026-09-2

Nếu có nhiều nhật ký, bạn có thể lọc ra một hàm cụ thể của bộ công cụ bằng lệnh sau:

firebase functions:log --only <function name>

Để tìm tên hàm cụ thể cho một thực thể bộ công cụ, bạn có thể sử dụng lệnh sau:

firebase functions:list | grep kit-<kit instance id>

Trong ví dụ này:

firebase functions:list | grep kit-firestore-bigquery-export
│ kit-firestore-bigquery-export-fsexportbigquery  │ v2      │ google.cloud.firestore.document.v1.written                    │
│ kit-firestore-bigquery-export-initBigQuerySync  │ v2      │ taskQueue                                                     │
│ kit-firestore-bigquery-export-setupBigQuerySync │ v2      │ taskQueue                                                     │
│ kit-firestore-bigquery-export-syncBigQuery      │ v2      │ taskQueue                                                     │

Xem tệp README của bộ hàm

Một số bộ công cụ có thể yêu cầu bạn thực hiện thêm một số thao tác ngoài những thao tác được bộ công cụ chức năng xử lý tự động. Xem lại README cho bộ công cụ bạn đang cài đặt và làm theo mọi hướng dẫn bổ sung.

Di chuyển bằng CLI của bộ chức năng

Trước khi bắt đầu, hãy xác định và ghi lại mã thực thể của tiện ích mà bạn muốn di chuyển sang một bộ công cụ và tên gói npm của bộ công cụ thay thế. Bạn có thể tìm thấy cả hai thông tin này bằng cách sử dụng kết quả của firebase ext:list. Hãy xem phần Xác định đường dẫn di chuyển để biết ví dụ về cách sử dụng ext:list.

1. Nâng cấp phiên bản tiện ích lên phiên bản mới nhất

Bạn phải cập nhật tiện ích lên phiên bản mới nhất để giảm thiểu sự khác biệt giữa phiên bản tiện ích và bộ thay thế. Nếu tiện ích của bạn không được nâng cấp, thì có thể có những thay đổi đáng kể, có thể gây lỗi giữa phiên bản tiện ích và bộ công cụ thay thế. Cấu hình đã xuất có thể không khớp với cấu hình mà bộ công cụ dự kiến do các thay đổi về tham số giữa các phiên bản.

Sử dụng một trong các lựa chọn sau để cập nhật tiện ích, tuỳ thuộc vào nơi cài đặt tiện ích:

  • Từ Firebase console
  • Từ Firebase CLI bằng cách sử dụng:
    • firebase ext:update <extension-instance-id> --project <project-id> firebase deploy --only extensions --project <project-id>

Nếu bạn bỏ qua bước này, CLI sẽ nhắc bạn nâng cấp khi xuất cấu hình nếu tiện ích của bạn không phải là phiên bản mới nhất.

2. Xem lại và cài đặt phiên bản bộ hàm thay thế

Bạn có thể cài đặt bộ hàm bằng lệnh CLI sau:

firebase functions:kits:install --template migration --no-configure --package <npm-package-name> --project <project-id>

Khi bạn chọn một mã thực thể cho bộ công cụ trong quá trình cài đặt, hãy nhớ ghi lại mã đó để sử dụng sau này trong hướng dẫn di chuyển.

Sau khi cài đặt bộ công cụ, một thư mục mới sẽ được tạo bên trong dự án Firebase của bạn, có vị trí như function-kits/<kit-name>/source. Thư mục này chứa gói npm có bộ công cụ thay thế tiện ích của bạn và một tệp index.ts cơ bản xuất các hàm đó để Firebase triển khai và đặt cấu hình tuỳ chỉnh.

Xem lại README cho bộ công cụ và làm theo mọi hướng dẫn bổ sung được liệt kê trong đó.

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 lệnh này để tạo 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 hai dự án Firebase khác nhau 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 chế độ thiết lập nâng cao này, hãy xem phần Di chuyển nâng cao.

Ví dụ minh hoạ:

firebase functions:kits:install --template migration --no-configure --package @firebase-function-kits/firestore-bigquery-export --project my-project

3. Định cấu hình thực thể bộ hàm giống hệt với tiện ích

Bạn cần tuỳ chỉnh thực thể bộ công cụ này bằng một cấu hình giống hệt với tiện ích mà nó thay thế. Bạn có thể xuất cấu hình thực thể tiện ích vào tệp .env. Tệp này lưu trữ dữ liệu cấu hình tham chiếu bí mật, biến môi trường và tham số cho tất cả Cloud Functions, bao gồm cả bộ công cụ. Để xuất trực tiếp vào tệp cấu hình của bộ công cụ, hãy chạy:

firebase ext:export --mode functions --instance <extension-instance-id> --kit-instance <kit-instance-id> --project <project-id>

Khi kết thúc bước này, thông tin cấu hình cho phiên bản này sẽ được lưu trữ trong tệp .env dành riêng cho dự án trong thư mục cấu hình phiên bản, chẳng hạn như: function-kits/<kit-name>/config-<instance-id>/.env.<project-id>

4. Triển khai và xác minh bộ thay thế

Giờ đây, khi bộ công cụ đã được cài đặt và có sẵn dưới dạng một tập hợp các hàm, bạn có thể triển khai bộ công cụ thay thế. Bộ hàm hoạt động giống như các hàm tiêu chuẩn, trong đó mỗi thực thể của bộ hàm đóng vai trò là một toàn bộ mã nguồn riêng biệt để sắp xếp các hàm của bạn. Bạn có thể chọn triển khai tất cả các hàm hoặc chỉ một thực thể bộ công cụ cụ thể. Trong khi di chuyển một phiên bản tiện ích, chỉ triển khai phiên bản bộ công cụ đó.

Nếu bộ công cụ của bạn sử dụng bất kỳ tham số mới nào không có trong phiên bản tiện ích mà bạn đã di chuyển, thì Firebase CLI sẽ nhắc bạn về các tham số đó khi bắt đầu quá trình triển khai. Điều này không nằm trong dự kiến của ví dụ thực tế này từ một tiện ích firestore-bigquery-export mới nhất, nhưng nhiều bộ công cụ sẽ nhắc nhập một tham số mới cho mọi nguồn kích hoạt sự kiện mà bộ công cụ sử dụng. Trong quá trình di chuyển này, các bộ công cụ đã cập nhật sẽ sử dụng các hàm thế hệ thứ 2, trong khi trước đây các tiện ích sử dụng các hàm thế hệ thứ 1. Trong thế hệ thứ 2, các hàm nằm gần nguồn sự kiện và được thêm dưới dạng tham số bổ sung. Trong các bản cập nhật sau này, nếu có thêm tham số mới, CLI sẽ nhắc bạn trong lần triển khai tiếp theo.

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!

Để xác minh rằng firebase deploy của bộ công cụ không có lỗi, hãy kiểm tra nhật ký triển khai để xem có trình kích hoạt vòng đời nào được kích hoạt hay không. Các tiện ích phổ biến, chẳng hạn như Stream Cloud Firestore to BigQuery, sử dụng hook vòng đời. Sau đây là ví dụ về giao diện của một hook vòng đời khi được kích hoạt:

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/europe-west1/queues/kit-firestore-bigquery-export-initBigQuerySync.
i  functions: View logs for afterFirstDeploy at: https://console.cloud.google.com/logs/query;query=resource.type%3D%22cloud_run_revision%22%0Aresource.labels.service_name%3D%22kit-firestore-bigquery-export--initbigquerysync%22%0Aresource.labels.location%3D%22europe-west1%22;project=my-project

Các thông điệp nhật ký này xác nhận những điều sau:

  • Đã tìm thấy và thực thi một hook vòng đời.
  • Một tác vụ đã được đưa vào hàng đợi trong hàng đợi tác vụ liên kết với trình nối vòng đời.
  • Đường liên kết đến Cloud Logging được cung cấp để bạn có thể xác thực rằng tác vụ đã hoàn tất mà không có lỗi.

Hãy nhấp vào đường liên kết đến nhật ký trong bảng điều khiển Google Cloud để xác thực rằng không có lỗi nào trong nhật ký và sự kiện hàng đợi tác vụ của bạn đã được xử lý thành công. Nếu sự kiện trong vòng đời không thực thi thành công, bạn có thể kích hoạt lại sự kiện đó bằng cách chạy:

firebase functions:lifecycle:run <hook-name> <codebase>

Nếu bạn triển khai một thực thể bộ hàm lần đầu tiên, hãy chạy lệnh:

firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id>

Nếu tại bất kỳ thời điểm nào trong quá trình xác thực, bạn quyết định muốn dừng hoặc huỷ quá trình di chuyển này, bạn có thể gỡ cài đặt bộ công cụ theo hướng dẫn trong phần Gỡ cài đặt tiện ích.

Sau khi xác minh rằng quá trình triển khai ban đầu của bộ hàm đã hoàn tất thành công, bạn cần xác thực rằng chức năng của bộ hàm thực sự hoạt động như mong đợi. Vì bản thân tiện ích vẫn đang chạy, bạn cần cẩn thận để đảm bảo rằng những gì bạn đang kiểm tra không chỉ là một trong hai đã hoạt động, vì tiện ích đã và sẽ tiếp tục hoạt động.

Trong trường hợp quá trình xử lý không thay đổi và bạn không thấy kết quả trùng lặp từ tiện ích và bộ công cụ, thì cách tốt nhất là trực tiếp kiểm tra nhật ký của bộ công cụ sau khi kích hoạt chức năng của bộ công cụ.

Ví dụ thực tế: Chuyển đổi luồng Cloud Firestore thành BigQuery

Với tiện ích Stream Cloud Firestore to BigQuery, các lượt ghi vào cả Bảng nhật ký thay đổi thô (*_raw_changelog) và bảng chế độ xem mới nhất (*_raw_latest) sẽ loại bỏ trùng lặp nếu cùng một sự kiện được phân phối đến bộ công cụ và tiện ích. Vì vậy, bạn không thể sử dụng sự hiện diện của bất kỳ hàng hoặc hàng trùng lặp nào trong BigQuery để xác thực bộ công cụ đang hoạt động.

Bạn có thể xem nhật ký hàm ngay sau khi ghi vào tập hợp Firestore bằng firebase functions:logs và tìm một mục nhập nhật ký cho biết hàm đã xử lý thành công một thao tác ghi. Đối với bộ công cụ này, mã thực thể mặc định firestore-bigquery-export sẽ có dạng như sau:

2026-09-25T19:52:46.328612Z I kit-firestore-bigquery-export-fsexportbigquery: Started execution of extension
2026-09-25T19:52:46.328644Z I kit-firestore-bigquery-export-fsexportbigquery: {"message":"Firestore event received by onDocumentWritten trigger","document_name":"projects/extensions-eventarc-testing/databases/(default)/documents/exported-messages/cmGP6XLyksqGdw2OgTOq","operation":0,"event_id":"9f59a2a4-1a5e-4c41-a32d-561e3c734502"}
2026-09-25T19:52:46.616064Z I kit-firestore-bigquery-export-fsexportbigquery: Completed execution of extension
2026-09-2

Nếu có nhiều nhật ký, bạn có thể lọc ra một hàm cụ thể của bộ công cụ bằng lệnh sau:

firebase functions:log --only <function name>

Để tìm tên hàm cụ thể cho một thực thể bộ công cụ, bạn có thể sử dụng lệnh sau:

firebase functions:list | grep kit-<kit instance id>

Trong ví dụ này:

firebase functions:list | grep kit-firestore-bigquery-export
│ kit-firestore-bigquery-export-fsexportbigquery  │ v2      │ google.cloud.firestore.document.v1.written                    │
│ kit-firestore-bigquery-export-initBigQuerySync  │ v2      │ taskQueue                                                     │
│ kit-firestore-bigquery-export-setupBigQuerySync │ v2      │ taskQueue                                                     │
│ kit-firestore-bigquery-export-syncBigQuery      │ v2      │ taskQueue                                                     │

5. Gỡ cài đặt tiện ích

Sau khi xác minh bộ hàm đã triển khai, bạn có thể gỡ cài đặt tiện ích để không lặp lại hành vi của tiện ích một lần cho bộ hàm và một lần cho tiện ích. Bạn có thể gỡ cài đặt tất cả tiện ích khỏi CLI Firebase bất kể bạn đã cài đặt chúng như thế nào nếu bạn truyền cờ --immediate:

firebase ext:uninstall <extension-instance-id> --project <project-id> --immediate

Ví dụ minh hoạ:

firebase ext:uninstall firestore-bigquery-export --project my-project --immediate

Kết quả:

i  extensions: uninstalling firestore-bigquery-export...
i  extensions: deleting extension instance resources in project my-project...
✔  extensions: successfully uninstalled firestore-bigquery-export

Di chuyển nâng cao

Bạn có thể có các tiện ích trong nhiều dự án Firebase mà bạn muốn quản lý bằng một toàn bộ mã nguồn duy nhất. Ví dụ: nếu bạn triển khai cùng một cơ sở hạ tầng cho môi trường testing và môi trường production, mỗi môi trường có một thực thể documents Cloud Firestore mà bạn xuất sang BigQuery, thì bạn có thể đã cài đặt hai thực thể của tiện ích firestore-bigquery-export:

  • export-documents-testing
  • export-documents-production

Nếu bạn di chuyển hai thực thể tiện ích này sang hai thực thể bộ hàm trong một toàn bộ mã nguồn duy nhất khi làm việc với CLI Firebase và triển khai bằng firebase deploy --project testing và firebase deploy --project production, mỗi lần triển khai sẽ tạo hai thực thể trong cả môi trường testing và production.

Thay vào đó, hãy thay thế hai phiên bản tiện ích bằng một phiên bản bộ hàm của firestore-bigquery-export được triển khai cho nhiều dự án, trong đó mỗi dự án có cấu hình riêng. Thư mục cấu hình cho phiên bản sẽ có dạng như sau:

  • config-export-documents/
    • .env.testing
    • .env.production

Mỗi lần triển khai cho testing và production sẽ tạo một thực thể của bộ công cụ với cấu hình tương ứng. Các lệnh CLI hiện có sẽ tạo chế độ thiết lập này miễn là bạn truyền cờ --project trong mỗi lệnh gọi ext:migrate hoặc functions:kits:install.

Ví dụ minh hoạ:

firebase functions:kits:install --package @firebase-function-kits/firestore-bigquery-export --project testing --no-configure --template migration

✔ What would you like to name this kit? firestore-bigquery-export
✔ What would you like to name this instance? export-documents
✔  Wrote function-kits/firestore-bigquery-export/source/package.json
✔  Wrote function-kits/firestore-bigquery-export/source/tsconfig.json
✔  Wrote function-kits/firestore-bigquery-export/source/.gitignore
✔  Wrote function-kits/firestore-bigquery-export/source/src/index.ts
i  functions: Running npm install
✔  Wrote configuration info to firebase.json
✔  functions: Function kit firestore-bigquery-export successfully installed.

# This creates the export-documents instance with an empty .env.testing file
# for the testing project. Now populate it via export:
firebase ext:export --mode functions --instance export-documents-testing \
  --kit-instance export-documents --project testing

# Repeat the export for production into the same kit instance to create
# .env.production from the export-documents-prod instance:
firebase ext:export --mode functions --instance export-documents-prod \
  --kit-instance export-documents --project production

Giờ đây, bạn đã có một thực thể bộ công cụ duy nhất được định cấu hình để triển khai cho các dự án testing và production với cấu hình tương ứng. Nếu bạn tạo một thực thể trong dự án testing và chạy lệnh functions:kits:install cho cùng một gói trong dự án production, bạn sẽ được nhắc chọn sử dụng lại thực thể đã định cấu hình cho testing hoặc cài đặt thực thể thứ hai.