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

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

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

Консоль Firebase Firebase CLI Автоматически созданный SDK

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

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

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

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

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

Чтобы впервые опробовать Firebase Extension , мы рекомендуем установить его в тестовом проекте или проекте разработки.

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

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

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

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

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

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

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

   • Идентификатор проекта — запускайте firebase projects:list из любого места на вашем компьютере.
   • Псевдоним проекта — запустите firebase use из локального каталога приложений.
   Примечание. Чтобы устанавливать расширения и управлять ими с помощью команд CLI, вам необходимо иметь проект Firebase, связанный с локальным каталогом приложения. Если вы еще этого не сделали, запустите firebase init , чтобы настроить локальный каталог Firebase.

Шаг 1. Просмотрите подробную информацию о расширении.

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

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

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

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

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

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

   firebase ext:info publisher-id/extension-id

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

Примечание. Эту подробную информацию также можно просмотреть в README , включенном в каталог расширения .

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

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

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

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

Если вы начинаете новый проект или ваш проект еще не использует облачные функции для Firebase, запустите init functions :

cd your-project
firebase init functions

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

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

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

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

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

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

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

Чтобы настроить расширение, импортируйте 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://[e-mail]@smtp.example.com:465",
       SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"),
       MAIL_COLLECTION: "mail",
       DEFAULT_FROM: "ExampleCo <[e-mail]>",
       TTL_EXPIRE_VALUE: "1",
       TTL_EXPIRE_TYPE: "day",
   });
   

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

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

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

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

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

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

   Примечание. Установка и подготовка расширения может занять у системы 3–5 минут.

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

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

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

Важно! Включение событий может привести к взиманию платы, если вы превысите бесплатную квоту. См. цены на Eventarc .

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

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

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

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

• Просмотрите подробную информацию и конфигурацию установленного расширения в консоли Firebase .

• Отслеживайте активность установленного расширения, включая проверку его работоспособности, использования и журналов.

• Управляйте установленным расширением с помощью консоли Firebase . Для официальных расширений Firebase вы можете перенастроить или удалить расширение, а также обновить его до последней версии.

• Рекомендуется для всех проектов обязательно настроить оповещения о бюджете для вашего проекта и отслеживать панель использования и выставления счетов в консоли Firebase .