Obsługa zdarzeń cyklu życia rozszerzenia

Rozszerzenie może zawierać funkcje Cloud Tasks, które są wywoływane, gdy instancja rozszerzenia przechodzi przez jeden z tych zdarzeń cyklu życia:

• Rozszerzenie jest zainstalowane
• instancja rozszerzenia jest aktualizowana do nowej wersji,
• Zmiana konfiguracji instancji rozszerzenia

Jedną z najważniejszych zastosowań tej funkcji jest uzupełnianie danych. Załóżmy, że tworzysz rozszerzenie, które generuje podgląd miniatur obrazów przesłanych do zasobnika Cloud Storage. Główna część rozszerzenia będzie wykonywana w funkcji wywoływanej przez zdarzenie onFinalize Cloud Storage. Przetwarzane będą jednak tylko obrazy przesłane po zainstalowaniu rozszerzenia. Jeśli w rozszerzeniu umieścisz funkcję wywoływaną przez zdarzenie cyklu życia onInstall, po zainstalowaniu rozszerzenia możesz też generować podgląd miniatur wszystkich dotychczasowych obrazów.

Oto kilka innych zastosowań wyzwalaczy zdarzeń cyklu życia:

• Automatyzacja konfiguracji po instalacji (tworzenie rekordów bazy danych, indeksowanie itp.)
• Jeśli musisz opublikować zmiany niezgodne ze starszymi wersjami, automatycznie migruj dane podczas aktualizacji.

Krótko działające moduły obsługi zdarzeń cyklu życia

Jeśli zadanie może zostać wykonane w maks. Cloud Functions czasu (9 minut w przypadku interfejsu API pierwszej generacji), możesz napisać metodę obsługi zdarzenia cyklu życia jako pojedynczą funkcję, która uruchamia zdarzenie kolejki zadań onDispatch:

export const myTaskFunction = functions.tasks.taskQueue()
  .onDispatch(async () => {
    // Complete your lifecycle event handling task.
    // ...

    // When processing is complete, report status to the user (see below).
  });

Następnie w pliku extension.yaml rozszerzenia:

1. Zarejestruj funkcję jako zasób rozszerzenia w zestawie właściwości taskQueueTrigger. Jeśli ustawisz taskQueueTrigger na pustą mapę ({}), Twoje rozszerzenie zarezerwuje kolejkę Cloud Tasks, używając domyślnych ustawień. Możesz opcjonalnie dostosować te ustawienia.

   resources:
     - name: myTaskFunction
       type: firebaseextensions.v1beta.function
       description: >-
         Describe the task performed when the function is triggered by a lifecycle
         event
       properties:
         location: ${LOCATION}
         taskQueueTrigger: {}
   

2. Zarejestruj funkcję jako moduł obsługi co najmniej 1 zdarzenia cyklu życia:

   resources:
     - ...
   lifecycleEvents:
     onInstall:
       function: myTaskFunction
       processingMessage: Resizing your existing images
     onUpdate:
       function: myOtherTaskFunction
       processingMessage: Setting up your extension
     onConfigure:
       function: myOtherTaskFunction
       processingMessage: Setting up your extension
   
   

   Funkcje możesz rejestrować w przypadku każdego z tych zdarzeń: onInstall, onUpdate i onConfigure. Wszystkie te zdarzenia są opcjonalne.

   Uwaga: komunikat, który tutaj podasz, zostanie automatycznie ustawiony jako stan przetwarzania rozszerzenia w konsoli Firebase po wywołaniu funkcji. Aby zaktualizować lub wyczyścić stan przetwarzania po zakończeniu pracy funkcji, wywołaj funkcję setProcessingState() w sposób opisany w sekcji Zgłoszenie stanu.

3. Zalecane: jeśli zadanie przetwarzania nie jest wymagane do działania rozszerzenia, dodaj parametry konfigurowane przez użytkownika, które pozwolą użytkownikom na włączenie tej funkcji.

   Możesz na przykład dodać parametr o takiej treści:

   params:
     - param: DO_BACKFILL
       label: Backfill existing images
       description: >
         Should existing, unresized images in the Storage bucket be resized as well?
       type: select
       options:
         - label: Yes
           value: true
         - label: No
           value: false
   

   Jeśli w funkcji parametr ma wartość false, funkcja zakończy się wcześniej:

   export const myTaskFunction = functions.tasks.taskQueue()
     .onDispatch(async () => {
       if (!process.env.DO_BACKFILL) {
         await runtime.setProcessingState(
           "PROCESSING_COMPLETE",
           "Existing images were not resized."
         );
         return;
       }
       // Complete your lifecycle event handling task.
       // ...
     });
   

Wykonywanie długotrwałych zadań

Jeśli zadanie nie może zostać ukończone w maksymalnie dozwolonym czasie Cloud Functions, podziel je na podzadania i wykonuj je po kolei, umieszczając je w kole za pomocą metody TaskQueue.enqueue() w Admin SDK.

Uwaga: nie próbuj umieszczać w kolejce wszystkich podzadań naraz, aby przetwarzać je równolegle. Autoryzacja odbywa się w momencie umieszczania zadań w kolejce, więc zadania znajdujące się na końcu kolejki nie zostaną wykonane, jeśli autoryzacja wygaśnie przed ich rozpoczęciem. Zamiast tego wykonaj zadania podrzędne po kolei, jak opisano w tej sekcji.

Załóżmy na przykład, że chcesz uzupełnić dane Cloud Firestore. Za pomocą wskaźników zapytań możesz podzielić kolekcję dokumentów na części. Po przetworzeniu fragmentu zwiększ przesunięcie początkowe i ustaw w kole inny wywołania funkcji, jak pokazano poniżej:

import { getFirestore } from "firebase-admin/firestore";
import { getFunctions } from "firebase-admin/functions";

exports.backfilldata = functions.tasks.taskQueue().onDispatch(async (data) => {
  // When a lifecycle event triggers this function, it doesn't pass any data,
  // so an undefined offset indicates we're on our first invocation and should
  // start at offset 0. On subsequent invocations, we'll pass an explicit
  // offset.
  const offset = data["offset"] ?? 0;

  // Get a batch of documents, beginning at the offset.
  const snapshot = await getFirestore()
    .collection(process.env.COLLECTION_PATH)
    .startAt(offset)
    .limit(DOCS_PER_BACKFILL)
    .get();
  // Process each document in the batch.
  const processed = await Promise.allSettled(
    snapshot.docs.map(async (documentSnapshot) => {
      // Perform the processing.
    })
  );

  // If we processed a full batch, there are probably more documents to
  // process, so enqueue another invocation of this function, specifying
  // the offset to start with.
  //
  // If we processed less than a full batch, we're done.
  if (processed.length == DOCS_PER_BACKFILL) {
    const queue = getFunctions().taskQueue(
      "backfilldata",
      process.env.EXT_INSTANCE_ID
    );
    await queue.enqueue({
      offset: offset + DOCS_PER_BACKFILL,
    });
  } else {
      // Processing is complete. Report status to the user (see below).
  }
});

Dodaj funkcję do funkcji extension.yaml w sposób opisany w poprzedniej sekcji.

Stan raportowania

Gdy wszystkie funkcje przetwarzania zostaną ukończone (z pomyślnie lub z błędem), zgłoś stan zadania za pomocą metod interfejsu rozszerzenia w Admin SDK. Użytkownicy mogą zobaczyć ten stan na stronie z informacjami o rozszerzeniu w konsoli Firebase.

Uwaga: raportuj stan tylko raz za każdym razem, gdy obsługujesz zdarzenie cyklu życia. W szczególności, jeśli podzielisz zadanie przetwarzania na wiele wywołań funkcji, nie zgłaszaj stanu po każdym wywołaniu.

Udane ukończenie i błędy niekrytyczne

Aby zgłosić udane zakończenie i błędy niekrytyczne (błędy, które nie powodują nieprawidłowego działania rozszerzenia), użyj metody czasu wykonywania rozszerzenia setProcessingState() w Admin SDK:

import { getExtensions } from "firebase-admin/extensions";

// ...

getExtensions().runtime().setProcessingState(processingState, message);

Możesz ustawić te stany:

Stany niekrytyczne
PROCESSING_COMPLETE	Użyj tego polecenia, aby zgłosić udane wykonanie zadania. Przykład: getExtensions().runtime().setProcessingState( "PROCESSING_COMPLETE", `Backfill complete. Successfully processed ${numSuccess} documents.` );
PROCESSING_WARNING	Użyj tego parametru, aby zgłosić częściowy sukces. Przykład: getExtensions().runtime().setProcessingState( "PROCESSING_WARNING", `Backfill complete. ${numSuccess} documents processed successfully.` + ` ${numFailed} documents failed to process. ${listOfErrors}.` + ` ${instructionsToFixTheProblem}` );
PROCESSING_FAILED	Używaj go do zgłaszania błędów, które uniemożliwiają wykonanie zadania, ale nie powodują, że rozszerzenie staje się bezużyteczne. Przykład: getExtensions().runtime().setProcessingState( "PROCESSING_FAILED", `Backfill failed. ${errorMsg} ${optionalInstructionsToFixTheProblem}.` ); Aby zgłosić błędy, które uniemożliwiają korzystanie z rozszerzenia, zadzwoń pod numer setFatalError().
NONE	Użyj tego, aby wyczyścić stan zadania. Opcjonalnie możesz użyć tego parametru, aby wyczyścić komunikat o stanie z konsoli (np. po upływie określonego czasu od ustawienia parametru PROCESSING_COMPLETE). Przykład: getExtensions().runtime().setProcessingState("NONE");

Błędy krytyczne

Jeśli wystąpi błąd uniemożliwiający działanie rozszerzenia (np. wymagane zadanie konfiguracyjne się nie powiedzie), zgłoś ten błąd krytyczny, korzystając z funkcji setFatalError():

import { getExtensions } from "firebase-admin/extensions";

// ...

getExtensions().runtime().setFatalError(`Post-installation setup failed. ${errorMessage}`);

Dostosowanie kolejki zadań

Jeśli ustawisz właściwość taskQueueTrigger na {}, po zainstalowaniu instancji rozszerzenia zostanie utworzona kolejka Cloud Tasks z ustawieniami domyślnymi. Możesz też dostosować limity równoległości i zachowanie przy ponownym próbie w kolejce zadań, podając określone wartości:

resources:
  - name: myTaskFunction
    type: firebaseextensions.v1beta.function
    description: >-
      Perform a task when triggered by a lifecycle event
    properties:
      location: ${LOCATION}
      taskQueueTrigger:
        rateLimits:
          maxConcurrentDispatches: 1000
          maxDispatchesPerSecond: 500
        retryConfig:
          maxAttempts: 100  # Warning: setting this too low can prevent the function from running
          minBackoffSeconds: 0.1
          maxBackoffSeconds: 3600
          maxDoublings: 16
lifecycleEvents:
  onInstall: 
    function: myTaskFunction
    processingMessage: Resizing your existing images
  onUpdate:
    function: myTaskFunction
    processingMessage: Setting up your extension
  onConfigure:
    function: myOtherTaskFunction
    processingMessage: Setting up your extension

Szczegółowe informacje o tych parametrach znajdziesz w dokumentacji Google Cloud w artykule Konfigurowanie kolejek Cloud Tasks.

Nie próbuj określać parametrów kolejki zadań, przekazując je do funkcji taskQueue(). Te ustawienia są ignorowane na rzecz konfiguracji w extension.yaml i ustawień domyślnych.

Na przykład:

export const myBrokenTaskFunction = functions.tasks
  // DON'T DO THIS IN AN EXTENSION! THESE SETTINGS ARE IGNORED.
  .taskQueue({
    retryConfig: {
      maxAttempts: 5,
      minBackoffSeconds: 60,
    },
    rateLimits: {
      maxConcurrentDispatches: 1000,
      maxDispatchesPerSecond: 10,
    },
  })
  .onDispatch(
    // ...
  );

Właściwość taskQueueTrigger w pliku extension.yaml to jedyny sposób konfigurowania kolejek zadań rozszerzenia.

Przykłady

Oficjalne rozszerzenia storage-resize-images, firestore-bigquery-export i firestore-translate-text używają wszystkich elementów obsługi zdarzeń cyklu życia do uzupełniania danych.