Dodaj zaczepy użytkownika do rozszerzenia

Możesz zapewnić użytkownikom, którzy zainstalują Twoje rozszerzenie, możliwość wstawienia własnej, niestandardowej logiki do wykonania Twojego rozszerzenia. Można to osiągnąć na dwa sposoby:

  • Wydarzenia Eventarc : aby dać użytkownikom możliwość asynchronicznego reagowania na zdarzenia, możesz publikować w Eventarc. Użytkownicy mogą wdrażać funkcje obsługi zdarzeń, które na przykład wysyłają powiadomienia po zakończeniu długotrwałych zadań, lub mogą definiować własne funkcje przetwarzania końcowego.

  • Synchroniczne zaczepy : aby dać użytkownikom możliwość dodania logiki blokowania do Twojego rozszerzenia, możesz dodać synchroniczne zaczepy w określonych wcześniej punktach działania rozszerzenia. W tym momencie uruchamiasz funkcję dostawcy użytkownika i kontynuujesz ją dopiero po jej zakończeniu. Do tej kategorii często zaliczają się zadania związane z przetwarzaniem wstępnym.

Rozszerzenie może używać jednej lub obu metod.

Wydarzenia Eventarc

Aby opublikować wydarzenia z rozszerzenia:

  1. Zadeklaruj typy zdarzeń, które będziesz publikować w pliku extension.yaml :

    events:
  - type: publisher-id.extension-name.version.event-name
    description: event-description
  - type: publisher-id.extension-name.version.another-event-name
    description: another-event-description

    Identyfikator type składa się z kilku pól rozdzielonych kropkami. Pola identyfikatora wydawcy , nazwy rozszerzenia i nazwy wydarzenia są wymagane. Zalecane jest pole wersji. Wybierz unikalną i opisową nazwę wydarzenia dla każdego typu wydarzenia, które publikujesz.

    Na przykład rozszerzenie storage-resize-images deklaruje pojedynczy typ zdarzenia:

    events:
  - type: firebase.extensions.storage-resize-images.v1.complete
    description: |
      Occurs when image resizing completes. The event will contain further
      details about specific formats and sizes.

    Użytkownicy będą mogli wybrać, które wydarzenia chcą subskrybować po zainstalowaniu rozszerzenia.

  2. W funkcjach rozszerzenia zaimportuj interfejs Eventarc API z pakietu Admin SDK i zainicjuj kanał zdarzeń, korzystając z ustawień instalacji użytkownika. Te ustawienia są ujawniane przy użyciu następujących zmiennych środowiskowych:

    • EVENTARC_CHANNEL : pełna nazwa kanału Eventarc, na którym użytkownik zdecydował się publikować wydarzenia.
    • EXT_SELECTED_EVENTS : rozdzielona przecinkami lista typów wydarzeń, które użytkownik zdecydował się opublikować. Gdy zainicjujesz kanał tą wartością, pakiet Admin SDK automatycznie odfiltruje zdarzenia, których użytkownik nie wybrał.
    • EVENTARC_CLOUD_EVENT_SOURCE : identyfikator źródła zdarzenia w chmurze. Pakiet Admin SDK automatycznie przekazuje tę wartość w polu source opublikowanych zdarzeń. Zwykle nie trzeba jawnie używać tej zmiennej.

    Jeśli podczas instalacji nie włączono zdarzeń, zmienne te będą niezdefiniowane. Możesz wykorzystać ten fakt do zainicjowania kanału zdarzeń tylko wtedy, gdy zdarzenia są włączone:

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

admin.initializeApp();

// Set eventChannel to a newly-initialized channel, or `undefined` if events
// aren't enabled.
const eventChannel =
  process.env.EVENTARC_CHANNEL &&
  getEventarc().channel(process.env.EVENTARC_CHANNEL, {
    allowedEventTypes: process.env.EXT_SELECTED_EVENTS,
  });

  3. Publikuj wydarzenia na kanale w tych punktach rozszerzenia, które chcesz udostępnić użytkownikom. Na przykład:

    // If events are enabled, publish a `complete` event to the configured
// channel.
eventChannel && eventChannel.publish({
    type: 'firebase.extensions.storage-resize-images.v1.complete',
    subject: filename,  // the name of the original file
    data: {
      // ...
    }
});

  4. Dokumentuj publikowane zdarzenia w pliku PREINSTALL lub POSTINSTALL.

    Dla każdego zdarzenia udokumentuj następujące informacje:

    • Jego zamierzony cel
    • Punkt logiki rozszerzenia, w którym działa
    • Dane wyjściowe, które zawiera
    • Warunki jego wykonania

    Ponadto ostrzegaj użytkowników, aby nie wykonywali w swoich programach obsługi zdarzeń żadnych akcji, które mogłyby wywołać to samo rozszerzenie, co spowodowałoby nieskończoną pętlę.

Gdy publikujesz zdarzenia z rozszerzenia, użytkownicy mogą wdrożyć procedury obsługi zdarzeń, aby reagować za pomocą niestandardowej logiki.

Na przykład poniższy przykład usuwa oryginalny obraz po zmianie jego rozmiaru. Należy zauważyć, że ta przykładowa procedura obsługi korzysta z właściwości subject zdarzenia, którą w tym przypadku jest oryginalna nazwa pliku obrazu.

exports.onimageresized = onCustomEventPublished(
    "firebase.extensions.storage-resize-images.v1.complete",
    (event) => {
      logger.info("Received image resize completed event", event);
      // For example, delete the original.
      return admin.storage()
          .bucket("my-project.appspot.com")
          .file(event.subject)
          .delete();
    });

Aby uzyskać więcej informacji, zobacz wyzwalacze zdarzeń niestandardowych .

Przykład

Oficjalne rozszerzenie Resize Images zapewnia asynchroniczne przechwytywanie, publikując w Eventarc po zmianie rozmiaru obrazu.

Haki synchroniczne

Jeśli chcesz udostępnić użytkownikom hak, który musi zostać pomyślnie zakończony, aby jedna z funkcji rozszerzenia mogła działać, użyj haków synchronicznych .

Przechwytywanie synchroniczne wywołuje zdefiniowaną przez użytkownika funkcję Cloud Function wywoływaną przez protokół HTTPS i oczekuje na zakończenie (prawdopodobnie ze zwróconą wartością) przed kontynuowaniem. Błąd w funkcji dostarczonej przez użytkownika powoduje błąd w funkcji rozszerzenia.

Aby odsłonić hak synchroniczny:

  1. Dodaj do swojego rozszerzenia parametr, który umożliwi użytkownikom skonfigurowanie rozszerzenia za pomocą adresu URL ich niestandardowej funkcji w chmurze. Na przykład:

    - param: PREPROCESSING_FUNCTION
  label: Pre-processing function URL
  description: >
    An HTTPS callable function that will be called to transform the input data
    before it is processed by this function.
  type: string
  example: https://us-west1-my-project-id.cloudfunctions.net/preprocessData
  required: false

  2. W tym miejscu rozszerzenia, w którym chcesz odsłonić hak, wywołaj funkcję, używając jej adresu URL. Na przykład:

    const functions = require('firebase-functions');
const fetch = require('node-fetch');

const preprocessFunctionURL = process.env.PREPROCESSING_FUNCTION;

exports.yourFunctionName = functions.firestore.document("collection/{doc_id}")
    .onWrite((change, context) => {
      // PREPROCESSING_FUNCTION hook begins here.
      // If a preprocessing function is defined, call it before continuing.
      if (preprocessFunctionURL) {
        try {
          await fetch(preprocessFunctionURL); // Could also be a POST request if you want to send data.
        } catch (e) {
          // Preprocessing failure causes the function to fail.
          functions.logger.error("Preprocessor error:", e);
          return;
        }
      }
      // End of PREPROCESSING_FUNCTION hook.

      // Main function logic follows.
      // ...
    });

  3. Udokumentuj wszystkie udostępnione haczyki w pliku PREINSTALL lub POSTINSTALL.

    Dla każdego haka zapisz następujące informacje:

    • Jego zamierzony cel
    • Punkt logiki rozszerzenia, w którym działa
    • Oczekiwane wejścia i wyjścia
    • Warunki (lub opcje) jego wykonania

    Dodatkowo ostrzegaj użytkowników, aby nie wykonywali żadnych działań w funkcji przechwytującej, które mogłyby wywołać to samo rozszerzenie, co spowodowałoby nieskończoną pętlę.

Przykład

Rozszerzenie Algolia Search zapewnia synchroniczny mechanizm umożliwiający wywołanie dostarczonej przez użytkownika funkcji transformacji przed zapisaniem do Algolii.