Работа с JSON
1С: Предприятие 8.3.14.Документация
1 Общая информация
Формат JSON является универсальным способом представления при обмене данными (RFC 7159, https://tools.ietf.org/html/rfc7159). Данные в формате JSON представляют собой (в закодированном виде):
● Объект – неупорядоченное множество пар ключ:значение, заключенный в фигурные скобки ({}). Пары ключ:значение разделяются запятыми (,).
● Массив – множество значений. Массив заключается в квадратные скобки ([]). Значения разделяются запятыми (,).
● Значение – может быть строкой, числом, объектом, массивов или литералом true, false, null.
● Строка – набор символов, заключенный в двойные кавычки (“”).
● Число – сериализуется с разделителем точка (.). Точность числа не ограничена.
Таким образом, с помощью вышеперечисленных элементов допускается описание объектов любой сложности для представления в формате JSON. Например, некоторый код на встроенном языке, формирует некоторый набор данных (в структуре):
Данные = Новый Структура;
Данные.Вставить("Фамилия", "Иванов");
Данные.Вставить("Имя", "Иван");
Данные.Вставить("Отчество", "Иванович");
Данные.Вставить("ДеньРождения", ДатаРождения);
Телефоны = Новый Массив;
Телефоны.Добавить("+7-987-123-45-67");
Телефоны.Добавить("+7-986-987-65-43");
Данные.Вставить("Телефоны", Телефоны);
Сериализуя этот объект в JSON, может быть получен следующий документ:
{
"Фамилия": "Иванов",
"Имя": "Иван",
"Отчество": "Иванович",
"ДатаРождения": "2009-02-15T00:00:00Z",
"Телефоны": [
"+7-987-123-45-67",
"+7-986-987-65-43"
]
}
JSON не стандартизует формат представления даты. В силу этого представление даты в JSON-документе определяется предпочтениями прикладного разработчика, который формирует документ, и требованиями системы, которая будет обрабатывать JSON-документ. Система «1С:Предприятие» поддерживает несколько форматов представления даты (задается с помощью системного перечисления ФорматДатыJSON):
1. Формат ISO (значение ФорматДатыJSON.ISO). В этом случае дата сериализуется следующим образом: “2009-02-15T00:00:00+0400”.
2. Формат JavaScript (значение ФорматДатыJSON.JavaScript). В этом случае дата сериализуется следующим образом: “new Date
(1234656000000)”.
3. Формат Microsoft (значение ФорматДатыJSON.Microsoft). В этом случае дата сериализуется следующим образом: “\/Date(1234656000000)\/”
или “/Date(1234656000000)/” (в зависимости от режима экранирования символов).
Дата может записываться несколькими вариантами (для примера используется дата 10 мая 2014 13:14:15 в зоне UTC+4):
● как локальная дата: 2014-05-10T13:14:15.
● как локальная дата с указанием смещения: 2014-05-10T13:14:15+04:00.
● как дата в UTC: 2014-05-10T09:14:15Z.
Управлять этим можно с помощью системного перечисления ВариантЗаписиДатыJSON. Дату в варианте UTC можно записать в любом формате (ISO, JavaScript и Microsoft), остальные варианты представления даты возможны только в том случае, если сериализация выполняется в формате ISO.
При записи JSON-документа предоставляются возможности по управлению формируемыми данными: настраивать перенос строк, формат сериализации даты, обработка символа “/” и т. д. Эти настройки можно выполнять с помощью объектов НастройкиСериализацииJSON и ПараметрыЗаписиJSON.
Работа с данными в формате JSON может выполняться в нескольких техниках:
● Объектная техника – позволяет формировать простые и небольшие JSON-документы для обмена с внешними приложениями или веб-сервисами. Структура JSON-документа автоматически формируется системой «1С:Предприятие» во время записи документа. Более подробно описание данной техники см. раздел 16.2.2. Специальным вариантом такой техники является возможность сериализации в формате JSON для XDTO-
объектов системы «1С:Предприятие». Более подробное описание работы с XDTO-объектами см. раздел 16.2.3.
● Потоковая техника – позволяет работать с данными большого объема без загрузки их в память приложения. Навигация по JSON-документу полностью ложится на прикладного разработчика (как при записи, так и при чтении документа). Более подробно описание данной техники см. раздел 16.2.4.
● Совмещенная техника – позволяет сочетать гибкость потоковой техники и простоту объектной техники. Более подробно описание данной техники см. раздел 16.2.5.
2. Объектная техника работы
2.1. Общая информация
Система «1С:Предприятие» поддерживает сериализацию следующих данных в формат JSON:
● Строка – сериализуется в строку;
● Число – сериализуется в число;
● Булево – сериализуется в литералы true и false;
● Неопределено – сериализуется в null
● Массив, ФиксированныйМассив – сериализуется в массив JSON в том случае, если любой элемент массива может быть сериализован в JSON.
● Структура, ФиксированнаяСтруктура – сериализуется в объект JSON:
● Ключ – ключ элемента структуры.
● Значение – значение элемента структуры в том случае, если значение может быть сериализовано в JSON.
● Соответствие, ФиксированноеСоответствие – сериализуется в объект JSON:
● Ключ – ключ элемента соответствия. Ключ может быть только значением типа Строка, в противном случае будет генерироваться исключение.
● Значение – значение элемента соответствия в том случае, если значение может быть сериализовано в JSON.
● Дата – формат сериализации определяется настройками.
● Если выполняется попытка сериализации типа, отсутствующего в данном списке – будет вызвано исключение.
При работе с объектной техникой, имеется возможность читать (и писать) данные в соответствие или структуру. Основное отличие между этими объектами состоит в том, что ключ элемента структуры подчиняется правилам формирования переменной на встроенном языке, а ключ элемента соответствия может быть любым. С учетом того, чтоб JSON не накладывает ограничений на значение ключа, не все JSON-документы можно
прочитать в структуру. Еще одним различием между структурой и соответствием является то, что к элементам структуры можно обращаться «через точку», а к элементам соответствия такой доступ не предоставляется. В связи с этим, может оказаться удобным получать данные в виде структуры, если ключи из JSON-документа соответствуют требованиям к ключам структур системы «1С:Предприятие».
Объектная техника предполагает достаточно простую работу с данными, однако платой за это является большой расход памяти, т. к. весь JSON-документ обрабатывается целиком в оперативной памяти.
2.2. Запись
Для того чтобы выполнить запись объекта в формате JSON, необходимо использовать (в простейшем случае) следующие объекты:
1. Собственно записываемый объект, например типа Структура.
2. Объект, обеспечивающий низкоуровневую запись данных в формате JSON – ЗаписьJSON.
3. Объект настроек сериализации НастройкиСериализацииJSON.
Метод глобального контекста ЗаписатьJSON() оперирует вышеперечисленными объектами. Рассмотрим пример, в котором потребуется записать структуру, которая состоит из трех элементов разного типа (но типы являются примитивными):
Запись = Новый ЗаписьJSON;
Запись.ОткрытьФайл("c:\temp\simpleWrite.json");
Данные = Новый Структура;
Данные.Вставить("ДлинаЗаписи", 20);
Данные.Вставить("КлючЗаписи", "abcdefgh");
Данные.Вставить("ДатаИзменения", ТекущаяДата());
ЗаписатьJSON(Запись, Данные, Новый НастройкиСериализацииJSON);
Запись.Закрыть();
В результате работы данный пример сформирует следующий JSON-документ:
{
“ДлинаЗаписи”: 20,
“КлючЗаписи”: “abcdefgh”,
“ДатаИзменения”: “2014-09-24T17:32:11”
}
Если в сериализуемых данных участвуют значения типа Дата, то может потребоваться управлять форматом сериализации. Для этого необходимо установить параметры объекта НастройкиСериализацииJSON. В следующем примере дата будет сериализоваться в формате JavaScript:
НастройкиСериализации = Новый НастройкиСериализацииJSON;
НастройкиСериализации.ФорматСериализацииДат = ФорматДатыJSON.JavaScript;
НастройкиСериализации.ВариантЗаписиДаты = ВариантЗаписиДатыJSON.УниверсальнаяДата;
Запись = Новый ЗаписьJSON;
Запись.ОткрытьФайл("c:\temp\simpleWrite.json");
Данные = Новый Структура;
Данные.Вставить("ДлинаЗаписи", 20);
Данные.Вставить("КлючЗаписи", "abcdefgh");
Данные.Вставить("ДатаИзменения", ТекущаяДата());
ЗаписатьJSON(Запись, Данные, НастройкиСериализации);
Запись.Закрыть();
В результате работы данный пример сформирует следующий JSON-документ:
{
"ДлинаЗаписи": 20,
"КлючЗаписи": "abcdefgh",
"ДатаИзменения": "new Date(1411565832000)"
}
Если несколько расширить набор записываемых данных, например, добавить к ним значение типа УникальныйИдентификатор, то запись не будет выполнена. В результате исполнения кода:
Запись = Новый ЗаписьJSON;
Запись.ОткрытьФайл("c:\temp\simpleWrite.json");
Данные = Новый Структура;
Данные.Вставить("ДлинаЗаписи", 20);
Данные.Вставить("КлючЗаписи", "abcdefgh");
Данные.Вставить("ДатаИзменения", ТекущаяДата());
Данные.Вставить("UID", Новый УникальныйИдентификатор);
ЗаписатьJSON(Запись, Данные, Новый НастройкиСериализацииJSON);
Запись.Закрыть();
Будет вызвано исключение:
Ошибка при вызове метода контекста (ЗаписатьJSON) ЗаписатьJSON(Запись, Данные, Новый НастройкиСериализацииJSON); по причине: Передано значение недопустимого типа
Причиной такого поведения является то, что тип УникальныйИдентификатор не входит в состав JSON-сериализуемых типов данных системы «1С:Предприятие». Однако система предоставляет возможность «обойти» это ограничение: необходимо передать в функцию ЗаписатьJSON() имя функции обратного вызова, которая будет заниматься JSON-сериализацией неподдерживаемых объектов. Эта функция будет называться
функцией преобразования. При этом формат такой сериализации будет разрабатывать непосредственно сам прикладной разработчик. Надо понимать, что такая сериализация не будет универсальной, т. к. принимающая сторона, не обладающая знаниями о формате сериализации, не сможет прочитать переданные данные. Другими словами, формат сериализации необходимо разрабатывать совместно всеми сторонами обмена
такого рода данными.
С учетом вышесказанного, более сложный вариант обмена теперь происходит следующим образом:
● Вызывается функция сериализации объекта в формат JSON (ЗаписатьJSON()).
● Система «1С:Предприятие» для каждого элемента структуры, тип значения которого не сериализуется в формат JSON, будет вызываться функция преобразования.
● Функция преобразования анализирует переданный объект и принимает решение – отказаться от его записи или вернуть платформе значение, которое может быть сериализовано в JSON.
Доработанный код записи будет выглядеть следующим образом:
&НаСервере
Процедура ЗаписьНаСервере()
Запись = Новый ЗаписьJSON;
Запись.ОткрытьФайл("c:\temp\compositeWrite.json");
Данные = Новый Структура;
Данные.Вставить("ДлинаЗаписи", 20);
Данные.Вставить("КлючЗаписи", "abcdefgh");
Данные.Вставить("ДатаИзменения", ТекущаяДата());
Данные.Вставить("UID", Новый УникальныйИдентификатор);
ЗаписатьJSON(Запись, Данные, Новый НастройкиСериализацииJSON, "ФункцияПреобразованияЗаписи", ЭтотОбъект);
Запись.Закрыть();
КонецПроцедуры
&НаСервере
Функция ФункцияПреобразованияЗаписи(Свойство, Значение, ДополнительныеПараметры, Отказ) Экспорт
Если ТипЗнч(Значение) = Тип("УникальныйИдентификатор") Тогда
Возврат Строка(Значение);
КонецЕсли;
Отказ = Истина;
КонецФункции
Следует обратить внимание, что функция преобразования должна быть объявлена с указанием ключевого слова Экспорт. Также следует помнить, что функция преобразования (в модуле управляемой формы) может быть описана только в «контекстной» части модуля, т. е. с использованием директивы компиляции &НаКлиенте или &НаСервере.
В результате работы приведенного примера будет сформирован следующий JSON-документ:
{
"ДлинаЗаписи": 20,
"КлючЗаписи": "abcdefgh",
"ДатаИзменения": "2014-09-24T18:09:13",
"UID": "5a80e5dc-252b-416f-b487-d9ddcebc523e"
}
При создании функции преобразования следует помнить о следующих особенностях:
● Функция преобразования вызывается для значений всех типов, которые не поддерживают сериализацию в JSON (см. раздел 16.2.1).
● Если функция преобразования вернет значение, которое не может быть сериализовано в JSON – будет вызвано исключение.
● Если переданное значение является структурой, то вызов функции преобразования для элементов этой структуры будет вызваться до того, как в поток будет записано имя свойства этого элемента. В результате функция преобразования может отказаться от записи значения и структура формируемого JSON-документа не будет нарушена.
● Имя свойства будет передано в функцию преобразования только для элементов структур и соответствий.
2.3. Чтение
2.3.1. Общая схема
Чтение данных в объектной технике выглядит аналогично записи. Рассмотрим пример чтения файлов, которые формировались во время рассмотрения объектной записи (предыдущий раздел).
Чтение = Новый ЧтениеJSON;
Чтение.ОткрытьФайл("c:\temp\simpleWrite.json");
Данные = ПрочитатьJSON(Чтение, Ложь, "ДатаИзменения", ФорматДатыJSON.JavaScript);
Чтение.Закрыть();
Документ имеет следующее содержание (с точностью до значения даты):
{
"ДлинаЗаписи": 20,
"КлючЗаписи": "abcdefgh",
"ДатаИзменения": "new Date(1411565832000)"
}
При чтении JSON-документа в переменную Данные будет сформирована структура вида:
Ключ = ДлинаЗаписи, значение = 20
Ключ = КлючЗаписи, значение = abcdefgh
Ключ = ДатаИзменения, значение = <значение даты и времени>
Такой вариант чтения хорошо подходит в том случае, если читаемые данные могут быть преобразованы в структуру или соответствие и все читаемые данные могут быть однозначно десериализованы без потери информации о типе. Если читаемые данные обладают сложной структурой или требуют выполнения дополнительных преобразований при чтении, то можно пойти двумя путями:
1. Получить соответствие (или структуру), в которое будет полностью загружен JSON-документ, и потом завершить преобразование с помощью обхода получившегося объекта.
2. Заниматься необходимым преобразованием непосредственно во время загрузки данных.
Для этого необходимо передать в функцию ПрочитатьJSON() имя функции обратного вызова, которая будет заниматься десериализацией JSON-данных в нужные объекты системы «1С:Предприятие». Эта функция будет называться функцией восстановления.
В обоих случаях прикладной разработчик должен знать, какие данные и в каком виде находятся JSON-документе. Далее будут подробно рассмотрены оба варианта загрузки данных. В качестве макетной задачи будет рассматриваться получение погоды в г. Москва с помощью некоторого интернет-сервиса. В качестве ответа интернет-сервис возвращает JSON-документ следующего содержания:
{
"id":524901,"name":"Moscow","dt":1411464940000,
"coord": { "lon":37.62,"lat":55.75 },
"sys": { "country":"RU","sunrise":1411442400000,"sunset":1411485660000 },
"weather": [
{ "main":"Clouds","description":"пасмурно" }
],
"main": { "temp":282.93,"pressure":1014,"humidity":93 },
"wind": { "speed":4,"deg":350 },
"clouds": { "all":90 }
}
Кратко рассмотрим описание формата:
● id – идентификатор города;
● name – имя города;
● dt – дата и время получения погоды, в формате Unix, GMT;
● coord – местоположение города:
● lon – долгота;
● lan – широта.
● sys – дополнительная информация:
● country – страна расположения города;
● sunrise – время восхода Солнца в формате Unix, GMT;
● sunset – время заката Солнца, в формате Unix, GMT.
● weather – дополнительная информация о погоде:
● main – общая характеристика погоды;
● description – описание погоды.
● main – собственно описание погоды:
● temp – температура, в градусах Кельвина. Для получения градусов Цельсия необходимо вычесть 273.15;
● pressure – давление в гектопаскалях. Для перевода в миллиметры ртутного столба, надо значение давления умножить на 0,75.
● humidity – влажность в %.
● wind – параметры ветра:
● speed – скорость в милях в час. Для перевода в километры в час необходимо умножить на 1,61.
● deg – направление ветра, в градусах.
● clouds – информация об осадках:
● all – вероятность возникновения осадков, в %.
В результате загрузки этих данных должна получиться структура, где все времена представлены стандартным типом Дата, температура – в градусах Цельсия, скорость – в километрах в час, а давление – в миллиметрах ртутного столба.
Рассмотрим загрузку данной информации обоими способами. Данные записаны в файле c:\temp\weather.json.
2.3.2. Чтение с постобработкой
Собственно процесс чтения выглядит просто:
Чтение = Новый ЧтениеJSON;
Чтение.ОткрытьФайл("c:\temp\weather.json");
Данные = ПрочитатьJSON(Чтение, Ложь);
Чтение.Закрыть();
В результате в переменной Данные будет следующая информация:
Без учета необходимости конвертации все выглядит предсказуемо. Однако дата и время автоматически не преобразовались. Можно попробовать указать системе на то, что поле dt (например) является полем, где находится дата и время:
Чтение = Новый ЧтениеJSON; Чтение.ОткрытьФайл("c:\temp\weather.json");
Данные = ПрочитатьJSON(Чтение, Ложь, "dt", ФорматДатыJSON.JavaScript);
Чтение.Закрыть();
В результате получим сообщение об ошибке следующего вида:
Ошибка при вызове метода контекста (ПрочитатьJSON) Данные = ПрочитатьJSON(Чтение, Ложь, "dt", ФорматДатыJSON.JavaScript); по причине: Представление даты имеет неверный формат
Ошибка произошла потому, что система не понимает формат даты и времени, выраженной простым числом. Программный интерфейс работы с JSON предлагает функцию, помогающую выполнить конвертацию полей типа Дата – ПрочитатьДатуJSON(). Для использования этой функции необходимо привести десериализованную строку к формату, принятому, например, в JavaScript. В рассматриваемом примере получится
следующий программный текст:
Данные.dt = ПрочитатьДатуJSON(“new Date(“+Формат(Данные.dt, “ЧГ=”)+”)”, ФорматДатыJSON.JavaScript);
В результате значение свойства Данные.dt станет равно значению 23.09.2014 13:35:40 (типа Дата). Остальная конвертация выполняется аналогичным образом.
2.3.3. Чтение с функцией восстановления
Вариант постобработкой выглядит не очень хорошо, если чтение JSON-документа предполагается выполнять в разных местах прикладного решения. В этом случае может возникнуть ситуация, когда код преобразования будет расположен в нескольких местах прикладного решения.
Хорошей заменой постобработки, в этом случае, является использование функции восстановления. Для применения функции восстановления необходимо описать саму функцию и несколько изменить само чтение документа:
&НаСервере
Функция ФункцияВосстановленияЧтения(Свойство, Значение, ДополнительныеПараметры) Экспорт
Если Свойство = "dt" ИЛИ Свойство = "sunrise" ИЛИ Свойство = "sunset" Тогда
Возврат ПрочитатьДатуJSON("new Date("+Формат(Значение, "ЧГ=")+")", ФорматДатыJSON.JavaScript);
КонецЕсли;
Если Свойство = "pressure" Тогда
Возврат Значение*0.75;
КонецЕсли;
Если Свойство = "temp" Тогда
Возврат Значение-273.15;
КонецЕсли;
Если Свойство = "speed" Тогда
Возврат Значение*1.61;
КонецЕсли;
КонецФункции
&НаСервере
Процедура ЧтениеНаСервере()
Чтение = Новый ЧтениеJSON;
Чтение.ОткрытьФайл("c:\temp\weather.json");
Данные = ПрочитатьJSON(Чтение, Ложь, , , "ФункцияВосстановленияЧтения", ЭтотОбъект);
Чтение.Закрыть();
КонецПроцедуры
В вышеуказанном примере присутствует особенность – функция восстановления будет вызвана для всех свойств, которые будут обнаружены в JSON-документе. Это не всегда удобно и, кроме того, существенно снижает производительность чтения JSON-документа (за счет вызова функции восстановления). Например, при чтении метеорологических данных нам необходимо выполнять особое преобразование только для свойств, в
которых содержится дата и время, а остальные свойства мы конвертировать не собираемся. Чтобы не анализировать в функции восстановления имя реквизита (как в вышеприведенном примере), можно поступить другим способом: явным образом передать в функцию чтения JSON-документа список реквизитов, которые содержат дату и время, а функцию восстановления написать исходя из того, что эта функция будет вызвана только для необходимых свойств. В результате получится следующий код:
&НаСервере
Процедура ЧтениеНаСервере()
Чтение = Новый ЧтениеJSON;
Чтение.ОткрытьФайл("c:\temp\weather.json");
Реквизиты = Новый Массив;
Реквизиты.Добавить("dt");
Реквизиты.Добавить("sunrise");
Реквизиты.Добавить("sunset");
Данные = ПрочитатьJSON(Чтение, Ложь, , , "ФункцияВосстановленияЧтения", ЭтотОбъект, , Реквизиты);
Чтение.Закрыть();
КонецПроцедуры
&НаСервере
Функция ФункцияВосстановленияЧтения(Свойство, Значение, ДополнительныеПараметры) Экспорт
Возврат ПрочитатьДатуJSON("new Date("+Формат(Значение, "ЧГ=")+")", ФорматДатыJSON.JavaScript);
КонецФункции
Следует обратить внимание, что функция восстановления должна быть объявлена с указанием ключевого слова Экспорт. Также следует помнить, что функция восстановления (в модуле управляемой формы) может быть описана только в «контекстной» части модуля, т. е. с использованием директивы компиляции &НаКлиенте или &НаСервере. При разработке функции восстановления необходимо принимать во внимание тот факт, что свойства документа считываются не в том порядке, как они представлены в файле.
Рассмотрим последовательность, в которой свойства JSON-документа попадают в функцию восстановления. Для этого разместим в таблице каждое свойство файла и то, в каком порядке будет прочитано свойство:
В общем случае, можно сформулировать следующее правило обхода: первым будет прочитано свойство, которому не подчинено ни одно другое свойство. Например, свойству id не подчинено никакое свойство, и оно считывается первым. Однако свойству coord подчинено свойства lon и lat, поэтому вначале будут считаны эти свойства, а лишь затем – свойство coord, которое в качестве значения получит структуру (или соответствие) из подчиненных свойств документа.
3. Работа с XDTO-объектами
3.1. Общая информация
Работа с XDTO-объектами, в основном, ориентирована на обмен информации между системами, написанными на платформе «1С:Предприятие».
Однако сам механизм не накладывает никаких ограничений на его использование для обмена с другими системами.
JSON-сериализация XDTO-объекта выполняется сразу в JSON-документ, без формирования в памяти полной структуры сериализуемых объектов.
Также следует учитывать, что JSON-сериализация «эмулирует» XML-сериализацию, в силу чего получающийся JSON-документ внешне выглядит очень похоже на соответствующий XML-документ.
В JSON-документ могут быть помещены любые объекты системы «1С:Предприятие», для которых указано, что они могут быть сериализованы в XDTO. При попытке выполнить сериализацию значения неподдерживаемого типа будет вызвано исключение.
3.2. Запись
Для того чтобы выполнить запись XDTO-объекта в формате JSON, необходимо использовать (в простейшем случае) следующие объекты:
1. Собственно записываемый объект, поддерживающий преобразование в/из XDTO, например, элемент справочника.
2. Сериализатор XDTO-объектов – СериализаторXDTO;
3. Объект, обеспечивающий низкоуровневую запись данных в формате JSON – ЗаписьJSON.
4. Объект настроек сериализации НастройкиСериализацииJSON.
Собственно сериализация выполняется с помощью метода ЗаписатьJSON() объекта СериализаторXDTO. Рассмотрим пример сериализации данных типа СправочникОбъект. В качестве примера используется справочник Валюты, который содержит поля Курс (типа Число) и ДатаКурса (типа Дата):
Данные = Справочники.Валюты.НайтиПоКоду("978").ПолучитьОбъект();
Запись = Новый ЗаписьJSON;
Запись.ОткрытьФайл("c:\temp\simpleXDTOWrite.json");
СериализаторXDTO.ЗаписатьJSON(Запись, Данные);
Запись.Закрыть();
В результате работы данный пример сформирует следующий JSON-документ:
{ “#value”: { “Ref”: “5b65bd8e-ea70-11e4-af93-e03f49b16069”, “DeletionMark”: false, “Code”: “978”, “Description”: “Евро”, “Курс”: 54.659, “ДатаКурса”: “2015-04-25T00:00:00” } }
Сериализация значений типа Дата выполняется в формате ISO (определяется механизмом XDTO) и не управляется при записи данных. Также не поддерживается использование функции преобразования при операции сериализации, в отличие от потоковой (см. раздел 16.2.4) и объектной (см. раздел 16.2.2) техник.
Также следует помнить о следующей особенности: при записи объекта не формируется его тип, поэтому после JSON-сериализации XDTO-объекта отсутствует возможность выполнить десериализацию без указания типа считываемого объекта. Предыдущий пример сериализации элемента справочника Валюты будет невозможно десериализовать без явного указания типа значения. Чтобы упростить ситуацию, можно воспользоваться
параметром НазначениеТипаXML метода ЗаписатьJSON() объекта СериализаторXDTO. Если в качестве значения этого параметра указать НазначениеТипаXML.Явное, то появится возможность выполнить десериализацию без явного указания типа, а сформированный файл будет выглядеть следующим образом:
{ “#type”: “jcfg:CatalogObject.Валюты”, “#value”: { “Ref”: “5b65bd8e-ea70-11e4-af93-e03f49b16069”, “DeletionMark”: false, “Code”: “978”, “Description”: “Евро”, “Курс”: 54.659, “ДатаКурса”: “2015-04-25T00:00:00” } }
В данном примере особого внимания заслуживает элемент #type, который и описывает тип текущего элемента. Описание префиксов пространств имен см. приложение
Общие принципы JSON-сериализации объектов XDTO идентичны XML-сериализации:
● Структура данных соответствует структуре XML-документа.
● Имеются незначительные отличия, связанные с особенностями хранения типов и представлением массивов в JSON:
● Порядок и состав свойств определен в модели XDTO и не может быть изменен.
● Если тип записываемого значения однозначно определяется из типа, определенного в соответствующем свойстве XDTO-модели, то записывается только значение без идентификации типа.
● Если тип записываемого значения неоднозначно определяется из типа, определенного в соответствующем свойстве XDTO-модели (например, значение составного типа), то значение будет записано в виде сложного объекта JSON с отдельными свойствами для типа (свойство #type) и значения (свойство #value). В следующем примере записаны эквивалентные варианты представления значения типа Строка. Первая запись используется при неоднозначном определении типа, вторая – при однозначном:
Первая запись
{
“#type”: “jxs:string”,
“#value”: “Строка с примером”
}
Вторая запись
“Строка с примером”
JSON-сериализация объектов XDTO имеет ряд особенностей (по сравнению с XML-сериализацией):
● Коллекции значений (например, значения типа Массив, Структура и т. д.) всегда записываются виде массива JSON.
● Тип значения реквизита записывается в специальное свойство JSON с именем #type.
● Пространство имен типов записывается в специальное свойство JSON с именем #ns:
● Для встроенных в платформу пространств имен типы записываются без использования свойства #ns, но с указанием префикса:
jxс:ChartOfCharacteristicTypesObject.ДемоПланВидовХарактеристик
jxs:string
jxs:decimal
Соответствие префиксов и пространств имен см.в приложении.
● Если встретится схема, которая не имеет префикса, то имя схемы явно записывается с помощью свойства #ns:
{
"#ns": "http://mycompany.com/data/enterprise/myscheme",
"#type": "СпециальныйОбъект",
"#value": …
}
Значения Неопределено и NULL сериализуются особым образом:
1. Неопределено:
{
"#type": "jv8:Null",
"#value": ""
}
2. NULL:
{
"ИмяРеквизита": null
}
С помощью JSON возможно выполнить сериализацию XDTO-объектов, которые не соответствуют какой-либо схеме. В этом случае используется явное описание типов реквизитов, одноименные свойства не будут объединяться в массив, а будут выводиться в JSON-документ поэлементно, в соответствии с XDTO-объектом.
Пример:
{
"#type": "jxs:anyType",
"#value": {
"Filters": {
"Filter": {
"Name": "Recorder",
"Value": {
"#type": "jxs:anySimpleType",
"#value": "acc2d259-c8f3-11e2-b5da-5404a6a68c42"
}
}
},
"Record": {
"Recorder": {
"#type": "jxs:anySimpleType",
"#value": "acc2d259-c8f3-11e2-b5da-5404a6a68c42"
},
"Period": {
"#type": "jxs:anySimpleType",
"#value": "2012-09-08T00:00:00"
},
"Active": {
"#type": "jxs:anySimpleType",
"#value": "true"
},
},
"Record": {
"Recorder": {
"#type": "jxs:anySimpleType",
"#value": "acc2d259-c8f3-11e2-b5da-5404a6a68c42"
},
"Period": {
"#type": "jxs:anySimpleType",
"#value": "2012-09-08T00:00:00"
},
"Active": {
"#type": "jxs:anySimpleType",
"#value": "true"
},
},
}
}
3.3. Чтение
В общем случае, чтение XDTO-объекта из JSON-документа аналогично записи. Чтение выполняется с помощью механизма чтения XDTO-объектов из XML-файла, поэтому чтение выполняется со следующими ограничениями:
● Возможно чтение только тех объектов, для которых существует XDTO-сериализация.
● Свойства в JSON-документе должны следовать в том же порядке, как и в XDTO-объекте.
● В случае если читаемый объект не соответствует схеме – будет вызвано исключение.
● Имеется возможность выполнять чтение произвольного JSON-документа в объект XDTO (ОбъектXDTO) с помощью фабрики XDTO (ФабрикаXDTO). Такое чтение возможно в том случае, если:
● фабрика XDTO, с помощью которой выполняется чтение, «знает» о типах, которые присутствуют в JSON-документе, из которого производится чтение.
● все элементы JSON указаны без явного указания типов и элементов, специфичных для JSON-документов, формируемых при сериализации объектов XDTO.
Выполнить чтение JSON-документа в том случае, если в нем используются типы, которые неизвестны фабрике XDTO, с помощью которой выполняется чтение документа – невозможно.
Рассмотрим пример чтения некоторого JSON-документа, например, полученного при работе примера работы со справочником Валюты из предыдущего раздела .
Чтение = Новый ЧтениеJSON;
Чтение.ОткрытьФайл("c:\temp\simpleXDTOWrite.json");
Данные = СериализаторXDTO.ПрочитатьJSON(Чтение);
Чтение.Закрыть();
В результате работы примера в переменно Данные будет помещен объект типа СправочникОбъект.Валюты для валюты с кодом 978. Однако данное поведение будет наблюдаться только в том случае, если при выполнении JSON-сериализация значение параметра НазначениеТипаXML было установлено в значение Явное. В противном случае при попытке чтения (как указано выше) будет вызвано исключение. При чтении объекта с
неявным указанием типа объекта, читаемый тип можно передать в виде параметра метода ПрочитатьJSON(). В этом случае пример будет выглядеть следующим образом:
Чтение = Новый ЧтениеJSON;
Чтение.ОткрытьФайл("c:\temp\simpleXDTOWrite.json");
Данные = СериализаторXDTO.ПрочитатьJSON(Чтение, Тип("СправочникОбъект.Валюты"));
Чтение.Закрыть();
При обмене данными между прикладными решениями с помощью объектов XDTO может возникать задача, когда требуется выполнить некоторую предобработку данных, которые поступают в пакете обмена. Например, заменить любое значение некоторого типа на фиксированное значение того же типа. Для упрощения такой предобработки предназначена функция восстановления. Имя функции восстановления передается в
функцию чтения из JSON-документа для сериализатора или фабрики XDTO. При чтении объекта функция восстановления будет вызываться при десериализации значений следующих типов:
● Булево;
● Число;
● Строка;
● Дата;
● УникальныйИдентификатор;
● ДвоичныеДанные;
● ХранилищеЗначения;
● Значения перечислений;
● Значения системных перечислений;
● Ссылки на объекты базы данных.
Для значений Неопределено функция восстановления не вызывается.
При разработке функции восстановления необходимо помнить, что в этой функции можно заменить значение, которое считано из JSON-документа, но нельзя изменить тип считываемого объекта. Функция восстановления также не будет вызываться для служебных свойств, которые создаются и используются системой «1С:Предприятие», например, #type, #ns и т. д.
4. Потоковая техника работы
4.1. Общая информация
Потоковая техника работы с документом ориентирована на то, что документ целиком не загружается в память и обрабатывается последовательно, от элемента к элементу. Например, если надо прочитать только какой-то объект из JSON-документа, то потоковая техника может дать существенный выигрыш, особенно в том случае, если требуемый элемент находится в начале обрабатываемого документа.
4.2. Запись
Для того чтобы выполнить потоковую запись JSON-документа, необходимы записываемые данные и объект ЗаписьJSON. При этом следует понимать, что формирование корректной структуры JSON-документа полностью лежит на прикладном разработчике, который формирует документ. Для упрощения такого контроля объект ЗаписьJSON имеет свойство ПроверятьСтруктуру.
Рассмотрим простой пример записи документа:
ПараметрыJSON = Новый ПараметрыЗаписиJSON(ПереносСтрокJSON.Авто, " ", Истина);
Запись = Новый ЗаписьJSON;
Запись.ПроверятьСтруктуру = Истина;
Запись.ОткрытьФайл("c:\temp\streamWrite.json", , , ПараметрыJSON);
Запись.ЗаписатьНачалоОбъекта();
Запись.ЗаписатьИмяСвойства("ДлинаЗаписи");
Запись.ЗаписатьЗначение(20);
Запись.ЗаписатьИмяСвойства("Товар");
Запись.ЗаписатьНачалоОбъекта();
Запись.ЗаписатьИмяСвойства("Код");
Запись.ЗаписатьЗначение("0020");
Запись.ЗаписатьИмяСвойства("Наименование");
Запись.ЗаписатьЗначение("Товар");
Запись.ЗаписатьКонецОбъекта();
Запись.ЗаписатьИмяСвойства("МассивЧисел");
Запись.ЗаписатьНачалоМассива();
Запись.ЗаписатьЗначение(3.141592654, Истина);
Запись.ЗаписатьЗначение(2.718281828, Ложь);
Запись.ЗаписатьКонецМассива();
Запись.ЗаписатьКонецОбъекта();
Запись.Закрыть();
В результате исполнения этого программного кода будет сформирован следующий документ:
{
"ДлинаЗаписи": 20,
"Товар": {
"Код": "0020",
"Наименование": "Товар"
},
"МассивЧисел": [
3.141592654E0,
2.718281828
]
}
Такой формат документа удобен для визуального просмотра, но занимает больше места. Можно изменить значение первого параметра конструктора ПараметрыЗаписиJSON на значение ПереносСтрокJSON.Нет и результирующий документ примет такой вид (разница составит примерно 20%):
{“ДлинаЗаписи”:20,”Товар”:{“Код”:”0020″,”Наименование”:”Товар”},”МассивЧисел”:[3.141592654E0,2.718281828]}
Если необходимо получить JSON-документ без формирования файла, то можно использовать метод УстановитьСтроку() объекта ЗаписьJSON.
После вызова этого метода, для получения строки со сформированным JSON-документом, достаточно просто завершить запись документа методом Закрыть() объекта ЗаписьJSON:
ПараметрыJSON = Новый ПараметрыЗаписиJSON(ПереносСтрокJSON.Нет, ” “, Истина);
Запись = Новый ЗаписьJSON;
Запись.УстановитьСтроку(ПараметрыJSON);
…
Документ = Запись.Закрыть();
Теперь данный документ (из переменной Документ) можно передавать, например, в тело HTTP-запроса.
4.3. Чтение
Потоковое чтение JSON-документа выполняется аналогично его записи: прикладной разработчик в цикле читает следующий элемент, определяет, что считано и обрабатывает считываемые данные.
Примитивный случай потокового чтения документа может выглядеть следующим образом:
Чтение = Новый ЧтениеJSON;
Чтение.ОткрытьФайл("c:\temp\streamWrite.json");
Пока Чтение.Прочитать() Цикл
Сообщить("Тип текущего элемента " + Чтение.ТипТекущегоЗначения);
Если Чтение.ТипТекущегоЗначения = ТипЗначенияJSON.ИмяСвойства Тогда
Сообщить("Имя = " + Чтение.ТекущееЗначение);
КонецЕсли;
Если Чтение.ТипТекущегоЗначения = ТипЗначенияJSON.Булево Или
Чтение.ТипТекущегоЗначения = ТипЗначенияJSON.Строка Или
Чтение.ТипТекущегоЗначения = ТипЗначенияJSON.Число Или
Чтение.ТипТекущегоЗначения = ТипЗначенияJSON.Комментарий Тогда
Сообщить("Значение = " + Чтение.ТекущееЗначение);
КонецЕсли;
КонецЦикла;
Чтение.Закрыть();
Тогда при чтении документа, сформированного при рассмотрении потоковой записи JSON-документа , будет сформирован следующий результат:
Тип текущего элемента Начало объекта
Тип текущего элемента Имя свойства
Имя = ДлинаЗаписи
Тип текущего элемента Число
Значение = 20
Тип текущего элемента Имя свойства
Имя = Товар
Тип текущего элемента Начало объекта
Тип текущего элемента Имя свойства
Имя = Код
Тип текущего элемента Строка
Значение = 0020
Тип текущего элемента Имя свойства
Имя = Наименование
Тип текущего элемента Строка
Значение = Товар
Тип текущего элемента Конец объекта
Тип текущего элемента Имя свойства
Имя = МассивЧисел
Тип текущего элемента Начало массива
Тип текущего элемента Число
Значение = 3,141592654
Тип текущего элемента Число
Значение = 2,718281828
Тип текущего элемента Конец массива
Тип текущего элемента Конец объекта5. Совмещение техник
Для упрощения работы с JSON, можно совмещать различные техники при формировании одного документа. Например, необходимо сформировать документ, который содержит в себе некоторый набор структур и массив. В этом случае можно все оформление документа
выполнять с помощью потоковой техники, а уже готовые структуры и массив записывать с помощью объектной техники. Важно только обеспечить корректную структуру документа перед началом объектной записи.
Приведем пример совмещения техник на следующем примере:
● В ответ на запрос внешней системы, этой системе необходимо возвращать список заказов.
● Список должен содержать дату формирования и набор заказов (соответствующий некоторому критерию).
● Каждый заказ описывается следующими параметрами:
1. Номер заказа;
2. Дата формирования заказа;
3. Контрагент по заказу;
4. Уникальный идентификатор заказа, по которому впоследствии можно получить всю информацию по заказу.
Фрагмент кода на встроенном языке, который формирует JSON-документ, будет иметь следующий вид:
НастройкиСериализации = Новый НастройкиСериализацииJSON;
НастройкиСериализации.ВариантЗаписиДаты = ВариантЗаписиДатыJSON.УниверсальнаяДата;
НастройкиСериализации.ФорматСериализацииДат = ФорматДатыJSON.ISO;
НастройкиСериализации.СериализовыватьМассивыКакОбъекты = Истина;
ПараметрыJSON = Новый ПараметрыЗаписиJSON(ПереносСтрокJSON.Авто, " ", Истина);
Запись = Новый ЗаписьJSON;
Запись.ПроверятьСтруктуру = Истина;
Запись.ОткрытьФайл("c:\temp\combinedWrite.json", , , ПараметрыJSON);
Запись.ЗаписатьНачалоОбъекта();
Запись.ЗаписатьИмяСвойства("ДатаФормирования");
Запись.ЗаписатьЗначение(ЗаписатьДатуJSON(КогдаСформировано, ФорматДатыJSON.ISO, ВариантЗаписиДатыJSON.УниверсальнаяДата));
Запись.ЗаписатьИмяСвойства("Заказы");
Заказы = Новый Массив;
Для каждого Заказ Из СписокЗаказов Цикл
ОписаниеЗаказа = Новый Структура("Ссылка, Номер, Дата, Контрагент");
ОписаниеЗаказа.Ссылка = Строка(Заказ.Ссылка);
ОписаниеЗаказа.Номер = Заказ.Номер;
ОписаниеЗаказа.Дата = Заказ.Дата;
ОписаниеЗаказа.Контрагент = Строка(Заказ.Контрагент);
Заказы.Добавить(ОписаниеЗаказа);
КонецЦикла;
ЗаписатьJSON(Запись, Заказы, НастройкиСериализации);
Запись.ЗаписатьКонецОбъекта();
Запись.Закрыть();
При исполнении данного кода предполагается, что:
● Переменная КогдаСформировано содержит значение типа Дата. Содержит дату и время формирования JSON-документа.
● Переменная СписокЗаказов является массивом ссылок на документы заказов.
Исполнение данного код приведет к формированию следующего JSON-документа:
{
"ДатаФормирования": "2014-10-06T12:57:35Z",
"Заказы": {
"0": {
"Ссылка": "f4d1495a-02b5-4d56-92c6-840c11dfb592",
"Номер": 234,
"Дата": "2014-09-30T20:00:00Z",
"Контрагент": "Иванов И.И."
},
"1": {
"Ссылка": "ee821799-2d57-475e-a330-f414e53b8bda",
"Номер": 436,
"Дата": "2014-09-24T20:00:00Z",
"Контрагент": "Петров А.П."
},
"2": {
"Ссылка": "e058a5a8-3c0d-453b-8b1c-963a35fe2b7a",
"Номер": 118,
"Дата": "2014-08-31T20:00:00Z",
"Контрагент": "Иванов И.И."
}
}
}
Изменяя значения параметров объектов НастройкиСериализации и ПараметрыJSON, а также манипулируя параметрами метода ЗаписатьДатуJSON(), можно изменять результирующий JSON-документ для максимального соответствия «ожиданиям» принимающей системы.