В дескрипторе провайдера интеграций вы объявляете параметры интеграции, их группировку по секциям настроек, валидацию и необязательную проверку соединения. На этой странице собран полный справочник по каждому полю, которое можно в нём указать.
Роли участников и то, как параметр проходит путь от дескриптора до итогового значения во время выполнения, описаны в разделе Основные концепции.
Создайте дескриптор через . Он собирает из каталога схему , которая используется для , значений по умолчанию и полной валидации.
providers/integration-my/services/my-integration.ts1import { defineIntegration, AbstractIntegrationProviderService } from "@gorgo/medusa-integration"23const descriptor = defineIntegration({4 category: "payment",5 displayName: "my.name",6 options: {7 apiKey: {8 type: "string",9 control: "secret",10 secret: true,11 required: true,12 label: "my.apiKey"13 },14 sandbox: {15 type: "boolean",16 control: "switch",17 default: false,18 label: "my.sandbox"19 },20 },21 sections: [22 {23 id: "credentials",24 title: "my.credentials",25 options: ["apiKey", "sandbox"]26 },27 ],28})2930export class MyIntegration extends AbstractIntegrationProviderService {31 static identifier = "my"3233 get descriptor() {34 return descriptor35 }36}
Этот дескриптор объявляет и , сгруппированные в одну секцию . сразу выбрасывает ошибку при загрузке в двух случаях: если секция ссылается на id параметра, которого нет в , и если параметра типа смешивает строки и числа.
принимает следующие свойства:
провайдера в дескриптор не входит. Модуль добавляет его из класса провайдера, когда регистрирует провайдер.
Каждый элемент становится карточкой на странице интеграции с собственным действием Редактировать. Секция ссылается на параметры по идентификатору, а параметр может не входить ни в одну секцию, например если его редактирует собственная секция.
Каждый параметр в представляет собой объект вида . Поле определяет доступные значения и остальные поля, общие для всех типов:
У некоторых типов есть свои поля сверх общих:
Модуль генерирует CRUD API из дескриптора и валидирует каждую запись. Валидация покрывает правила на уровне отдельного параметра (типы, диапазоны, паттерны) вместе с правилами между секциями, охватывающими всю конфигурацию. Ничего писать под каждую интеграцию не нужно.
Когда срабатывает каждое правило и как тестировать правила дескриптора, читайте в руководстве Валидация параметров интеграции, а сгенерированные роуты описаны в справочнике API-роуты Admin.
Параметры становятся активными, только когда интеграция и включена, и заполнена, то есть проходит полную валидацию. Незавершённый черновик или выключенная интеграция никогда не отдают параметры, поэтому недоделанная конфигурация не может попасть в работающее приложение.
Параметры с пометкой шифруются при хранении алгоритмом AES-256-GCM и никогда не попадают в браузер. CRUD API маскирует их и сообщает лишь, задано значение или нет. Сохранение секрета пустым оставляет прежнее хранимое значение, а не стирает его.
не выбирает контрол . Без Admin показывает параметр как обычное текстовое поле, поэтому вводимое значение видно на экране, а подсказки о том, что пустое поле сохранит прежнее значение, нет. Если параметр к тому же , Admin требует значение при каждом сохранении его секции, и администратору магазина приходится заново вводить уже сохранённый секрет. Задавайте для каждого параметра с .
Значения секретных параметров не попадают и в историю изменений. Для них история показывает только, что значение задано, заменено или удалено. Значения остальных параметров она хранит как есть.
Параметр с учётными данными без пометки показывается в Admin и хранится в истории изменений открытым текстом. При запуске модуль пишет в лог предупреждение о каждом параметре, название которого похоже на учётные данные, но не помечено . Предупреждение пишется один раз на идентификатор провайдера, даже если провайдер зарегистрирован несколько раз. Похожим считается название, в котором без учёта регистра встречается , , , , или . и совпадают и с подчёркиванием или дефисом между словами, например или . Совпадение ищется внутри названия, поэтому подходят и , а и не подходят.
Модуль шифрует секретное значение при сохранении и расшифровывает его при чтении интеграции. Если изменить флаг у параметра, значение которого администратор магазина уже сохранил, интеграция продолжит работать:
Ошибка остаётся в одном случае. Модуль считает сохранённую строку зашифрованной, если она начинается с или похожа на значение, зашифрованное версией модуля 0.x. Такое значение записано в стандартном base64 (, , , , и для выравнивания), длиной не меньше 40 символов и кратной 4, а после декодирования занимает не меньше 29 байт. Значение открытым текстом такого вида в параметре, который вы только что пометили , не расшифруется, и чтение интеграции завершится ошибкой, описанной в разделе Параметры Модуля интеграций. Чтобы восстановить работу, удалите сохранённые настройки через роут и введите их заново. Чтобы этого избежать, решите, секретный ли параметр, до того как администратор магазина сохранит его значение.
Для шифрования модулю нужен ключ, задайте его как при регистрации модуля. О том, как задать его и что происходит без него, смотрите в разделе Параметры Модуля интеграций.
Дескриптор может объявить необязательную проверку соединения, которая сверяет учётные данные со сторонним сервисом. Администраторы магазина запускают её по требованию, а запланированная задача раз в сутки, в 03:00 по часам сервера, заново проверяет каждую включённую интеграцию.
Добавьте в дескриптор. Он получает уже итоговые (расшифрованные) параметры и возвращает статус:
providers/integration-my/services/my-integration.ts1const descriptor = defineIntegration({2 // ...3 testConnection: async ({ options }) => {4 const res = await fetch("https://api.my.com/ping", {5 headers: { Authorization: `Bearer ${options.apiKey}` },6 })78 if (!res.ok) {9 return { status: "failed", message: `My responded with ${res.status}` }10 }1112 return { status: "passed" }13 },14})
принимает одно из значений , или . Модуль сохраняет статус в интеграции и отправляет событие . Само модуль не сохраняет, оно есть только в событии и в уведомлении Admin.
Если статус не , Admin показывает в уведомлении, а при отсутствии сообщения сам статус. Результат всегда показывает одно и то же уведомление об успехе, что бы ни содержало .
Проверка выполняется только с параметрами, которые удалось получить. Если интеграция не настроена, выключена или не завершена, модуль сообщает с текстом и не вызывает. Если выбрасывает исключение, модуль сообщает с текстом ошибки. Какие ещё результаты модуль формирует сам, в том числе для неизвестного провайдера и дескриптора без , описано в разделе Воркфлоу Модуля интеграций.
Потребители читают типизированные, проверенные и расшифрованные параметры с применёнными значениями по умолчанию из дескриптора. Незаполненная или выключенная интеграция возвращает пустой результат, а не частичные данные. Способы чтения параметров и то, как долго модуль их кэширует, описаны в руководстве Чтение параметров.
Несколько полей дескриптора принимают значение из фиксированного списка. Это , и параметра, секции, и , который возвращает . Между версиями модуля эти списки меняются так:
Код, который ветвится по одному из этих значений, например по , должен обрабатывать и незнакомое значение. Тогда минорная версия модуля его не сломает.
По умолчанию:
По умолчанию:
По умолчанию:
По умолчанию:
По умолчанию: