YML — різновид XML для товарних каталогів, який став фактичним стандартом обміну: у ньому приймають фіди маркетплейси, агрегатори цін, рекламні кабінети, CMS і чимало облікових систем. Якщо сервіс просить «XML-фід», «прайс у форматі YML» або «товарний файл» — майже завжди йдеться саме про нього.
У Elbuz є готові типи вивантаження під конкретні майданчики, де все вже підігнано під їхні вимоги. А є універсальний YML — для всіх інших випадків: коли сервіс приймає стандартний фід, коли файл потрібен партнеру чи підряднику, коли ви робите фід під власний сайт. Про нього ця стаття.
Зворотний напрямок — читання чужого YML — описано в статті про імпорт каталогу з XML / YML. Загальні правила будь-якого вивантаження (відбір товарів, ціни, запуск, журнал) — в огляді вивантаження товарів; тут лише те, що стосується формату.
Де це у програмі
У вікні вивантаження створіть шаблон: у списку типів відкрийте групу «XML-фід (YML)» й оберіть «YML (XML)» — це і є універсальний фід, решта пунктів групи налаштовані під конкретні майданчики. Один шаблон — один файл: якщо фіди потрібні різним сервісам і з різним складом даних, робіть окремі шаблони, а не переналаштовуйте один.
1
Поле з текстом шаблону- Поле з текстом шаблону — початок файлу yml_catalog/shop із макросом {datetime}.
Що всередині файлу
Новий шаблон одразу створюється з готовим фідом — переписувати його з нуля не потрібно. У файлі три частини:
| Частина файлу | Що в ній |
|---|---|
| Шапка | Кореневий вузол yml_catalog з датою вивантаження, далі shop: назва магазину, компанія, адреса сайту, службові відомості про платформу й пошта. Тут же блок currencies — валюта фіда та її курс |
| Категорії | Блок categories, у ньому рядок category на кожен розділ: власний ідентифікатор, ідентифікатор батьківського розділу й назва. Так у файлі відтворюється ваше дерево |
| Пропозиції | Блок offers, у ньому offer на кожен товар: посилання, ціна, валюта, категорія, фото, назва, виробник, артикул, опис і характеристики |
Рядок категорії й рядок товару розмножує сама програма: у шаблоні вони описані один раз, а у файл потрапляють стільки разів, скільки у вас розділів і товарів.
Шаблон XML: файл складаєте ви
Головна відмінність цього типу вивантаження від решти: вміст файлу задаєте ви самі, у полі «Шаблон XML». Це один суцільний документ — такий, яким має вийти фід, — а замість значень у ньому стоять макроси у фігурних дужках: {name}, {price}, {uuid} і так далі. Під час вивантаження кожен макрос замінюється значенням конкретного товару.
Звідси гнучкість: сервіс просить додатковий вузол — ви дописуєте рядок у шаблон; просить інше ім'я вузла — перейменовуєте; не приймає опис — прибираєте. Жодного програмування, звичайний текст.
Коли значення треба не просто підставити, а обчислити — у шаблоні працюють формули у подвійних квадратних дужках: наприклад, віддавати рекомендовану ціну, якщо вона заповнена, і звичайну, якщо ні. Синтаксис і приклади — в огляді вивантаження товарів, розділ про ціну.
Не тримайте назви макросів у голові: натисніть Ctrl+Space або просто введіть { — і з'явиться підказка. Поруч із полем є повний довідник макросів, згрупований за змістом: поля товару, мовні версії полів, спец-макроси, категорії маркетплейсів, генератор описів і посадкові сторінки, шапка файлу та ім'я файлу. Клік по макросу вставляє його в позицію курсора.
Нерозпізнані макроси під час вивантаження просто зникають із результату — без попередження й без запису в журналі. Тобто описка у назві дасть не помилку, а порожній вузол у фіді, і помітите ви це вже на боці сервісу. Саме тому перед першим бойовим запуском варто зробити пробне вивантаження — воно якраз показує макроси, які програма не впізнала (див. нижче).
Підшаблони: фото й характеристики
У товара не одне фото й не одна характеристика, тому для них є окремі підшаблони — рядки, які повторюються стільки разів, скільки у товара фотографій або атрибутів. У головному шаблоні на їхньому місці стоять макроси {image_list} і {attribute_list}, а самі рядки задаються у картці «Підшаблони».
Приклад із життя: одному сервісу потрібні фото вузлом picture, іншому — image з атрибутом, третьому головне фото окремо від решти. Усе це — правка одного рядка підшаблону, головний шаблон не чіпається.
Ідентифікатор товару
У пропозиції offer ідентифікатором за замовчуванням іде UUID товару — власний незмінний ключ картки в Elbuz. Це важливо для будь-якого приймача фіда: доки ідентифікатор стабільний, сервіс оновлює наявні позиції; якщо ж він змінюється від вивантаження до вивантаження, на тому боці плодяться дублі.
Той самий UUID читає й імпорт: коли фід із Elbuz завантажується назад — у вас чи у партнера, — товари впізнаються за ним і не дублюються. Тому міняти ідентифікатор у шаблоні варто лише тоді, коли приймач фіда прямо вимагає іншого (наприклад, числового коду).
Поруч стоїть атрибут групування: різновиди одного товару (кольори, розміри) отримують спільний ідентифікатор головної картки, тож на боці приймача вони складаються в один товар із варіантами, а не розсипаються окремими позиціями.
Наявність
Наявність у пропозиції — це атрибут available, і підставляє його макрос {xml_stock_status}. Значення береться не з повітря: у картці «Пов'язані налаштування» є кнопка «Статуси наявності», де кожному вашому статусу задається, що саме піде у фід і яку кількість показувати. За замовчуванням статус «в наявності» дає true, решта — false; якщо приймач хоче не true/false, а власні слова, впишіть їх там же.
Це зручніше, ніж здається: у вас може бути десяток внутрішніх статусів («очікується», «під замовлення», «знято з виробництва»), а у фід поїдуть лише два стани — так, як розуміє приймач.
Категорії, фото, характеристики
| Налаштування | Що робить |
|---|---|
| Категорії (галочка) | Чи включати у файл блок розділів. Деякі сервіси приймають фід без дерева — тоді галочку можна зняти |
| Символ роздільника категорій | Чим розділяти рівні у повному шляху розділу, коли він іде одним рядком |
| Фото (галочка) | Чи вивантажувати зображення |
| Посилання на фото товару | Адреса, з якої приймач качатиме фото: домен і папка. Фото віддаються посиланнями, а не файлами |
| Максимальна кількість фотографій | Обмеження на товар — у більшості майданчиків свій ліміт, і зайві фото вони або відкидають, або відхиляють увесь фід |
| Атрибути, Опції (галочки) | Чи вивантажувати характеристики й опції товару |
Обмеження вивантаження
Окрема картка задає, чий саме залишок і яка мова потрапляють у фід: магазин, склад, мовна версія полів і галочка «лише в наявності в цьому магазині». Це не те саме, що відбір товарів (він живе в загальних налаштуваннях шаблону): тут ви обираєте, з якого джерела брати числа й тексти для тих товарів, які вже пройшли відбір.
Поруч — галочка «Вивантажувати лише нові дані»: у файл потраплять тільки товари, змінені з часу минулого вивантаження. Корисно для великих каталогів і частих оновлень, але приймач має розуміти часткові фіди — інакше він вирішить, що решта товарів зникла.
Пробне вивантаження
Перед першим бойовим запуском натисніть «Перевірити». Програма виконає той самий код, що й повне вивантаження, але на одному товарі, збереже результат в окремий файл і покаже його вам — разом із переліком макросів, яких вона не впізнала. Боєвий файл і посилання на нього при цьому не чіпаються.
Це найшвидший спосіб зловити описку в назві макроса, зайвий вузол чи не ту адресу фото — на одному товарі, а не на тридцяти тисячах.
Куди лягає файл і як оновлюється
Готовий файл Elbuz кладе у ваше сховище й дає на нього постійне посилання — саме його ви віддаєте сервісу. За розкладом файл перезбирається, посилання лишається тим самим, тож налаштовувати приймач щоразу не треба. За потреби той самий файл можна класти на FTP приймача — кнопка налаштування є в картці «Пов'язані налаштування».
Частоту обирайте за товаром: якщо ціни й залишки рухливі, має сенс кілька разів на день; якщо каталог статичний — раз на добу. Докладніше про запуск, розклад і журнал прогону — в огляді вивантаження товарів.
Коли брати готовий тип, а не універсальний
Якщо приймач — відомий майданчик, для нього зазвичай уже є свій тип вивантаження: у ньому враховані обов'язкові вузли, ліміти й особливості ідентифікаторів. Універсальний YML беріть тоді, коли готового типу немає: власний сайт, партнерський обмін, сервіс аналітики, нішевий агрегатор. Перевірити просто — відкрийте список типів при створенні шаблону й пошукайте назву сервісу; немає в списку — беріть YML (XML).
Формат стандартний, але кожен сервіс додає свої умови: обов'язкові вузли, довжину назви, ліміт фото, набір валют, вимогу до категорій. Тому не орієнтуйтеся на «загальний YML» — відкрийте вимоги того сервісу, якому віддаєте фід, і підженіть шаблон під них. Пробне вивантаження на одному товарі показує результат так, як його побачить приймач.
Часті питання
Що таке YML і чим він відрізняється від звичайного XML?
YML — це XML із наперед відомою структурою для товарних каталогів: корінь yml_catalog, усередині магазин, блоки валют, категорій і пропозицій. Саме тому приймачі розуміють такий файл без додаткової розмітки, тоді як довільний XML доводиться описувати вручну.
Чи треба редагувати шаблон, якщо мене влаштовує стандартний фід?
Ні. Новий шаблон створюється вже з робочим фідом: шапка, валюта, категорії й пропозиції з основними полями. Правити його потрібно лише тоді, коли приймач просить додаткові вузли або інші імена.
Що буде, якщо помилитися в назві макроса?
Нерозпізнаний макрос під час вивантаження видаляється з результату без попередження — у файлі просто буде порожньо на цьому місці. Тому перед бойовим запуском робіть пробне вивантаження: воно показує перелік макросів, яких програма не впізнала.
Звідки береться значення available у фіді?
З таблиці «Статуси наявності» у картці «Пов'язані налаштування»: там кожному вашому статусу задано, що саме піде у фід і яку кількість показувати. За замовчуванням «в наявності» дає true, решта — false, але значення можна замінити на власні слова, якщо приймач вимагає інших.
Скільки фото потрапляє у фід і звідки беруться посилання?
Стільки, скільки задано в полі «Максимальна кількість фотографій», а адреса складається з поля «Посилання на фото товару» — домену й папки, де лежать зображення. Самі файли у фід не вкладаються: приймач качає їх за посиланнями.
Як у фід потрапляють різновиди товару?
Через атрибут групування в пропозиції: варіанти отримують спільний ідентифікатор головної картки, і приймач складає їх в один товар із варіантами. Якщо конкретний сервіс групування не підтримує, цей атрибут із шаблону прибирають.