Anda dapat menginstal (dan mengelola) ekstensi Firebase resmi menggunakan Firebase console, Firebase CLI (antarmuka command line), atau menggunakan SDK yang dibuat secara otomatis.
Pastikan untuk meninjau perbedaan tindakan yang didukung untuk setiap metode penginstalan.
Penginstalan menggunakan SDK yang dibuat secara otomatis adalah opsi baru untuk menginstal dan mengelola ekstensi. Dengan opsi ini, Anda menggunakan CLI untuk membuat Node SDK secara otomatis untuk versi ekstensi tertentu, yang dapat Anda impor sebagai dependensi biasa di Cloud Functions JavaScript atau TypeScript.
SDK yang dibuat secara otomatis ini berisi:
- Antarmuka yang mewakili parameter ekstensi, dan deklarasi jenis untuk sebagian besar jenis parameter non-primitif.
- Fungsi konstruktor yang melakukan inisialisasi instance ekstensi
- Class ekstensi yang berisi pemicu Eventarc untuk semua peristiwa yang dikeluarkan oleh ekstensi.
Setelah Anda membuat SDK ekstensi, semua konfigurasi ekstensi akan terjadi dalam kode.
Dengan menggunakan opsi penginstalan ini, Anda dapat menyederhanakan pengelolaan beberapa instance ekstensi, terutama dalam project yang berisi Cloud Functions yang ditentukan di luar ekstensi.
Untuk menginstal atau mengelola ekstensi, salah satu peran berikut harus ditetapkan untuk Anda: Pemilik atau Editor atau Firebase Admin.
Untuk menginstal ekstensi, project Anda harus menggunakan paket Blaze (bayar sesuai penggunaan). Meskipun penginstalan ekstensi dapat dilakukan secara gratis, Anda mungkin akan dikenai biaya atas penggunaan layanan Firebase atau layanan Cloud seperti Cloud Secret Manager, jika penggunaan Anda melebihi paket gratis layanan tersebut.
Sebelum memulai
Tambahkan Firebase ke project, jika belum melakukannya.
Upgrade project Anda ke paket Blaze (bayar sesuai penggunaan), jika belum melakukannya.
Catat project ID Firebase Anda atau alias project yang dikonfigurasi sebelumnya.
- Project ID — Jalankan
firebase projects:list
dari mana saja di komputer Anda. - Alias project — Jalankan
firebase use
dari direktori aplikasi lokal Anda.
- Project ID — Jalankan
Langkah 1: Lihat informasi mendetail tentang ekstensi
Langkah ini bersifat opsional, tetapi sangat direkomendasikan.
Sebelum menginstal Firebase Extension, sebaiknya Anda meninjau informasi mendetail tentang ekstensi tersebut, termasuk:
- Cara kerja ekstensi, tugas pra-penginstalan, dan detail tentang ekstensi
- Informasi dan deskripsi identitas umum
- Apakah tugas ekstensi memerlukan akun penagihan atau tidak
- Layanan Google (API) dan peran akses yang diperlukan untuk operasi
- Resource yang dibuat untuk ekstensi (seperti fungsi)
- Deskripsi parameter yang dapat dikonfigurasi oleh pengguna
Untuk melihat informasi mendetail tentang ekstensi:
Pastikan Anda telah menyiapkan lingkungan dan memilih ekstensi.
Jalankan perintah extension-info dari mana saja di komputer Anda:
firebase ext:info
publisher-id /extension-id Argumen
publisher-id
danextension-id
diperlukan dan dapat ditemukan di halaman detail pra-penginstalan ekstensi.
Langkah 2: Instal ekstensi
Sebelum penginstalan, tinjau spesifikasi dasar ekstensi (seperti API yang diaktifkan, resource yang dibuat, akses yang diberikan, dll.) dan persyaratan penagihannya.
Sebelum melanjutkan, pastikan Anda telah menyiapkan lingkungan dan memilih ekstensi.
Melakukan inisialisasi Cloud Functions for Firebase
Jika Anda memulai project baru atau jika project Anda belum menggunakan
Cloud Functions for Firebase, jalankan init functions
:
cd your-project
firebase init functions
Pilih TypeScript atau JavaScript sebagai bahasa fungsi Anda.
Jika project Anda sudah melakukan inisialisasi Cloud Functions, pastikan Anda menggunakan
paket firebase-functions
versi 5.1.0 atau yang lebih baru:
cd your-project/functions
npm upgrade --save firebase-functions
Jika menggunakan ESLint, Anda mungkin juga ingin mengecualikan SDK yang dihasilkan dari
konfigurasi (.eslintrc.js
):
ignorePatterns: [
"/generated/**/*", // Ignore generated files.
// ...
],
Membuat SDK ekstensi
Dari direktori Firebase lokal, jalankan perintah ext:sdk:install
.
firebase ext:sdk:installpublisher-id /extension-id @version
Misalnya, untuk menginstal ekstensi firestore-send-email
versi 0.1.34:
firebase ext:sdk:install firebase/firestore-send-email@0.1.34
publisher-id
dan extension-id
diperlukan dan dapat ditemukan di halaman detail pra-penginstalan ekstensi di
extensions.dev.
Bagian @version
bersifat opsional; jika Anda menghapusnya,
alat akan menginstal versi terbaru.
Ada dua opsi yang dapat Anda tentukan:
--force
: Melakukan semua hal berikut tanpa konfirmasi lebih lanjut:- Buat SDK secara otomatis meskipun SDK telah dibuat untuk ekstensi dan versi yang sama.
- Instal paket SDK yang dibuat secara otomatis di project Node Cloud Functions.
--codebase
: Nama codebase tempat SDK akan ditambahkan. Jika tidak ditentukan, perintah akan menambahkan SDK ke codebase default,functions
.
Perintah ini membuat paket Node yang berisi SDK yang otomatis
dihasilkan untuk ekstensi, dan menambahkannya ke salah satu
codebase Cloud Functions project Anda. Dalam codebase default
(functions
), SDK disimpan ke lokasi berikut:
functions/generated/extensions/publisher-id /extension-id /version
Setelah membuat SDK, perintah akan menanyakan apakah Anda juga ingin menginstal SDK ke project Node Cloud Functions. Jawab Ya untuk perintah ini.
Mengonfigurasi instance ekstensi
Untuk mengonfigurasi ekstensi, impor SDK, dan untuk setiap instance ekstensi yang ingin diinstal, panggil fungsi konstruktor, dengan meneruskan ID instance unik project dan parameter konfigurasi yang diperlukan oleh ekstensi.
Di sumber Cloud Functions, impor konstruktor menggunakan pernyataan yang dicetak oleh perintah
ext:sdk:install
.Misalnya, jika Anda membuat SDK untuk ekstensi
firestore-send-email
, pernyataanimport
akan terlihat seperti berikut:import { firestoreSendEmail } from "@firebase-extensions/firebase-firestore-send-email-sdk";
Jika ekstensi memerlukan nilai rahasia seperti sandi, Anda juga memerlukan fungsi
defineSecret
dari Cloud Functions SDK:import { defineSecret } from "firebase-functions/params";
Misalnya, jika Anda membuat SDK untuk ekstensi
firestore-send-email
, pernyataanrequire
akan terlihat seperti berikut:const { firestoreSendEmail } = require("@firebase-extensions/firebase-firestore-send-email-sdk");
Jika ekstensi memerlukan nilai rahasia seperti sandi, Anda juga memerlukan fungsi
defineSecret
dari Cloud Functions SDK:const { defineSecret } = require('firebase-functions/params');
Untuk setiap instance yang ingin Anda konfigurasi, panggil fungsi konstruktor dan ekspor hasilnya.
Berikan ID unik pada setiap instance, yang hanya berisi huruf kecil, angka, dan tanda hubung.
export const firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { SMTP_CONNECTION_URI: "smtps://username@example.com@smtp.example.com:465", SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"), MAIL_COLLECTION: "mail", DEFAULT_FROM: "ExampleCo <username@example.com>", TTL_EXPIRE_VALUE: "1", TTL_EXPIRE_TYPE: "day", });
exports.firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { SMTP_CONNECTION_URI: "smtps://username@example.com@smtp.example.com:465", SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"), MAIL_COLLECTION: "mail", DEFAULT_FROM: "ExampleCo <username@example.com>", TTL_EXPIRE_VALUE: "1", TTL_EXPIRE_TYPE: "day", });
Perhatikan bahwa nilai rahasia harus ditentukan menggunakan fungsi
defineSecret
.Kemudian, untuk men-deploy ekstensi yang Anda konfigurasi, jalankan:
firebase deploy --only functions --project=
projectId-or-alias Semua opsi deployment Cloud Functions biasa berlaku. Misalnya, untuk men-deploy satu instance ekstensi dari codebase tertentu:
firebase deploy --only functions:
codebase :extension-instance-id --project=projectId-or-alias
Langkah 3: Selesaikan penyiapan pasca-penginstalan
Beberapa ekstensi memiliki langkah wajib atau opsional yang harus Anda selesaikan sebelum menggunakannya. Temukan petunjuk ini di halaman detail pasca-penginstalan ekstensi di dasbor Extensions pada Firebase console (link spesifik ke dasbor akan ditampilkan di terminal setelah penginstalan).
Anda juga dapat menemukan petunjuk ini dalam file POSTINSTALL.md
yang disertakan di
direktori sumber ekstensi.
Membuat resource Firebase
Jika Anda mengonfigurasi ekstensi untuk menggunakan resource Firebase (koleksi Cloud Firestore, jalur Realtime Database, bucket Cloud Storage) yang belum ada, buat resource tersebut sebelum menggunakan ekstensi.
Membuat pengendali peristiwa Eventarc
Beberapa ekstensi dipublikasikan ke Eventarc saat peristiwa penting terjadi selama eksekusi. Jika ekstensi memublikasikan peristiwa, Anda dapat menulis fungsi yang bereaksi terhadap peristiwa tersebut dengan logika kustom Anda sendiri. Hal ini dapat berguna, misalnya, untuk memberi tahu pengguna saat tugas yang berjalan lama selesai, atau untuk pasca-pemrosesan output fungsi ekstensi.
Jika ingin menentukan pengendali untuk peristiwa apa pun yang dikeluarkan oleh ekstensi, Anda dapat melakukannya menggunakan metode pemicu setiap instance:
export const firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });
export const emailErrorHandler = firestoreSendEmail_1.onError((event) => {
// Handle mail errors.
});
exports.firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });
exports.emailErrorHandler = exports.firestoreSendEmail_1.onError((event) => {
// Handle mail errors.
});
Anda harus mengekspor pengendali peristiwa beserta instance ekstensi.
Setelah menentukan pengendali peristiwa, dan setiap kali Anda membuat perubahan pada pengendali, deploy ulang ekstensi dan pengendali.
Menginstal beberapa instance ekstensi
Catatan: Anda dapat menginstal ekstensi yang sama beberapa kali dalam project yang sama. Setiap instance yang diinstal dapat memiliki konfigurasi yang disesuaikan sendiri dan resource ekstensinya sendiri. Anda mengidentifikasi dan merujuk ke setiap instance yang diinstal menggunakan ID instance yang bersifat unik dalam project Anda.
Panggil fungsi konstruktor SDK yang dibuat secara otomatis satu kali untuk setiap instance yang ingin Anda instal dan konfigurasi.
Langkah Berikutnya
Lihat detail dan konfigurasi ekstensi yang diinstal di Firebase console.
Pantau aktivitas ekstensi yang diinstal, termasuk memeriksa respons, penggunaan, dan log-nya.
Kelola ekstensi yang diinstal menggunakan Firebase console. Untuk ekstensi Firebase resmi, Anda dapat mengonfigurasi ulang atau meng-uninstal ekstensi, serta mengupdate ekstensi ke versi terbaru.
Sebagai praktik terbaik untuk semua project, pastikan Anda menyiapkan pemberitahuan anggaran untuk project Anda dan memantau dasbor Usage and billing di Firebase console.