О формате XML-файла импорта в инфоблоки Битрикса

mike 26 октября 2018

В предыдущей статье на тему переноса контента в Битрикс мы рассказали об основных задачах, которые необходимо решать для массового импорта данных. Также отметили, почему XML файл посчитан нашей студией наиболее пригодным для осуществления импорта данных в Битрикс.

В этой статье мы вкратце осветим тему построения XML структуры файла импорта.

Что должен содержать XML файл

Укрупнённо XML файл импорта-экспорта имеет следующую структуру:

<КоммерческаяИнформация ВерсияСхемы="2.021« ДатаФормирования="01.01.2001T12:00:00«>
    <Классификатор>
        <Ид>42</Ид>
        <Наименование>Наименование</Наименование>
        <! — 
            Описание свойств элементов и структуры инфоблока, 
            т. е. какие данные инфоблок должен (может) содержать, например:
            — активность элемента
            — картинка „подробно“
            — свойства, которые дополнительно созданы для инфоблока
            — разделы (папки)
        -->
    </Классификатор>
    <Каталог>
        <Ид>42</Ид>
        <ИдКлассификатора>42</ИдКлассификатора>
        <! — 
            Ещё разные элементы, описывающие инфоблок, например
            — код инфоблока альфанумериками    
            — нужно ли индексировать элементы
            — и т. п.
        -->
        <Товары>
            <Товар>
                <! — 
                    Самый главный XML элемент, содержит данные 
                    для импортируемого элемента инфоблока 
                -->
            </Товар>
        </Товары>
    </Каталог>
</КоммерческаяИнформация>

Как видно, файл содержит два основных раздела — <Классификатор/> и <Каталог/>. Несколько слов о каждом из них.

<Классификатор/>

Предназначен для описания, ну скажем так, схемы инфоблока (примерно как схема БД), т. е. описывает поля и свойства, которые у инфоблока имеются (или должны иметься). Кстати, с точки зрения импорта, тем более если мы импортируем в уже существующий инфоблок, это очень важный раздел, так как в случае его отсутствия Битрикс любезно допишет в инфоблок свойства, которые, как он считает, должны быть там по умолчанию — Цена, ШтрихКодТовара, Изгтовитель, Вес и еще много подобных. Удалять их придётся вручную.

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

<Каталог/>

Предполагает наличие дополнительной информации об инфоблоке, такой как буквенно-цифровой код инфоблока (например, ‘news’), код сортировки инфоблока в списке, флаг разрешения индексации элементов и прочие.

Самым важным элементом в каталоге является, конечно, элемент <Товары/>, который содержит те данные, которые мы собираемся импортировать, в виде <Товар/>-ов.

Идентификация

В Битриксе для инфоблоков и их содержимого существует понятие „внешних“ кодов (XML_ID или EXTERNAL_ID), которые нужны для связи с внешним миром. То есть если для целей импорта надо каким-то образом идентифицировать инфоблок, его раздел, или его элемент, надо применять такой внешний код. В интернете этот вопрос поднимался много раз (здесь, здесь, здесь, и далее по списку google).

Соответственно, всё, что содержит в себе файл импорта, будет записано в тот инфоблок, который:

имеет внешний код, равный <Ид> внутри <Классификатор/>-а;
имеет внешний код, равный <Ид> и <ИдКлассификатора> внутри <Каталог/>-а.

Обращаем внимание, что внутри <Каталог/>-а должно быть именно два различных элемента (с одинаковым значением). В документации по формату (пусть это слишком громкое название, но она есть, оказывается — доступна здесь) оба этих элемента упомянуты как несущие идентичную семантическую нагрузку („Идентификатор каталога.“). Почему это так и какая логика предполагалась разработчиками формата — неизвестно, и, судя по всему, навсегда останется тайной.

Во время импорта при добавлении элемента инфоблока для него (элемента) будет создан обычный уникальный ID (тот самый, к которому все привыкли: $arResult[„ELEMENT_ID"]), и также ему будет присвоен внешний код (XML_ID), значением которого будет установлено то, что содержится в файле импорта в элементе <Ид> соответствующего <Товар>-а. Учитывая наличие такого кода, при очередном импорте, если в файле импорта найдётся <Товар> с таким <Ид>, что в Битриксе в инфоблоке, куда осуществляется импорт, уже есть элемент с аналогичным XML_ID, такой элемент будет обновлён (а не добавлен новый).

Отметим также, что теоретические размышления наводят на мысль, что существует гипотетическая возможность в одном файле импорта разместить несколько <Классификатор/>-ов и несколько <Каталог/>-ов. На практике таких экспериментов нами пока поставлено не было, упоминаний в интернете об этом мы тоже не встречали. Если кто-то эти опыты поставит раньше нас — будем очень благодарны и обновим данную статью.

Импортируемые файлы

Файлы, которые должны быть импортированы в инфоблок как свойства элементов, при импорте должны лежать где-то таким образом, чтобы в файле импорта до них был прописан путь относительно файла импорта. На примере картинки «подробно» (DETAIL_PICTURE):

имеется news.xml

…
<Товар>
   <Ид>42</Ид>
   <Наименование>Название новости</Наименование>
   <Картинка>news_files/picture.png</Картинка>
   …
</Товар>
…

тогда должно быть расположение файлов:

/uploads/
   news.xml
   news_files/
       picture.png

Свойства элементов

Все импортируемые данные каждого элемента должны быть описаны в дочерних элементах каждого <Товар/>-а. Они могут быть как простыми элементами, вроде:

…
<Товар>
   <Ид>42</Ид>
   <Наименование>Название новости</Наименование>
   <Картинка>news_files/picture.png</Картинка>
   …
</Товар>
…

так и иметь более сложную структуру, как, например:

…
<Товар>
   …
   <ЗначенияСвойств>
       <ЗначенияСвойства>
           <Ид>CML2_ACTIVE</Ид>
           <Значение>true</Значение>
       </ЗначенияСвойства>
       <ЗначенияСвойства>
           <Ид>CML2_CODE</Ид>
           <Значение>peredaca-predmetov-vremen-vov</Значение>
       </ЗначенияСвойства>
   </ЗначенияСвойств>
   …
</Товар>
…

множественные свойства имеют такую форму:

…
<Товар>
   …
   <ЗначенияСвойств>
       <ЗначенияСвойства>
           <Ид>142</Ид>
           <Значение>Значение 1</Значение>
           <ЗначениеСвойства>
               <Значение>Значение 1</Значение>
               <Описание/>
           </ЗначениеСвойства>
           <Значение>Значение 2</Значение>
           <ЗначениеСвойства>
               <Значение>Значение 2</Значение>
               <Описание/>
           </ЗначениеСвойства>
       </ЗначенияСвойства>
   </ЗначенияСвойств>
   …
</Товар>
…

А так выглядит структура некоторых свойств, значения которых, по логике Битрикса, не должны быть описаны прямым образом в xml структуре, но должны быть представлены в виде сериализованных данных:

…
<Товар>
   …
   <ЗначенияСвойств>
       <ЗначенияСвойства>
           <Ид>108</Ид>
           <Значение>s: 13:"simple string«;</Значение>
           <ЗначениеСвойства>
               <Значение>s: 13:"simple string«;</Значение>
               <Описание/>
               <Сериализовано>true</Сериализовано>
           </ЗначениеСвойства>
       </ЗначенияСвойства>
   </ЗначенияСвойств>
   …
</Товар>
…

Обратите внимание: <Значение/>-я содержат строку — результат PHP-сериализации строчного литерала ‘simple string’ вместо строки, и <ЗначениеСвойства> содержит элемент <Сериализовано/> со значением true. В такой форме должны быть представлены данные для свойства с типом „Видео“, например: там будет содержаться сериализованный ассоциативный массив всех характеристик видеофайла (путь к файлу, высота и ширина, название, продолжительность, и прочие).

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

Ошибки импорта

Если во время импорта произойдут какие-либо ошибки, Битрикс обязательно об этом сообщит. На этом любезности и удобства заканчиваются, так как не будет не только указаний о том, какие ошибки произошли, но также умалчивается, при импорте каких именно элементов они случились (представьте ситуацию — импорт на 4 тысячи элементов, и 2 ошибки в конце, видимо, предлагается беглым осмотром инфоблока в админке установить, что не импортировалось). В данном случае реальный способ выявить ошибочные — провести экспорт из инфоблока и сопоставить фактически попавшие в инфоблок элементы с исходным файлом импорта.

Ошибки из-за ЧПУ кодов

Как мы уже отмечали в предыдущей статье, Битрикс не генерирует ЧПУ коды во время импорта (даже если в настройках полей инфоблока установлена опция „Транслитерировать из названия при добавлении элемента.“ — вероятно, по мнению Битрикса, на импорт через XML это не распространяется). Соответственно, если кроме этого стоит галочка обязательности кода, то если импортировать элемент без кода, это вызовет ошибку, а если галка обязательности не указана, то проимпортируется с пустым кодом. Если код вам нужен, то оба сценария вас не устраивают. Технический момент: если вы импортируете в инфоблок, где уже есть элементы, необходимо позаботиться о том, чтобы ЧПУ коды импортируемых элементов не дублировали уже имеющиеся.

Ошибки из-за файлов

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

Ошибки формата

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

Обязательные данные

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

Бэкап перед импортом?

Во избежание проблем, тем более, если нет уверенности, что сформированный вами пакет импорта не приведёт к непредсказуемым результатам, сделайте архивную копию данных перед началом импорта. Идеальным подходом (в экосистеме Битрикса) делать это всегда.