Skip to main content

Создание и настройка каталога

Требования к каталогу и данным о продуктах​

MoodRec работает с файлами каталога в формате YML (Yandex Market Language). Файл каталога должен содержать:

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

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

Рекомендуется передавать для каждого продукта следующие параметры:

  • category/categories — категория или список категорий продукта;
  • price — цена;
  • availability/stock — наличие;
  • brand — бренд или производитель;
  • image/image_url — ссылка на изображение;
  • url — ссылка на страницу продукта;
  • created_at/date — дата добавления продукта в каталог.

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

Помимо рекомендуемых параметров, каталог может содержать любые дополнительные поля. Пользовательские атрибуты могут быть использованы:

  • для фильтрации продуктов;
  • в правилах мерчендайзинга;
  • при формировании шаблонов отображения рекомендаций.

Структура и назначение таких атрибутов определяется пользователем самостоятельно.

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

  • Идентификаторы продуктов должны быть стабильными между загрузками.
  • Типы данных должны быть согласованными.
  • Не рекомендуется передавать пустые или некорректные значения.
  • Файл должен быть синтаксически корректен.

Подробнее о формате YML можно прочесть здесь.

Импорт продуктов​

Для добавления нового каталога или продуктов в уже существующий, перейдите в соответствующий раздел сервиса:

Раздел Каталоги

Доступны следующие способы импорта:

  • Разовый импорт — однократная загрузка данных из файла без обновлений
  • Импорт по расписанию — регулярное обновление из URL-источника
  • Импорт через API — регулярное обновление с помощью API-запроса

Разовый импорт​

При разовом импорте сервис берет информацию из файла с вашего устройства или по URL-ссылке и однократно добавляет продукты в каталог:

Разовый импорт

При импорте из файла необходимо выбрать YML-файл на устройстве и выбрать режим обновления.

Формат файла

Вы можете загружать в сервис не только файлы YML-формата, но и:

  • XML-файл, размеченный по правилам YML;
  • Архивы ZIP и GZ, содержащие YML-файлы

Импорт из файла

При импорте по ссылке загрузка продуктов происходит из внешнего источника. Необходимо указать URL, тип авторизации и данные для авторизации (токен, логин/пароль).

Импорт из файла

Для первого заполнения каталога рекомендуется выбрать режим Полное обновление из файла. Этот режим создаёт каталог с нуля и полностью заменяет существующие данные. При повторных загрузках файла для обновления каталога используйте режим Добавить новых и обновить существующих. В этом случае новые объекты будут добавлены, а уже существующие — обновлены без полного пересоздания каталога.

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

Импорт по расписанию​

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

Импорт по расписанию

Импорт через API​

Импорт через API позволяет обновлять каталог запросами к сервису — без загрузки файла и без настройки URL-источника. Способ подходит для точечных правок каталога: запрос создаёт новые продукты и обновляет существующие по идентификатору id. В одном запросе можно передать массив продуктов.

Параметры подключения доступны на странице Подключение API: URL запроса, готовый код подключения и таблица параметров.

Подключение API

Запрос выполняется методом POST на адрес /offers/upsert. Продукты передаются в теле запроса в формате JSON, в массиве offers. Для каждого продукта указываются:

  • id — идентификатор продукта;
  • category_id — идентификатор категории продукта;
  • params — дополнительные параметры продукта в формате «название — значение».

Все три поля обязательны. Авторизация выполняется через заголовок X-MOODREC-API с токеном доступа.

Полное описание метода с примерами запроса и ответа — в статье Создание или обновление продукта.

Журнал​

Журнал каталога содержит информацию об операциях с продуктами в каталоге. В журнале можно найти:

  • дату и время импорта;
  • тип импорта;
  • тип операции (добавление/удаление);
  • количество обработанных продуктов;
  • количество возникших ошибок и статус импорта.

Журнал каталога