Membuat dan menangani pemicu peristiwa kustom

Dengan Cloud Functions (generasi ke-2), Anda dapat memicu fungsi sebagai respons terhadap peristiwa kustom. Peristiwa kustom yang dimaksud adalah yang disediakan oleh penyedia peristiwa khusus atau tambahan, bukan peristiwa Firebase yang secara native didukung oleh Firebase SDK untuk Cloud Functions. Melalui pemicu peristiwa kustom, aplikasi Anda dapat merespons peristiwa yang disediakan oleh Firebase Extensions, atau Anda dapat memublikasikan peristiwa kustom sendiri dan memicu fungsi sebagai respons terhadap peristiwa tersebut.

Semua peristiwa kustom sesuai dengan format peristiwa JSON CloudEvents dan dipublikasikan di Eventarc. Biaya penggunaan Eventarc berlaku.

Memicu fungsi dengan peristiwa kustom

Anda dapat memublikasikan peristiwa kustom (atau mendapatkan peristiwa dari ekstensi Firebase) dan memicu fungsi sebagai respons terhadap peristiwa tersebut dengan menerapkan alur dasar ini:

  1. Publikasikan peristiwa yang diinginkan ke saluran Eventarc, atau identifikasi peristiwa yang tersedia yang disediakan oleh ekstensi yang telah Anda instal.
  2. Dalam kode fungsi, berlangganankan peristiwa di saluran Eventarc dengan pengendali onCustomEventPublished.
  3. Dalam fungsi, uraikan payload yang diberikan dalam objek CloudEvent dan jalankan logika kustom apa pun yang diperlukan aplikasi Anda.

Misalnya, aplikasi game mungkin ingin mengirim notifikasi kepada pengguna saat mereka masuk atau keluar dari papan peringkat sepuluh pesaing teratas. Aplikasi ini dapat memublikasikan peristiwa papan peringkat ke saluran default, lalu menangani peristiwa dalam fungsi yang mengirimkan notifikasi push yang ditargetkan kepada pengguna.

Untuk contoh lain, ekstensi yang dirancang untuk membantu aplikasi memproses gambar berukuran besar dapat memunculkan peristiwa saat penyelesaian pengubahan ukuran gambar. Aplikasi yang menginstal ekstensi ini dapat menangani peristiwa penyelesaian dengan memperbarui link dalam aplikasi agar mengarah ke versi gambar yang diubah ukurannya.

Memublikasikan peristiwa ke saluran

Peristiwa eventarc dipublikasikan di saluran. Saluran adalah cara untuk mengelompokkan peristiwa terkait dan mengelola izin akses. Saat Anda menginstal ekstensi atau men-deploy fungsi yang menggunakan peristiwa kustom, Firebase otomatis membuat saluran default yang diberi nama firebase di region us-central1. Firebase Admin SDK menyediakan subpaket eventarc untuk memublikasikan ke saluran.

Untuk memublikasikan peristiwa dari server tepercaya (atau fungsi lainnya) menggunakan saluran default:

import {getEventarc} from 'firebase-admin/eventarc';

getEventarc().channel().publish({
    type: 'achieved-leaderboard',
    subject: 'Welcome to the top 10',
    data: {
      message: 'You have achieved the nth position in our leaderboard!  To see . . .'
    }
});

Selain membuat saluran default secara otomatis, Firebase menetapkan variabel lingkungan EVENTARC_CLOUD_EVENT_SOURCE, yang menentukan sumber peristiwa. Jika memublikasikan peristiwa di luar Cloud Functions for Firebase, Anda harus secara eksplisit menambahkan kolom source pada payload peristiwa.

Menangani peristiwa dengan onCustomEventPublished

Anda dapat menangani semua peristiwa kustom, termasuk peristiwa ekstensi, dengan pengendali onCustomEventPublished. Pertama, impor pengendali ini dari Eventarc SDK bersama dengan Firebase Admin SDK untuk Node.js untuk logika kustom dan SDK logger untuk menangani error:

const {onCustomEventPublished} = require("firebase-functions/v2/eventarc");
const logger = require("firebase-functions/logger");
const {initializeApp} = require("firebase-admin/app");
const {getFirestore} = require("firebase-admin/firestore");

Dalam kode fungsi, teruskan nama peristiwa seperti yang ditunjukkan untuk contoh fungsi onimageresized:

exports.onimageresized = onCustomEventPublished(
    "firebase.extensions.storage-resize-images.v1.complete",
    (event) => {
      logger.info("Received image resize completed event", event);
      // For example, write resized image details into Firestore.
      return getFirestore()
          .collection("images")
          .doc(event.subject.replace("/", "_")) // original file path
          .set(event.data); // resized images paths and sizes
    });

Untuk setiap ekstensi tertentu, payload yang ditampilkan dalam objek peristiwa menyediakan data yang dapat digunakan untuk menjalankan logika kustom bagi alur aplikasi Anda. Dalam hal ini, fungsi tersebut menggunakan Admin SDK untuk menyalin metadata tentang gambar yang diubah ukurannya ke koleksi di Cloud Firestore, mendapatkan nama file dari subject yang disediakan oleh peristiwa, dan menyimpan metadata dari data yang disediakan oleh peristiwa.

Memublikasikan dan menangani peristiwa di saluran non-default

Saluran khusus dapat berguna untuk kasus ketika Anda memiliki kebutuhan izin khusus atau persyaratan lainnya, dan tidak ingin tingkat visibilitas dan akses yang sama untuk semua peristiwa. Anda dapat membuat saluran sendiri menggunakan Google Cloud Console. Memublikasikan dan berlangganan peristiwa harus dilakukan di channel yang sama.

Jika peristiwa kustom dipublikasikan di saluran non-default, Anda harus menentukan saluran tersebut dalam kode fungsi Anda. Misalnya, jika Anda ingin menangani peristiwa yang dipublikasikan di saluran non-default untuk lokasi us-west1, Anda harus menentukan saluran seperti yang ditunjukkan berikut:

import { onCustomEventPublished } from "firebase-functions/v2/eventarc";

export const func = onCustomEventPublished(
    {
      eventType: "firebase.extensions.storage-resize-images.v1.complete",
      channel: "locations/us-west1/channels/firebase",
      region: "us-west1",
    },
    (event) => { ... });