Instalowanie rozszerzenia Firebase

Możesz zainstalować (i zarządzać) dowolne oficjalne rozszerzenia Firebase za pomocą konsoli Firebase, Firebase interfejsu wiersza poleceń lub automatycznie wygenerowanego pakietu SDK.

Zapoznaj się z różnicami w obsługiwanych działaniach w przypadku każdej metody instalacji.


Instalacja za pomocą automatycznie wygenerowanego pakietu SDK to nowa opcja instalowania rozszerzeń i zarządzania nimi. W tym przypadku używasz interfejsu CLI do automatycznego generowania pakietu Node SDK dla określonej wersji rozszerzenia, który możesz zaimportować jako zwykłą zależność w funkcjach Cloud Functions w JavaScript lub TypeScript.

Ten wygenerowany automatycznie pakiet SDK zawiera:

  • Interfejs reprezentujący parametry rozszerzenia i deklaracje typów większości typów parametrów innych niż podstawowe.
  • funkcja konstruktora, która inicjuje instancję rozszerzenia;
  • Klasa rozszerzenia, która zawiera aktywatory Eventarc dla wszystkich zdarzeń emitowanych przez rozszerzenie.

Po wygenerowaniu pakietu SDK rozszerzenia cała konfiguracja rozszerzenia odbywa się w kodzie.

Korzystanie z tej opcji instalacji może znacznie uprościć zarządzanie wieloma instancjami rozszerzeń, zwłaszcza w projektach, które zawierają funkcje Cloud zdefiniowane poza rozszerzeniami.


Aby instalować rozszerzenia i nimi zarządzać, musisz mieć jedną z tych ról: Właściciel lub Edytujący albo Administrator Firebase.

Aby zainstalować rozszerzenie, projekt musi być objęty abonamentem Blaze (płatność według zużycia zasobów). Instalacja rozszerzenia jest bezpłatna, ale jeśli wykorzystanie usług Firebase lub usług w chmurze, takich jak Cloud Secret Manager, przekroczy poziom bezpłatny, mogą zostać naliczone opłaty.

Zanim zaczniesz

  1. Dodaj Firebase do projektu, jeśli nie korzystasz w nim jeszcze z tej usługi.

  2. Jeśli jeszcze tego nie zrobiono, przenieś projekt na abonament Blaze (płatność według wykorzystania).

  3. Zainstaluj lub zaktualizuj interfejs wiersza poleceń Firebase do najnowszej wersji.

  4. Zapisz identyfikator projektu Firebase lub wcześniej skonfigurowany alias projektu.

Krok 1. Wyświetl szczegółowe informacje o rozszerzeniu

Ten krok jest opcjonalny, ale zdecydowanie zalecany.

Przed zainstalowaniem Firebase Extension zalecamy zapoznanie się ze szczegółowymi informacjami o rozszerzeniu, w tym:

  • Jak działa rozszerzenie, jakie zadania należy wykonać przed jego instalacją i szczegóły dotyczące rozszerzenia.
  • Ogólne informacje identyfikacyjne i opis
  • Czy zadania rozszerzenia wymagają konta rozliczeniowego.
  • Usługi Google (interfejsy API) i role dostępu wymagane do działania
  • Zasoby utworzone na potrzeby rozszerzenia (np. funkcje)
  • Opisy parametrów konfigurowanych przez użytkownika

Aby wyświetlić szczegółowe informacje o rozszerzeniu:

  1. Upewnij się, że środowisko jest skonfigurowane i wybrano rozszerzenie.

  2. Uruchom polecenie extension-info z dowolnego miejsca na komputerze:

    firebase ext:info publisher-id/extension-id

    Argumenty publisher-id i extension-id są wymagane i można je znaleźć na stronie szczegółów przedinstalacyjnych rozszerzenia.

Krok 2. Zainstaluj rozszerzenie

Przed instalacją zapoznaj się z podstawowymi specyfikacjami rozszerzenia (np. włączonymi interfejsami API, utworzonymi zasobami, przyznanym dostępem itp.) oraz wymaganiami dotyczącymi płatności.

Zanim przejdziesz dalej, upewnij się, że skonfigurowano środowisko i wybrano rozszerzenie.

Inicjowanie Cloud Functions dla Firebase

Jeśli zaczynasz nowy projekt lub Twój projekt nie korzysta jeszcze z Cloud Functions for Firebase, uruchom init functions:

cd your-project
firebase init functions

Jako język funkcji wybierz TypeScript lub JavaScript.

Jeśli w projekcie masz już zainicjowane Cloud Functions, sprawdź, czy używasz pakietu firebase-functions w wersji 5.1.0 lub nowszej:

cd your-project/functions
npm upgrade --save firebase-functions

Jeśli używasz ESLint, możesz też wykluczyć wygenerowane pakiety SDK z konfiguracji (.eslintrc.js):

ignorePatterns: [
  "/generated/**/*", // Ignore generated files.
  // ...
],

Generowanie pakietu SDK rozszerzenia

W lokalnym katalogu Firebase uruchom polecenie ext:sdk:install.

firebase ext:sdk:install publisher-id/extension-id@version

Aby na przykład zainstalować wersję 0.1.34 rozszerzenia firestore-send-email:

firebase ext:sdk:install firebase/firestore-send-email@0.1.34

Znaki publisher-id i extension-id są wymagane i można je znaleźć na stronie szczegółów przed instalacją rozszerzenia na extensions.dev. Część @version jest opcjonalna. Jeśli ją pominiesz, narzędzie zainstaluje najnowszą wersję.

Możesz określić 2 opcje:

  • --force: Wykonaj wszystkie te czynności bez dodatkowego potwierdzenia:

    • Automatyczne generowanie pakietu SDK, nawet jeśli został już wygenerowany dla tego samego rozszerzenia i wersji.
    • Zainstaluj automatycznie wygenerowany pakiet SDK w projekcie Cloud Functions Node.

  • --codebase: nazwa bazy kodu, do której chcesz dodać pakiet SDK. Jeśli nie podasz żadnej wartości, polecenie doda pakiet SDK do domyślnej bazy kodu functions.

To polecenie tworzy pakiet Node zawierający automatycznie wygenerowany pakiet SDK rozszerzenia i dodaje go do jednej z baz kodu Cloud Functions w projekcie. W domyślnej bazie kodufunctions pakiet SDK jest zapisywany w tej lokalizacji: 

functions/generated/extensions/publisher-id/extension-id/version

Po wygenerowaniu pakietu SDK polecenie zapyta, czy chcesz go też zainstalować w projekcie Cloud Functions Node. Odpowiedz Tak na ten prompt.

Konfigurowanie instancji rozszerzeń

Aby skonfigurować rozszerzenie, zaimportuj pakiet SDK i dla każdej instancji rozszerzenia, którą chcesz zainstalować, wywołaj funkcję konstruktora, przekazując do niej unikalny w projekcie identyfikator instancji i parametry konfiguracji wymagane przez rozszerzenie.

  1. W źródle Cloud Functions zaimportuj konstruktor za pomocą instrukcji wydrukowanej przez polecenie ext:sdk:install.

    TypeScript

    Jeśli na przykład wygenerujesz pakiet SDK dla rozszerzenia firestore-send-email, instrukcja import będzie wyglądać mniej więcej tak:

    import { firestoreSendEmail } from "@firebase-extensions/firebase-firestore-send-email-sdk";

    Jeśli rozszerzenie wymaga wartości tajnych, takich jak hasła, potrzebujesz też funkcji defineSecret z pakietu SDK Cloud Functions:

    import { defineSecret } from "firebase-functions/params";

    JavaScript

    Jeśli na przykład wygenerujesz pakiet SDK dla rozszerzenia firestore-send-email, instrukcja require będzie wyglądać tak:

    const { firestoreSendEmail } = require("@firebase-extensions/firebase-firestore-send-email-sdk");

    Jeśli rozszerzenie wymaga wartości tajnych, takich jak hasła, potrzebujesz też funkcji defineSecret z pakietu SDK Cloud Functions:

    const { defineSecret } = require('firebase-functions/params');

  2. W przypadku każdej instancji, którą chcesz skonfigurować, wywołaj funkcję konstruktora i wyeksportuj wynik.

    Każdej instancji przypisz unikalny identyfikator zawierający tylko małe litery, cyfry i łączniki.

    TypeScript

    export const firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", {
    SMTP_CONNECTION_URI: "smtps://username@example.com@smtp.example.com:465",
    SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"),
    MAIL_COLLECTION: "mail",
    DEFAULT_FROM: "ExampleCo <username@example.com>",
    TTL_EXPIRE_VALUE: "1",
    TTL_EXPIRE_TYPE: "day",
});

    JavaScript

    exports.firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", {
    SMTP_CONNECTION_URI: "smtps://username@example.com@smtp.example.com:465",
    SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"),
    MAIL_COLLECTION: "mail",
    DEFAULT_FROM: "ExampleCo <username@example.com>",
    TTL_EXPIRE_VALUE: "1",
    TTL_EXPIRE_TYPE: "day",
});

    Pamiętaj, że wartości tajne należy określać za pomocą funkcji defineSecret.

  3. Następnie, aby wdrożyć skonfigurowane rozszerzenia, uruchom to polecenie: 

    firebase deploy --only functions --project=projectId-or-alias

    Obowiązują wszystkie standardowe opcje wdrażania Cloud Functions. Aby na przykład wdrożyć pojedynczą instancję rozszerzenia z określonej bazy kodu: 

    firebase deploy --only functions:codebase:extension-instance-id --project=projectId-or-alias

Krok 3. Dokończ konfigurację po instalacji

Niektóre rozszerzenia wymagają wykonania określonych czynności przed rozpoczęciem korzystania z nich. Instrukcje te znajdziesz na stronie z informacjami po instalacji rozszerzenia na Extensions panelu Firebase konsoli (konkretny link do panelu wyświetla się w terminalu po instalacji).

Instrukcje znajdziesz też w POSTINSTALL.mdpliku w katalogu źródłowym rozszerzenia.

Tworzenie zasobów Firebase

Jeśli rozszerzenie zostało skonfigurowane do korzystania z zasobów Firebase (Cloud Firestorekolekcji, Realtime Database ścieżek, Cloud Storage zasobników), które jeszcze nie istnieją, utwórz je przed użyciem rozszerzenia.

Tworzenie modułów obsługi zdarzeń Eventarc

Niektóre rozszerzenia publikują informacje w Eventarc, gdy podczas wykonywania wystąpią ważne zdarzenia. Jeśli rozszerzenie publikuje zdarzenia, możesz napisać funkcje, które reagują na te zdarzenia za pomocą własnej logiki niestandardowej. Może to być przydatne np. do powiadamiania użytkowników o zakończeniu długotrwałych zadań lub do przetwarzania końcowego danych wyjściowych funkcji rozszerzenia.

Jeśli chcesz zdefiniować procedury obsługi dowolnych zdarzeń emitowanych przez rozszerzenie, możesz to zrobić za pomocą metod wywoływania poszczególnych instancji:

TypeScript

export const firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });

export const emailErrorHandler = firestoreSendEmail_1.onError((event) => {
  // Handle mail errors.
});

JavaScript

exports.firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });

exports.emailErrorHandler = exports.firestoreSendEmail_1.onError((event) => {
  // Handle mail errors.
});

Musisz wyeksportować procedurę obsługi zdarzeń wraz z instancją rozszerzenia.

Po zdefiniowaniu procedury obsługi zdarzeń i po każdej zmianie w niej ponownie wdrażaj zarówno rozszerzenie, jak i procedurę obsługi.

Instalowanie wielu instancji rozszerzenia

Tę samą usługę możesz zainstalować w tym samym projekcie więcej niż raz. Każda zainstalowana instancja może mieć własną, dostosowaną konfigurację i własne zasoby rozszerzeń. Każda zainstalowana instancja jest identyfikowana i przywoływana za pomocą identyfikatora instancji, który jest unikalny w Twoim projekcie.

Wywołaj funkcję konstruktora automatycznie wygenerowanego pakietu SDK raz dla każdej instancji, którą chcesz zainstalować i skonfigurować.

Następne kroki