В этом документе вы узнаете, что такое провайдер Модуля интеграций, что нужно для его реализации, как модуль регистрирует его при старте приложения и как модель данных представляет каждый зарегистрированный инстанс в базе данных.
Провайдер Модуля интеграций объявляет интеграцию: её параметры, их группировку в секции настроек и необязательную проверку соединения. Администратор магазина настраивает её в Admin, без правок и без повторного развёртывания.
Модуль интеграций не зависит от типа провайдера, поэтому, в отличие от встроенных коммерческих модулей Medusa, он не поставляется с провайдером по умолчанию или провайдером-заглушкой. Провайдером Модуля интеграций может быть любой плагин, провайдер или собственный модуль. Полный список сценариев смотрите в разделе Где можно применять Модуль интеграций.
Каждый провайдер, зарегистрированный в параметре Модуля интеграций, представлен в базе данных моделью данных .
Провайдер Модуля интеграций представляет собой модуль, чей сервис расширяет , импортированный из . Как и у других провайдеров Medusa, один модуль может регистрировать несколько сервисов провайдера Модуля интеграций, каждый со своим , и каждый становится отдельным провайдером.
объявляет следующие члены класса:
| Член класса | Описание |
|---|---|
| Обязательное поле. Стабильный идентификатор провайдера, общий для всех его инстансов. | |
| Обязательное абстрактное свойство. Возвращает дескриптор, созданный через : параметры, секции, валидацию и необязательную проверку соединения. | |
| Необязательный метод. Fail-fast проверка конфигурации провайдера из при загрузке приложения. По умолчанию ничего не делает. | |
| Реализован в базовом классе. Возвращает класса. | |
| Реализован в базовом классе. Возвращает регистрации этого инстанса, взятый из аргумента конструктора, или для инстанса по умолчанию. |
Вот минимальная форма провайдера со всеми членами класса из таблицы выше, кроме тех, что уже реализует базовый класс:
providers/integration-my/services/my-integration.ts1import { AbstractIntegrationProviderService } from "@gorgo/medusa-integration"23class MyIntegrationProvider extends AbstractIntegrationProviderService {4 static identifier = "my"56 static validateOptions(options: Record<string, unknown>) {7 // необязательная fail-fast проверка8 }910 get descriptor() {11 return descriptor12 }13}1415export default MyIntegrationProvider
здесь представляет собой результат . Все поля, которые он принимает, смотрите на странице Дескриптор провайдера интеграций. и в примере не показаны, потому что уже реализует оба метода. возвращает класса, а возвращает , который модуль передаёт третьим аргументом конструктора. Поэтому подкласс добавляет только , и, опционально, .
Если у подкласса есть собственный конструктор, он должен передать в все три аргумента, , и . Иначе вернёт , даже для именованного инстанса.
Прежнее имя было . Пакет по-прежнему экспортирует его как устаревший алиас, сохранит во всех версиях 2.x и удалит в версии 3.0.
Полный пошаговый пример с кодом смотрите в разделе Как создать провайдер Модуля интеграций.
Модуль интеграций принимает параметр , в котором вы настраиваете провайдеры, зарегистрированные в вашем приложении, а также параметр , используемый для секретных полей модуля. Точную структуру смотрите в шаге 4 руководства «Как создать провайдер Модуля интеграций».
При старте приложения Medusa Модуль интеграций регистрирует каждый провайдер из параметра . Сначала Medusa проверяет и каждой записи. Затем модуль вызывает провайдера с записи и объединяет класса с записи в ключ . Это тот же формат, что используется для этого инстанса в базе данных. Модуль регистрирует провайдер в своём контейнере под этим ключом, а контейнер создаёт инстанс через .
Для каждой записи шаги идут в таком порядке:
Если проверка или не проходит, приложение останавливается при старте, и неверная запись до ключа не доходит. Запись, прошедшая проверки, становится инстансом в контейнере модуля, а Admin показывает каждый зарегистрированный инстанс, настроенный или нет, в разделе Настройки → Интеграции.
Зарегистрировав все провайдеры, модуль пишет в лог предупреждение о каждом параметре, название которого похоже на учётные данные, но который не помечен . Как модуль обращается с секретами, описано на странице Дескриптор провайдера интеграций.
Medusa останавливает приложение при старте, если запись в нарушает одно из этих правил, и ошибка называет проблему:
Чтобы избежать первой ошибки, задайте каждому инстансу провайдера собственный . Как образует ключ, описано на странице Основные концепции.
Инстанс зарегистрированного провайдера Модуля интеграций представлен в приложении Medusa моделью данных .
Собственный модели служит лишь её внутренним идентификатором записи, таким же, как у любой другой модели данных Medusa. Это не то же самое, что , поле, которое хранит ключ из раздела Инстансы и их идентификаторы.
Запись хранит инстанса, его , настройки администратора магазина в с зашифрованными секретными параметрами, флаг и результат последней проверки соединения. Модуль создаёт запись при первом сохранении любой секции, поэтому зарегистрированный провайдер без записи показывается в Admin как Не настроено. Все свойства модели перечислены в справочнике Модели данных Модуля интеграций.
История изменений инстанса хранится в отдельной модели данных , которая не связана с и переживает её. Подробнее на странице История изменений настроек.
Вы можете удалить зарегистрированный провайдер Модуля интеграций, удалив его запись из параметра в . В отличие от отключения интеграции из Admin, это не затрагивает сохранённую запись. Провайдер перестаёт регистрироваться, поэтому модуль больше не может найти его запись по . Интеграция исчезает из списка в Admin, а её сохранённые данные становятся недоступны через собственные admin-роуты Модуля интеграций. Её записи остаются в истории изменений всех интеграций.
Удалите интеграцию из Admin, прежде чем убирать провайдер из , а не наоборот. Как только провайдер исчезает из конфигурации, его запись становится недостижима, в том числе через сам роут удаления, и остаётся в базе данных без возможности удалить её из Admin. Обычный порядок удаления описан в разделе Удаление интеграции.
То же происходит, если изменить записи или класса, потому что меняется ключ . У нового ключа нет сохранённой записи , поэтому инстанс показывается как Не настроено, а настройки остаются в базе данных под старым ключом, недоступные из Admin. Есть два выхода:
Входные данные воркфлоу и путь импорта описаны на странице Воркфлоу Модуля интеграций.
Чтобы временно прекратить использование провайдера, сохранив его настройки и возможность быстро вернуть его обратно, отключите интеграцию из Admin вместо удаления провайдера из . Как это сделать, описано на странице Управление интеграциями в Medusa Admin.