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

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

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


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

Этот автоматически сгенерированный 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. В исходном коде Cloud Functions импортируйте конструктор, используя оператор, выводимый командой ext:sdk:install .

    Машинопись

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

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

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

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

    JavaScript

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

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

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

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

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

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

    Машинопись 

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

    Обратите внимание, что секретные значения необходимо указывать с помощью функции 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 , когда они происходят во время выполнения. Если расширение публикует события, вы можете написать функции, которые реагируют на эти события с помощью собственной пользовательской логики. Это может быть полезно, например, для уведомления пользователей о завершении длительных задач или для постобработки выходных данных функции расширения.

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

Машинопись 

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

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

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

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

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

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

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