Rozpocznij tworzenie rozszerzenia

Na tej stronie znajdziesz instrukcje tworzenia prostego rozszerzenia Firebase, które możesz zainstalować w swoich projektach lub udostępnić innym. Ten prosty przykład rozszerzenia Firebase będzie sprawdzać bazę danych Realtime Database pod kątem wiadomości i przekształcać je na wielkie litery.

1. Konfigurowanie środowiska i inicjowanie projektu

Zanim zaczniesz kompilować rozszerzenie, musisz skonfigurować środowisko kompilacji z wymaganymi narzędziami.

  1. Zainstaluj Node.js w wersji 16 lub nowszej. Jedną z możliwości instalacji Node jest użycie nvm (lub nvm-windows).

  2. Zainstaluj lub zaktualizuj wiersz poleceń Firebase do najnowszej wersji. Aby zainstalować lub zaktualizować za pomocą npm, uruchom to polecenie:

    npm install -g firebase-tools

Teraz zainicjuj nowy projekt rozszerzenia za pomocą wiersza poleceń Firebase:

  1. Utwórz katalog dla rozszerzenia i cd:

    mkdir rtdb-uppercase-messages && cd rtdb-uppercase-messages

  2. Uruchom polecenie ext:dev:init w wierszu poleceń Firebase:

    firebase ext:dev:init

    Gdy pojawi się odpowiedni komunikat, wybierz JavaScript jako język funkcji (pamiętaj, że podczas tworzenia własnego rozszerzenia możesz też użyć TypeScript), a na pytanie o instalowanie zależności odpowiedz „tak”. (w przypadku innych opcji zaakceptuj wartości domyślne). To polecenie skonfiguruje szkielet bazy kodu nowego rozszerzenia, od którego możesz rozpocząć tworzenie rozszerzenia.

2. Wypróbuj przykładowe rozszerzenie za pomocą emulatora

Podczas inicjowania nowego katalogu rozszerzeń wiersz poleceń Firebase utworzył prostą przykładową funkcję i katalog integration-tests zawierający pliki potrzebne do uruchamiania rozszerzenia za pomocą zestawu emulatorów Firebase.

Spróbuj uruchomić przykładowe rozszerzenie w emulatorze:

  1. Przejdź do katalogu integration-tests:

    cd functions/integration-tests

  2. Uruchom emulator z projektem demonstracyjnym:

    firebase emulators:start --project=demo-test

    Emulator wczytuje rozszerzenie do wstępnie zdefiniowanego „fikcyjnego” projektu (demo-test). Dotychczasowe rozszerzenie składa się z pojedynczej funkcji wywoływanej przez HTTP (greetTheWorld), która po wywołaniu zwraca wiadomość „hello world”.

  3. Gdy emulator nadal działa, wypróbuj funkcję greetTheWorld rozszerzenia, odwiedzając adres URL wydrukowany po jego uruchomieniu.

    W przeglądarce wyświetli się komunikat „Hello World from greet-the-world”.

  4. Kod źródłowy tej funkcji znajduje się w katalogu functionsrozszerzenia. Otwórz kod źródłowy w wybranym edytorze lub środowisku IDE:

    functions/index.js

    const functions = require("firebase-functions/v1");

exports.greetTheWorld = functions.https.onRequest((req, res) => {
  // Here we reference a user-provided parameter
  // (its value is provided by the user during installation)
  const consumerProvidedGreeting = process.env.GREETING;

  // And here we reference an auto-populated parameter
  // (its value is provided by Firebase after installation)
  const instanceId = process.env.EXT_INSTANCE_ID;

  const greeting = `${consumerProvidedGreeting} World from ${instanceId}`;

  res.send(greeting);
});

  5. Podczas działania emulator automatycznie wczytuje wszystkie zmiany wprowadzone w kodzie funkcji. Spróbuj wprowadzić niewielką zmianę w funkcji greetTheWorld:

    functions/index.js

    const greeting = `${consumerProvidedGreeting} everyone, from ${instanceId}`;

    Zapisz zmiany. Emulator ponownie wczyta kod, a teraz, gdy otworzysz adres URL funkcji, zobaczysz zaktualizowane powitanie.

3. Dodawanie podstawowych informacji do pliku extension.yaml

Gdy skonfigurujesz środowisko programistyczne i uruchomisz emulator rozszerzeń, możesz zacząć pisać własne rozszerzenie.

Jako pierwszy krok edytuj wstępnie zdefiniowane metadane rozszerzenia, aby odzwierciedlały rozszerzenie, które chcesz napisać zamiast greet-the-world. Te metadane są przechowywane w pliku extension.yaml.

  1. Otwórz plik extension.yaml w edytorze i zastąp całą jego zawartość tym kodem:

    name: rtdb-uppercase-messages
version: 0.0.1
specVersion: v1beta  # Firebase Extensions specification version; don't change

# Friendly display name for your extension (~3-5 words)
displayName: Convert messages to upper case

# Brief description of the task your extension performs (~1 sentence)
description: >-
  Converts messages in RTDB to upper case

author:
  authorName: Your Name
  url: https://your-site.example.com

license: Apache-2.0  # Required license

# Public URL for the source code of your extension
sourceUrl: https://github.com/your-name/your-repo

    Zwróć uwagę na konwencję nazewnictwa używaną w polu name: oficjalne rozszerzenia Firebase mają nazwy z prefiksem wskazującym główny produkt Firebase, z którym działają, a następnie opis działania rozszerzenia. W swoich rozszerzeniach używaj tej samej konwencji.

  2. Ponieważ zmieniłeś nazwę rozszerzenia, musisz też zaktualizować konfigurację emulatora, podając nową nazwę:

    1. W pliku functions/integration-tests/firebase.json zmień greet-the-world na rtdb-uppercase-messages.
    2. Zmień nazwę functions/integration-tests/extensions/greet-the-world.env na functions/integration-tests/extensions/rtdb-uppercase-messages.env.

W kodzie rozszerzenia nadal znajdują się pozostałości rozszerzenia greet-the-world, ale na razie nie zmieniaj ich. Zaktualizujesz je w kolejnych sekcjach.

4. Pisanie funkcji w Cloud Functions i deklarowanie jej jako zasobu rozszerzenia

Teraz możesz zacząć pisać kod. W tym kroku napiszesz funkcję Cloud Function, która wykonuje główne zadanie rozszerzenia, czyli sprawdza bazę danych w czasie rzeczywistym pod kątem wiadomości i konwertuje je na wielkie litery.

  1. Otwórz kod źródłowy funkcji rozszerzenia (w katalogu functions rozszerzenia) w wybranym edytorze lub środowisku IDE. Zamień zawartość pliku na tę:

    functions/index.js

    import { database, logger } from "firebase-functions/v1";

const app = initializeApp();

// Listens for new messages added to /messages/{pushId}/original and creates an
// uppercase version of the message to /messages/{pushId}/uppercase
// for all databases in 'us-central1'
export const makeuppercase = database
  .ref("/messages/{pushId}/uppercase")
  .onCreate(async (snapshot, context) => {
    // Grab the current value of what was written to the Realtime Database.
    const original = snapshot.val();

    // Convert it to upper case.
    logger.log("Uppercasing", context.params.pushId, original);
    const uppercase = original.toUpperCase();

    // Setting an "uppercase" sibling in the Realtime Database.
    const upperRef = snapshot.ref.parent.child("upper");
    await upperRef.set(uppercase);
});

    Stara funkcja, którą została zastąpiona, była funkcją aktywowaną przez HTTP, która działała po uzyskaniu dostępu do punktu końcowego HTTP. Nowa funkcja jest wywoływana przez zdarzenia bazy danych w czasie rzeczywistym: sprawdza ona nowe elementy na określonym ścieżce i gdy wykryje nowy element, zapisuje z powrotem w bazie danych jego wartość w wersji z dużymi literami.

    Ten nowy plik używa składnia modułów ECMAScript (import i export) zamiast CommonJS (require). Aby używać modułów ES w Node, określ "type": "module" w functions/package.json:

    {
  "name": "rtdb-uppercase-messages",
  "main": "index.js",
  "type": "module",
  …
}

  2. Każda funkcja w rozszerzeniu musi być zadeklarowana w pliku extension.yaml. Przykładowe rozszerzenie deklaruje greetTheWorld jako jedyną funkcję usługi w chmurze. Teraz, gdy zastąpisz ją funkcją makeuppercase, musisz też zaktualizować jej deklarację.

    Otwórz extension.yaml i dodaj pole resources:

    resources:
  - name: makeuppercase
    type: firebaseextensions.v1beta.function
    properties:
      eventTrigger:
        eventType: providers/google.firebase.database/eventTypes/ref.create
        # DATABASE_INSTANCE (project's default instance) is an auto-populated
        # parameter value. You can also specify an instance.
        resource: projects/_/instances/${DATABASE_INSTANCE}/refs/messages/{pushId}/original
      runtime: "nodejs18"

  3. Ponieważ rozszerzenie używa teraz Bazy danych czasu rzeczywistego jako wyzwalacza, musisz zaktualizować konfigurację emulatora, aby uruchamiać emulator Bazy danych czasu rzeczywistego obok emulatora Cloud Functions:

    1. Jeśli emulowany system nadal działa, zatrzymaj go, naciskając Ctrl+C.

    2. W katalogu functions/integration-tests uruchom to polecenie:

      firebase init emulators

      Gdy pojawi się taka prośba, pomiń konfigurowanie projektu domyślnego, a potem wybierz emulatory funkcji i bazy danych. Zaakceptuj domyślne porty i zezwól narzędziu konfiguracyjnemu na pobranie wymaganych plików.

    3. Uruchom ponownie emulator:

      firebase emulators:start --project=demo-test

  4. Wypróbuj zaktualizowane rozszerzenie:

    1. Otwórz interfejs emulatora bazy danych, korzystając z linku wydrukowanego przez emulator podczas jego uruchamiania.

    2. Zmień węzeł główny bazy danych:

      • Pole: messages
      • Typ: json
      • Wartość: {"11": {"original": "recipe"}}

      Jeśli wszystko jest prawidłowo skonfigurowane, po zapisaniu zmian w bazie danych funkcja makeuppercase rozszerzenia powinna zostać uruchomiona i dodać do wiadomości 11 rekord podrzędny z treścią "upper": "RECIPE". Aby sprawdzić oczekiwane wyniki, zajrzyj do logów i kart bazy danych w interfejsie emulatora.

    3. Spróbuj dodać więcej elementów podrzędnych do węzła messages ({"original":"any text"}). Za każdym razem, gdy dodasz nowy rekord, rozszerzenie powinno dodać pole uppercase zawierające wielką literę zawartości pola original.

Masz teraz kompletne, choć proste, rozszerzenie, które działa na instancji RTDB. W kolejnych sekcjach dodasz do tego rozszerzenia kilka dodatkowych funkcji. Następnie przygotujesz rozszerzenie do dystrybucji, a na koniec dowiesz się, jak opublikować je w Centrum rozszerzeń.

5. Deklarowanie interfejsów API i ról

Firebase przyznaje każdej instancji zainstalowanego rozszerzenia ograniczony dostęp do projektu i jego danych za pomocą konta usługi na potrzeby danej instancji. Każde konto ma minimalny zestaw uprawnień potrzebnych do działania. Z tego powodu musisz wyraźnie zadeklarować wszystkie role uprawnień wymagane przez Twoje rozszerzenie. Gdy użytkownicy zainstalują Twoje rozszerzenie, Firebase utworzy konto usługi z tymi rolami i użyje go do uruchomienia rozszerzenia.

Aby wywołać zdarzenia usługi, nie musisz deklarować ról, ale musisz zadeklarować rolę, aby w inny sposób z nią współpracować. Funkcja dodana w ostatnim kroku zapisuje dane w danych w czasie rzeczywistym, więc musisz dodać do funkcji extension.yaml tę deklarację:

roles:
  - role: firebasedatabase.admin
    reason: Allows the extension to write to RTDB.

Podobnie w polu apis deklarujesz interfejsy API Google, których używa rozszerzenie. Gdy użytkownicy zainstalują Twoje rozszerzenie, zostaną poproszeni o automatyczne włączenie tych interfejsów API w swoim projekcie. Jest to zwykle konieczne tylko w przypadku interfejsów API Google innych niż Firebase. Nie jest to wymagane w tym przewodniku.

6. Definiowanie parametrów konfigurowalnych przez użytkownika

Funkcja utworzona w poprzednich 2 krokach sprawdzała określoną lokalizację RTDB pod kątem przychodzących wiadomości. Czasami obserwowanie konkretnej lokalizacji jest tym, czego naprawdę potrzebujesz, np. gdy rozszerzenie działa na podstawie struktury bazy danych, której używasz wyłącznie do rozszerzenia. W większości przypadków warto jednak umożliwić użytkownikom instalującym rozszerzenie w swoich projektach konfigurowanie tych wartości. Dzięki temu użytkownicy mogą korzystać z Twojego rozszerzenia w połączeniu z dotychczasową konfiguracją bazy danych.

Umożliw użytkownikowi konfigurowanie ścieżki, którą rozszerzenie ma sprawdzać pod kątem nowych wiadomości:

  1. W pliku extension.yaml dodaj sekcję params:

    - param: MESSAGE_PATH
  label: Message path
  description: >-
    What is the path at which the original text of a message can be found?
  type: string
  default: /messages/{pushId}/original
  required: true
  immutable: false

    Określa nowy parametr ciągu znaków, który użytkownicy będą musieli ustawić podczas instalowania rozszerzenia.

  2. W pliku extension.yaml wróć do deklaracji makeuppercase i zmodyfikuj pole resource w ten sposób:

    resource: projects/_/instances/${DATABASE_INSTANCE}/refs/${param:MESSAGE_PATH}

    Element ${param:MESSAGE_PATH} to odwołanie do właśnie zdefiniowanego parametru. Gdy rozszerzenie zostanie uruchomione, ten token zostanie zastąpiony wartością skonfigurowaną przez użytkownika dla tego parametru, co spowoduje, że funkcja makeuppercase będzie nasłuchiwać ścieżki określonej przez użytkownika. Możesz używać tej składni, aby odwoływać się do dowolnego parametru zdefiniowanego przez użytkownika w dowolnym miejscu w pliku extension.yaml (i w pliku POSTINSTALL.md – więcej informacji na ten temat znajdziesz później).

  3. Parametry zdefiniowane przez użytkownika możesz też uzyskać z poziomu kodu funkcji.

    W funkcji napisanej w poprzedniej sekcji ścieżka do pliku watch została zakodowana na stałe. Zmień definicję reguły, aby odwoływała się do wartości zdefiniowanej przez użytkownika:

    functions/index.js

    export const makeuppercase = database.ref(process.env.MESSAGE_PATH).onCreate

    Pamiętaj, że w przypadku Rozszerzeń w Firebase ta zmiana ma na celu wyłącznie ułatwienie dokumentacji: gdy funkcja Cloud Functions jest wdrażana jako część rozszerzenia, używa definicji aktywatora z pliku extension.yaml i ignoruje wartość określoną w definicji funkcji. Mimo to warto zanotować w kodzie, skąd pochodzi ta wartość.

  4. Możesz być rozczarowany, że zmiana kodu nie ma wpływu na działanie w czasie wykonywania. Ważną lekcją jest jednak to, że w kodzie funkcji możesz uzyskać dostęp do dowolnego parametru zdefiniowanego przez użytkownika i używać go jako zwykłej wartości w logice funkcji. Aby umożliwić korzystanie z tej funkcji, dodaj to polecenie logowania, aby pokazać, że rzeczywiście uzyskujesz dostęp do wartości zdefiniowanej przez użytkownika:

    functions/index.js

    export const makeuppercase = database.ref(process.env.MESSAGE_PATH).onCreate(
  async (snapshot, context) => {
    logger.log("Found new message at ", snapshot.ref);

    // Grab the current value of what was written to the Realtime Database.
    ...

  5. Zwykle użytkownicy otrzymują prośbę o podanie wartości parametrów podczas instalowania rozszerzenia. Jednak gdy używasz emulatora do testowania i programowania, pomijasz proces instalacji, więc zamiast tego podajesz wartości parametrów zdefiniowanych przez użytkownika za pomocą pliku env.

    Otwórz plik functions/integration-tests/extensions/rtdb-uppercase-messages.env i zamień definicję GREETING na tę:

    MESSAGE_PATH=/msgs/{pushId}/original

    Zwróć uwagę, że powyższa ścieżka różni się od ścieżki domyślnej i ścieżki zdefiniowanej wcześniej. Ma to na celu potwierdzenie, że gdy spróbujesz użyć zaktualizowanego rozszerzenia, Twoja definicja zacznie obowiązywać.

  6. Teraz uruchom ponownie emulator i ponownie otwórz interfejs emulatora bazy danych.

    Zmień węzeł względny bazy danych, korzystając ze ścieżki zdefiniowanej powyżej:

    • Pole: msgs
    • Typ: json
    • Wartość: {"11": {"original": "recipe"}}

    Gdy zapiszesz zmiany w bazie danych, funkcja makeuppercase rozszerzenia powinna zostać uruchomiona tak jak wcześniej, ale teraz powinna też wydrukować parametr zdefiniowany przez użytkownika w logu konsoli.

7. Dostarczanie uchwytów zdarzeń na potrzeby logiki zdefiniowanej przez użytkownika

Jako autor rozszerzenia wiesz już, jak usługa Firebase może wywołać logikę udostępnioną przez rozszerzenie: tworzenie nowych rekordów w Baza danych czasu rzeczywistym powoduje wywołanie funkcji makeuppercase. Twoje rozszerzenie może mieć analogiczne relacje z użytkownikami, którzy je zainstalowali: rozszerzenie może aktywować logikę zdefiniowaną przez użytkownika.

Rozszerzenie może zawierać punkty synchronizacji, punkty asynchroniczne lub oba te elementy. Zaczepy synchroniczne umożliwiają użytkownikom wykonywanie zadań, które blokują wykonanie jednej z funkcji rozszerzenia. Może to być przydatne, np. gdy chcesz umożliwić użytkownikom niestandardowe wstępne przetwarzanie danych przed działaniem rozszerzenia.

W tym przewodniku dowiesz się, jak dodać do rozszerzenia asynchroniczny element wywołujący, który umożliwi użytkownikom definiowanie własnych kroków przetwarzania, które mają być wykonywane po zapisaniu przez rozszerzenie wiadomości w wielkich literach w Realtime Database. Zaczepy asynchroniczne używają Eventarc do wywoływania funkcji zdefiniowanych przez użytkownika. Rozszerzenia deklarują typy emitowanych zdarzeń, a użytkownicy, gdy je instalują, wybierają te, które ich interesują. Jeśli wybiorą co najmniej 1 zdarzenie, Firebase zarezerwuje kanał Eventarc dla rozszerzenia w ramach procesu instalacji. Użytkownicy mogą następnie wdrażać własne funkcje w chmurze, które nasłuchują na tym kanale i uruchamiają się, gdy rozszerzenie opublikuje nowe zdarzenia.

Aby dodać asynchroniczny element wywoławczy:

  1. W pliku extension.yaml dodaj tę sekcję, która deklaruje jeden typ zdarzenia emitowany przez rozszerzenie:

    events:
  - type: test-publisher.rtdb-uppercase-messages.v1.complete
    description: >-
      Occurs when message uppercasing completes. The event subject will contain
      the RTDB URL of the uppercase message.

    Typy zdarzeń muszą być unikalne. Aby zapewnić ich unikalność, zawsze nadawaj im nazwy w tym formacie: <publisher-id>.<extension-id>.<version>.<description>. (nie masz jeszcze identyfikatora wydawcy, więc na razie użyj wartości test-publisher).

  2. Na końcu funkcji makeuppercase dodaj kod, który publikuje zdarzenie o właśnie zadeklarowanym typie:

    functions/index.js

    // Import the Eventarc library:
import { initializeApp } from "firebase-admin/app";
import { getEventarc } from "firebase-admin/eventarc";

const app = initializeApp();

// In makeuppercase, after upperRef.set(uppercase), add:

// 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,
  });

// If events are enabled, publish a `complete` event to the configured
// channel.
eventChannel &&
  eventChannel.publish({
    type: "test-publisher.rtdb-uppercase-messages.v1.complete",
    subject: upperRef.toString(),
    data: {
      "original": original,
      "uppercase": uppercase,
    },
  });

    Ten przykładowy kod korzysta z tego, że zmienna środowiskowa EVENTARC_CHANNEL jest zdefiniowana tylko wtedy, gdy użytkownik włączył co najmniej 1 typ zdarzenia. Jeśli zmienna EVENTARC_CHANNEL nie jest zdefiniowana, kod nie próbuje publikować żadnych zdarzeń.

    Do wydarzenia Eventarc możesz dołączyć dodatkowe informacje. W przykładzie powyżej zdarzenie ma pole subject, które zawiera odwołanie do nowo utworzonej wartości, oraz data, które zawiera oryginalne wiadomości i wiadomości z wielkimi literami. Funkcje zdefiniowane przez użytkownika, które uruchamiają zdarzenie, mogą korzystać z tych informacji.

  3. Zwykle zmienne środowiska EVENTARC_CHANNEL i EXT_SELECTED_EVENTS są definiowane na podstawie opcji wybranych przez użytkownika podczas instalacji. Aby przetestować emulator, ręcznie zdefiniuj te zmienne w pliku rtdb-uppercase-messages.env:

    EVENTARC_CHANNEL=locations/us-central1/channels/firebase
EXT_SELECTED_EVENTS=test-publisher.rtdb-uppercase-messages.v1.complete

W tym momencie wykonałeś/wykonałaś już czynności potrzebne do dodania do rozszerzenia asynchronicznego punktu wywołania zdarzenia.

Aby wypróbować właśnie wdrożone nowe rozszerzenie, w kolejnych kilku krokach wciel się w rolę użytkownika instalującego rozszerzenie:

  1. W katalogu functions/integration-tests zainicjuj nowy projekt Firebase:

    firebase init functions

    Gdy pojawi się taka prośba, zrezygnuj z konfigurowania projektu domyślnego, wybierz JavaScript jako język Cloud Functions i zainstaluj wymagane zależności. Ten projekt reprezentuje projekt użytkownika, w którym zainstalowano Twoje rozszerzenie.

  2. Otwórz plik integration-tests/functions/index.js i wklej ten kod:

    import { logger } from "firebase-functions/v1";
import { onCustomEventPublished } from "firebase-functions/v2/eventarc";

import { initializeApp } from "firebase-admin/app";
import { getDatabase } from "firebase-admin/database";

const app = initializeApp();

export const extraemphasis = onCustomEventPublished(
  "test-publisher.rtdb-uppercase-messages.v1.complete",
  async (event) => {
    logger.info("Received makeuppercase completed event", event);

    const refUrl = event.subject;
    const ref = getDatabase().refFromURL(refUrl);
    const upper = (await ref.get()).val();
    return ref.set(`${upper}!!!`);
  }
);

    Oto przykład funkcji do dalszego przetwarzania, którą użytkownik może napisać. W tym przypadku funkcja nasłuchuje, czy rozszerzenie opublikowało zdarzenie complete, a gdy tak się stanie, dodaje do wiadomości, która zostanie zapisana wielkimi literami, 3 znaki wykrzyknika.

  3. Uruchom ponownie emulator. Emulator wczyta funkcje rozszerzenia, a także funkcję przetwarzania wtórnego zdefiniowaną przez „użytkownika”.

  4. Otwórz interfejs emulatora bazy danych i edytuj węzeł główny bazy danych, korzystając z określonej powyżej ścieżki:

    • Pole:msgs
    • Typ: json
    • Wartość: {"11": {"original": "recipe"}}

    Gdy zapiszesz zmiany w bazie danych, funkcja makeuppercase rozszerzenia i funkcja extraemphasis użytkownika powinny być wywoływane kolejno, co spowoduje, że pole upper otrzyma wartość RECIPE!!!.

8. Dodawanie modułów obsługi zdarzeń cyklu życia

Dotychczasowe rozszerzenie przetwarza wiadomości w miarę ich tworzenia. Co jednak, jeśli użytkownicy mają już bazę danych wiadomości, gdy instalują rozszerzenie? Rozszerzenia Firebase mają funkcję elementów wywołujących zdarzenia cyklu życia, której możesz używać do uruchamiania działań podczas instalowania, aktualizowania lub rekonfigurowania rozszerzenia. W tej sekcji użyjesz haka zdarzenia cyklu życia, aby uzupełnić istniejącą bazę danych wiadomości projektu o wiadomości z wielkimi literami, gdy użytkownik zainstaluje Twoje rozszerzenie.

Rozszerzenia Firebase używają Listy zadań Cloud do uruchamiania obsługi zdarzeń cyklu życia. Moduł obsługi zdarzeń definiujesz za pomocą funkcji Cloud Functions. Gdy instancja rozszerzenia dotrze do jednego z obsługiwanych zdarzeń cyklu życia, a jeśli zdefiniujesz moduł obsługi, zostanie on dodany do kolejki zadań w Cloud Tasks. Następnie Cloud Tasks asynchronicznie wykona interfejs obsługi. Podczas działania modułu obsługi zdarzeń cyklu życia konsola Firebase informuje użytkownika, że instancja rozszerzenia ma w toku zadanie przetwarzania. Funkcja obsługi musi przekazać użytkownikowi informacje o bieżącym stanie i zakończeniu zadania.

Aby dodać moduł obsługi zdarzenia cyklu życia, który uzupełnia istniejące wiadomości:

  1. Zdefiniuj nową funkcję w Cloud Functions, która jest wywoływana przez zdarzenia kolejki zadań:

    functions/index.js

    import { tasks } from "firebase-functions/v1";

import { getDatabase } from "firebase-admin/database";
import { getExtensions } from "firebase-admin/extensions";
import { getFunctions } from "firebase-admin/functions";

export const backfilldata = tasks.taskQueue().onDispatch(async () => {
  const batch = await getDatabase()
    .ref(process.env.MESSAGE_PATH)
    .parent.parent.orderByChild("upper")
    .limitToFirst(20)
    .get();

  const promises = [];
  for (const key in batch.val()) {
    const msg = batch.child(key);
    if (msg.hasChild("original") && !msg.hasChild("upper")) {
      const upper = msg.child("original").val().toUpperCase();
      promises.push(msg.child("upper").ref.set(upper));
    }
  }
  await Promise.all(promises);

  if (promises.length > 0) {
    const queue = getFunctions().taskQueue(
      "backfilldata",
      process.env.EXT_INSTANCE_ID
    );
    return queue.enqueue({});
  } else {
    return getExtensions()
      .runtime()
      .setProcessingState("PROCESSING_COMPLETE", "Backfill complete.");
  }
});

    Zwróć uwagę, że funkcja przetwarza tylko kilka rekordów, zanim zostanie dodana z powrotem do kolejki zadań. Jest to powszechnie stosowana strategia postępowania z zadaniami przetwarzania, które nie mogą zostać ukończone w okresie limitu czasu funkcji Cloud Function. Ponieważ nie możesz przewidzieć, ile wiadomości użytkownik może mieć już w swojej bazie danych, gdy zainstaluje Twoje rozszerzenie, ta strategia jest odpowiednia.

  2. W pliku extension.yaml zadeklaruj funkcję wypełniania jako zasób rozszerzenia o właściwości taskQueueTrigger:

    resources:
  - name: makeuppercase
    ...
  - name: backfilldata
    type: firebaseextensions.v1beta.function
    description: >-
      Backfill existing messages with uppercase versions
    properties:
      runtime: "nodejs18"
      taskQueueTrigger: {}

    Następnie zadeklaruj funkcję jako obsługę zdarzenia cyklu życia onInstall:

    lifecycleEvents:
  onInstall:
    function: backfilldata
    processingMessage: Uppercasing existing messages

  3. Chociaż uzupełnianie istniejących wiadomości jest przydatne, rozszerzenie może działać bez niego. W takich sytuacjach należy ustawić opcjonalne uruchamianie metod obsługi zdarzeń cyklu życia.

    Aby to zrobić, dodaj nowy parametr do extension.yaml:

    - param: DO_BACKFILL
  label: Backfill existing messages
  description: >-
    Generate uppercase versions of existing messages?
  type: select
  required: true
  options:
    - label: Yes
      value: true
    - label: No
      value: false

    Następnie na początku funkcji uzupełniania danych sprawdź wartość parametru DO_BACKFILL i w razie potrzeby zakończ ją wcześniej:

    functions/index.js

    if (!process.env.DO_BACKFILL) {
  return getExtensions()
    .runtime()
    .setProcessingState("PROCESSING_COMPLETE", "Backfill skipped.");
}

Po wprowadzeniu tych zmian rozszerzenie będzie konwertować istniejące wiadomości na wielkie litery po zainstalowaniu.

Do tej pory używasz emulatora rozszerzeń do tworzenia rozszerzenia i testowania wprowadzanych zmian. Jednak emulator rozszerzeń pomija proces instalacji, więc aby przetestować swojego onInstall, musisz zainstalować rozszerzenie w rzeczywistym projekcie. To dobrze, bo dzięki dodaniu tej funkcji automatycznego uzupełniania samouczek jest już gotowy pod względem kodu.

9. Wdrażanie w rzeczywistym projekcie Firebase

Chociaż emulator rozszerzeń to świetne narzędzie do szybkiego iterowania rozszerzenia podczas tworzenia, w pewnym momencie warto wypróbować go w rzeczywistym projekcie.

Aby to zrobić, najpierw utwórz nowy projekt z kilkoma włączonymi usługami:

  1. W konsoli Firebase dodaj nowy projekt.
  2. Przenieś projekt na abonament Blaze z płatnościami według wykorzystania. Cloud Functions for Firebase wymaga, aby Twój projekt miał konto rozliczeniowe, więc do zainstalowania rozszerzenia musisz też mieć konto rozliczeniowe.
  3. W nowym projekcie włącz Bazę danych czasu rzeczywistego.
  4. Chcesz przetestować, czy rozszerzenie może uzupełnić istniejące dane po zainstalowaniu, więc importujesz do instancji bazy danych w czasie rzeczywistym przykładowe dane:
    1. Pobierz dane RTDB na potrzeby inicjalizacji.
    2. Na stronie Bazy danych w czasie rzeczywistym w konsoli Firebase kliknij (Więcej) > Importuj plik JSON i wybierz pobrany właśnie plik.

  5. Aby umożliwić funkcji uzupełniania danych korzystanie z metody orderByChild, skonfiguruj bazę danych tak, aby indeksowała wiadomości według wartości upper:

    {
  "rules": {
    ".read": false,
    ".write": false,
    "messages": {
      ".indexOn": "upper"
    }
  }
}

Teraz zainstaluj rozszerzenie z źródła lokalnego w nowym projekcie:

  1. Utwórz nowy katalog dla projektu Firebase:

    mkdir ~/extensions-live-test && cd ~/extensions-live-test

  2. Inicjalizacja projektu Firebase w katalogu roboczym:

    firebase init database

    Gdy pojawi się taka prośba, wybierz utworzony przez siebie projekt.

  3. Zainstaluj rozszerzenie w lokalnym projekcie Firebase:

    firebase ext:install /path/to/rtdb-uppercase-messages

    Tutaj możesz zobaczyć, jak wygląda proces instalacji rozszerzenia za pomocą narzędzia wiersza poleceń Firebase. Gdy narzędzie do konfiguracji zapyta, czy chcesz uzupełnić istniejącą bazę danych, wybierz „Tak”.

    Po wybraniu opcji konfiguracji narzędzie wiersza poleceń Firebase zapisze konfigurację w katalogu extensions, a lokalizację źródła rozszerzenia w pliku firebase.json. Te 2 rekordy są nazywane pliku manifestu rozszerzeń. Użytkownicy mogą używać pliku manifestu do zapisywania konfiguracji rozszerzeń i wdrażania jej w różnych projektach.

  4. Wprowadź konfigurację rozszerzenia do projektu na żywo:

    firebase deploy --only extensions

Jeśli wszystko pójdzie dobrze, interfejs wiersza poleceń Firebase powinien przesłać rozszerzenie do projektu i je zainstalować. Po zakończeniu instalacji rozpocznie się zadanie uzupełniania danych, a po kilku minutach baza danych zostanie zaktualizowana o wiadomości z dużymi literami. Dodaj do bazy danych wiadomości kilka nowych węzłów i upewnij się, że rozszerzenie działa również w przypadku nowych wiadomości.

10. Tworzenie dokumentacji

Zanim udostępnisz rozszerzenie użytkownikom, upewnij się, że dostarczasz wystarczającą dokumentację, aby mogli je zainstalować.

Podczas inicjowania projektu rozszerzenia wiersz poleceń Firebase utworzył wersje zastępcze wymaganej dokumentacji. Zaktualizuj te pliki, aby dokładnie odzwierciedlały utworzone przez Ciebie rozszerzenie.

extension.yaml

Podczas tworzenia tego rozszerzenia plik ten został już zaktualizowany, więc obecnie nie musisz go aktualizować.

Nie zapominaj jednak o tym, jak ważna jest dokumentacja zawarta w tym pliku. Oprócz najważniejszych informacji identyfikujących rozszerzenie (nazwa, opis, autor, oficjalna lokalizacja repozytorium) plik extension.yaml zawiera dokumentację dla użytkownika dotyczącą każdego zasobu i parametru, który można skonfigurować. Te informacje są widoczne dla użytkowników w konsoli Firebase, Centrum rozszerzeń i interfejsie wiersza poleceń Firebase.

PREINSTALL.md

W tym pliku podaj informacje, których użytkownik potrzebuje przed zainstalowaniem rozszerzenia: krótko opisz, do czego służy rozszerzenie, wyjaśnij, jakie są wymagania wstępne, i podaj informacje o konsekwencjach rozliczeniowych zainstalowania rozszerzenia. Jeśli masz stronę internetową z dodatkowymi informacjami, możesz dodać do niej link.

Tekst tego pliku jest wyświetlany użytkownikowi w Centrum rozszerzeń i za pomocą polecenia firebase ext:info.

Oto przykład pliku PREINSTALL:

Use this extension to automatically convert strings to upper case when added to
a specified Realtime Database path.

This extension expects a database layout like the following example:

    "messages": {
      MESSAGE_ID: {
        "original": MESSAGE_TEXT
      },
      MESSAGE_ID: {
        "original": MESSAGE_TEXT
      },
    }

When you create new string records, this extension creates a new sibling record
with upper-cased text:

    MESSAGE_ID: {
      "original": MESSAGE_TEXT,
      "upper": UPPERCASE_MESSAGE_TEXT,
    }

#### Additional setup

Before installing this extension, make sure that you've
[set up Realtime Database](https://firebase.google.com/docs/database/quickstart)
in your Firebase project.

#### Billing

To install an extension, your project must be on the
[Blaze (pay as you go) plan](https://firebase.google.com/pricing).

- This extension uses other Firebase and Google Cloud Platform services, which
  have associated charges if you exceed the service's no-cost tier:
  - Realtime Database
  - Cloud Functions (Node.js 10+ runtime)
    [See FAQs](https://firebase.google.com/support/faq#extensions-pricing)
- If you enable events,
  [Eventarc fees apply](https://cloud.google.com/eventarc/pricing).

POSTINSTALL.md

Ten plik zawiera informacje przydatne dla użytkowników po zainstalowaniu rozszerzenia, np. kolejne kroki konfiguracji, przykład działania rozszerzenia itp.

Treść pliku POSTINSTALL.md jest wyświetlana w konsoli Firebase po skonfigurowaniu i zainstalowaniu rozszerzenia. W tym pliku możesz odwoływać się do parametrów użytkownika, które zostaną zastąpione skonfigurowanymi wartościami.

Oto przykładowy plik po instalacji rozszerzenia samouczka:

### See it in action

You can test out this extension right away!

1.  Go to your
    [Realtime Database dashboard](https://console.firebase.google.com/project/${param:PROJECT_ID}/database/${param:PROJECT_ID}/data) in the Firebase console.

1.  Add a message string to a path that matches the pattern `${param:MESSAGE_PATH}`.

1.  In a few seconds, you'll see a sibling node named `upper` that contains the
    message in upper case.

### Using the extension

We recommend adding data by pushing -- for example,
`firebase.database().ref().push()` -- because pushing assigns an automatically
generated ID to the node in the database. During retrieval, these nodes are
guaranteed to be ordered by the time they were added. Learn more about reading
and writing data for your platform (iOS, Android, or Web) in the
[Realtime Database documentation](https://firebase.google.com/docs/database/).

### Monitoring

As a best practice, you can
[monitor the activity](https://firebase.google.com/docs/extensions/manage-installed-extensions#monitor)
of your installed extension, including checks on its health, usage, and logs.

CHANGELOG.md

W pliku CHANGELOG.md należy też udokumentować zmiany wprowadzone między wersjami rozszerzenia.

Ponieważ przykładowe rozszerzenie nie zostało jeszcze nigdy opublikowane, dziennik zmian zawiera tylko 1 pozycję:

## Version 0.0.1

Initial release of the _Convert messages to upper case_ extension.

README.md

Większość rozszerzeń zawiera też plik readme, który jest przydatny dla użytkowników odwiedzających repozytorium rozszerzenia. Możesz go napisać ręcznie lub wygenerować za pomocą polecenia.

Na potrzeby tego przewodnika pomiń pisanie pliku readme.

Dodatkowa dokumentacja

Omówiona powyżej dokumentacja to minimalny zestaw dokumentów, które należy udostępnić użytkownikom. Aby użytkownicy mogli z nich korzystać, wiele rozszerzeń wymaga bardziej szczegółowej dokumentacji. W takim przypadku należy napisać dodatkową dokumentację i opublikować ją w miejscu, do którego użytkownicy będą mogli się odnieść.

Na potrzeby tego przewodnika pomiń tworzenie obszerniejszej dokumentacji.

11. Publikowanie w Centrum rozszerzeń

Teraz, gdy kod rozszerzenia jest gotowy i opracowany, możesz udostępnić je innym użytkownikom w Centrum rozszerzeń. Ponieważ to tylko samouczek, nie musisz tego robić. Zacznij pisać własne rozszerzenie, korzystając z informacji zawartych w tej dokumentacji i w pozostałych dokumentach dotyczących rozszerzeń wydawcy Firebase. Możesz też zapoznać się ze źródłem oficjalnych rozszerzeń Firebase.

Gdy będziesz gotowy/gotowa do opublikowania swojej pracy w Extensions Hub, wykonaj te czynności:

  1. Jeśli publikujesz pierwsze rozszerzenie, zarejestruj się jako wydawca rozszerzeń. Gdy zarejestrujesz się jako wydawca rozszerzeń, utworzysz identyfikator wydawcy, który pozwoli użytkownikom szybko zidentyfikować Cię jako autora rozszerzeń.

  2. Umieść kod źródłowy rozszerzenia w publicznie dostępnej lokalizacji. Gdy Twój kod jest dostępny z weryfikowalnego źródła, Firebase może opublikować rozszerzenie bezpośrednio z tego miejsca. Dzięki temu możesz mieć pewność, że publikujesz aktualną wersję rozszerzenia, a użytkownicy mogą sprawdzić kod, który instalują w swoich projektach.

    Obecnie oznacza to udostępnienie rozszerzenia w publicznym repozytorium GitHub.

  3. Prześlij rozszerzenie do Centrum rozszerzeń za pomocą polecenia firebase ext:dev:upload.

  4. W konsoli Firebase otwórz panel wydawcy, znajdź właśnie przesłane rozszerzenie i kliknij „Opublikuj w Centrum rozszerzeń”. W tym celu nasz zespół musi sprawdzić Twoją prośbę, co może potrwać kilka dni. Po zatwierdzeniu rozszerzenie zostanie opublikowane w Centrum rozszerzeń. Jeśli Twoja prośba zostanie odrzucona, otrzymasz wiadomość z wyjaśnieniem przyczyny. Następnie możesz rozwiązać zgłoszone problemy i ponownie przesłać prośbę do sprawdzenia.