Работа с импортом (ч.1)

Самые частые вопросы, связанные с самым востребованным модулем Diafan.CMS - "Магазином", касаются, как правило, двух тем: синхронизации с 1С и использованием функций импорта/экспорта модуля. Решил восполнить информационный пробел по второй теме и написать руководство по импорту. Подробности в статье.

После обновления функционала раздел импорта/экспорта стал доступен из двух мест в админ-панели CMS - раздела "Модули и БД" (располагается там сейчас) и раздела "Каталог" (располагался там ранее и сейчас переводит в "Модули и БД"). Вкладка "Импорт/экспорт" в разделе "Каталог"

Вкладка "Экспорт/импорт данных" в разделе "Модули и БД"

Термины и определения

Ниже перечислю основные определения и термины, используемые при работе с импортом/экспортом:

• Импорт - загрузка данных в модуль CMS через интерфейс посредством файла или удалённо через API.
• Экспорт - выгрузка (скачивание) файла с данными из модуля в виде файла с расширением CSV.
• Файл импорта - содержит в себе импортируемые данные. Такой файл со списком товаров, например, Вам может предоставить Ваш партнёр или крупная интернет-площадка торговли (дропшиппинг). В файле содержатся объекты, в качестве которых могут выступать товары, статьи, категории, производители и пр.. Всё зависит от того, какие данные и куда Вы планируете импортировать. Самым простым и часто используемым файлом является CSV-файл.
• CSV - Comma-Separated Values, формат текстовых данных. Представляет собой обычный текстовой файл с расширением .csv, данные в котором разделяются символом-разделителем. Информация о товарах (или других объектах) записана построчно (один объект - одна строка). В строке содержатся характеристики объекта, разделяемые точкой с запятой. CSV может быть открыт/отредактирован в любом текстовом редакторе, а также в табличном редакторе типа Exel (в виде таблицы). XLS-файл (таблица Exel) может быть сохранён в формат CSV для последующего импорта через меню "Сохранить как...". CSV является простым и нетребовательным к ресурсам форматом, поэтому является предпочтительным. По возможности XLS и XLSX-таблицы лучше перед импортом сохранять в формат CSV.
• Описание файла импорта/экспорта - представляет собой совокупность настроек модуля, которые определяют вид, очерёдность и формат импортируемых данных. Описание настраивается под конкретный файл с данными, который планируется импортировать. Делается это заранее (особенно если есть несколько файлов от разных поставщиков), либо прямо в процессе импорта после загрузки файла (если файл один). Описание состоит из полей, каждое из которых определяет тип и формат импортируемых данных. Например, изображение/ссылка на файл изображения, описание товара/текст описания и т.п..
• Поле - составная часть описания. Содержит название поля, его тип и настройки, которые у каждого типа поля свои.
• Тип поля - список типов данных, которые используются в модуле и могут быть в него загружены или выгружены из него. Например, идентификатор (уникальный номер), название товара, описание товара, характеристики товара и пр..
• Разделитель данных - внутри полей могут содержаться комбинированные данные, например, список цветов товара. Чтобы их отделить друг от друга в рамках одной характеристики, используют разделители.

Структура файла CSV

Для наглядности приведу ниже примеры как выглядит сам файл CSV при просмотре в текстовом и табличном (MS Excel) редакторе. При открытии в табличном редакторе Вы увидите таблицу со строками и столбцами:

В данном случае каждая строка - это товар (информация о нём и перечень его характеристик). Строка содержит ячейки, идущие слева направо, каждая из которых содержит свой тип данных. Каждый тип данных образует столбец.

На скриншоте видно, что в первом таком столбце находятся данные об изображениях товара, а именно имена файлов изображений:

112_palatkabravo5n.jpg

Второй столбец содержит название товара:

Палатка «Браво 5» N

И т.д. Если открыть файл CSV в текстовом редакторе, картина будет следующая:

Как можно заметить, в табличном редакторе товар "Палатка Браво 5" идёт под строкой №9, а в текстовом это строка №12. Всё потому, что в описаниях товара присутствуют переводы строк и текстовой редактор это учитывает. Но пусть Вас это не смущает. Главное тут не в этом, а в символах-разделителях.

Точка с запятой (;) разделяет данные в строке (ячейки). Каждый такой символ обозначает конец ячейки и начало следующей. В каждой ячейке свой тип данных. Если какая-то ячейка содержит несколько значений, то внутри ячейки данные по-умолчанию разделяются символом вертикальной черты (|).

Т.е. на скриншоте стрелка указывает на ячейку, содержащую характеристику "Цвет", а вертикальная черта разделяет два её значения - "Хаки/Бежевый" и "Синий/Голубой":

;Хаки/Бежевый|Синий/Голубой;

Имена изображений в первой ячейке также разделены вертикальной чертой:

112_palatkabravo5n.jpg|113_palatkabravo5n.jpg|114_palatkabravo5n.jpg|115_palatkabravo5n.jpg;

Открывая/сохраняя файл CSV в табличном редакторе, нужно правильно указывать кодировку файла и символ разделителя ячеек. По-умолчанию это точка с запятой. А кодировка Win-1251.

Импорт/Экспорт в автоматическом режиме

Для запуска импорта нужно перейти на вкладку "Импорт" и перейти непосредственно к процессу. При помощи интерфейса указываете расширение Вашего файла:

Рядом с пунктом CSV видим иконку шестерёнки. Это настройки кодировки и разделителя. Разделитель оставляем по-умолчанию, если Вы не знаете кодировку своего файла импорта, оставляйте ту, что по-умолчанию. В большинстве случаев она именно Win 1251.

Для других типов файлов эти настройки не нужны, поэтому иконок шестерёнок там нет. Описание процесса импорта указано для файла с расширением CSV как для типового и наиболее часто встречающегося.

Указываем файл посредством кнопки "Обзор" или указываем URL (ссылку на файл) в поле "загрузите файл по ссылке" и нажимаем кнопку "Загрузить" ниже.

На страницу выводятся настройки. Тут тоже всё можно оставить по-умолчанию. Если Вы в первый раз импортируете, то можно не трогать ничего. Единственное, отметьте галку "Опубликовать записи на сайте" (записи опубликуются сразу после импорта, в противном случае будут неактивными) и "Не учитывать первую строку в файле" (если первой строкой в файле идут названия столбцов).

Ниже, под настройками, данные из файла (первые три строки). Слева указаны типы полей, а справа - данные ячеек первых трёх строк в порядке следования слева направо.

Если стоит галка "не учитывать первую строку", первый столбец будет помечен как неактивный. Это нужно если у Вас в первой строке содержится не информация о первом товаре, а наименования столбцов (ID, Название, Цена и т.д.).

Каждое поле в списке может быть отредактировано. Можно менять его тип (выпадающий список) и настройки (иконка шестерёнки справа). Есть два нюанса, на которые стоит обратить внимание - разделители в Категориях, Изображениях и Редиректах. Я рассказывал о них в разделе, посвященном формату CSV:

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

Когда все поля настроены, можно запускать импорт. CMS предложит сохранить конфигурацию полей в виде описания файла импорта:

В поле "Название импорта" будет отображаться название описания по-умолчанию на основе выше указанных настроек. Если будет стоять галка "Создать новый импорт", то создастся новое описание с указанным в поле "Название импорта" именем.

Если в используемом ранее созданном описании в процессе что-то меняется, то можно сохранить его как новое, либо снять галку "Создать новый импорт" и нажать на кнопку "Сохранить описание импорта" (при первом импорте это Вам не понадобится). При этом данные перезапишутся:

Если снять галку и не нажимать кнопку, то импорт пройдёт по изменённым правилам, а файл описания останется неизменным.

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

По его окончании CMS либо сообщит о наличии ошибок и предоставит файл со списком ошибок для ознакомления и исправления, либо всё закончится благополучно:

После окончания процесса импорта следует перейти в раздел "Каталог" и детально ознакомиться с результатом:

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

Импорт/Экспорт в ручном режиме (настройки)

Перед началом работы нужно ознакомиться с настройками, понять какие за что отвечают и выставить нужные. Заходим в раздел "Модули и БД" в админ-панели, переходим на вкладку "Экспорт/импорт данных" и переходим по неприметной ссылке "Настройки модуля" справа вверху страницы.

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

Тут можно настроить кодировку файлов по-умолчанию и количество записей в одной итерации. Под записью имеется ввиду строка в файле (товар). Т.е. по-умолчанию за одну итерацию или один проход обрабатывается 1000 строк.

У товаров может быть по нескольку фотографий, множество характеристик, в т.ч. взаимосвязанных. Поэтому единовременная обработка 1000 и более строк может потребовать большого объёма времени и ресурсов сервера/хостинга.

Если при запуске импорта сервер возвращает ошибку 500 или появляется белый экран, либо процесс зависает на длительное время - обязательно уменьшите этот параметр. Можете смело уменьшить его до 500, 200 или даже до 50.

При снижении этого параметра файл обработается медленнее, но проблем с ресурсами и временем при этом уже не будет.

Описание файла импорта/экспорта

Файл импорта имеет строки (товары), разбитые на ячейки с данными (информация о товаре). В каждой ячейке содержится конкретный тип и набор данных. Строгих требований нет абсолютно никаких. Всё зависит от структуры имеющегося у Вас файла и описание импорта составляется под него.

Описание файла импорта/экспорта представляет собой набор полей, для каждого из которых указан свой тип данных. Каждой ячейке в файле импорта CSV соответствует Поле в описании файла импорта.

Вернёмся к скриншоту начальной страницы импорта/экспорта:

Про глобальные (общие) настройки я уже рассказал. Теперь смотрим ниже: на скриншоте представлен список описаний файлов импорта. Изначально их нет вообще (список пуст) и Вы можете загрузить стандартный набор описаний, который использовался в старой версии импорта CMS, а именно описание для производителей, товаров и категорий при помощи кнопки "Перенести описания".

Это делать необязательно, но если Вы ни разу не пользовались импортом, можно воспользоваться этим набором для наглядности. Также Вы можете создать новое описание и настроить его полностью самостоятельно.

Итак, описание файла импорта создано/перенесено и в списке имеется хотя бы один пункт (одно описание). Теперь следует его настроить/наполнить полями. Переходим в него:

Над вкладками импорт/экспорт видим ссылку "изменить" [1] - это настройки описания. Ниже представлен список полей, т.е. данные, которые будут импортироваться или экспортироваться. Экспортировать данные можно прямо тут, нажав кнопку "Скачать файл экспорта" [2]. Кнопка "Добавить поле" добавляет новое поле в список полей ниже [3]. Подробнее об этом.

Создание полей в описании

При создании нового поля Вы увидите несколько настроек (их число зависит от выбранного типа поля). На скриншоте выше представлены настройки для типа поля "Категория". Большинство типов имеют одинаковые и простые настройки (4-5 штук). Рассмотрим те, что на скриншоте:

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

2. Тип поля. Соответствует загружаемым данным. Особняком тут стоит тип "Дополнительная характеристика", в которой содержатся все характеристики товара. Сначала выбирается тип, затем выбирается характеристика. Отдельно характеристик в списке нет.

3. Если поле не должно быть пустым, то ставим эту галку. При импорте система сообщит об ошибке, если данные будут отсутствовать. Актуально, например, для типа "Цена".

4. Настройка определяет каким образом система будет обрабатывать содержащееся значение. Если в модуле уже создана категория, то у неё имеется название и идентификатор. И в систему можно передавать как первое, так и второе. Проще и понятнее работать с названиями.

   Однако, файл Вы можете получать из сторонних источников, там могут быть указаны ID и повлиять Вы на это не сможете. Придётся работать с ID, т.е. c цифрами. Разница между Импортируемый ID и ID на сайте в том, что в первом случае система назначает содержащийся в файле ID как идентификатор категории, а во втором случае она ищет совпадение указанного идентификатора с имеющимися в модуле и связывает товар с категорией, имеющий указанный ID.

5. Разделитель данных внутри поля. Для примера: данными может быть текст. И запятая в тексте может быть знаком препинания, а может быть разделителем значений. Например, цвета - синий, красный, зелёный. Зависит от контекста. Те же категории могут быть представлены в файле в следующем виде: категория_1/категория_2. В этом случае нужно указать в качестве разделителя символ слеша /. Такие разделители используются в трёх типах полей - в "Категориях", "Изображениях" (указываются alt и title вкупе с адресом/именем изображения), а также в типе "Редитект", где через разделитель указывается код редиректа (301, 302 и т.д.).

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

Полей может быть и больше. В типе "Цена" их столько:

Поскольку в данном руководстве рассматривается типовой пример импорта, я не буду разбирать настройки каждого типа поля. Поэтому допущу, что значение для типа цена будет вида "1950" (1950 рублей) и в этом поле не придётся учитывать/связывать цены, характеристики, на них влияющие, количество товара и валюты. Такие сложные варианты импорта - тема для отдельной статьи.

Новые описания файлов импорта

Если Вы создаёте новое описание вручную, то нужно учесть, что создавать нужно столько же полей, сколько ячеек содержится в строках файла импорта. Т.е. по полю на каждый тип данных. В строке может быть 1000 ячеек, но Вам по факту нужно будет всего 10 из них. В этом случае нужно будет создать 1000 полей и для 990 из них (не нужных) указать тип "Пропустить поле".

Если Вы создадите только нужные поля, то при загрузке файла зачтутся первые 10 ячеек строки, а остальные игнорируются. Поэтому в таких случаях описание лучше не создавать отдельно вручную, а сохранить его при загрузке файла импорта в автоматическом режиме, о котором было сказано выше. Так будет быстрее.

Настройки описания файлов импорта

Настройки описания [1] выглядят следующим образом:

1. Название описания (отображается в в списке описаний)

2. Модуль, в который импортируем данные. Можно импортировать не только товары, но и статьи с новостями в одноимённые модули.

3. Указываем товары, новости или статьи.

4. Указываем раздел сайта, куда импортировать. Модули в DIAFAN.CMS прикрепляются к страницам. Можно создать несколько страниц и прикрепить к каждой из них один и тот же модуль. Например, создать два "Магазина", допустим, розничный и оптовый. И в каждом из них получить свои настройки, данные и пр.. И разные процедуры импорта в том числе (по разным правилам и из разных источников).

5. В рамках конкретного модуля можно указать в какую конкретно категорию импортировать данные. Таким образом можно работать с каждой конкретной категорией индивидуально.

6. При импорте можно автоматически сгенерировать меню согласно импортируемым данным, например, получить меню в виде списка категорий товаров, которые импортированы.

7. Данный пункт очищает все имеющиеся в модуле данные и после этого начинает импортировать данные из файла. Особенно полезно при тестировании и обучении. На рабочем сайте эту настройку лучше не трогать, иначе потеряете уже накопленные данные по продажам и т.п..

8. Если у Вас на руках более новая версия файла импорта, нежели та, которую Вы загружали ранее, например, с новой категорией товаров, то можно воспользоваться этой настройкой. Тогда импортируется именно эта новая категория и её товары, а старые записи останутся нетронутыми.

9. По-умолчанию записи на сайте после импорта неактивны. Это делается для того, чтобы предварительно всё проверить перед началом продаж. Если Вы абсолютно уверены в том, что процесс пройдёт нормально или уже ранее выполняли импорт посредством этого описания, то товары можно сразу опубликовывать (делать активными).

10. Количество строк в одной итерации. Выше упоминалась глобальная настройка. Эта частная для каждого описания в отдельности.

11. Этот символ разделяет данные внутри ячейки (поля). О нём говорилось выше.

12. Часто в файлах импорта первой строкой идут названия типов данных (названия столбцов). Например, "ID", "Название" и т.д.. Если в Вашем файле так, то обязательно отметьте эту галку.

Надеюсь, статья оказалась для Вас полезной. Во второй части статьи разбираю более сложные случаи импортирования данных и работы с ними через импорт/экспорт.