Імпорт каталогу з XML / YML

XML — найпоширеніший формат обміну товарами між системами, а його різновид YML (Yandex Market Language) став фактичним стандартом для товарних фідів. У ньому віддають каталоги Prom, Rozetka, Hotline, E-Katalog, безліч CMS і постачальників. Якщо у вас є файл .xml чи .yml зі списком товарів — або посилання на нього, — Elbuz прочитає його напряму й розкладе значення по картках. Ця стаття — докладний розбір: які елементи фіда в які поля потрапляють, за якою логікою зіставляються товари, як читається наявність і валюта.

Це один зі способів завантаження з огляду завантаження даних. Формат стандартний, тож колонки розмічати вручну не треба — Elbuz упізнає елементи за назвами. Якщо ж ваш XML нестандартний (з довільними назвами вузлів), для нього краще підійде універсальний імпорт.

Зворотний напрямок — віддати свій каталог у цьому ж форматі — описано в статті про вивантаження у форматі YML (XML).

Де це у програмі

У вікні імпорту ви створюєте шаблон і обираєте тип «XML / Yandex Market (YML)». Це файлове джерело: файл можна завантажити з комп'ютера або дати посилання, за яким Elbuz забиратиме його сам. Посилання зручніше — його ставлять на розклад, і каталог оновлюється без ручних завантажень.

1

Перемикач «Локальний файл / Зовнішнє посилання»

2

Поле джерела (файл або посилання)

1. Перемикач дозволяє обрати, звідки брати файл — локальний комп'ютер чи зовнішнє посилання.
2. Поле джерела показує обраний файл або адресу посилання, з якої буде завантажено дані.

Структура YML-фіда

Усередині YML — звичайний XML із наперед відомою структурою. У корені лежить yml_catalog, у ньому — магазин, а в магазині кілька блоків: валюти (currencies), категорії (categories) і пропозиції (offers). Кожна пропозиція offer — це один товар із набором вкладених елементів. Саме тому для YML не потрібна ручна розмітка: назви елементів стандартні, і Elbuz знає, де ціна, де картинка, а де категорія.

1

Рядок шаблону «Yandex Market (формат YML)»

1. Рядок шаблону «Yandex Market (формат YML)» типу XML у списку завантажень.

Ідентифікатор і зіставлення

Найважливіше для повторних завантажень — як програма впізнає, що товар із фіда вже є в каталозі. У YML за це відповідає атрибут id пропозиції (offer id="…"): Elbuz зберігає його у системне поле товару «UUID» й далі зіставляє товари саме за ним. Якщо id стабільний, повторний імпорт оновлює наявну картку; якщо ж id у фіді щоразу різний, кожне завантаження створюватиме дублі. Тому фід зі сталими id — надійне джерело; саморобний фід без ідентифікаторів варто спершу перевірити на невеликій частині.

Атрибут group_id зв'язує різновиди (варіанти) одного товару: пропозиції з однаковим group_id складаються в один товар із варіантами, а перша в групі стає основною. Так кольори й розміри лишаються згрупованими, а не розсипаються окремими картками.

Куди потрапляють значення

Кожну пропозицію Elbuz розкладає по полях картки:

Є й нюанс із назвою: якщо пропозиція має тип vendor.model, назва збирається з бренду й моделі (vendor + model), інколи з префіксом типу (typePrefix) — так фіди без готового поля name все одно дають осмислену назву товару. Якщо якогось елемента у фіді немає, відповідне поле картки просто лишиться порожнім: програма не вигадує того, чого немає в джерелі.

Наявність

Наявність у YML задається атрибутом available: true означає, що товар готовий до відправки (у стандарті — протягом двох робочих днів), false — що його немає під рукою й термін від кількох днів до кількох тижнів. Elbuz переводить true у статус «у наявності», false — у «немає». Якщо у фіді замість цього є текстовий елемент наявності (presence чи stock), програма читає його й зіставляє за вашими правилами визначення статусу (текст на кшталт «в наявності», «під замовлення» → ваш статус). Коли нічого не вказано, береться найперший заведений статус вашого довідника з класифікацією наявності «Є», і разом із ним — його «Кількість за замовчуванням». Тобто фід без ознаки наявності зробить товари не «під замовлення», а такими, що є на складі: якщо це не те, що потрібно, статуси й кількість у довіднику варто перевірити до першого прогону.

Валюта й ціна

Ціна може приходити у різних елементах (price, а також priceuah, pricerub, priceusd, pricekzt) — Elbuz бере перше заповнене. Валюта задається елементом currencyId, а курси — блоком currencies у фіді. Якщо валюта товару відрізняється від вашої базової, ціна перераховується за курсом: спершу за курсом із самого фіда, а якщо його там немає — за курсом із вашого довідника валют. Тож числа приходять уже у вашій валюті, а не «як є».

Категорії

Дерево категорій Elbuz будує з блоку categories: кожен елемент category з атрибутами id та parentId і назвою розділу задає розділ і його батька, так відтворюється вкладеність. Товар прив'язується до розділу за своїм categoryId.

Що можна робити з розділами, які створив фід

Розділи з фіда — звичайні розділи каталогу, але прогін вважає їх своїми й повертає до стану файлу. Перейменували розділ у Elbuz — наступне завантаження запише назву з фіда назад. Перенесли товар в інший розділ — прогін поверне й це: основний розділ картки береться з фіда, а зв'язки «товар — розділ» для всіх позицій, що є у файлі, видаляються й записуються заново. Перенесення переживе рівно до наступного прогону. Виняток один: якщо для цієї позиції у фіді розділу немає, ваш розділ лишається.

Тому службові розділи фіда зазвичай не видаляють, а або лишають як є, або перебудовують у самому джерелі. Якщо потрібна своя структура — розкладайте по ній товари, які фід не веде: усе, що приїхало з файлу, повернеться у свій розділ на найближчому завантаженні.

Характеристики

Характеристики товару у YML — це елементи param з атрибутом name (назва характеристики) і значенням усередині; за потреби вказують одиницю виміру. Elbuz переносить їх у атрибути товару: назва стає атрибутом, значення — його значенням. Окремий випадок — param name="sku": його Elbuz трактує як артикул SKU. Характеристики завантажуються разом з рештою даних фіда.

Чому товар іноді не оновлюється

Якщо після повторного імпорту товар лишився без змін, причина зазвичай не у фіді, а в ознаках самого товару. Позиції з прапорцем «Не оновлювати» прогін пропускає. Якщо стоїть «Фіксована ціна», оновляться всі поля, крім ціни: фід не перезапише те, що ви зафіксували свідомо. Це захист вручну вивіреної картки від затирання автоматичним завантаженням.

Чиє значення лишиться, якщо джерел кілька

Ключем зіставлення стає id пропозиції як він записаний у файлі. Тому два різні фіди з простою нумерацією (1, 2, 3…) дають однакові ключі: другий шаблон знайде картки, заведені першим, і перепише їх своїми значеннями. Збоку це виглядає як «товари підмінилися», хоча програма зробила рівно те, що сказали ключі.

На цей випадок у шаблоні є прапорець «Перевірити унікальність записів з урахуванням цього джерела завантаження». З ним шаблон шукає збіг лише серед власних карток — а ще серед тих, що заведені вручну, прийшли з прайс-листа або від парсера; картки інших шаблонів завантаження для нього невидимі, і той самий id заведеться окремим товаром. За замовчуванням прапорець вимкнений, тобто всі джерела працюють в одному просторі ключів.

Коли одну картку пише кілька фідів, лишається значення того прогону, що відпрацював останнім. Але поля поводяться по-різному:

• Порожнє значення у фіді ваше не стирає. Артикул, гарантія, штрихкод, модель, посилання на товар, виробник і розділ оновлюються тільки тоді, коли у фіді для них щось є.
• Кількість, ціна й назва записуються як є. Немає в пропозиції quantity — у картці стане нуль. Немає name — назва спорожніє. Тут порожнє значення затирає.
• «Фіксована ціна» лишає вашу ціну, «Не оновлювати» — решту полів, крім назви й опису.

Що відбувається після того, як дані лягли в картки

Фід не останній, хто пише в картку. Коли значення розкладені по полях, прогін виконує формули полів, у яких стоїть ознака «Застосовувати при завантаженні БК із зовнішніх джерел» (вікно «Налаштування формул для полів базового каталогу»), у порядку сортування правил. Якщо така формула рахує ціну з націнкою, у картці лишиться її результат, а не число з фіда. Формули обходять товари з прапорцем «Не оновлювати», а ті, що пишуть у поле типу «ціна», ще й не чіпають карток із «Фіксованою ціною».

Далі йдуть службові кроки, і їх видно в журналі окремими рядками: «Оновлення значень на основі формул», «Перевірка цілісності даних», «Індексування товарів». Там же перераховується кількість товарів у розділах і у виробників, а пошук по каталогу позначається на переіндексацію. Завершує прогін рядок «Завантаження даних завершено!» з витраченим часом.

Що буде з товаром, який зник із фіда

За замовчуванням — нічого. Прогін чіпає лише ті позиції, які знайшов у файлі: зникла пропозиція лишається в каталозі з тією самою ціною, статусом наявності й залишком, її не деактивує й не обнуляє.

Дзеркальний режим вмикає прапорець «Видаляти записи в базовому каталозі, яких немає в завантаженому файлі». Він не деактивує, а видаляє: картку разом з описом, фотографіями, атрибутами, зв'язками з розділами й магазинами, питаннями-відповідями й супутніми товарами; зіставлення позиції з рядком прайс-листа при цьому рветься. Розділи, яких немає у фіді, видаляються так само.

Переліку видаленого в журналі не буде: там стоїть тільки рядок кроку «Видаляємо категорії та товари в базовому каталозі, яких немає у файлі». Відкотити видалення нічим — повернути позиції можна лише повторним завантаженням фіда, і це будуть уже нові картки.

Оновлення за посиланням

Головна користь YML — автоматичне оновлення. Коли шаблон налаштовано за посиланням і перевірено, поставте його на розклад кнопкою «Налаштування розкладу» в картці шаблону: Elbuz сам забиратиме свіжий фід за адресою й оновлюватиме ціни, наявність і залишки. Частоту обирайте за джерелом: якщо постачальник міняє ціни раз на добу, щогодинний імпорт сенсу не має. Кожен запуск лишає слід у журналі — скільки товарів оновлено, скільки додано, чи були помилки; перші кілька разів варто туди зазирати.

За розкладом працює тільки варіант із посиланням. Планувальник завжди бере адресу, записану в шаблоні: файл із комп'ютера він взяти не може, це разова ручна операція. Тому шаблон, у якому заповнене лише поле файлу, за розкладом просто нічого не робитиме.

Вимкнути шаблон чи видалити

Пілюля «Активний / Вимкнений» у шапці картки шаблону перемикає одну ознаку й більше нічого не чіпає. Що це дає:

• Планувальник вимкнений шаблон пропускає — за розкладом він не запуститься, і рядків у журналі завантаження від нього не з'явиться. Запуск «усі активні» його теж не візьме.
• Кнопка «Завантажити» в самій картці шаблону працює й у вимкненому стані — вимкнення зупиняє автоматику, а не ручний запуск.
• Завантажені товари лишаються як були: вимкнення шаблону нічого не видаляє й не деактивує в каталозі.
• Увімкнули назад — усе продовжується з тієї самої точки. Ні розклад, ні налаштування, ні посилання при вимкненні не губляться, і наступний прогін за розкладом піде як звичайно.

Видалення шаблону влаштоване інакше, ніж очікують: шаблон ховається зі списку, а його завдання знімаються з розкладу — але товари, розділи й атрибути, які він завантажив, лишаються в каталозі разом із позначкою джерела. Тобто видалення шаблону — це спосіб прибрати джерело, а не прибрати те, що воно принесло.

Якщо прогін обірвався посеред роботи

Кнопка «Стоп» ставить позначку зупинки, і прогін звіряється з нею після кожного розділу, після кожної пропозиції та між етапами. На найближчій перевірці він припиняє роботу й пише в журнал «Операція перервана користувачем!». Де саме це сталося, визначає, що лишилося в каталозі:

• Зупинили під час читання файла — у каталозі не зміниться нічого: до записування справа ще не дійшла.
• Зупинили після того, як додано розділи — розділи лишаються, товари не чіпаються.
• Обірвалося посеред записування товарів — лишається рівно те, що встигло записатися. Єдиної транзакції тут немає: прогін виконує послідовність окремих запитів — спершу заводить нові картки з їхніми описами й зв'язками з розділами, потім оновлює наявні, далі атрибути й фото. Обрив між цими кроками лишає в базі все, що пройшло до нього.

Повторний запуск безпечний і роботу не задвоює. Тимчасові таблиці прогону створюються наново на кожен запуск, тож недороблене попереднього разу не домішується. Картки шукаються за тим самим ключем: те, що вже створено, оновиться, а не задублюється. Умова одна — id у фіді від прогону до прогону не змінюються.

Прогін, який упав разом із процесом, видно в Центрі операцій: картка операції, що 15 хвилин не пише в журнал жодного рядка, сама отримує статус помилки. Отже, якщо картка досі «виконується», а рядки йдуть — робота триває, просто крок довгий.

Якщо дублі вже з'явилися

Дублі від нестабільного id впізнаються за трьома ознаками: назва однакова, «ID товару (рядок UUID)» різний, «Дата додавання» — день того прогону. Усі три колонки є в сітці товарів, за всіма трьома можна фільтрувати. Далі — на вибір:

• Відібрати й видалити в сітці. Увімкніть колонки «Джерело: назва» і «Дата додавання», відберіть картки того прогону, перевірте кілька очима й видаліть виділене пунктом «Видалити товар».
• Вікно «Дублікати каталогу». Воно саме шукає пари однакових карток; кнопка «Застосувати» зливає підтверджені пари — лишається картка з більшим наповненням, друга видаляється. Скасувати злиття не можна.
• Один прогін у дзеркальному режимі. Прапорець «Видаляти записи в базовому каталозі, яких немає в завантаженому файлі» прибере все, чого немає в поточному фіді, — разом зі старими дублями. Область дії в нього така сама, як описано вище, тож спершу перечитайте попередження про весь каталог.

Спершу полагодьте джерело. Поки фід віддає нові id на кожну вигрузку, дублі з'являтимуться після кожного завантаження, скільки їх не прибирай. Якщо змінити джерело не можна, лишається дзеркальний режим: він прибирає старі картки в тому самому прогоні, який заводить нові.

Межі, тривалість і чи можна закривати вікно

Стелі за кількістю пропозицій програма не задає. Файл читається потоково, вузол за вузлом: значення відразу лягають у проміжний файл і вже звідти одним запитом заливаються в базу. Тому довжина фіда не впирається в пам'ять.

Скільки тривав прогін — не оцінка, а записане число. Дивіться колонку «Останнє завантаження» у списку шаблонів: під датою стоїть тривалість останнього прогону. Те саме число пише останній рядок журналу («Витрачено часу»), а всю послідовність запусків шаблону показує кнопка «Історія запусків» у шапці його картки.

Вікно журналу можна закривати. Прогін зупиняє тільки кнопка «Стоп» — закриття вікна такої позначки не ставить. Журнал ведеться в базі, тож у Центрі операцій він лишається й після того, як вікно закрили. Прогін за розкладом від браузера не залежить узагалі, тому великий фід надійніше ставити на розклад, а не запускати руками.

Як зрозуміти, що процес іде. У журналі лічильник прочитаних товарів оновлюється кожну тисячу пропозицій, розділів — кожну сотню. Тобто на фіді в кілька сотень позицій рядок «З файлу отримано товарів» може не з'явитися жодного разу — це нормально, підсумок усе одно буде в рядку «Всього товарів завантажено».

Обмеження на розмір файла, який ви вибираєте з комп'ютера, задає сервер, а не програма; коли файл не доїхав, у журналі буде «Файл не вдалося передати на сервер. Можливо, він завеликий або зв'язок обірвався». На завантаження за посиланням це обмеження не поширюється: там файл забирає сам сервер.

Часті труднощі

Найчастіші проблеми з XML — кодування й адреса. Файл має бути у кодуванні UTF-8, інакше кирилиця «поламається». Посилання має вести напряму на фід, а не на сторінку із захистом чи авторизацією. Друга типова дрібниця — валюта: якщо у фіді немає курсу, а ціни в іншій валюті, задайте курс у своєму довіднику валют, інакше перерахунок не відбудеться. І третє — нестандартний XML: якщо назви вузлів довільні (кожна система вигадує свої), Elbuz не знатиме, де ціна, а де картинка; такий файл вантажать універсальним імпортом, де відповідність полів ви задаєте самі.

Часті питання

Яка різниця між XML і YML?

YML — це XML із фіксованою структурою, яку задав Yandex Market. Для Elbuz це один тип шаблону: якщо файл відповідає структурі YML (yml_catalog, offers, categories), колонки розмічати не треба. Довільний XML із власними назвами вузлів вантажать універсальним імпортом.

За чим Elbuz упізнає товар при повторному імпорті?

За атрибутом id пропозиції — він зберігається у поле UUID товару. Якщо id стабільний, повторний імпорт оновлює наявну картку. Якщо id у фіді щоразу різний, з'являться дублі.

Як читається наявність?

З атрибута available: true → «у наявності», false → «немає». Якщо у фіді текстовий елемент наявності (presence/stock), він зіставляється за вашими правилами визначення статусу. Без наявності застосовується статус за замовчуванням.

Ціни у фіді в іншій валюті — що буде?

Elbuz перерахує їх у вашу базову валюту за курсом: спершу за курсом із самого фіда (блок currencies), а якщо його немає — за курсом із вашого довідника валют. Тому важливо, щоб курс потрібної валюти був заданий.

Як переносяться різновиди (варіанти)?

Через атрибут group_id: пропозиції з однаковим group_id складаються в один товар із варіантами, перша в групі — основна. Так варіанти лишаються згрупованими.

Чому в товарах немає опису чи характеристик?

Elbuz бере лише те, що є у фіді. Якщо у пропозиції немає description чи param, відповідні поля лишаться порожніми. Дозаповнити картки можна окремо — зібрати опис, фото й характеристики зі сторонніх сайтів парсером.

Що буде з товаром, якого не стало у фіді?

За замовчуванням — нічого: картка лишається з тією самою ціною, статусом і залишком. Видаляє такі позиції лише прапорець «Видаляти записи в базовому каталозі, яких немає в завантаженому файлі», і видаляє остаточно — разом з описом, фото й атрибутами. Перед тим як його вмикати, прочитайте розділ про область видалення: без прапорця перевірки унікальності під нього потрапляє весь каталог.

Як зупинити автоматичне оновлення, нічого не видаляючи?

Перемкніть пілюлю в шапці шаблону на «Вимкнений». Планувальник такий шаблон пропускає, завантажені товари лишаються недоторканими, розклад і налаштування зберігаються. Кнопка «Завантажити» в самій картці шаблону при цьому працює й далі, а після зворотного вмикання все продовжується як було.

Чи безпечно запускати завантаження вдруге, якщо перше обірвалося?

Так. Тимчасові таблиці прогону створюються наново, а картки шукаються за тим самим ключем: уже створене оновиться, а не задвоїться. Умова одна — id у фіді не змінюються від вигрузки до вигрузки.