Как создавать и обрабатывать триггеры специальных событий

С помощью Cloud Functions (второго поколения) можно запускать функции в ответ на специальные события. Это события, предоставляемые специальными или дополнительными поставщиками событий, в отличие от событий Firebase, которые изначально поддерживаются SDK Firebase для Cloud Functions. С помощью триггеров пользовательских событий ваше приложение может реагировать на события, предоставляемые Firebase Extensions, или вы можете публиковать собственные пользовательские события и запускать функции в ответ на них.

Все специальные события соответствуют формату событий CloudEvents JSON и публикуются в Eventarc. Eventarc Взимается комиссия за использование.

Как активировать функции с помощью специальных событий

Вы можете публиковать специальные события (или получать события из Firebase Extensions) и активировать функции в ответ на эти события, реализовав следующий базовый процесс:

1. Опубликуйте нужные события в канале Eventarc или определите доступные события, предоставляемые установленным расширением.
2. В коде функции подпишитесь на события в канале Eventarc с помощью обработчика событий.
3. В функции проанализируйте полезную нагрузку, возвращенную в объекте CloudEvent, и выполните любую пользовательскую логику, необходимую вашему приложению.

Например, мобильная игра может отправлять пользователям уведомления, когда они входят в рейтинг игроков из первой десятки или выбывают из него. Это приложение может публиковать события таблицы лидеров в канале по умолчанию, а затем обрабатывать событие в функции, которая отправляет пользователям целевые push-уведомления.

В другом примере расширение, предназначенное для помощи приложениям в обработке больших изображений, может генерировать событие по завершении изменения размера изображения. Приложения, в которых установлено это расширение, могут обрабатывать событие завершения, обновляя ссылки в приложении, чтобы они указывали на версии изображения с измененным размером.

Как опубликовать событие в канале

События Eventarc публикуются в каналах. Каналы позволяют группировать связанные события и управлять разрешениями на доступ. Когда вы устанавливаете расширение или развертываете функцию, которая использует специальные события, Firebase автоматически создает канал по умолчанию с названием firebase в регионе us-central1. В Firebase Admin SDK есть подпакет eventarc для публикации каналов.

Чтобы опубликовать событие с доверенного сервера (или другой функции) с помощью канала по умолчанию:

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

Помимо автоматического создания канала по умолчанию, Firebase задает переменную среды EVENTARC_CLOUD_EVENT_SOURCE, которая указывает источник события. Если вы публикуете события за пределами Cloud Functions for Firebase, вам нужно будет явно добавить поле source в полезную нагрузку события.

Как обрабатывать специальные события

Для обработки всех специальных событий, включая события расширений, можно использовать обработчики onCustomEventPublished или on_custom_event_published. Сначала импортируйте этот обработчик из Eventarc SDK вместе с Firebase Admin SDK:

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

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

В коде функции передайте название события, как показано в примере:

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

@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

Для каждого расширения полезная нагрузка, возвращаемая в объекте события, предоставляет данные, которые можно использовать для выполнения пользовательской логики в потоке приложения. В этом случае функция использует Admin SDK, чтобы скопировать метаданные об изображении с измененным размером в коллекцию в Cloud Firestore, получить название файла из subject, предоставленного событием, и сохранить метаданные из data, предоставленного событием.

Как публиковать и обрабатывать события в каналах, не используемых по умолчанию

Пользовательские каналы могут быть полезны, если вам нужны особые разрешения или у вас есть другие требования и вы не хотите, чтобы все события имели одинаковый уровень видимости и доступа. Вы можете создать собственные каналы в консоли Google Cloud. Публикация событий и подписка на них должны выполняться в одном канале.

Если специальное событие публикуется в канале, который не используется по умолчанию, вам нужно будет указать канал в коде функции. Например, если вы хотите обрабатывать события, опубликованные в канале, который не является каналом по умолчанию для местоположения us-west1, укажите канал, как показано ниже:

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

@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