Установите расширение Firebase

Вы можете установить (и управлять ) любым официальным расширением Firebase , используя консоль Firebase , Firebase CLI (интерфейс командной строки) или используя автоматически сгенерированный SDK.

Обязательно ознакомьтесь с различиями в поддерживаемых действиях для каждого метода установки.


Установка с использованием автоматически сгенерированного SDK — это новый вариант установки и управления расширениями. С помощью этого варианта вы используете CLI для автоматического создания Node SDK для определенной версии расширения, которую вы можете импортировать как обычную зависимость в ваши JavaScript или TypeScript Cloud Functions.

Этот автоматически сгенерированный SDK содержит:

  • Интерфейс, представляющий параметры расширения, и объявления типов для большинства непримитивных типов параметров.
  • Функция-конструктор, которая инициализирует экземпляр расширения.
  • Класс расширения, содержащий триггеры Eventarc для всех событий, генерируемых расширением.

После создания SDK расширения вся настройка расширения происходит в коде.

Использование этого варианта установки может значительно упростить управление несколькими экземплярами расширений, особенно в проектах, содержащих облачные функции, определенные вне расширений.


Для установки или управления расширениями вам должна быть назначена одна из следующих ролей: Владелец, Редактор или Администратор Firebase .

Для установки расширения ваш проект должен быть на плане Blaze (оплата по мере использования). Хотя плата за установку расширения не взимается, с вас может взиматься плата за использование служб Firebase или облачных служб, таких как Cloud Secret Manager , если ваше использование превышает бесплатный уровень служб.

Прежде чем начать

  1. Если вы еще этого не сделали, добавьте Firebase в свой проект .

  2. Если вы еще этого не сделали, обновите свой проект до тарифного плана Blaze (оплата по мере использования).

  3. Установите или обновите Firebase CLI до последней версии.

  4. Запишите идентификатор вашего проекта Firebase или ранее настроенный псевдоним проекта.

Шаг 1 : Просмотр подробной информации о расширении

Этот шаг необязателен, но настоятельно рекомендуется.

Перед установкой Firebase Extension мы рекомендуем вам ознакомиться с подробной информацией о расширении, включая:

  • Как работает расширение, какие задачи необходимо выполнить перед установкой и подробности о расширении
  • Общая идентификационная информация и описание
  • Требуют ли задачи расширения наличия платежного аккаунта
  • Службы Google (API) и роли доступа , необходимые для работы
  • Ресурсы, созданные для расширения (например, функции)
  • Описания настраиваемых пользователем параметров

Чтобы просмотреть подробную информацию о расширении:

  1. Убедитесь, что вы настроили свою среду и выбрали расширение .

  2. Запустите команду extension-info из любого места на вашем компьютере:

    firebase ext:info publisher-id/extension-id

    Аргументы publisher-id и extension-id являются обязательными и могут быть найдены на странице сведений о предустановленном расширении .

Шаг 2 : Установите расширение

Перед установкой ознакомьтесь с основными характеристиками расширения (такими как включенные API, созданные ресурсы , предоставленный доступ и т. д.), а также требованиями к оплате.

Прежде чем продолжить, убедитесь, что вы настроили свою среду и выбрали расширение .

Инициализация облачных функций для Firebase

Если вы начинаете новый проект или ваш проект еще не использует Cloud Functions for Firebase, запустите init functions :

cd your-project
firebase init functions

Выберите TypeScript или JavaScript в качестве языка функций.

Если в вашем проекте уже инициализированы Cloud Functions, убедитесь, что вы используете версию 5.1.0 или более позднюю версию пакета firebase-functions :

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

Если вы используете ESLint, вы также можете захотеть исключить сгенерированные SDK из своей конфигурации ( .eslintrc.js ):

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

Сгенерировать расширение SDK

Из локального каталога Firebase выполните команду ext:sdk:install .

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

Например, чтобы установить версию 0.1.34 расширения firestore-send-email :

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

publisher-id и extension-id являются обязательными и могут быть найдены на странице сведений о предварительной установке расширения на extensions.dev . Часть @ version необязательна; если вы ее пропустите, инструмент установит последнюю версию.

Вы можете указать два варианта:

  • --force : Выполнить все следующие действия без дополнительного подтверждения:

    • Автоматически сгенерировать SDK, даже если он уже был сгенерирован для того же расширения и версии.
    • Установите автоматически сгенерированный пакет SDK в проект Cloud Functions Node.

  • --codebase : Имя кодовой базы, в которую нужно добавить SDK. Если не указано, команда добавляет SDK в кодовую базу по умолчанию, functions .

Эта команда создает пакет Node, содержащий SDK, автоматически сгенерированный для расширения, и добавляет его в одну из кодовых баз Cloud Functions вашего проекта. В кодовой базе по умолчанию ( functions ) SDK сохраняется в следующем месте: 

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

После генерации SDK команда спросит, хотите ли вы также установить SDK в свой проект Cloud Functions Node. Ответьте Да на этот запрос.

Настроить экземпляры расширения

Чтобы настроить расширение, импортируйте SDK и для каждого экземпляра расширения, который вы хотите установить, вызовите функцию конструктора, передав ей уникальный для проекта идентификатор экземпляра и параметры конфигурации, требуемые расширением.

  1. В исходном коде облачных функций импортируйте конструктор с помощью оператора, выведенного командой ext:sdk:install .

    МашинописьJavaScript

    Например, если вы сгенерировали SDK для расширения firestore-send-email , оператор import будет выглядеть примерно так: 

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

    Если расширение требует каких-либо секретных значений, таких как пароли, вам также понадобится функция defineSecret из Cloud Functions SDK: 

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

    Например, если вы сгенерировали SDK для расширения firestore-send-email , оператор require будет выглядеть примерно так: 

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

    Если расширение требует каких-либо секретных значений, таких как пароли, вам также понадобится функция defineSecret из Cloud Functions SDK: 

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

  2. Для каждого экземпляра, который вы хотите настроить, вызовите функцию конструктора и экспортируйте результат.

    Присвойте каждому экземпляру уникальный идентификатор, содержащий только строчные буквы, цифры и дефисы.

    Машинопись JavaScript 
    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",
});

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

    Обратите внимание, что секретные значения необходимо указывать с помощью функции defineSecret .

  3. Затем, чтобы развернуть настроенные вами расширения, выполните: 

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

    Применяются все обычные параметры развертывания Cloud Functions . Например, для развертывания одного экземпляра расширения из определенной кодовой базы: 

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

Шаг 3 : Завершите настройку после установки

Некоторые расширения имеют обязательные или необязательные шаги, которые вам необходимо выполнить перед их использованием. Найдите эти инструкции на странице сведений о вашем расширении после установки в панели управления Extensions консоли Firebase (конкретная ссылка на панель управления отображается в терминале после установки).

Эти инструкции вы также можете найти в файле POSTINSTALL.md , включенном в исходный каталог расширения .

Создать ресурсы Firebase

Если вы настроили расширение для использования ресурсов Firebase (коллекции Cloud Firestore , пути Realtime Database , контейнеры Cloud Storage ), которые еще не существуют, создайте их перед использованием расширения.

Создание обработчиков событий Eventarc

Некоторые расширения публикуются в Eventarc , когда во время выполнения происходят важные события. Если расширение публикует события, вы можете написать функции, которые реагируют на эти события с помощью собственной пользовательской логики. Это может быть полезно, например, для уведомления пользователей о завершении длительных задач или для постобработки выходных данных функции расширения.

Если вы хотите определить обработчики для любого из событий, генерируемых расширением, вы можете сделать это с помощью методов триггера каждого экземпляра:

Машинопись JavaScript 
export const firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });

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

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

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

Необходимо экспортировать обработчик событий вместе с экземпляром расширения.

После определения обработчика событий и после каждого внесения в него изменений повторно развертывайте и расширение, и обработчик.

Установить несколько экземпляров расширения

Вы можете установить одно и то же расширение несколько раз в одном проекте. Каждый установленный экземпляр может иметь собственную настроенную конфигурацию и собственные ресурсы расширения. Вы идентифицируете и ссылаетесь на каждый установленный экземпляр, используя его идентификатор экземпляра , который является уникальным в пределах вашего проекта.

Вызовите функцию конструктора автоматически сгенерированного SDK один раз для каждого экземпляра, который вы хотите установить и настроить.

Следующие шаги