Instalowanie rozszerzenia Firebase

Możesz instalować (i zarządzać) dowolnymi oficjalnymi rozszerzeniami Firebase za pomocą konsoli Firebase, wiersza poleceń Firebase (interfejsu wiersza poleceń) lub automatycznie wygenerowanego pakietu SDK.

Sprawdź różnice w obsługiwanych działaniach w przypadku każdej metody instalacji.


Instalacja za pomocą wygenerowanego automatycznie pakietu SDK to nowa opcja instalowania i zarządzania rozszerzeniami. W przypadku tej opcji używasz interfejsu wiersza poleceń, aby automatycznie wygenerować pakiet Node SDK dla konkretnej wersji rozszerzenia. Możesz go zaimportować jako zwykłe zależności w funkcjach JavaScript lub TypeScript Cloud Functions.

Ten automatycznie wygenerowany pakiet SDK zawiera:

  • Interfejs reprezentujący parametry rozszerzenia oraz deklaracje typów w przypadku większości typów parametrów niepierwotnych.
  • Funkcja konstruktora, która inicjuje wystąpienie rozszerzenia.
  • Klasa rozszerzenia, która zawiera uruchamiane przez Eventarc selektory 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 przypadku projektów zawierających funkcje Cloud Functions zdefiniowane poza rozszerzeniami.


Aby instalować rozszerzenia lub 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). Chociaż zainstalowanie rozszerzenia jest bezpłatne, możesz zostać obciążony opłatami za korzystanie z usług Firebase lub usług w chmurze, takich jak Cloud Secret Manager, jeśli przekroczysz bezpłatny poziom tych usług.

Zanim zaczniesz

  1. Dodaj Firebase do projektu, jeśli jeszcze tego nie zrobiono.

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

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

  4. Zanotuj 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 tym rozszerzeniu, w tym:

  • jak działa rozszerzenie, jakie zadania należy wykonać przed instalacją oraz 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 dla rozszerzenia (np. funkcje).
  • Opisy parametrów konfigurowalnych przez użytkownika

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

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

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

    firebase ext:info publisher-id/extension-id

    Argumenty publisher-id i extension-id są wymagane. Znajdziesz je na stronie z informacjami o preinstalowaniu rozszerzenia.

Krok 2. Zainstaluj rozszerzenie

Przed instalacją zapoznaj się z podstawowymi specyfikacjami rozszerzenia (np. włączone interfejsy API, utworzone zasoby, udzielone dostępy itp.) oraz jego wymaganiami dotyczącymi rozliczeń.

Zanim przejdziesz dalej, skonfiguruj środowisko i wybierz 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 na Twoim projekcie funkcje Cloud Functions są już zainicjowane, upewnij się, że używasz wersji 5.1.0 lub nowszej pakietu firebase-functions:

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

Parametry publisher-id i extension-id są wymagane. Znajdziesz je na stronie z informacjami o wstępnym instalowaniu rozszerzenia na stronie extensions.dev. Część @version jest opcjonalna. Jeśli ją pominiesz, narzędzie zainstaluje najnowszą wersję.

Dostępne są 2 opcje:

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

    • automatycznie wygenerować pakiet SDK, nawet jeśli został on już wygenerowany dla tego samego rozszerzenia i tej samej wersji;
    • Zainstaluj wygenerowany automatycznie pakiet SDK w projekcie Node Cloud Functions.

  • --codebase: nazwa kodu źródłowego, do którego 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 pakiet SDK wygenerowany automatycznie dla rozszerzenia i dodaje go do jednej z baz kodu Cloud Functions w projekcie. W domyślnej bazie kodu (functions) pakiet SDK jest zapisywany w tym miejscu: 

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

Po wygenerowaniu pakietu SDK pojawi się pytanie, czy chcesz go zainstalować również w projekcie węzła Cloud Functions. Odpowiedz Tak na to pytanie.

Konfigurowanie instancji rozszerzenia

Aby skonfigurować rozszerzenie, zaimportuj pakiet SDK, a następnie w przypadku każdego wystąpienia rozszerzenia, które chcesz zainstalować, wywołaj funkcję konstruktora, przekazując mu identyfikator wystąpienia unikalnego dla projektu i parametry konfiguracji wymagane przez rozszerzenie.

  1. W kodzie źródłowym funkcji 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ć tak:

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

    Jeśli rozszerzenie wymaga wartości tajnych, takich jak hasła, musisz też użyć 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ć mniej więcej tak:

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

    Jeśli rozszerzenie wymaga wartości tajnych, takich jak hasła, musisz też użyć 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żdemu wystąpieniu nadaj unikalny identyfikator, który będzie zawierać 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 muszą być określone za pomocą funkcji defineSecret.

  3. Aby wdrożyć skonfigurowane rozszerzenia, uruchom: 

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

    Dostępne są wszystkie zwykłe opcje wdrażania Cloud Functions. Aby na przykład wdrożyć pojedynczy egzemplarz rozszerzenia z poziomu konkretnej bazy kodu: 

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

Krok 3. Dokończ konfigurowanie po instalacji

Niektóre rozszerzenia wymagają wykonania określonych czynności przed ich użyciem. Instrukcje te znajdziesz na stronie z informacjami o rozszerzeniu po jego zainstalowaniu w panelu Extensions konsoli Firebase (link do panelu wyświetla się w terminalu po instalacji).

Instrukcje te znajdziesz też w pliku POSTINSTALL.md, który znajduje się w katalogu źródłowym rozszerzenia.

Tworzenie zasobów Firebase

Jeśli skonfigurujesz rozszerzenie tak, aby używało zasobów Firebase (Cloud Firestorekolekcji, Realtime Databaseścieżek i Cloud Storagepojemników), które jeszcze nie istnieją, utwórz je przed użyciem rozszerzenia.

Tworzenie modułów obsługi zdarzeń Eventarc

Niektóre rozszerzenia publikują dane w Eventarc, gdy podczas wykonywania rozszerzenia występują ważne zdarzenia. Jeśli rozszerzenie publikuje zdarzenia, możesz napisać funkcje, które będą na nie reagować, korzystając z własnej logiki niestandardowej. Może to być przydatne na przykład do powiadamiania użytkowników o zakończeniu długotrwałych zadań lub do dalszego przetwarzania danych wyjściowych funkcji rozszerzenia.

Jeśli chcesz zdefiniować metody obsługi zdarzeń emitowanych przez rozszerzenie, możesz to zrobić za pomocą metod aktywacji poszczególnych wystąpień:

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.
});

Obsługę zdarzenia musisz wyeksportować razem z instancją rozszerzenia.

Po zdefiniowaniu i za każdym razem, gdy wprowadzasz zmiany w obsługującym zdarzeń, ponownie wdróż zarówno rozszerzenie, jak i obsługujący.

Instalowanie wielu instancji rozszerzenia

W tym samym projekcie możesz zainstalować to samo rozszerzenie więcej niż raz. Każde zainstalowane wystąpienie może mieć własną konfigurację i własne zasoby rozszerzenia. Każdą zainstalowaną instancję możesz identyfikować i odwoływać się do niej za pomocą jej identyfikatora instancji, który jest unikalny w ramach projektu.

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

Następne kroki