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

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

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


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

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

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

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

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


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

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

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

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

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

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

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

    • ID проекта — Запустите firebase projects:list из любого места на вашем компьютере.
    • Псевдоним проекта — Запустите firebase use из локального каталога приложения.

Шаг 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.

  • --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. В исходном коде Cloud Functions импортируйте конструктор, используя оператор, выведенный командой 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.
});

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

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

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

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

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

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