Setelah Anda bermigrasi dari Firebase Extensions ke kit fungsi, Anda mengelola instance kit sebagai Cloud Functions generasi ke-2 standar di project Firebase Anda. Panduan ini membahas cara menginstal kit fungsi baru langsung dari npm tanpa memigrasikan ekstensi yang ada, memperbarui parameter kit dan opsi global, mengupgrade versi paket npm saat penerbit merilis update, dan melakukan roll back migrasi jika diperlukan.
Menggunakan kit fungsi dari paket npm tanpa melakukan migrasi
Jika Anda tidak bermigrasi dari ekstensi, penggunaan kit fungsi terdiri dari dua bagian:
Menginstal kit
Anda dapat menginstal kit fungsi menggunakan perintah CLI berikut:
firebase functions:kits:install --package <npm-package-name>
Contoh penggunaan:
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.
Mengubah opsi global default
Untuk mengonfigurasi opsi
global
untuk instance kit Anda, ubah file index.ts yang ada di
function-kits/<your-kit-id>/source/src/index.ts.
Jika Anda ingin setelan default dibagikan di semua instance kit, tetapkan setelan tersebut langsung di index.ts. Jika tidak, buat
parameter yang ditetapkan per instance,
dengan mengikuti contoh dan petunjuk yang didokumentasikan di index.ts.
Men-deploy kit
Untuk men-deploy kit fungsi, jalankan:
firebase deploy --only functions:<kit-instance-id>
Contoh penggunaan:
firebase deploy --only functions:firestore-bigquery-export --project my-project
Output:
=== 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!
Menginstal dan men-deploy kit akan melakukan tindakan berikut:
- Membuat
function-kits/firestore-bigquery-export/source, yang berisi sumber kit termasuk fileindex.tsdasar yang mengimpor dan mengekspor paket kit sambil menyiapkan parameter yang memungkinkan Anda memilih lokasi berbeda untuk setiap instance kit. - Membuat
function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.<project-id>dan mengisinya dengan data konfigurasi yang dimasukkan untuk fungsi. Jika pembaruan mendatang menambahkan parameter baru, Anda akan diminta untuk melakukannya pada deployment berikutnya. - Membuat resource Google Cloud yang diperlukan untuk menjalankan kit ini, termasuk akun layanan dengan peran IAM, fungsi, pemicu Eventarc, dan antrean Cloud Tasks tertentu.
Jika memiliki beberapa instance kit dalam project yang sama, Anda dapat mengulangi perintah ini untuk membuat dan men-deploy instance baru dari kit yang sama. Anda juga dapat men-deploy satu instance kit ke beberapa project Firebase dengan konfigurasi yang berbeda (misalnya, project staging dan project produksi). Untuk mempelajari lebih lanjut penyiapan lanjutan, lihat Migrasi lanjutan.
Meng-uninstal kit
Untuk menghapus kit dan semua instance-nya, jalankan:
firebase functions:kits:uninstall --kit <kit-id>
Tindakan ini akan menghapus semua instance dan konfigurasinya serta menghapus sumber kit dari disk.
Untuk menghapus hanya satu instance kit, jalankan:
firebase functions:kits:uninstall --instance <kit-instance-id>
Jika Anda hanya memiliki satu instance kit, tindakan ini akan meng-uninstal seluruh kit.
Memperbarui konfigurasi kit
Selama penginstalan atau deployment pertama, Anda akan diminta untuk mengonfigurasi semua
parameter untuk kit (kecuali jika Anda memigrasikan konfigurasi dari ekstensi).
Parameter ini disimpan dalam file .env di direktori konfigurasi instance kit Anda. Misalnya, jika Anda memiliki instance kit bernama
firestore-bigquery-export di project my-project, file .env terletak
di
function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project.
Tampilannya akan terlihat seperti berikut:
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
Jika mengetahui nilai konfigurasi yang ingin diubah, Anda dapat mengeditnya secara langsung
di file .env. Jika Anda lebih suka menggunakan perintah interaktif yang berjalan selama penginstalan dan deployment, hapus parameter yang ingin Anda ubah dari file .env dan deploy ulang instance kit. Anda akan diminta untuk memasukkan parameter tersebut selama deployment.
Misalnya, jika Anda menghapus baris COLLECTION_PATH=posts dan men-deploy, Anda akan diminta untuk memasukkannya selama deployment:
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)
Memelihara dan mengupgrade kit fungsi
Dari waktu ke waktu, penayang dapat mengupdate paket npm mereka untuk memperbaiki bug, menambahkan fitur, mengupdate dependensi, atau mengatasi kerentanan keamanan. Sebaiknya selalu ikuti info terbaru tentang rilis ini dan instal update, terutama yang mengatasi kerentanan keamanan.
Perintah functions:kits:install membuat codebase yang menginstal kit sebagai
paket npm dan mengekspor semua fungsinya untuk setiap instance kit Anda.
Untuk mengupgrade kit, perbarui versi paket, lalu deploy ulang setiap instance kit untuk menerapkan perubahan.
Menentukan apakah kit memiliki update
Buka direktori source kit Anda di
function-kits/<your-kit-id>/source. Dari direktori source ini, jalankan perintah berikut untuk mendapatkan laporan tentang semua paket npm yang sudah tidak berlaku, termasuk kit fungsi dan SDK Cloud Functions:
npm outdated
Jika Anda sudah menggunakan alat untuk mengidentifikasi dependensi yang perlu diupdate, seperti Dependabot untuk GitHub, sebaiknya integrasikan direktori kit Anda ke dalam alur kerja tersebut.
Memperbarui kit
Untuk mengupdate kit dan dependensinya ke versi non-breaking terbaru (tidak termasuk update versi utama yang mungkin berisi perubahan yang merusak), jalankan:
npm update --save
Jika Anda hanya ingin mengupdate paket kit fungsi dan tidak ada paket lain, teruskan
nama paket ke npm update:
npm update <package-name> --save
Untuk mengupgrade paket ke versi utama terbaru (yang dapat memperkenalkan perubahan yang merusak), jalankan:
npm update --save <npm-package-name>@latest
Tinjau dokumentasi paket dan catatan rilis untuk melihat apa yang telah berubah dan apakah Anda perlu melakukan langkah tambahan sebelum atau setelah deployment untuk mencegah perubahan yang merusak.
Men-deploy instance yang diupdate
Menjalankan npm update hanya akan memperbarui kode sumber lokal Anda. Untuk memperbarui fungsi yang sedang berjalan di cloud, deploy ulang fungsi tersebut. Anda dapat men-deploy ulang semua fungsi di project, termasuk semua kit fungsi, dengan menjalankan:
firebase deploy --only functions
Membatalkan migrasi
Untuk mengurungkan migrasi, instal ulang ekstensi terlebih dahulu. Anda dapat menggunakan file .env
kit untuk menemukan nilai konfigurasi yang diperlukan selama penginstalan.
Setelah ekstensi di-deploy, uninstal instance kit (tindakan ini akan meng-uninstal seluruh kit jika instance tersebut adalah instance terakhir yang tersisa):
firebase functions:kits:uninstall --instance <kit-instance-id> --project <project-id>
Menyimpan konfigurasi ekstensi untuk migrasi mendatang
Setelah 31 Maret 2027, Anda tidak akan dapat mengambil konfigurasi ekstensi yang ada. Jika Anda tidak dapat melakukan migrasi sebelum 31 Maret 2027, sebaiknya simpan ekstensi Anda jika Anda memutuskan untuk melakukan migrasi setelah tanggal ini.
Dapatkan daftar ID instance ekstensi Anda:
Anda dapat menggunakan perintah CLI
ext:listuntuk mendapatkan daftar semua instance ekstensi di project Firebase Anda:firebase ext:list --project <project-id>Contoh penggunaan:
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-troubleshootingPerintah
ext:listjuga memiliki format output JSON, dan jika Anda telah menginstal utilitas jq, Anda dapat menggunakannya untuk mendapatkan daftar semua ID instance untuk sebuah project:firebase ext:list --json --project <project-id> | jq -r '.result[].instanceId'Contoh soal:
firebase ext:list --json --project my-project | jq -r '.result[].instanceId'Output:
firestore-bigquery-export-zbrp firestore-bigquery-exportEkspor konfigurasi untuk setiap instance:
Untuk setiap instance, Anda dapat menyimpan konfigurasinya di disk dengan menjalankan perintah ekspor berikut:
firebase ext:export --mode functions --project <project-id> --instance <your-instance-id>Contoh soal:
firebase ext:export --mode functions --project my-project --instance firestore-bigquery-exportOutput:
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.testingDi disk, Anda akan menemukan ekspor instance ekstensi ini di lokasi seperti
<instance-id>/.env.<project-id>. Dalam contoh ini, lokasinya berada difirestore-bigquery-export/.env.my-project.Anda dapat mengulangi proses ini sekali per instance, dan proses ini akan membuat serangkaian file
.envdengan semua konfigurasi instance ekstensi Anda yang dapat digunakan kembali nanti sebagai bagian dari migrasi.Pindahkan file
.envyang diekspor ke lokasi yang lebih baik:File
.envyang diekspor dari ekstensi Anda ditempatkan langsung ke project Firebase Anda, tetapi tidak diperlukan setiap hari jika Anda belum bermigrasi ke kit fungsi. Anda dapat memindahkannya dari project ke lokasi penyimpanan lain yang sesuai hingga Anda membutuhkannya di masa mendatang atau memilih untuk menghapusnya.