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 CloudEvents JSON 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, berlanggananlah ke peristiwa di saluran Eventarc dengan pengendali.
  3. Dalam fungsi, uraikan payload yang ditampilkan 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 kustom

Anda dapat menangani semua peristiwa kustom, termasuk peristiwa ekstensi, dengan pengendali onCustomEventPublished atau on_custom_event_published . Pertama, impor pengendali ini dari Eventarc SDK bersama dengan Firebase Admin SDK:

Node.js

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");

index.js

Python

from firebase_admin import firestore, initialize_app
from firebase_functions import eventarc_fn
main.py

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

Node.js

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
    });
index.js

Python

@eventarc_fn.on_custom_event_published(
    event_type="firebase.extensions.storage-resize-images.v1.complete")
def onimageresized(event: eventarc_fn.CloudEvent) -> None:
    print("Received image resize completed event: ", event.type)

    if not isinstance(event.subject, str):
        print("No 'subject' data.")
        return

    # For example, write resized image details into Firestore.
    firestore_client: google.cloud.firestore.Client = firestore.client()
    collection = firestore_client.collection("images")
    doc = collection.document(event.subject.replace("/", "_"))  # original file path
    doc.set(event.data)  # resized images paths and sizes
main.py

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:

Node.js

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) => { ... });

Python

@eventarc_fn.on_custom_event_published(
    event_type="firebase.extensions.storage-resize-images.v1.complete",
    channel="locations/us-west1/channels/firebase",
    region="us-west1")
def onimageresizedwest(event: eventarc_fn.CloudEvent) -> None:
    print("Received image resize completed event: ", event.type)
    # ...
main.py