Crea y administra activadores de eventos personalizados

Con Cloud Functions (2ª gen.), puedes activar funciones en respuesta a eventos personalizados. Estos son eventos que proporcionan proveedores especiales o adicionales, a diferencia de los eventos de Firebase que son compatibles de forma nativa con el SDK de Firebase para Cloud Functions. Mediante los activadores de eventos personalizados, tu app puede responder a los eventos proporcionados por Firebase Extensions o puedes publicar tus propios eventos personalizados y activar funciones en respuesta a ellos.

Todos los eventos personalizados cumplen con el formato de evento de JSON de CloudEvents y se publican en Eventarc. Se aplican las tarifas por uso de Eventarc.

Activa funciones con eventos personalizados

Puedes publicar eventos personalizados (o, también, obtener eventos de las Extensiones de Firebase) y activar funciones en respuesta a esos eventos mediante la implementación de este flujo básico:

  1. Publica los eventos deseados en un canal de Eventarc o identifica los eventos disponibles que proporciona una extensión que instalaste.
  2. En el código de la función, suscríbete a eventos en el canal de Eventarc con un controlador de eventos.
  3. En la función, analiza la carga útil que se muestra en el objeto CloudEvent y realiza la lógica personalizada que requiera tu app.

Por ejemplo, en una app de juego, podrías enviar notificaciones a los usuarios cuando ingresan a la tabla de clasificación de los diez competidores principales o salen de ella. Esta app podría publicar eventos de tablas de clasificación en el canal predeterminado y, luego, controlar el evento en una función que envíe notificaciones push segmentadas a los usuarios.

En otro ejemplo, una extensión diseñada para ayudar a las apps a procesar imágenes grandes puede emitir un evento cuando se complete el cambio de tamaño de las imágenes. Las apps que tienen instalada esta extensión podrían controlar el evento de finalización si actualizas los vínculos de la app para que hagan referencia a las versiones de la imagen con el tamaño modificado.

Publica un evento en un canal

Los eventos de Eventarc se publican en canales. Los canales son una forma de agrupar los eventos relacionados y administrar permisos de acceso. Cuando instalas una extensión o implementas una función que consume eventos personalizados, Firebase crea automáticamente un canal predeterminado llamado firebase en la región us-central1. Firebase Admin SDK proporciona un subpaquete eventarc para publicar en canales.

Para publicar un evento desde un servidor de confianza (o cualquier otra función) con el canal predeterminado, sigue estos pasos:

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

Además de crear automáticamente el canal predeterminado, Firebase establece la variable de entorno EVENTARC_CLOUD_EVENT_SOURCE, que especifica la fuente del evento. Si publicas eventos fuera de Cloud Functions for Firebase, tendrás que agregar de manera explícita el campo source a la carga útil de tu evento.

Controla eventos personalizados

Puedes controlar todos los eventos personalizados, incluidos los de extensiones, con los controladores onCustomEventPublished o on_custom_event_published. Primero, importa este controlador desde el SDK de Eventarc junto con el 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

En el código de tu función, pasa el nombre del evento como se muestra en la función de ejemplo:

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

Para cada extensión en particular, la carga útil que se muestra en el objeto de evento proporciona datos que puedes usar a fin de realizar una lógica personalizada para el flujo de tu aplicación. En este caso, la función usa el Admin SDK para copiar metadatos sobre la imagen a la que se le cambió el tamaño a una colección en Cloud Firestore, obtener el nombre de archivo del subject proporcionado por el evento y guardar metadatos de los data que proporciona el evento.

Publica y administra eventos en canales no predeterminados

Los canales personalizados pueden ser útiles en casos en los que necesites permisos especiales o algún otro requisito, y no desees tener el mismo nivel de visibilidad y acceso para todos los eventos. Puedes crear tus propios canales con la consola de Google Cloud. La publicación y la suscripción a eventos deben realizarse en el mismo canal.

En los casos en que se publique un evento personalizado en un canal no predeterminado, deberás especificar el canal en el código de la función. Por ejemplo, si deseas controlar eventos que se publican en un canal no predeterminado para la ubicación us-west1, debes especificar el canal como se muestra a continuación:

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