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

Możesz umożliwić użytkownikom, którzy zainstalują Twoje rozszerzenie, wstawianie własnej logiki niestandardowej podczas jego wykonywania. Są 2 sposoby możesz osiągnąć ten cel:

• Zdarzenia Eventarc: aby umożliwić użytkownikom asynchroniczne reagowanie na zdarzenia, możesz publikować je w Eventarc. Użytkownicy mogą stosować funkcje obsługi zdarzeń, które na przykład wysyłają powiadomienia po zakończeniu długotrwałych zadań, lub definiować własne funkcje przetwarzania w trakcie.

• Elementy synchroniczne: aby umożliwić użytkownikom dodawanie logiki blokowania do rozszerzenia, możesz dodawać elementy synchroniczne w wybranych punktach działania rozszerzenia. W tym momencie uruchamiasz funkcję dostawcy danych o użytkownikach i kontynuuj dopiero po jego zakończeniu. Zadania przetwarzania wstępnego często należą do kategorii w tej kategorii.

Rozszerzenie może używać jednej lub 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, nazwa rozszerzenia i nazwa zdarzenia są wymagane. Pole wersji jest zalecane. Wybierz unikalną i opisową nazwę zdarzenia dla każdego publikowanego 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.
   

   Po zainstalowaniu rozszerzenia użytkownicy będą mogli wybrać, na które wydarzenia chcą się zapisać.

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, w którym użytkownik wybrał publikowanie zdarzeń.
   • EXT_SELECTED_EVENTS: rozdzielona przecinkami lista typów zdarzeń wykonywanych przez użytkownika do publikacji. Gdy inicjujesz kanał za pomocą tej wartości, pakiet Admin SDK automatycznie odfiltrowuje zdarzenia, których użytkownik nie wybrał.
   • EVENTARC_CLOUD_EVENT_SOURCE: identyfikator źródła zdarzenia Cloud. Pakiet Admin SDK automatycznie przekazuje tę wartość w polu source opublikowanych zdarzeń. Zwykle nie trzeba go używać .

   Jeśli podczas instalacji zdarzenia nie zostały włączone, te zmienne będą nieokreślone. Możesz użyć tego faktu, aby zainicjować kanał 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 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,
   • Dane wyjściowe, które zawiera.
   • warunki jego wykonania,

   Dodatkowo ostrzegaj użytkowników, aby nie wykonywali żadnych działań w obsługach zdarzeń, które mogłyby wywołać to samo rozszerzenie, powodując nieskończoną pętlę.

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

Na przykład w tym przykładzie oryginalny obraz jest usuwany po zmianie jego rozmiaru. 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.

Zaczep synchroniczny wywołuje zdefiniowaną przez użytkownika funkcję uruchamianą przez HTTPS w usłudze Cloud Function i czeka na jej zakończenie (być może z wartością zwracaną) przed kontynuacją. Błąd w funkcji dostarczonej 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 miejscu w rozszerzeniu, w którym chcesz użyć funkcji hook, wywołaj ją 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 szablonach PREINSTALL albo POSTINSTALL.

   Dla każdego zaczepienia udokumentuj te kwestie:

   • Zamierzone zastosowanie
   • Miejsce w logice rozszerzenia, w którym jest ono wykonywane
   • Oczekiwane dane wejściowe i wyjściowe
   • warunki (lub opcje) jego wykonania;

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

Przykład

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