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:

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: {}
```
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.

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.

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.

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.