Dodawanie do rozszerzenia elementów, które zaciągają użytkowników

Możesz zapewnić użytkownikom, którzy zainstalowali Twoje rozszerzenie, możliwość wstawiania własnych rozszerzeń za pomocą niestandardowej logiki podczas wykonywania rozszerzenia. Są 2 sposoby możesz osiągnąć ten cel:

  • Zdarzenia Eventarc: aby umożliwić użytkownikom asynchroniczne reagowanie na które możesz publikować w Eventarc. Użytkownicy mogą wdrażać moduł obsługi zdarzeń funkcje, które np. wysyłają powiadomienia po dłuższym okresie mogą definiować własne funkcje przetwarzania.

  • Synchroniczne elementy przykuwające uwagę: aby umożliwić użytkownikom dodanie logiki blokującej do możesz dodać synchroniczne punkty zaczepienia w wstępnie zdefiniowanych punktach działania rozszerzenia. W tym momencie uruchamiasz funkcję dostawcy danych o użytkownikach, i kontynuować dopiero po jego zakończeniu. Zadania przetwarzania wstępnego często należą do kategorii w tej kategorii.

Rozszerzenie może korzystać z jednej z tych metod lub z obu tych metod.

Zdarzenia 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 kropką. Pola identyfikator wydawcy, nazwy rozszerzenia i nazwy zdarzenia to Pole wersji jest zalecane. Wybierz unikalną, opisową w przypadku każdego opublikowanego typu zdarzenia.

    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ć zainstalować rozszerzenie.

  2. W funkcjach rozszerzeń zaimportuj Eventarc API z Admin SDK i zainicjuj kanał zdarzenia za pomocą ustawień instalacji wybranych przez użytkownika. Te ustawienia są ujawniane przy użyciu następujących zmiennych środowiskowych:

    • EVENTARC_CHANNEL: w pełni kwalifikowana nazwa kanału Eventarc, do którego w których przypadku użytkownik publikował zdarzenia.
    • EXT_SELECTED_EVENTS: rozdzielona przecinkami lista typów zdarzeń wykonywanych przez użytkownika do publikacji. Gdy zainicjujesz kanał przy użyciu tej wartości, Pakiet Admin SDK automatycznie odfiltrowuje zdarzenia, które nie zostały wybrane przez użytkownika.
    • EVENTARC_CLOUD_EVENT_SOURCE: identyfikator źródła zdarzeń Cloud. Pakiet Admin SDK automatycznie przekazuje tę wartość w polu source metody opublikowane wydarzenia. Zwykle nie trzeba go używać .

    Jeśli zdarzenia nie były włączone podczas instalacji, te zmienne zostaną nie zdefiniowano. Możesz go użyć do zainicjowania kanału zdarzenia tylko wtedy, gdy: włączone wydarzenia:

    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 wybranych punktach rozszerzenia nie jest ujawniana użytkownikom. 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. Zapisz publikowane zdarzenia za pomocą instrukcji PREINSTALL lub POSTINSTALL .

    W przypadku każdego wydarzenia udokumentuj te informacje:

    • Przeznaczenie
    • punkt w logice rozszerzenia,
    • zawarte w nim dane wyjściowe,
    • warunki jego wykonania.

    Dodatkowo ostrzegaj użytkowników, aby nie wykonywali żadnych działań w ramach wydarzenia moduły obsługi, które mogą aktywować to samo rozszerzenie, co skutkuje nieskończeniem w pętli.

Gdy publikujesz zdarzenia z rozszerzenia, użytkownicy mogą wdrażać moduły obsługi zdarzeń dostosowane do własnych potrzeb.

W poniższym przykładzie można usunąć oryginalne zdjęcie po tym, jak zostało rozmiar został zmieniony. Zwróć uwagę, że w tym przykładowym module obsługi używana jest właściwość subject zdarzenie, czyli w tym przypadku jest to 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();
    });

Więcej informacji znajdziesz w artykule Reguły zdarzeń niestandardowych. i informacjami o nich.

Przykład

Oficjalne rozszerzenie Resize Images. udostępnia asynchroniczny obiekt zaczepienia, publikując w Eventarc po zmianie rozmiaru obrazu.

Synchroniczne haki

Gdy chcesz udostępnić użytkownikom element przykuwający uwagę, który musi się zakończyć aby umożliwić działanie jednej z funkcji rozszerzenia, użyj funkcji zaczepienia synchronicznego.

Synchroniczny punkt zaczepienia wywołuje zdefiniowaną przez użytkownika chmurę z możliwością wywoływania HTTPS funkcjii oczekuje na zakończenie (prawdopodobnie z zwracaną wartość). Błąd w funkcji podanej przez użytkownika powoduje błąd w funkcji rozszerzenia.

Aby udostępnić synchroniczny punkt zaczepienia:

  1. Dodaj do rozszerzenia parametr, który pozwoli użytkownikom skonfigurować z adresem URL jej niestandardowej funkcji w Cloud Functions. 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 punkcie rozszerzenia, w którym chcesz pokazać zaczep, wywołaj funkcję za pomocą jej adresu URL. Przykład:

    const functions = require('firebase-functions/v1');
    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. Wszystkie udostępnione punkty zaczepienia zapisz w opcji PREINSTALL albo POSTINSTALL.

    Dla każdego zaczepienia udokumentuj te kwestie:

    • Przeznaczenie
    • punkt w logice rozszerzenia,
    • Oczekiwane dane wejściowe i wyjściowe
    • warunki (lub opcje) wykonania kodu;

    Dodatkowo ostrzegaj użytkowników, aby nie wykonywali żadnych działań związanych z haczykiem , która może aktywować to samo rozszerzenie, powodując nieskończoną liczbę w pętli.

Przykład

rozszerzenie wyszukiwania Algolia udostępnia synchroniczny punkt zaczepienia do wywołania dostarczonej przez użytkownika funkcji transformacji przed napisaniem do Algolii.