Panduan ini menunjukkan cara memigrasikan ekstensi Anda dari lingkungan Firebase Extensions yang tidak digunakan lagi ke fungsi yang diinstal dan di-deploy pengguna di Cloud Functions mereka sendiri untuk codebase Firebase (generasi ke-2).
Ini adalah jalur migrasi yang direkomendasikan. Firebase akan mengelola daftar ekstensi dengan padanan npm resmi; panduan ini akan memandu Anda membuat ekstensi sendiri.
Di sepanjang panduan ini, ekstensi Stream Cloud Firestore ke
BigQuery
(firestore-bigquery-export) digunakan sebagai contoh yang berjalan. Setiap
bagian diakhiri dengan Contoh yang berhasil yang menunjukkan tampilan ekstensi tersebut
sebelum migrasi, dan tampilannya setelah migrasi, sebagai
paket
@firebase-function-kits/firestore-bigquery-export.
Daftar untuk mendapatkan informasi dan bantuan selengkapnya terkait migrasi ekstensi
Jika ada pertanyaan tentang cara bermigrasi dari Firebase Extensions, Anda dapat menghubungi kami di firebase-extensions-migrator-support-external@google.com. Kami juga akan mengirimkan email ke grup ini saat kami memperbarui panduan dengan informasi selengkapnya tentang pengemasan, pengujian, dan pendistribusian fungsi generasi ke-2.
Untuk bergabung ke grup ini, kirim pesan ke firebase-extensions-migrator-support-external+subscribe@google.com, yang akan merespons dengan email permintaan keanggotaan. Anda harus membalas email tersebut, bukan mengklik tombol "Gabung ke Grup Ini".
Sebelum memulai
Untuk menyelesaikan migrasi ini sesuai petunjuk, Anda akan menggunakan fitur Cloud Functions berikut:
Konfigurasi Berparameter. Setiap parameter yang Anda deklarasikan di
extension.yamlakan menjadi parameter yang ditentukan dalam kode paket Anda.Peran IAM deklaratif dan API yang diperlukan. Setiap peran yang Anda deklarasikan di
extension.yamlmenjadi panggilanrequiresRole(...), dan setiap API menjadi panggilanrequiresAPI(...)dalam kode paket Anda. Pada waktu deployment, Firebase CLI memberikan peran yang dideklarasikan ke akun layanan runtime terkelola dan mengaktifkan API yang dideklarasikan atas nama Anda.Peristiwa siklus proses untuk codebase Cloud Functions. Codebase Cloud Functions kini mendukung peristiwa siklus proses yang serupa dengan Firebase Extensions. Deklarasikan penyiapan waktu penginstalan dan waktu update dengan hook siklus proses
afterFirstDeploy(...)danafterRedeploy(...). Ini menggantikanlifecycleEventsyang Anda deklarasikan diextension.yaml.
Memigrasikan sumber Firebase Extensions ke fungsi generasi ke-2
(Opsional) Migrasi otomatis dengan Agen Skill Firebase
Anda dapat mengotomatiskan Langkah 1 hingga 8 (menginventarisasi resource, memicu
upgrade, konversi parameter dan secret, IAM deklaratif, hook siklus proses, dan
membuat README paket) menggunakan skill agen AI
extension-to-functions-codebase
resmi.
Menginstal keahlian
Jika Anda atau asisten coding AI Anda (Gemini di Firebase, Cursor, Claude Code, GitHub Copilot) belum menginstal keahlian tersebut, jalankan perintah berikut menggunakan CLI keahlian:
npx skills add firebase/agent-skills --skill extension-to-functions-codebase
Setelah skill diinstal di project, asisten coding AI Anda akan otomatis mengikuti aturan migrasi dan langkah transformasinya. Anda dapat menggunakan perintah berikut:
"Migrasikan Firebase Extension ini ke paket Function Kit Generasi ke-2 yang dapat dipublikasikan
dengan mengikuti petunjuk dalam keterampilan extension-to-functions-codebase."
1. Menginventarisasi ekstensi
Mulailah dengan membuat inventaris ekstensi Anda: daftar lengkap semua hal yang dideklarasikan, dikirim, dan didokumentasikan oleh ekstensi, sehingga setiap perilaku memiliki tujuan yang ditentukan dalam fungsi generasi ke-2 dan tidak ada yang hilang dalam migrasi.
Tinjau setiap hal berikut, dan catat apa yang Anda temukan:
extension.yaml, yang mendeklarasikan parameter, fungsi, peristiwa, peran IAM, API yang diperlukan, secret, dan hook siklus proses Anda.functions/, yang berisi kode fungsi, dependensi, konfigurasi build, pemicu, dan fungsi task queue Anda.README.md,PREINSTALL.md, danPOSTINSTALL.md, yang berisi langkah-langkah penyiapan, peringatan, dan catatan penagihan.scripts/, yang berisi utilitas impor, pengisian ulang, IAM, perbaikan, atau migrasi, dan alat lain yang Anda kirimkan bersama ekstensi.
Kemudian, untuk setiap item di
extension.yaml, tentukan tempatnya
dalam paket npm:
Mengonversi konfigurasi pengguna menjadi parameter Cloud Functions (Langkah 4).
Konversikan secret menjadi secret Cloud Functions (Langkah 4).
Mengonversi peran IAM menjadi deklarasi
requiresRole(...)(Langkah 6).Konversikan Google API yang diperlukan menjadi deklarasi
requiresAPI(...)jika sesuai (Langkah 6).Konversikan hook penginstalan dan update menjadi deklarasi
afterFirstDeploy(...)danafterRedeploy(...)(Langkah 7).Konversikan ID instance dari
EXT_INSTANCE_IDkeFIREBASE_KIT_INSTANCE_ID(Langkah 4).
Contoh yang berhasil: Melakukan streaming Cloud Firestore ke BigQuery
Membaca firestore-bigquery-export/extension.yaml dan functions/ akan menghasilkan inventaris ini:
Di extension.yaml |
Jumlah/nilai | Tempat data Anda digunakan |
|---|---|---|
params |
25 (COLLECTION_PATH, DATASET_ID, TABLE_ID, DATASET_LOCATION, VIEW_TYPE, …) |
Cloud Functions parameter (Langkah 4) |
apis |
bigquery.googleapis.com |
requiresAPI(...) (Langkah 6) |
roles |
bigquery.dataEditor, datastore.user, bigquery.user |
requiresRole(...) (Langkah 6) |
resources |
1 pemicu peristiwa (fsexportbigquery) + fungsi task queue (initBigQuerySync, setupBigQuerySync) |
Fungsi paket yang diekspor (Langkah 3) |
lifecycleEvents |
onInstall → initBigQuerySync; onUpdate / onConfigure → setupBigQuerySync |
afterFirstDeploy / afterRedeploy (Langkah 7) |
| ID instance | Tidak digunakan (tidak ada pembacaan EXT_INSTANCE_ID) |
Tidak ada yang perlu dimigrasikan |
scripts/ |
import/ (pengisian ulang), gen-schema-view/ |
Disimpan sebagai skrip (di luar cakupan di sini) |
Analisis. Ekstensi tidak mendeklarasikan parameter type: secret, sehingga tidak ada yang perlu dimigrasikan untuk secret di Langkah 4. Pemicu peristiwa sudah merupakan generasi ke-2; hanya fungsi task queue yang masih merupakan generasi ke-1 (relevan di Langkah 3).
2. Mengupdate package.json
Perbarui file package.json ekstensi Anda. Jika Anda memigrasikan satu ekstensi,
ekstensi ini dapat menjadi package.json root. Jika Anda memigrasikan banyak ekstensi dalam satu repositori, berikan paketnya sendiri untuk setiap ekstensi.
Versi SDK minimum: Deklarasikan
firebase-functions >=
7.4.0 dan firebase-admin >=
14.2.0 sebagai dependensi. Deklarasikan versi firebase-functions Anda sebagai dependensi
peer juga, sehingga project Cloud Functions pengguna Anda memiliki versi
SDK yang sama dengan yang digunakan untuk menulis library Anda.
{
"name": "<package-name>",
"version": "1.0.0",
"main": "lib/index.js",
"types": "lib/index.d.ts",
"exports": {
".": {
"types": "./lib/index.d.ts",
"default": "./lib/index.js"
}
},
"engines": {
"node": "22"
},
"peerDependencies": {
"firebase-functions": "^7.4.0"
},
"dependencies": {
"firebase-functions": "^7.4.0",
"firebase-admin": "^14.2.0"
}
}
Contoh yang berhasil: Melakukan streaming Cloud Firestore ke BigQuery
Sebelumnya. functions/package.json ekstensi bersifat pribadi, memberi nama
ID ekstensi, dan mendeklarasikan firebase-functions sebagai dependensi langsung:
{
"name": "firestore-bigquery-export",
"main": "lib/index.js",
"private": true,
"dependencies": {
"@firebaseextensions/firestore-bigquery-change-tracker": "^2.0.4",
"firebase-admin": "^14.2.0",
"firebase-functions": "^6.3.2"
}
}
Setelah. Paket yang dapat dipublikasikan: nama cakupan, peta exports, dan
firebase-functions dipindahkan ke peerDependencies:
{
"name": "@firebase-function-kits/firestore-bigquery-export",
"version": "0.1.0",
"main": "lib/index.js",
"types": "lib/index.d.ts",
"exports": {
".": {
"types": "./lib/index.d.ts",
"default": "./lib/index.js"
}
},
"engines": {
"node": "22"
},
"peerDependencies": {
"firebase-functions": "^7.4.0"
},
"dependencies": {
"@firebaseextensions/firestore-bigquery-change-tracker": "^2.0.4",
"firebase-admin": "^14.2.0",
"firebase-functions": "^7.4.0"
}
}
3. Mengupgrade fungsi dari generasi ke-1 ke generasi ke-2
Jika ekstensi Anda masih mengekspor fungsi generasi ke-1, konversikan setiap pemicu ke
fungsi generasi ke-2 yang setara. Impor dari modul firebase-functions/..., dan teruskan setelan runtime dalam opsi pemicu.
Lihat panduan upgrade Cloud Functions generasi ke-2. Khususnya, Anda dapat meminimalkan upaya penulisan ulang dengan menggunakan destrukturisasi peristiwa yang di-patch generasi ke-2 dan menghindari penulisan ulang logika fungsi karena SDK generasi ke-2 mengekspos parameter v1 sebagai kolom dalam objek peristiwa, sehingga Anda dapat menggunakan parameter yang didestrukturisasi/dinamai dan menjaga logika bisnis Anda tidak berubah.
Sebelumnya. Generasi ke-1:
import * as functions from "firebase-functions/v1";
export const sync = functions.firestore
.document("{collectionId}/{documentId}")
.onWrite(async (change, context) => {
await handleWrite(change.before, change.after, context.params);
});
Setelah. Generasi ke-2:
import { onDocumentWritten } from "firebase-functions/firestore";
export const syncV2 = onDocumentWritten(
{ document: "{collectionId}/{documentId}" },
async ({ change, context }) =>
await handleWrite(change.before, change.after, context.params)
);
Lihat perbandingan versi Cloud Functions untuk mengetahui daftar lengkap perbedaan antara fungsi generasi ke-1 dan generasi ke-2.
Perbedaan signifikan antara fungsi generasi ke-1 dan ke-2 adalah fungsi generasi ke-2 harus ditempatkan bersama dengan resource pemicunya. Saat pengguna bermigrasi dari ekstensi yang menggunakan fungsi generasi ke-1 ke kit yang menggunakan fungsi generasi ke-2, mereka mungkin perlu mengubah lokasi fungsi untuk memenuhi persyaratan ini.
Lokasi Cloud Functions yang dipilih pengguna mungkin rusak selama migrasi karena lokasi yang ada dipertahankan. Jika fungsi yang dipicu peristiwa ekstensi Anda mengandalkan lokasi fungsi yang disediakan pengguna, sebaiknya tambahkan parameter baru ke ekstensi Anda untuk mengumpulkan lokasi pemicu peristiwa dan memetakannya ke lokasi fungsi baru.
Contoh yang berhasil: Melakukan streaming Cloud Firestore ke BigQuery
defineString("DATABASE_REGION", {
label: "Firestore Instance Location",
description:
"Where is the Firestore database located? You can check your current database location at https://console.cloud.google.com/firestore/databases. The functions in this kit deploy to the Cloud Run region closest to this location.",
input: select({
"Multi-region (Europe - Belgium and Netherlands)": "eur3",
"Multi-region (United States)": "nam5",
"Multi-region (Iowa, North Virginia, and Oklahoma)": "nam7",
"Iowa (us-central1)": "us-central1",
// More locations...
})
});
// Firestore multi-region locations are not Cloud Run regions; deploying a
// function to one hard-fails, so they map to a region inside the multi-region.
const MULTI_REGION_TO_FUNCTION_REGION: Record<string, string> = {
nam5: "us-central1",
nam7: "us-central1",
eur3: "europe-west1",
};
/**
* Maps a Firestore database location to the Cloud Run region the functions
* should deploy to. The lookup is case-insensitive and ignores surrounding
* whitespace, as the CLI's own region handling is. Regional locations pass
* through lowercased; an unset or blank location returns `undefined`, meaning
* the functions declare no region.
*/
export function firestoreLocationToFunctionRegion(
location: string | undefined
): string | undefined {
const normalized = location?.trim().toLowerCase();
if (!normalized) {
return undefined;
}
return MULTI_REGION_TO_FUNCTION_REGION[normalized] ?? normalized;
}
const functionRegion = firestoreLocationToFunctionRegion(
process.env.DATABASE_REGION
);
export const fsexportbigquery = onDocumentWritten(
{
region: functionRegion,
// Other configuration
},
(event) => handleDocumentWrite(event, getHandlerContext())
);
Saat pertama kali men-deploy kit, pengguna akan diminta memasukkan
DATABASE_REGION dan fungsi akan di-deploy ke
functionRegion yang sesuai di atas, sehingga memperbaiki masalah lokasi untuk fungsi yang dipicu peristiwa
generasi ke-2.
4. Mengonversi parameter dan secret ekstensi
Params
Setiap parameter yang Anda deklarasikan di extension.yaml akan menjadi parameter
Cloud Functions.
Mengonversi pembacaan lingkungan langsung:
const collectionPath = process.env.COLLECTION_PATH;
ke dalam parameter Cloud Functions:
import { defineString } from "firebase-functions/params";
import { onDocumentWritten } from "firebase-functions/firestore";
const collectionPath = defineString("COLLECTION_PATH");
// Pass the param directly when used as a placeholder (e.g. trigger path)
export const sync = onDocumentWritten(
{ document: collectionPath },
async (event) => {
// Call .value() to read the string inside a handler
const path = collectionPath.value();
await handleWrite(path, event);
}
);
Gunakan collectionPath.value() untuk membaca string di dalam pengendali; gunakan collectionPath secara langsung di tempat yang memerlukan placeholder, seperti jalur pemicu fungsi.
Firebase CLI menemukan parameter Anda dan membaca nilainya dari .env,
.env.<projectId>, atau meminta pengguna Anda selama deployment. Pertahankan nama parameter yang sama, sehingga nilai dari penginstalan yang ada akan dipertahankan.
Anda tidak boleh mengubah nama parameter yang dideklarasikan dalam kode Anda sama sekali. Migrasi ekstensi mempertahankan nilai parameter pengguna akhir yang ada secara otomatis, tetapi hanya jika namanya tidak berubah.
Contoh yang berhasil: Melakukan streaming Cloud Firestore ke BigQuery
Sebelumnya. Parameter yang dideklarasikan di extension.yaml, dibaca sebagai variabel lingkungan mentah di config.ts:
# extension.yaml
- param: COLLECTION_PATH
label: Collection path
type: string
required: true
// functions/src/config.ts
collectionPath: process.env.COLLECTION_PATH,
Setelah. Satu defineString; CLI menemukannya dan membaca dari .env:
// src/config.ts
import { defineString } from "firebase-functions/params";
collectionPath: defineString("COLLECTION_PATH", {
label: "Collection path",
// We now support "nonEmpty: true" to ensure a value other than the empty string
// is entered, analogous to "required: true" in extension.yaml
input: { text: { nonEmpty: true } }
}),
Nama parameter tidak berubah, sehingga .env yang ada tetap berfungsi.
ID instance
Ekstensi membaca ID instance-nya dari EXT_INSTANCE_ID, yang dimasukkan oleh runtime Ekstensi. Kit fungsi membaca ID instance-nya dari FIREBASE_KIT_INSTANCE_ID, yang ditetapkan oleh Firebase CLI untuk setiap instance kit ke kunci instance di peta instances di firebase.json. CLI menyediakannya selama penemuan waktu deployment, di emulator, dan ke fungsi yang di-deploy.
ID instance bukan parameter, jadi jangan deklarasikan dengan defineString. Faktanya,
FIREBASE_... adalah awalan yang dicadangkan dalam file .env, sehingga pengguna tidak akan dapat
menetapkan atau menggantinya di sana. Nilai yang dimasukkan CLI tidak terlihat oleh sistem parameter. Baca langsung dari lingkungan:
// Before
const instanceId = process.env.EXT_INSTANCE_ID;
// After
const instanceId = process.env.FIREBASE_KIT_INSTANCE_ID;
Variabel hanya akan ditetapkan saat paket Anda di-deploy sebagai kit. Jika kode Anda juga di-deploy sebagai codebase mandiri (lihat Langkah 9), perlakukan kode tersebut sebagai opsional atau gagal cepat dengan pesan yang jelas jika tidak ada. Jika ekstensi Anda mengekspos ID instance sebagai parameter yang ditampilkan kepada pengguna, Anda harus menghapus parameter tersebut, karena Firebase CLI kini memiliki nilai tersebut.
Contoh yang berhasil: Menghapus Data Pengguna
(Ekstensi Stream Cloud Firestore to BigQuery tidak membaca ID instance-nya, sehingga tidak ada yang perlu dimigrasikan di sana. Ekstensi Delete User Data menggunakannya untuk memberi nama topik Pub/Sub-nya.)
Sebelumnya. Baca sebagai variabel lingkungan mentah di config.ts dengan awalan ext-
yang digunakan Extensions untuk resource-nya:
// functions/src/config.ts
discoveryTopic: `ext-${process.env.EXT_INSTANCE_ID}-discovery`,
deletionTopic: `ext-${process.env.EXT_INSTANCE_ID}-deletion`,
Setelah. Pembacaan process.env biasa dari FIREBASE_KIT_INSTANCE_ID yang digunakan untuk dua parameter biasa sehingga pengguna dapat mengganti nama topik:
// src/config.ts
const instanceId = process.env.FIREBASE_KIT_INSTANCE_ID;
// Non-empty defaults so Pub/Sub trigger bindings resolve during deploy
// discovery without freezing an empty topic name into the manifest.
discoveryTopicName: defineString("DISCOVERY_TOPIC_NAME", {
default: `kit-${instanceId}-discovery`,
}),
deletionTopicName: defineString("DELETION_TOPIC_NAME", {
default: `kit-${instanceId}-deletion`,
}),
Default tidak boleh kosong karena binding pemicu diselesaikan pada waktu penemuan. Default kosong akan ditulis ke dalam manifes deployment sebagai nama topik. Kit ini juga defensif terhadap eksekusi di luar konteks kit. Jika variabel tidak ada, default level modul akan dievaluasi ke
kit-undefined-discovery, sehingga loader konfigurasi akan gagal dengan error penjelasan:
// ...
const instanceId = process.env.FIREBASE_KIT_INSTANCE_ID;
if (!instanceId) {
throw new Error(
"FIREBASE_KIT_INSTANCE_ID is not set. It is provided automatically to " +
"kit instances by firebase-tools >= 15.32.0; deploy or emulate this " +
"kit with a supported CLI version."
);
}
// ...
Pemeriksaan ini berjalan saat pengendali pertama kali me-resolve konfigurasinya, sehingga variabel yang tidak ada akan menghasilkan error runtime yang jelas, bukan fungsi yang terikat secara otomatis ke topik kit-undefined-*. Untuk menolak deployment itu sendiri, lakukan pemeriksaan pada
cakupan modul sehingga berjalan selama penemuan. Karena CLI memperoleh ID instance dari firebase.json, tidak ada INSTANCE_ID yang dapat dikonfigurasi, dan tidak ada yang perlu disinkronkan di beberapa instance.
Rahasia
Di extension.yaml, Anda mendeklarasikan secret dengan type: secret. Runtime Extensions menyimpan dan mengikatnya, sehingga kode ekstensi Anda dapat membaca process.env.PARAM_NAME secara langsung. Dalam codebase Cloud Functions standar,
Anda mendeklarasikan dan mengikat setiap secret secara eksplisit:
import { defineSecret } from "firebase-functions/params";
import { onRequest } from "firebase-functions/https";
const apiKey = defineSecret("API_KEY");
export const fn = onRequest({ secrets: [apiKey] }, handler);
Setelah ekstensi Anda dimigrasikan ke paket/kit npm, referensi secret akan dikelola dalam file .env pengguna akhir. Penting bagi Anda untuk tidak
mengubah nama rahasia yang dideklarasikan dalam kode Anda sama sekali. Selama migrasi,
secret pengguna akhir akan dimigrasikan sebagaimana mestinya.
Contoh yang berhasil: Memicu Email Dari Cloud Firestore
Sebelumnya. MAIL_COLLECTION dan SMTP_PASSWORD dibaca sebagai variabel lingkungan mentah di config.ts:
# extension.yaml
- param: MAIL_COLLECTION
label: Email documents collection
type: string
default: mail
required: true
- param: SMTP_PASSWORD
label: SMTP password
type: secret
// functions/src/config.ts
mailCollection: process.env.MAIL_COLLECTION,
smtpPassword: process.env.SMTP_PASSWORD,
Setelah. Satu defineString dan satu defineSecret; CLI menemukan keduanya
dan membaca dari .env:
import { defineString, defineSecret } from "firebase-functions/params";
import { onDocumentWritten } from "firebase-functions/firestore";
const mailCollection = defineString("MAIL_COLLECTION", {
label: "Email documents collection",
default: "mail"
});
const smtpPassword = defineSecret("SMTP_PASSWORD", { label: "SMTP password" });
export const processQueue = onDocumentWritten(
{ document: `${mailCollection}/{documentId}`, secrets: [smtpPassword] },
async (event) => {
const collection = mailCollection.value();
const password = smtpPassword.value();
// ...
}
);
5. Memigrasikan panggilan task queue internal
Beberapa ekstensi mengantrekan tugas ke task queue mereka sendiri dari dalam kode fungsi, menggunakan Firebase Admin SDK. Hal ini berbeda dengan menerima tugas yang dikirim (dibahas di bagian Mengupgrade fungsi dan Mengonversi hook siklus proses). Di sini, kode Anda adalah produsen yang memanggil
queue.enqueue(...).
Versi Admin SDK sebelumnya mengharuskan ekstensi meneruskan ID instance ekstensi mereka sendiri sebagai parameter kedua untuk menargetkan fungsi Task Queue di ekstensi yang sama. Mulai firebase-admin 14.2.0, hal ini tidak diperlukan atau direkomendasikan. Task Queue API kini menargetkan task queue dalam konteks yang sama (misalnya, ekstensi atau kit) secara default. Menghapus parameter ini dalam kode Anda, baik sebagai ekstensi maupun sebagai fungsi mandiri, aman dan dianjurkan.
Menghapus parameter ini akan memastikan portabilitas dan kompatibilitas ke depan.
Semua hal lain tentang panggilan enqueue — jalur resource locations/<region>/functions/<name>, payload tugas, dan logika percobaan ulang Anda — tetap sama.
Baca artikel Mengantrekan fungsi dengan Cloud Tasks untuk mengetahui detail selengkapnya tentang cara mengantrekan fungsi dengan Cloud Tasks.
Sebelumnya. Ekstensi generasi ke-1:
import { getFunctions } from "firebase-admin/functions";
const queue = getFunctions().taskQueue(
`locations/${config.location}/functions/syncBigQuery`,
process.env.EXT_INSTANCE_ID, // extension instance ID, injected by the runtime
);
await queue.enqueue(taskData);
Setelah. Ekstensi generasi ke-2:
import { getFunctions } from "firebase-admin/functions";
const queue = getFunctions().taskQueue(
`locations/${process.env.FUNCTION_REGION}/functions/syncBigQuery`
);
await queue.enqueue(taskData);
Jika panggilan enqueue Anda menargetkan codebase dengan awalan, nama fungsi yang ditemukan
juga akan diawali (misalnya, orders-syncBigQuery); lihat
Meninjau dan menginstal instance kit fungsi pengganti
dan Menguji sebagai kit fungsi.
6. Mendeklarasikan API dan peran IAM yang diperlukan
Pindahkan persyaratan IAM dan API ekstensi Anda dari extension.yaml dan ke dalam kode:
import { requiresAPI, requiresRole } from "firebase-functions";
requiresAPI("bigquery.googleapis.com", "Needed to write changelog rows");
requiresRole("roles/bigquery.dataEditor");
requiresRole("roles/bigquery.user");
Dengan keamanan deklaratif, Firebase CLI membuat atau memperbarui akun layanan runtime terkelola untuk codebase, dan memberinya gabungan semua peran yang dideklarasikan. Dokumentasikan untuk pengguna Anda bahwa semua fungsi dalam codebase berjalan dengan peran tersebut, kecuali jika API akhir mendukung model yang lebih sempit.
Contoh yang berhasil: Melakukan streaming Cloud Firestore ke BigQuery
Sebelumnya. Dideklarasikan di extension.yaml; runtime Extensions mengaktifkan API dan memberikan peran ke akun terkelola:
apis:
- apiName: bigquery.googleapis.com
roles:
- role: bigquery.dataEditor
- role: datastore.user
- role: bigquery.user
Setelah. Dinyatakan dalam kode dengan requiresAPI dan requiresRole:
import { requiresAPI, requiresRole } from "firebase-functions";
requiresAPI(
"bigquery.googleapis.com",
"Needed to write changelog rows and views"
);
requiresRole("roles/bigquery.dataEditor");
requiresRole("roles/datastore.user");
requiresRole("roles/bigquery.user");
Jika ekstensi Anda memublikasikan peristiwa Eventarc, Anda juga perlu menetapkan peran dan API yang diperlukan untuk memublikasikan peristiwa. Hal ini sebelumnya ditangani oleh Ekstensi tanpa memerlukan perubahan apa pun di extensions.yaml Anda. Anda dapat melakukannya secara bersyarat dalam kode Anda sehingga kit
hanya meminta izin ini saat saluran Eventarc kustom digunakan.
if (!!process.env.EVENTARC_CHANNEL) {
requiresRole("roles/eventarc.publisher");
requiresAPI(
"eventarcpublishing.googleapis.com",
"Publishes the extension's custom events to its Eventarc channel."
);
}
7. Mengonversi hook siklus proses
Jika ekstensi Anda memanggil getExtensions().runtime() (misalnya,
setProcessingState atau setFatalError), hapus panggilan tersebut, karena akan menampilkan
error jika dipanggil dari fungsi generasi ke-2 yang di-deploy secara normal. Status siklus proses kini
didorong oleh afterFirstDeploy dan afterRedeploy, yang tidak menggunakan pelacakan status ini.
Firebase Extensions dapat menjalankan penyiapan saat pengguna menginstal, mengupdate, atau mengonfigurasi ulang ekstensi. Dalam paket npm, deklarasikan tindakan siklus proses yang setara dalam kode.
Untuk penyiapan satu kali:
import { afterFirstDeploy } from "firebase-functions/lifecycle";
import { onTaskDispatched } from "firebase-functions/tasks";
export const runInitialSetup = onTaskDispatched(async (request) => {
await initializeResources(request.data);
});
afterFirstDeploy({
task: {
function: "runInitialSetup",
body: {}
}
});
Untuk update konfigurasi atau kode:
import { afterRedeploy } from "firebase-functions/lifecycle";
afterRedeploy({
task: {
function: "runInitialSetup",
body: { reconcile: true }
}
});
Buat tindakan siklus proses Anda bersifat idempoten. Pengguna Anda mungkin perlu menjalankannya kembali secara manual jika pengiriman atau eksekusi gagal:
firebase functions:lifecycle:run afterFirstDeploy CODEBASE_NAME
firebase functions:lifecycle:run afterRedeploy CODEBASE_NAME
Contoh yang berhasil: Streaming Cloud Firestore ke BigQuery
Sebelumnya. lifecycleEvents di extension.yaml, yang didorong oleh runtime Ekstensi:
lifecycleEvents:
onInstall:
function: initBigQuerySync
processingMessage: Configuring BigQuery Sync.
onUpdate:
function: setupBigQuerySync
processingMessage: Configuring BigQuery Sync
onConfigure:
function: setupBigQuerySync
processingMessage: Configuring BigQuery Sync
Setelah. Dideklarasikan dalam kode; tugas menyediakan BigQuery pada deployment pertama:
import { afterFirstDeploy, afterRedeploy } from "firebase-functions/lifecycle";
afterFirstDeploy({ task: { function: "initBigQuerySync" } });
afterRedeploy({ task: { function: "setupBigQuerySync" } });
Penyediaan bersifat idempoten, sehingga operasi ulang akan merekonsiliasi set data, tabel, dan tampilan.
Pengguna dapat menjalankan ulang secara manual dengan firebase functions:lifecycle:run afterFirstDeploy
CODEBASE_NAME.
8. Penyiapan dokumen untuk pengguna Anda
Tulis paket README yang menjelaskan, setidaknya:
- Nilai
.envyang diperlukan paket. - Secret yang diperlukan paket, dan cara memigrasikan nilai secret yang ada.
- Peran IAM yang dideklarasikan paket dengan
requiresRole(...). - Google API yang diaktifkan atau diperlukan oleh paket.
- Hook siklus proses yang dideklarasikan paket, dan cara menjalankannya kembali secara manual.
- Catatan penagihan.
- Perubahan yang dilakukan dibandingkan dengan ekstensi asli.
- Cara paket mendapatkan ID instance-nya (
FIREBASE_KIT_INSTANCE_IDyang ditetapkan oleh CLI) dan bahwa semua fungsi instance di-deploy dengan awalankit-<instanceId>-.
Contoh yang berhasil: Melakukan streaming Cloud Firestore ke BigQuery
Paket README mengirimkan tabel "apa yang berubah" yang konkret:
| Kepedulian | Sebagai ekstensi | Sebagai @firebase-function-kits/firestore-bigquery-export |
|---|---|---|
| Konfigurasi | Parameter ekstensi | Cloud Functions parameter melalui .env |
| IAM | Diberikan oleh Ekstensi | requiresRole(...), diterapkan saat deployment |
| Penyediaan | Tugas siklus proses oleh Extensions | afterFirstDeploy / afterRedeploy tugas |
| Nama fungsi | ext-<instanceId>-fsexportbigquery |
fsexportbigquery (dengan awalan opsional) |
| ID instance | EXT_INSTANCE_ID dimasukkan oleh Ekstensi |
FIREBASE_KIT_INSTANCE_ID, ditetapkan oleh CLI dari firebase.json |
9. Menguji fungsi generasi ke-2
Sekarang Anda seharusnya memiliki fungsi generasi ke-2 yang, saat di-deploy, berperilaku sama dengan penginstalan baru ekstensi Anda. Langkah berikutnya adalah memverifikasi dan memperbaiki masalah apa pun yang tidak sengaja muncul selama proses tersebut.
Untuk memanggil setGlobalOptions
guna menetapkan opsi global seperti region atau CPU default, Anda harus melakukannya hanya saat
men-deploy kit sebagai fungsi generasi ke-2 mandiri. Saat kit Anda diinstal
sebagai paket npm, pengguna Anda akan memanggil setGlobalOptions dalam kode wrapper mereka untuk
mengonfigurasi parameter ini, dan mereka akan mendapatkan peringatan jika hal ini terjadi dua kali.
Anda dapat melindungi panggilan ini dengan memeriksa variabel lingkungan FIREBASE_KIT_INSTANCE_ID:
import { setGlobalOptions } from "firebase-functions";
if (!process.env.FIREBASE_KIT_INSTANCE_ID) {
setGlobalOptions({
region: "us-east1",
maxInstances: 10,
});
}
Pastikan Anda menggunakan
firebase-tools
>= 15.32.0, dan deploy fungsi generasi ke-2 yang telah dikonversi ke dalam project pengujian
dengan resource yang sesuai untuk menguji perilakunya. Jika Anda sudah menyiapkan project pengujian dari pengujian ekstensi, jalankan perintah berikut:
firebase deploy --only functions
Isi wizard yang dihasilkan yang meminta parameter value dengan cara yang sama seperti Anda mengisi formulir penginstalan di Firebase console untuk ekstensi.
Contoh yang berhasil: Melakukan streaming Cloud Firestore ke BigQuery
Kami memverifikasi sinkronisasi Cloud Firestore ke BigQuery secara menyeluruh:
- Di halaman Cloud Firestore pada Firebase console, buat koleksi yang Anda tetapkan sebagai
COLLECTION_PATH(users) jika belum ada. - Buat dokumen bernama
bigquery-mirror-testyang berisi kolom apa pun dengan nilai apa pun. Di halaman BigQuery pada Google Cloud console, buat kueri tabel changelog mentah. Tabel ini harus berisi satu baris yang mencatat pembuatan dokumen:
SELECT * FROM `PROJECT_ID.analytics.users_raw_changelog`Buat kueri tampilan terbaru, yang akan menampilkan peristiwa perubahan terbaru untuk satu-satunya dokumen yang ada (
bigquery-mirror-test):SELECT * FROM `PROJECT_ID.analytics.users_raw_latest`Hapus dokumen
bigquery-mirror-testdi Cloud Firestore. Peristiwa tersebut akan hilang dari tampilan terbaru, dan peristiwaDELETEakan ditambahkan ke tabel changelog mentah.Anda dapat memeriksa histori lengkap satu dokumen dengan:
SELECT * FROM `PROJECT_ID.analytics.users_raw_changelog` WHERE document_name = "bigquery-mirror-test" ORDER BY timestamp ASC
Perbedaan dari pengujian ekstensi:
- Pemicu di-deploy sebagai
fsexportbigquery(tanpa awalan saat di-deploy sebagai fungsi generasi ke-2 biasa dan bukan kit), bukanext-<instanceId>-fsexportbigquery. Cari nama tersebut di dasbor dan log Cloud Functions. - Kode Anda kini berjalan di Firebase Local Emulator Suite sebagai fungsi normal.
Anda dapat menetapkan nilai parameter yang akan digunakan di emulator dengan
.env.local. Anda juga dapat melakukan pengujian unit pada kode menggunakan SDKfirebase-functions-testseperti yang dijelaskan dalam Pengujian unit Cloud Functions. - Penyediaan tidak lagi didorong oleh runtime Extensions. Jika tabel changelog
tidak ada setelah deployment, jalankan ulang tugas penyiapan secara manual:
firebase functions:lifecycle:run afterFirstDeploy CODEBASE_NAME. Tugas ini idempoten, sehingga menjalankan ulang tugas akan merekonsiliasi set data, tabel, dan tampilan. - Nilai parameter berasal dari
.env, bukan formulir penginstalan, sehingga menjalankan ulangfirebase deploytidak bersifat interaktif setelah.envselesai.
10. Memublikasikan kit fungsi di npm
Setelah memvalidasi konversi dari ekstensi ke fungsi generasi ke-2, Anda dapat memublikasikan kandidat rilis ke npm untuk pengujian menyeluruh menggunakan salah satu panduan berikut:
- Membuat dan memublikasikan paket publik tanpa cakupan
- Membuat dan memublikasikan paket publik tercakup
Setelah kit Anda dipublikasikan ke npm, kit tersebut dapat diinstal dengan
firebase functions:kits:install dan dicantumkan sebagai
pengganti resmi untuk ekstensi Anda.
Sebaiknya publikasikan kandidat rilis terlebih dahulu. Kit diinstal berdasarkan nama dan versi paket, sehingga pra-rilis memungkinkan Anda menguji alur penginstalan yang sebenarnya terhadap registry tanpa mengekspos paket yang belum selesai kepada pengguna yang menginstal dengan tag latest default.
Sebelum Anda memublikasikan:
- Pilih nama paket. Nama tercakup dan tidak tercakup dapat digunakan (lihat panduan di atas). Perhatikan bahwa paket tercakup bersifat pribadi secara default, jadi teruskan
--access public. - Bangun dan periksa apa yang dikirim.
maindantypesmengarah ke output yang dikompilasi (lib/dalam contoh yang telah kita bahas), sehingga direktori tersebut harus disertakan dalam file tar yang dipublikasikan. Gunakan.npmignoreatau daftar yang diizinkanfiles, dan periksa hasilnya dengannpm pack --dry-run. SkripprepublishOnlyyang menjalankan build Anda mencegah publikasi output yang sudah tidak berlaku.
package.json penambahan yang membuat publikasi aman secara default:
{
"files": ["lib", "README.md", "CHANGELOG.md"],
"publishConfig": { "access": "public", "tag": "next" },
"scripts": {
"build": "tsc -b",
"prepublishOnly": "npm run build && npm test"
}
}
Kolom "publishConfig": { "tag": "next" } memastikan bahwa npm
publish biasa tidak pernah menimpa latest.
Membuat kandidat rilis:
Misalnya, untuk meningkatkan versi secara lokal dari 0.0.2-rc.3 ke 0.0.2-rc.4
(ini akan melakukan commit dan tag di Git jika package.json berada di root repositori):
npm version prerelease --preid rc
Untuk memublikasikan kandidat rilis dan mendaftarkan @your-org/your-kit@0.0.2-rc.4 di
npm dengan tag next:
npm publish
Situs npm mungkin memerlukan waktu beberapa menit untuk menampilkan versi baru; npm view membaca registry secara langsung:
npm view @your-org/your-kit versions dist-tags
Setelah Langkah 11 dan Langkah 12 panduan ini selesai, Anda dapat mempromosikan paket ke versi stabil:
npm version 0.0.2
npm publish --tag latest
npm dist-tag add @your-org/your-kit@0.0.2 next
Catatan tentang npm-shrinkwrap.json: Sebaiknya sertakan file npm-shrinkwrap.json dengan paket Anda; CLI akan memperingatkan pengguna saat penginstalan jika Anda tidak melakukannya. Hal ini memastikan pengguna menggunakan dependensi yang sama persis dengan yang Anda uji dan
membantu melindungi dari serangan supply chain. Namun, shrinkwrap diterapkan
secara verbatim dalam project pengguna Anda, termasuk selama build Cloud Functions
(npm ci), di mana entri khusus dev dapat gagal dengan EBADPLATFORM. Anda mungkin perlu
menghapus entri "dev": true dan devDependencies dari salinan shrinkwrap
yang dipublikasikan.
Contoh yang berhasil: Melakukan streaming Cloud Firestore ke BigQuery
package.json kit pada saat rilis kandidat keempatnya:
{
"name": "@firebase-function-kits/firestore-bigquery-export",
"version": "0.0.2-rc.4",
"repository": {
"type": "git",
"url": "https://github.com/firebase/extensions.git",
"directory": "kits/firestore-bigquery-export"
},
"main": "lib/index.js",
"types": "lib/index.d.ts",
"engines": { "node": "22" },
"scripts": { "build": "tsc -b" }
}
Perhatikan bahwa dalam kasus ini, kit berada di monorepo, jadi penting untuk
menyertakan repository.directory agar link registry npm mengarah ke folder
yang benar. CHANGELOG.md-nya menyimpan catatan untuk rilis yang tertunda.
11. Menguji sebagai kit fungsi
Setelah memublikasikan kit, sebaiknya uji kit Anda menggunakan npm.
Pastikan Anda menggunakan
firebase-tools
versi >= 15.32.0 dan instal kit:
firebase functions:kits:install --package <your-package-name>@<your-prerelease-version>
Tindakan ini akan mendownload paket Anda dari npm, menyiapkannya di dalam direktori sumber baru untuk kit Anda, dan memandu Anda mengonfigurasi instance pertama yang mirip dengan alur penginstalan ekstensi. Setelah menginstal dan menyiapkan paket secara lokal, jalankan deployment untuk membuat resource di project Google Cloud Anda:
firebase deploy --only functions:<your-kit-instance-id>
Setelah penginstalan, Firebase CLI akan mencetak perintah deploy yang serupa dengan ID instance persis yang Anda pilih selama penginstalan.
Validasi kit Anda lagi menggunakan petunjuk di
Langkah 9. Menguji fungsi generasi ke-2. Setelah Anda men-deploy menggunakan kit, fungsi Anda akan diawali dan diberi nama kit-<instance-id>-<method-name>. Hal ini memungkinkan kit memiliki beberapa instance, yang men-deploy fungsi yang sama beberapa kali dalam sebuah project, masing-masing dengan nama yang unik.
12. Menguji penggantian migrasi
Anda dapat menyiapkan instance ekstensi yang berfungsi, lalu menggunakan
panduan migrasi pengguna
(menggunakan firebase ext:migrate --package
atau perintah CLI function kit)
untuk menyelesaikan pengujian function kit sebagai pengganti migrasi.
13. Memberi tahu pengguna dan Google tentang penggantian ekstensi resmi Anda
Setelah pengganti kit fungsi Anda siap dan tersedia sebagai paket npm yang
harus dimigrasikan oleh pengguna, beri tahu pengguna dan Google tentang pengganti
resmi ini. Perbarui file README.md di repositori GitHub yang menghosting
ekstensi Anda dengan informasi berikut:
<!-- FIREBASE_EXTENSION_REPLACEMENT: extension="<your-extesion-id>" package="<your-npm-package-name>" -->
> [!WARNING]
> **Deprecation Notice:** The Firebase Extension `<your-extension>` is deprecated. Migrate to the [<your-npm-package-name>](<link-to-your-npm-package>) package.
Google memindai README ekstensi yang diketahui untuk menemukan komentar seperti <!--
FIREBASE_EXTENSION_REPLACEMENT: extension="firebase/firestore-bigquery-export"
package="@firebase-function-kits/firestore-bigquery-export" --> dan menggunakannya
untuk mengisi registry resmi pengganti yang disimpan di repositori firebase-tools
sebagai
replacements.json.
Anda juga dapat memeriksa replacements.json untuk melihat README.md yang akan dipindai
untuk ekstensi Anda. Daftar resmi pengganti diperbarui setiap minggu.
Contoh yang berhasil: Melakukan streaming Cloud Firestore ke BigQuery
Ekstensi firestore-bigquery-export
README.md
berisi:
<!-- FIREBASE_EXTENSION_REPLACEMENT: extension="firebase/firestore-bigquery-export" package="@firebase-function-kits/firestore-bigquery-export" -->
> [!WARNING]
> **Deprecation Notice:** The Firebase Extension `firebase/firestore-bigquery-export` is deprecated. Please migrate to the [`@firebase-function-kits/firestore-bigquery-export`](https://www.npmjs.com/package/@firebase-function-kits/firestore-bigquery-export) package.