JSON в 1С 8.3

JSON

Общее описание

JSON (JavaScript Object Notation) — это текстовый формат обмена данными, основанный на JavaScript. При этом JSON можно использоваться почти в любом языке программирования, в том числе и в 1С.

Формат JSON легко читается. Пример текстового файла в формате JSON:

Как правило JSON используется для обмена данными в веб-приложениях. Однако его можно применять и для обмена данными между двумя базами 1С.

JSON может включать в себя следующие элементы:

  • Объект
  • Строка
  • Число
  • Литералы: true, false, null
  • Массив

Объект

JSON-объект — это неупорядоченное множество пар ключ:значение. JSON-объект заключается в фигурные скобки { }. Между каждой парой ключ:значение ставится запятая «,». Между ключом и значением ставится двоеточие «:».

Ключ — это всегда строка, его нужно брать в двойные кавычки.

Значением может быть любой тип:

  • Другой JSON-объект
  • Массив
  • Строка
  • Число
  • Литералы: true, false, null

Пример JSON-объекта:

В данном примере три ключа:

  • ЭтоКлюч
  • ЭтоТожеКлюч
  • ЭтоВложенныйОбъект

После двоеточия указывается значение ключа. Значением для ключа «ЭтоВложенныйОбъект» является другой JSON-объект с ключами: «КлючВложенногоОбъекта» и «ЕщеКлюч».

Строка и число

Строка заключается в двойные кавычки. Число указывается без кавычек. В качестве разделителя между целой и дробной частью используется точка «.». Точность числа не ограничена. Например:

Литералы

В качестве литералов могут использоваться:

  • true — Истина
  • false — Ложь
  • null — отсутствие значения

Например:

Массив

JSON-массив — это упорядоченное множество значений. Массив заключается в квадратные скобки [ ]. Значения внутри массива разделяются запятой «,».

Пример JSON-массива:

Значения массива могут быть любого типа: строки, числа, литералы, объекты и даже другие массивы:

ЗаписатьJSON

Чтобы записать данные в формате JSON из 1с нужно:

  1. Создать программный объект ЗаписьJSON
  2. Вызвать у него метод ОткрытьФайл, передав параметром путь к файлу, куда будут записаны данные в формате JSON
  3. С помощью метода глобального контекста ЗаписатьJSON выполнить сериализацию. Параметрами нужно передать созданный объект ЗаписьJSON и сами данные
  4. Закрыть ЗаписьJSON методом Закрыть

Соответствие между типами 1С и типами JSON:

Тип 1СТип JSON
СтрокаСтрока
ЧислоЧисло
Булевоtrue или false
ДатаСтрока
Неопределеноnull
МассивJSON-массив
Фиксированный массивJSON-массив
СтруктураJSON-объект
Фиксированная структураJSON-объект
СоответствиеJSON-объект
Фиксированное соответствиеJSON-объект

Ключ соответствия и фиксированного соответствия может быть только строковым.

Например:

В результате файл будет содержать следующие данные:

В коде была использована строка:

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

Запись массива как JSON-объект

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

Сериализация таблицы значений в JSON

Таблица значений является одной из часто используемых коллекций в 1С, но для нее нет автоматической сериализации в JSON. Для сериализации можно преобразовать таблицу в массив структур, а массив сериализовать в JSON:

ПрочитатьJSON

Для чтения JSON файла используется программный объект ЧтениеJSON и метод ПрочитатьJSON:

  1. Создается программный объект ЧтениеJSON
  2. Методом ОткрытьФайл выполняется открытие файла с JSON
  3. Методом глобального контекста ПрочитатьJSON выполняется десериализация JSON
  4. Объект ЧтениеJSON закрывается методом Закрыть

Десериализация из JSON в типы 1С выполняется по следующим правилам:

Тип JSONТип 1С
ЧислоЧисло
СтрокаСтрока
trueИстина
falseЛожь
nullНеопределено
JSON-объектСтруктура или соответствие
JSON-массивМассив

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

JSON в структуру

Чтение JSON в соответствие

Сейчас все JSON-объекты были прочитаны в структуру. Даже те, которые изначально были сериализованы из соответствия. Однако, в отличии от структуры, в ключах JSON-объектов могут быть пробелы или другие символы, которые нельзя использовать в ключах структуры. Например, если бы соответствие было записано так:

В этом случае при чтении JSON будет выброшено исключение «Недопустимое имя свойства: ‘Ключ 2’ для чтения JSON в объект Структура».

Чтобы прочитать такой JSON нужно в метод ПрочитатьJSON передать вторым параметром Истина. Тогда чтение всех JSON-объектов будет выполнено в соответствие:

В результате в переменной Данные будет соответствие со следующим содержимым:

JSON в соответствие

Сериализация даты в JSON

Формат даты

При сериализации в JSON дата записывается как строка. При чтении тоже будет прочитана как строка, что не совсем удобно. Чтобы свойство с датой было прочитано как дата нужно в методе ПрочитатьJSON третьим параметром указать список имен свойств, которые должны быть прочитаны как дата. А четвертым параметром указать формат даты, в котором дата была записана в JSON. По умолчанию платформа 1С пишет дату в JSON в формате ISO.

В результате свойство Дата будет прочитано как дата:

Дата в JSON

Платформа 1С может записывать дату в JSON в трех форматах:

  • ISO
  • JavaScript
  • Microsoft

Формат ISO используется по умолчанию. Для записи в формате JavaScript или Microsoft нужно явно указать это. При этом форматы JavaScript и Microsoft могут быть записаны только в варианте даты UTC (универсальная дата).

Например, запись в формате JavaScript:

При чтении также нужно указать формат JavaScript:

Для записи в формате Microsoft нужно указать ФорматСериализацииДаты = Microsoft:

И то же самое при чтении JSON:

Для формата ISO дату можно записать в трех вариантах:

  • Локальная дата (без часового пояса)
  • Локальная дата со смещением (относительно UTC)
  • UTC (универсальная дата)

Локальная дата:

Локальная дата со смещением:

Универсальная дата:

Если при чтении JSON формат даты не будет совпадать с форматом записанной даты, то будет выброшено исключение «Представление даты имеет неверный формат».

ПрочитатьДатуJSON

Другой способ чтения даты из JSON это использование метода ПрочитатьДатуJSON. Сначала читаем JSON методом ПрочитатьJSON, а свойства с типом дата дополнительно читаем методом ПрочитатьДатуJSON. Первым параметром передается строковое представление даты, вторым формат даты. Результатом выполнения функции будет значение с типом дата:

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

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

Если попробовать сериализовать в JSON ссылку на справочник, документ или любой другой объектный тип, то будет выброшено исключение «Передано значение недопустимого типа».

Для возможности выгрузки данных прикладных типов 1С можно использовать функцию преобразования. Данная функция указывается в методе ЗаписатьJSON четвертым параметром. Она должна быть экспортной. Пятым параметром указывается где находится данная функция (если в этом же модуле, то нужно указать ЭтотОбъект). Шестым параметром можно указать произвольные дополнительные данные, которые будут переданы в функцию преобразования. Данная функция будет вызвана для тех типов, которые по умолчанию не сериализуются в JSON. Функция вызывается для всех свойств, включая вложенные свойства, а также для элементов массива.

Например, выгрузим контрагента, у которого в реквизите ДатаРегистрации содержится дата, в реквизите ОсновнойДоговор ссылка на справочник Договоры, а в табличной части список контактных лиц. Причем одно контактное лицо указано строкой, а второе ссылкой на справочник Контактные лица:

Контрагент

В результате для свойств Контрагент, ОсновнойДоговор и одного контактного лица будет вызвана функция ВыгрузкаКонтрагента:

Первым параметром передается имя свойства (для элемента массива будет передано Неопределено), вторым значение. Функция должна вернуть результат преобразования. Если установить параметр Отказ = Истина, то данное свойство не будет сериализовано в JSON. В параметре ДопПараметры будут произвольные данные, которые были переданы в метод ЗаписатьJSON.

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

Контрагент выгрузился как уникальный идентификатор, договор как отдельный JSON-объект, а в массиве контактных лиц только одно контактное лицо (так как для второго мы указали в функции преобразования Отказ = Истина).

Функция восстановления

При чтении JSON можно указать функцию восстановления. Имя функции указывается пятым параметром. Она должна быть экспортной. Шестым указывается местонахождение функции (если этот же модуль, то ЭтотОбъект). Седьмым можно передать произвольные данные в функцию восстановления. По умолчанию функция будет вызываться для каждого свойства и элемента массива. Для оптимизации можно восьмым параметром передать массив с именами свойств, только для которых нужно вызывать функцию восстановления.

JSON в структуру

Ограничение вложенности JSON-объектов

JSON-объекты могут быть сколько угодно раз вложены друг в друга:

Вложенные структуры

При чтении JSON последним параметром метода ПрочитатьJSON можно указать ограничение уровней вложенности:

При превышении данного уровня вложенности будет выброшено исключение «Превышена максимальная глубина вложенности JSON».

Сериализация в JSON через XDTO

XDTO (XML Data Transfer Objects) — это механизм платформы 1С, который позволяет автоматически сериализовать все типы данных, которые хранятся в базе данных.

Сериализация выполняется через объект СериализаторXDTO. С помощью данного объекта можно автоматически сериализовать контрагента в JSON. Для этого нужно вызвать метод ЗаписатьJSON у объекта СериализаторXDTO, передав параметрами ЗаписьJSON и объект контрагента:

Полученный JSON:

Для чтения JSON у объекта СериализаторXDTO нужно вызвать метод ПрочитатьJSON:

В переменной КонтрОбъект будет объект контрагента, найденный по уникальному идентификатору, который был записан в свойство Ref.

Дата всегда сериализуется и десериализуется в формате ISO. Переопределить нельзя.

Реквизиты ссылочных типов (ОсновнойДоговор, КонтактноеЛицо) тоже были найдены по своим уникальным идентификаторам.

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

В результате в JSON была записана информация о записанном типе:

Если при сериализации не указывать явное назначение типа:

То свойство с типом не будет записано в JSON. Тогда при чтении нужно указать тип данных, который хотим прочитать из JSON:

Иначе при чтении будет ошибка преобразования данных XDTO.

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

Кодировки

По умолчанию JSON будет записан в файл в кодировке UTF-8 и без маркера порядка байтов (без BOM). При необходимости это можно изменить через параметры метода ОткрытьФайл:

Экранирование

Если сериализовать в JSON строку с кавычками, например «ИП Иванов», то она будет записана так: \»ИП Иванов\». Это называется экранированием. Так как символ кавычка используется для выделения ключей JSON-объектов и строк, то мы не можем использовать его внутри строки. Поэтому кавычка автоматически заменяется на \».

Также можно экранировать:

  • Угловые скобки
  • Разделитель строк
  • Амперсанд
  • Одинарные кавычки
  • Слеш

Примеры результатов экранирования:

СтрокаРезультат экранирования
<ИП Иванов>\u003CИП Иванов\u003E
ИП Иванов&ИП Иванов\u0026
ИП ‘Иванов’ИП \u0027Иванов\u0027
/ИП Иванов\\/ИП Иванов\

Можно экранировать все символы вне ASCII, тогда ИП Иванов будет записано как \u0418\u041F \u0418\u0432\u0430\u043D\u043E\u0432.

Все параметры экранирования указываются в объекте ПараметрыЗаписиJSON, который передается параметром в метод ОткрытьФайл:

Строка JSON

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

  1. У объекта ЗаписьJSON вызывается метод УстановитьСтроку
  2. Выполняется сериализация в JSON
  3. При вызове метода Закрыть будет получена строка в формате JSON

Для чтения JSON из строки у объекта ЧтениеJSON нужно вызвать метод УстановитьСтроку, передав параметром строку в формате JSON:

Потоковая запись JSON

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

Соответствие элементов JSON и методов:

Элемент JSONМетод 1С
Начало объекта {ЗаписатьНачалоОбъекта
Конец объекта }ЗаписатьКонецОбъекта
Имя свойства объектаЗаписатьИмяСвойства
ЗначениеЗаписатьЗначение
Начало массива [ЗаписатьНачалоМассива
Конец массива ]ЗаписатьКонецМассива

В качестве значения можно записать только следующие типы:

  • Строка
  • Число
  • Булево
  • Неопределено

Для записи даты в нужном формате можно использовать метод ЗаписатьДатуJSON.

Например:

Полученный файл:

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

Например, не получится записать такой JSON:

Но если у объекта ЗаписьJSON установить свойство ПроверятьСтруктуру в Ложь, то проверка не будет выполняться:

В результате будет получен невалидный JSON:

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

Также есть метод ЗаписатьБезОбработки, который позволяет записать в JSON произвольный текст, без проверки:

Сериализацию и потоковую запись можно смешивать:

Потоковое чтение JSON

Для потокового чтения нужно:

  • Получить следующий элемент методом Прочитать
  • В свойстве ТекущееЗначение будет прочитанное значение из JSON. В свойстве ТипТекущегоЗначения его тип

В результате будет получена следующая структура:

JSON в структуру

В заключении стоит отметить, что механизмы для работы с JSON в 1с появились только начиная с версии платформы 8.3.6.

Содержание курса


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

;-) :| :x :twisted: :smile: :shock: :sad: :roll: :razz: :oops: :o :mrgreen: :lol: :idea: :grin: :evil: :cry: :cool: :arrow: :???: :?: :!:

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