1С таблица значений в json

Реализовано в версии 8.3.7.1759.

Некоторое время назад мы рассказывали о том, что в платформе реализованы средства работы с JSON. Потоковая запись/чтение и сериализация примитивных типов и коллекций.

Теперь мы рады рассказать вам о том, что мы полностью автоматизировали работу с JSON и реализовали в платформе третью группу средств. Они позволяют сериализовать в JSON прикладные типы 1С:Предприятия: ссылки, объекты, наборы записей и вообще любые типы, для которых поддерживается XDTO сериализация. Конечно же, мы обеспечили и обратную операцию — десериализацию.

Зачем это нужно

Прежде всего, и в основном, XDTO сериализацию в JSON мы рекомендуем использовать при обмене данными между двумя прикладными решениями 1С:Предприятия. По сравнению с XML формат JSON более компактный, сериализация/десериализация в/из JSON выполняется быстрее. Кроме этого мы предприняли дополнительные меры для того, чтобы сократить объём передаваемых данных.

Кроме обмена между приложениями 1С:Предприятия этот механизм можно использовать и для обмена с внешними системами, готовыми принимать типы данных 1С:Предприятия. Например, XDTO сериализацию в JSON можно использовать для организации собственного HTTP интерфейса прикладного решения. Сервис на платформе 1С:Предприятия будет формировать ответ в памяти в виде строки JSON. А затем передавать её при помощи объекта HTTPСервисОтвет. Реализованный нами механизм сериализации полностью соответствует стандарту JSON. Поэтому внешняя система не должна испытывать каких-либо трудностей с десериализацией.

Использование XDTO сериализации в JSON для других задач видится нам маловероятным. Потому что если внешняя система не готова работать с прикладными типами 1С:Предприятия, то зачем их ей передавать? А если предполагается обмениваться только примитивными типами и коллекциями, то для этой задачи хорошо подходят методы ПрочитатьJSON() и ЗаписатьJSON(), о которых мы рассказывали ранее.

Как это выглядит

Простейший код, выполняющий сериализацию элемента справочника, может выглядеть так:

В результате будет получен файл JSON следующего содержания:

Десериализацию такого файла можно выполнить следующим кодом:

В результате будет получен элемент справочника Контрагенты с наименованием Мосхлеб ОАО и кодом 000000012.

Особенности сериализации

Как вы уже могли заметить, сериализация/десериализация выполняется с помощью объекта СериализаторXDTO. Поэтому получаемая структура документа имеет «родовые черты» XML, JSON получается «похожим» на XML. Это оказывает отрицательное влияние и на «читаемость» и на компактность файла. Это своеобразная «плата» за удобства, получаемые от использования XDTO. Если же «чистота» получаемого JSON имеет для вас решающее значение, мы рекомендуем использовать инструменты, о которых мы рассказывали ранее.

Общие принципы сериализации в JSON идентичны XDTO сериализации в XML. В частности:

• Структура данных соответствует структуре XML документа;
• Имеются незначительные отличия, связанные с особенностями хранения типов и представлением массивов в JSON;
• Порядок и состав свойств JSON соответствует структуре объекта конфигурации и не может изменяться.

Кроме этого есть одна важная особенность. В отличие от XML, для записи начала объекта JSON нет необходимости указывать его имя. По этой причине сериализация/десериализация JSON может выполняться одним из двух способов.

Либо при сериализации вы указываете явное назначение типа и потом десериализуете без указания типа считываемого значения:

Либо вы сериализуете в JSON без явного назначения типа. Но тогда тип нужно будет указать при десериализации:

Ещё одна особенность сериализации заключается в том, что мы стремились оптимизировать объём результирующего файла. Поэтому для встроенных типов платформы пространства имен не записываются полностью в отдельном свойстве JSON, а указываются в виде префикса перед типом:

В данном случае префикс jcfg обозначает пространство имён http://v8.1c.ru/8.1/data/enterprise/current-config. Соответствие префиксов пространствам имён «зашито» в платформу. Поэтому каких-либо трудностей с определениями типов при обмене между приложениями 1С:Предприятия не возникает.

А при обмене с внешними системами, для правильной десериализации типов платформы, внешней системе понадобится полная таблица соответствия. Такая таблица есть, и она опубликована в документации.

Особенности десериализации

Общие принципы десериализации также связаны с использованием механизма XDTO. В частности:

• Десериализуются только те типы, которые поддерживают XDTO сериализацию;
• Порядок свойств JSON должен соответствовать структуре объекта конфигурации.

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

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

Допустим, в исходной базе описание товара хранится в HTML виде. А в вашей базе достаточно текстового описания, или такое описание вообще не нужно. Потому что у вас будет собственное описание.

Тогда, имея файл следующего содержания:

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

В результате этого кода будет прочитан объект СправочникОбъект.Товары, у которого реквизит Описание будет содержать пустую строку:

Реализовано в версии 8.3.6.1977.

JSON (JavaScript Object Notation) это текстовый формат обмена данными, широко используемый в веб-приложениях. По сравнению с XML он является более лаконичным и занимает меньше места. Кроме этого все браузеры имеют встроенные средства для работы с JSON.

Необходимость работы с этим форматом на уровне платформы обусловлена не только тем, что это «модный современный» формат, который прикладные решения 1С:Предприятия сами по себе могут использовать для интеграции со сторонними приложениями. Другая причина заключается ещё и в том, что JSON активно используется в HTTP интерфейсах. А в 1С:Предприятии как раз есть такие механизмы, в которых хочется использовать этот формат. Это REST интерфейс приложения, автоматически генерируемый платформой, и HTTP-сервисы, которые вы можете создавать самостоятельно.

Мы видим несколько основных сценариев использования JSON.

Во-первых, это интеграция с внешними системами через их HTTP интерфейсы: Google Calendar, Salesforce.com, REST интерфейс 1С:Предприятия, SharePoint и т.д.

Во-вторых, это организация собственного HTTP интерфейса прикладного решения.

В-третьих, обмен файлами JSON с внешними системами. Формирование конфигурационных, настроечных файлов. Использование их в процедурах обмена данными, например, с интернет-магазинами.

В-четвертых, это использование файлов JSON для обмена данными между разными приложениями 1С:Предприятия.

В платформе мы реализовали несколько слоёв работы с JSON. Самые простые и гибкие — это низкоуровневые средства потоковой записи и чтения. Более высокоуровневые и не такие универсальные — средства сериализации в JSON примитивных типов и коллекций 1С:Предприятия.

Потоковое чтение и запись JSON

Объекты потоковой работы — это общие объекты ЧтениеJSON и ЗаписьJSON. Они последовательно читают JSON из файла или строки, или последовательно записывают JSON в файл или строку. Таким образом, чтение и запись JSON происходят без формирования всего документа в памяти.

В качестве иллюстрации потокового чтения JSON можно привести следующий пример:

При записи JSON вы самостоятельно формируете его структуру. Чтобы «подстраховать» вас от ошибок, объект ЗаписьJSON автоматически проверяет правильность записываемой структуры. Для увеличения скорости работы эту проверку можно отключить. В примере ниже это строка:

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

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

Результат такой записи:

Сериализация примитивных типов и коллекций в JSON

Вторая группа средств работы с JSON хороша тем, что избавляет вас от рутинной работы по чтению/записи каждого отдельного значения или свойства. При чтении документы JSON отображаются в фиксированный набор типов платформы: Строка, Число, Булево, Неопределено, Массив, ФиксированныйМассив, Структура, ФиксированнаяСтруктура, Соответствие, Дата. Соответственно, в обратную сторону, композиция объектов этих типов позволяет сформировать в памяти и быстро записать в файл структуру JSON. Таким образом, чтение и запись небольшого объема JSON заранее известной структуры можно производить немногими строчками кода.

Основное назначение этих средств мы видим в обмене информацией с внешними системами, чтении конфигурационных файлов в формате JSON.

Сериализацию вы можете выполнять с помощью методов глобального контекста ПрочитатьJSON() и ЗаписатьJSON(). Они работают в связке с объектами ЧтениеJSON и ЗаписьJSON.

В качестве примера десериализации JSON можно рассмотреть чтение массива из двух объектов:

Код 1С:Предприятия, выполняющий десериализацию, может выглядеть следующим образом:

А пример сериализации (записи) в JSON может выглядеть так:

Функции преобразования и восстановления при сериализации

Не всегда сериализация может быть выполнена полностью автоматически. В жизни встречаются самые разные ситуации. Поэтому мы добавили возможность использовать «самописную» функцию обработки значений при записи в JSON и при чтении из JSON.

В методе ЗаписатьJSON() она называется Функция преобразования и описывается с помощью трёх параметров:

• ИмяФункцииПреобразования;
• МодульФункцииПреобразования;
• ДополнительныеПараметрыФункцииПреобразования.

В методе ПрочитатьJSON() она называется Функция восстановления и для неё есть аналогичные параметры:

• ИмяФункцииВосстановления;
• МодульФункцииВосстановления;
• ДополнительныеПараметрыФункцииВосстановления.

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

Например, так оказалось, что в записываемой структуре одно из значений — это ссылка на элемент справочника ПодразделенияОрганизаций. Такое значение (ссылка на объект 1С:Предприятия) не может быть автоматически сериализовано средствами платформы. Тогда, используя функцию преобразования, мы можем получить для этого значения его строковое представление в удобном виде. Например, в виде строки «ИП Петров: Отдел рекламы».

Результат выполнения примера:

При чтении из JSON функция восстановления может использоваться для того, чтобы преобразовать данные JSON в типы 1С, которые не могут являться результатом автоматического преобразования, или для того, чтобы самостоятельно (не автоматически) преобразовать даты JSON в даты 1С:Предприятия.

Сериализация типа Дата

Данные типа Дата сериализуются в JSON автоматически, а вот обратное преобразование (десериализация) может быть выполнено не всегда. JSON не содержит типа Дата, значения даты представляются в нём строкой. Конечно, существуют некоторые форматы представления дат, но вообще говоря, внешний вид такой строки может быть самым разнообразным.

Для сериализации типа Дата в JSON у метода ЗаписатьJSON() вы можете использовать параметр НастройкиСериализации. Это объект встроенного языка, который позволяет указать, в каком варианте будет записана дата (UTC, локальная дата или локальная дата со смещением) и в каком формате (ISO, JavaScript или Microsoft).

При чтении даты из JSON всё обстоит сложнее. В параметре ИменаСвойствСоЗначениямиДата вы можете перечислить те свойства JSON, значения которых нужно преобразовать в дату 1С:Предприятия (тип Дата). А в параметре ОжидаемыйФорматДаты вам нужно указать, в каком формате эти данные содержатся в JSON (ISO, JavaScript или Microsoft).

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

В такой ситуации, для большей универсальности, вы можете включить те же самые свойства JSON в массив, подлежащий обработке функцией восстановления — ИменаСвойствДляОбработкиВосстановления. И уже в функции восстановления вы самостоятельно десериализуете даты JSON, в каком бы формате они ни были представлены.

Использование JSON в HTTP интерфейсах приложений

Автоматически генерируемый REST интерфейс прикладных решений

При обращении к REST интерфейсу прикладного решения вы можете получать ответ в формате JSON. Для этого в адресной строке вам нужно указать параметр $format=json. Либо указать MIME тип "application/json" в заголовке Accept HTTP запроса. Например:

Вы можете управлять объёмом передаваемой информации за счёт изменения детальности представления метаданных в выгрузке. Существуют три уровня: Nometadata, Minimalmetadata и Fullmetadata. По-умолчанию (на примере вверху) используется средний уровень — Minimalmetadata. На уровне Nometadata объём передаваемой информации минимальный, а на уровне Fullmetadata — максимальный. Однако при этом нужно понимать, что сокращение объёма передаваемой информации приводит к более интенсивным вычислениям на клиенте. И наоборот, когда вся информация включается в выгрузку, объём вычислений на клиенте будет минимальным.

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

Сведения о метаданных не передаются:

Вся информация о метаданных включается в выгрузку:

HTTP-сервисы прикладного решения

HTTP-сервисы, реализованные в прикладном решении, также могут возвращать ответ в формате JSON. Для этого вам проще всего сформировать тело ответа в JSON, получить его как строку, а затем установить из этой строки тело HTTP ответа сервиса. При этом желательно указать, что BOM (Byte Order Mark, метка порядка байтов) использоваться не должна.

Последний параметр (ИспользованиеByteOrderMark.НеИспользовать) вы можете и не указывать, если режим совместимости конфигурации не установлен, или он больше чем Версия8_3_5. Потому что в этом случае BOM автоматически будет использоваться только для кодировок UTF-16 и UTF-32, а для UTF-8, UTF-16LE/UTF-16BE, UTF-32LE/UTF-32BE и других она использоваться не будет.

Взаимодействие со сторонними HTTP сервисами

При взаимодействии со сторонними HTTP интерфейсами у вас также может возникнуть необходимость формирования запросов к ним в формате JSON. В этом случае алгоритм ваших действий будет аналогичным. Формируете тело запроса в JSON. Получаете тело в виде строки. Из этой строки устанавливаете тело HTTP запроса. BOM не используете.

Дальнейшее развитие

Мы думаем над тем, чтобы предоставить вам возможность сериализации в JSON прикладных типов 1С:Предприятия: ссылок, объектов, наборов записей и т.д. Поэтому есть вероятность появления ещё одного, третьего уровня средств работы с JSON. Этот уровень позволит вам преобразовывать в JSON любые типы 1С:Предприятия, для которых поддерживается XDTO-сериализация в XML.

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

По сути, при работе с JSON требуется две операции: сформировать строку JSON (например, для передачи параметров на веб-сервер в формате JSON из 1С) и прочитать данные из строки JSON (например, когда мы получаем ответ от веб-сервера в формат JSON). Так как формат JSON в упрощенном виде представляет собой набор параметров в виде : то для работы с JSON в 1С мной был использован тип "Структура". Т.е. процедура чтения данных из формата JSON преобразует строку JSON в тип 1С "Структура". Так же и строка JSON в 1С формируется из структуры. Т.о. чтобы сформировать строку JSON сначала необходимо заполнить структуру необходимыми значениями, а потом вызвать функцию, преобразующую структуру в JSON. Позднее функционал функции формирования строки JSON был расширен — теперь в JSON может быть преобразован массив и таблица значений. При желании можно доработать функцию так, чтобы она "понимала" и другие типы. Такие как "Cоответствие", "ДеревоЗначений" и др. На практике это редко может пригодиться, поэтому сам я этого делать не стал.

А теперь подробней о том, как работать с функциями преобразования JSON.

Преобразование строки JSON в структуру 1С.
Для преобразования строки JSON в структуру 1С служит функция ЗаполнитьСтруктуруИзJSON().
Код 1C v 8.х
(обязательный) — строка в формате JSON,
которую необходимо преобразовать в структуру.

Возвращаемое значение.
Тип Структура.
Имя значения задается в структуре как Ключ, а само значение, соответственно, как значение. Поддерживаются также вложенные значение ("<>" в "<>") и массивы. В таких случаях тип значения будет Структура и Массив соответственно. Если у в JSON задан только массив, то сформируется структура с одним элементом с ключом "Значение" и типом "Массив". Ниже приведены поясняющие примеры:
Код 1C v 8.х

Следует заметить, что все значения заполняются как строковые (тип "Строка"). Последующее преобразование (например, к числу) лежит на самом разработчике.

Формирование строки JSON в 1С.
Для формирования строки в формате JSON в 1С предназначена функция СформироватьСтрокуJSON().
Код 1C v 8.х
(обязательный) — объект, который необходимо
преобразовать в формат JSON. Может иметь тип "Структура",
"Массив" или "ТаблицаЗначений".
Если Объект имеет тип "ТаблицаЗначений", то она рассматривается как массив из структур, соответствующих колонкам ТЗ. Все значения приводятся к строковому типу, дата приводится в формат unixtime, значение типа булево "Истина" преобразуется в строку "true", а "Ложь" — в "false, прочие объекты просто преобразуются как "Строка(Объект)".

Ниже приведены поясняющие примеры.
Код 1C v 8.х
Автор: Павел Толкачев