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

Провайдер Модуля интеграций объявляет интеграцию: её параметры, их группировку в секции настроек и необязательную проверку соединения. Администратор магазина настраивает её в Admin, без правок medusa-config и без повторного развёртывания.

Модуль интеграций не зависит от типа провайдера, поэтому, в отличие от встроенных коммерческих модулей Medusa, он не поставляется с провайдером по умолчанию или провайдером-заглушкой. Провайдером Модуля интеграций может быть любой плагин, провайдер или собственный модуль. Полный список сценариев смотрите в разделе Где можно применять Модуль интеграций.

Каждый провайдер, зарегистрированный в параметре providers Модуля интеграций, представлен в базе данных моделью данных Integration.

Провайдер Модуля интеграций представляет собой модуль, чей сервис расширяет AbstractIntegrationProvider, импортированный из @gorgo/medusa-integration. Как и у других провайдеров Medusa, один модуль может регистрировать несколько сервисов провайдера Модуля интеграций, каждый со своим static identifier, и каждый становится отдельным провайдером.

AbstractIntegrationProvider объявляет следующие члены класса:

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

providers/integration-my/services/my-integration.ts
1import { AbstractIntegrationProvider } from "@gorgo/medusa-integration"
2
3class MyIntegrationProvider extends AbstractIntegrationProvider {
4  static identifier = "my"
5
6  static validateOptions(options: Record<string, unknown>) {
7    // необязательная fail-fast проверка
8  }
9
10  get descriptor() {
11    return descriptor
12  }
13}
14
15export default MyIntegrationProvider

descriptor здесь представляет собой результат defineIntegration, подробнее об этом в разделе Основные концепции. getIdentifier() и getInstanceId() в примере не показаны: AbstractIntegrationProvider уже реализует оба метода через аргумент instanceId конструктора, поэтому подкласс добавляет только static identifier, descriptor и, опционально, static validateOptions.

Модуль интеграций принимает параметр providers, в котором вы настраиваете провайдеры, зарегистрированные в вашем приложении, а также параметр encryptionKey, используемый для секретных полей модуля. Точную структуру medusa-config.ts смотрите в шаге 4 руководства «Как создать провайдер Модуля интеграций».

При старте приложения Medusa Модуль интеграций регистрирует каждый провайдер из параметра providers. Для каждой записи он объединяет static identifier класса провайдера с id записи в ключ int_<identifier>[_<id>]. Это тот же формат, что используется для provider_id этого инстанса в базе данных. Затем он создаёт провайдер через new ProviderClass(container, options, instanceId).

Инстанс зарегистрированного провайдера Модуля интеграций представлен в приложении Medusa моделью данных Integration.

Вы можете удалить зарегистрированный провайдер Модуля интеграций, удалив его запись из параметра providers в medusa-config.ts. В отличие от отключения интеграции из Admin, это не затрагивает сохранённую запись. Провайдер просто перестаёт регистрироваться, поэтому модуль больше не может найти его запись Integration по provider_id. Интеграция исчезает из списка в Admin, а её сохранённые данные становятся недоступны через собственные admin-роуты Модуля интеграций.

Чтобы временно прекратить использование провайдера, сохранив его настройки и возможность быстро вернуть его обратно, отключите интеграцию из Admin вместо удаления провайдера из medusa-config.ts. См. Включение и отключение интеграции.