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. Możesz to zrobić na 2 sposoby:

• 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 tych miejscach uruchamiasz funkcję dostawcy danych o użytkownikach i kontynuujesz dopiero po jej zakończeniu. Do tej kategorii często należą zadania wstępnego przetwarzania.

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

Zdarzenia Eventarc

Aby opublikować zdarzenia z rozszerzenia:

1. Zadeklaruj typy zdarzeń, które chcesz 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 rozdzielanych kropkami. 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 1 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 rozszerzenia zaimportuj interfejs Eventarc API z Admin SDKi inicjuj kanał zdarzeń, używając ustawień instalacji użytkownika. Te ustawienia są dostępne za pomocą tych zmiennych środowiskowych:

   • EVENTARC_CHANNEL: w pełni kwalifikowana nazwa kanału Eventarc, w którym użytkownik wybrał publikowanie zdarzeń.
   • EXT_SELECTED_EVENTS: lista oddzielonych przecinkami typów wydarzeń, które użytkownik chce opublikować. 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 jawnie używać tej zmiennej.

   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 na kanale zdarzenia w miejscach rozszerzenia, które chcesz udostępnić 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. Udokumentuj publikowane zdarzenia w pliku PREINSTALL lub POSTINSTALL.

   W przypadku każdego zdarzenia odnotuj te informacje:

   • Zamierzone zastosowanie
   • Punkt w logice rozszerzenia, w którym jest ono wykonywane
   • 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 opublikujesz zdarzenia z poziomu rozszerzenia, użytkownicy będą mogli stosować ich obsługi, aby reagować na nie za pomocą logiki niestandardowej.

Na przykład w tym przykładzie oryginalny obraz jest usuwany po zmianie jego rozmiaru. Zwróć uwagę, że ten przykładowy moduł obsługi korzysta z właściwości subject zdarzenia, która w tym przypadku jest oryginalną nazwą 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 sekcji Wyzwalacze zdarzeń niestandardowych.

Przykład

Oficjalne rozszerzenie do zmiany rozmiaru obrazu zapewnia asynchroniczny element wywoławczy, który publikuje w Eventarc po zmianie rozmiaru obrazu.

Elementy synchroniczne

Jeśli chcesz udostępnić użytkownikom element wywołania, który musi zostać wykonany prawidłowo, aby jedna z funkcji rozszerzenia mogła działać, użyj elementów wywołania synchronicznego.

Zaczep synchroniczny wywołuje zdefiniowaną przez użytkownika funkcje 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 ujawnić element synchroniczny:

1. Dodaj do rozszerzenia parametr, który pozwoli użytkownikom skonfigurować rozszerzenie za pomocą adresu URL niestandardowej funkcji w Cloud. 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 ujawnić element wywołania, 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. Zapisz wszystkie dostępne punkty wywołania w pliku PREINSTALL lub POSTINSTALL.

   W przypadku każdego elementu zaczepu opisz te informacje:

   • Zamierzone zastosowanie
   • Punkt 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 Algolia Search zapewnia synchroniczny element wywołujący, który wywołuje funkcję przekształcenia podawaną przez użytkownika, zanim dane zostaną zapisane w Algolii.