Сериализация типа «Дата»
JSON не стандартизует формат представления даты. Поэтому разработчик может самостоятельно определить формат представления даты в JSON-документе исходя из своих предпочтений и требований принимающей стороны.
«1С:Предприятие» поддерживает несколько форматов представления даты, которые можно задать с помощью системного перечисления ФорматДатыJSON:
- Формат ISO. В этом случае дата сериализуется следующим образом: "2019-03-15T00:00:00+0400".
- Формат JavaScript. В этом случае дата сериализуется следующим образом: "new Date(1234656000000)".
- Формат Microsoft. В этом случае дата сериализуется следующим образом: "\/Date(1234656000000)\/" или "/Date(1234656000000)/" (в зависимости от режима экранирования символов).
Дата может записываться в нескольких вариантах (для примера используется дата 10 марта 2019 13:14:15 в зоне UTC+4):
- как локальная дата: 2019-03-10T13:14:15;
- как локальная дата с указанием смещения: 2019-03-10T13:14:15+04:00;
- как дата в UTC: 2019-03-10T09:14:15Z.
Управлять этим можно с помощью системного перечисления ВариантЗаписиДатыJSON. Дату в варианте UTC можно записать в любом формате (ISO, JavaScript и Microsoft), остальные варианты представления даты возможны только в том случае, если сериализация выполняется в формате ISO.
Для установки желаемого формата и варианта записи даты в JSON-документ у метода ЗаписатьJSON() можно использовать параметр НастройкиСериализации.
При чтении даты из JSON-документа нужно учитывать, что значения даты представляются в нем строкой. В параметре ИменаСвойствСоЗначениямиДата метода ПрочитатьJSON() можно перечислить те свойства JSON, значения которых нужно преобразовать в дату «1С:Предприятия». А в параметре ОжидаемыйФорматДаты можно указать, в каком формате эти данные содержатся в JSON (ISO, JavaScript или Microsoft). Однако если окажется, что в какой-то момент формат данных JSON не совпадает с ожидаемым форматом, то будет вызвано исключение.
Поясним вышесказанное на примерах. Сначала попробуем записать значение даты обычным образом (листинг 1.31).
Листинг 1.31. Пример сериализации даты в JSON-документ
&НаСервереБезКонтекста
Процедура СериализацияТипаДатаНаСервере()
// Создать структуру с данными контрагента.
Данные = Новый Структура;
Данные.Вставить("Контрагент", "ОАО Фонтан");
Данные.Вставить("Телефон", "81234567788");
Данные.Вставить("ДатаИзменения", ТекущаяДата());
// Создать объект записи и открыть файл, в который будет выполняться запись.
Запись = Новый ЗаписьJSON;
ПараметрыЗаписиJSON = Новый ПараметрыЗаписиJSON(ПереносСтрокJSON.Авто, Символы.Таб);
Запись.ОткрытьФайл("c:\temp\Serialisation_2.json",,, ПараметрыЗаписиJSON);
// Выполнить запись данных (Данные) с помощью объекта записи (Запись).
ЗаписатьJSON(Запись, Данные);
// Завершить работу с файлом.
Запись.Закрыть();
КонецПроцедуры
В результате сформированный JSON-документ будет иметь следующий вид (листинг 1.32).
Листинг 1.32. Содержимое JSON-документа
{
"Контрагент": "ОАО Фонтан",
"Телефон": "81234567788",
"ДатаИзменения": "2019-02-28T20:48:54"
}
То есть стандартно дата сериализуется как локальная дата в формате ISO. Прочитать такую дату можно следующим образом (листинг 1.33).
Листинг 1.33. Пример десериализации даты из JSON-документа
&НаСервереБезКонтекста
Процедура ДесериализацияТипаДатаНаСервере()
// Создать объект чтения и открыть файл, из которого будет выполняться чтение.
Чтение = Новый ЧтениеJSON;
Чтение.ОткрытьФайл("c:\temp\Serialisation_2.json");
// Выполнить чтение данных в структуру Данные с помощью объекта чтения (Чтение).
Данные = ПрочитатьJSON(Чтение, Ложь, "ДатаИзменения", ФорматДатыJSON.ISO);
// Завершить работу с файлом.
Чтение.Закрыть();
// Вывести результат чтения в сообщение.
Сообщение = Новый СообщениеПользователю;
Сообщение.Текст = "Контрагент: " + Данные.Контрагент + ", Телефон: " + Данные.Телефон +
", Дата изменения: "+ Данные.ДатаИзменения;
Сообщение.Сообщить();
КонецПроцедуры
В процедуре десериализации при вызове метода ПрочитатьJSON() мы указываем имя свойства, содержащее дату ("ДатаИзменения"), и ожидаемый формат даты – значение ISO перечисления ФорматДатыJSON.
Результат чтения JSON-документа, содержимое которого показано в листинге 1.32, будет выглядеть следующим образом (рис. 1.6).
Рис. 1.6. Чтение даты из JSON-документа
Однако если указать другой ожидаемый формат даты, например ФорматДатыJSON.JavaScript, то будет получена ошибка из-за неверного формата даты.
Чтобы этого избежать, можно считывать данные обычным образом, а затем использовать так называемую постобработку при помощи функции ПрочитатьДатуJSON() (листинг 1.34).
Листинг 1.34. Пример десериализации даты из JSON-документа
&НаСервереБезКонтекста
Процедура ДесериализацияТипаДатаНаСервере()
// Создать объект чтения и открыть файл, из которого будет выполняться чтение.
Чтение = Новый ЧтениеJSON;
Чтение.ОткрытьФайл("c:\temp\Serialisation_2.json");
// Выполнить чтение данных в структуру Данные с помощью объекта чтения (Чтение).
Данные = ПрочитатьJSON(Чтение);
// Завершить работу с файлом.
Чтение.Закрыть();
// Прочитать дату JSON в нужном формате.
ДатаИзменения = ПрочитатьДатуJSON(Формат(Данные.ДатаИзменения, "ЧГ="), ФорматДатыJSON.ISO);
// Вывести результат чтения в сообщение.
Сообщение = Новый СообщениеПользователю;
Сообщение.Текст = "Контрагент: " + Данные.Контрагент + ", Телефон: " + Данные.Телефон +
", Дата изменения: " + ДатаИзменения;
Сообщение.Сообщить();
КонецПроцедуры
Результат чтения будет аналогичен показанному на рис. 1.6.
Теперь укажем формат и вариант записи даты при помощи параметра НастройкиСериализации (листинг 1.35).
Листинг 1.35. Пример сериализации даты в JSON-документ
&НаСервереБезКонтекста
Процедура СериализацияТипаДатаНаСервере()
// Создать структуру с данными контрагента.
Данные = Новый Структура;
Данные.Вставить("Контрагент", "ОАО Фонтан");
Данные.Вставить("Телефон", "81234567788");
Данные.Вставить("ДатаИзменения", ТекущаяДата());
// Создать настройки сериализации для записи дат.
НастройкиСериализации = Новый НастройкиСериализацииJSON;
НастройкиСериализации.ФорматСериализацииДаты = ФорматДатыJSON.JavaScript;
НастройкиСериализации.ВариантЗаписиДаты = ВариантЗаписиДатыJSON.УниверсальнаяДата;
// Создать объект записи и открыть файл, в который будет выполняться запись.
Запись = Новый ЗаписьJSON;
ПараметрыЗаписиJSON = Новый ПараметрыЗаписиJSON(ПереносСтрокJSON.Авто, Символы.Таб);
Запись.ОткрытьФайл("c:\temp\Serialisation_3.json",,, ПараметрыЗаписиJSON);
// Выполнить запись данных (Данные) с помощью объекта записи (Запись).
ЗаписатьJSON(Запись, Данные, НастройкиСериализации);
// Завершить работу с файлом.
Запись.Закрыть();
КонецПроцедуры
В результате сформированный JSON-документ будет иметь следующий вид (листинг 1.36).
Листинг 1.36. Содержимое JSON-документа
{
"Контрагент": "ОАО Фонтан",
"Телефон": "81234567788",
"ДатаИзменения": "new Date(1551382927000)"
}
В показанном примере дата сериализуется как универсальная дата в формате JavaScript. Прочитать такую дату можно следующим образом (листинг 1.37).
Листинг 1.37. Пример десериализации даты из JSON-документа
&НаСервереБезКонтекста
Процедура ДесериализацияТипаДатаНаСервере()
// Создать объект чтения и открыть файл, из которого будет выполняться чтение.
Чтение = Новый ЧтениеJSON;
Чтение.ОткрытьФайл("c:\temp\Serialisation_3.json");
// Выполнить чтение данных в структуру Данные с помощью объекта чтения (Чтение).
Данные = ПрочитатьJSON(Чтение, Ложь, "ДатаИзменения", ФорматДатыJSON.JavaScript);
// Завершить работу с файлом.
Чтение.Закрыть();
// Вывести результат чтения в сообщение.
Сообщение = Новый СообщениеПользователю;
Сообщение.Текст = "Контрагент: " + Данные.Контрагент + ", Телефон: " + Данные.Телефон +
", Дата изменения: "+ Данные.ДатаИзменения;
Сообщение.Сообщить();
КонецПроцедуры
В процедуре десериализации при вызове метода ПрочитатьJSON() мы указываем имя свойства, содержащее дату ("ДатаИзменения"), и ожидаемый формат даты – значение JavaScript перечисления ФорматДатыJSON.
Результат чтения будет аналогичен показанному на рис. 1.6.
Этого же результата можно добиться, выполнив постобработку при помощи функции ПрочитатьДатуJSON() (листинг 1.38).
Листинг 1.38. Пример десериализации даты из JSON-документа
&НаСервереБезКонтекста
Процедура ДесериализацияТипаДатаНаСервере()
// Создать объект чтения и открыть файл, из которого будет выполняться чтение.
Чтение = Новый ЧтениеJSON;
Чтение.ОткрытьФайл("c:\temp\Serialisation_2.json");
// Выполнить чтение данных в структуру Данные с помощью объекта чтения (Чтение).
Данные = ПрочитатьJSON(Чтение);
// Завершить работу с файлом.
Чтение.Закрыть();
// Прочитать дату JSON в нужном формате.
ДатаИзменения = ПрочитатьДатуJSON(Формат(Данные.ДатаИзменения, "ЧГ="), ФорматДатыJSON.JavaScript);
// Вывести результат чтения в сообщение.
Сообщение = Новый СообщениеПользователю;
Сообщение.Текст = "Контрагент: " + Данные.Контрагент + ", Телефон: " + Данные.Телефон +
", Дата изменения: " + ДатаИзменения;
Сообщение.Сообщить();
КонецПроцедуры
Вместо постобработки данных в процедуре чтения лучше и методологически более правильно использовать чтение с функцией восстановления.
Например, дата в JSON-документе может быть представлена в виде числа (листинг 1.39).
Листинг 1.39. Содержимое JSON-документа
{
"Контрагент": "ОАО Фонтан",
"Телефон": "81234567788",
"ДатаИзменения": 63661814555
}
Чтобы прочитать такую дату, можно использовать чтение с функцией восстановления (листинг 1.40).
Листинг 1.40. Пример десериализации даты из JSON-документа с функцией восстановления
&НаСервереБезКонтекста
Процедура ДесериализацияТипаДатаНаСервере()
// Заполнить массив имен реквизитов для восстановления.
РеквизитыДляВосстановления = Новый Массив;
РеквизитыДляВосстановления.Добавить("Телефон");
РеквизитыДляВосстановления.Добавить("ДатаИзменения");
// Создать объект чтения и открыть файл, из которого будет выполняться чтение.
Чтение = Новый ЧтениеJSON;
Чтение.ОткрытьФайл("c:\temp\Serialisation_7.json");
// Выполнить чтение данных в структуру Данные с помощью объекта чтения (Чтение).
Данные = ПрочитатьJSON(Чтение, Ложь, , , "ФункцияВосстановленияЧтения", ЭтотОбъект, , РеквизитыДляВосстановления);
// Завершить работу с файлом.
Чтение.Закрыть();
// Вывести результат чтения в сообщение.
Сообщение = Новый СообщениеПользователю;
Сообщение.Текст = "Контрагент: " + Данные.Контрагент + ", Телефон: " + Данные.Телефон +
", Дата изменения: "+ Данные.ДатаИзменения;
Сообщение.Сообщить();
КонецПроцедуры
В функции восстановления дата, выраженная простым числом, с помощью функции ПрочитатьДатуJSON() приводится к формату JavaScript (листинг 1.41).
Листинг 1.41. Функция восстановления
&НаСервере
Функция ФункцияВосстановленияЧтения(Свойство, Значение, ДополнительныеПараметры) Экспорт
Если Свойство = "ДатаИзменения" Тогда
Возврат ПрочитатьДатуJSON("new Date(" + Формат(Значение, "ЧГ=")+")", ФорматДатыJSON.JavaScript);
КонецЕсли;
Если Свойство = "Телефон" Тогда
СтрокаТелефона = Лев(Значение,1) + " " + Сред(Значение, 2, 3) + "-" + Сред(Значение, 5, 3) + "-" +
Сред(Значение, 8, 2) + "-" + Прав(Значение,2);
Возврат СтрокаТелефона;
КонецЕсли;
КонецФункции
Результат чтения JSON-документа, содержимое которого показано в листинге 1.39, будет выглядеть следующим образом (рис. 1.7).
Рис. 1.7. Чтение даты из JSON-документа с функцией восстановления
При сериализации/десериализации даты с использованием потоковой техники также можно использовать методы глобального контекста ЗаписатьДатуJSON() / ПрочитатьДатуJSON().
Например, в следующем фрагменте потоковой записи дата сериализуется как универсальная дата в формате ISO (листинг 1.42).
Листинг 1.42. Сериализация даты в JSON-документ с использованием потоковой техники
…
Запись.ЗаписатьИмяСвойства("ДатаИзменения");
Запись.ЗаписатьЗначение(ЗаписатьДатуJSON(ТекущаяДата(), ФорматДатыJSON.ISO, ВариантЗаписиДатыJSON.УниверсальнаяДата));
…
В результате в сформированном JSON-документе значение даты будет выглядеть следующим образом (листинг 1.43).
Листинг 1.43. Фрагмент сформированного JSON-документа
…
"ДатаИзменения": "2019-03-22T12:50:16Z"
…
Прочитать такую дату можно следующим образом (листинг 1.44).
Листинг 1.44. Десериализация даты из JSON-документа с использованием потоковой техники
…
Если Чтение.ТекущееЗначение = "ДатаИзменения" Тогда
Чтение.Прочитать();
Сообщение.Текст = "Значение = " +
ПрочитатьДатуJSON(Формат(Чтение.ТекущееЗначение, "ЧГ="), ФорматДатыJSON.ISO);
Сообщение.Сообщить();
КонецЕсли;
…
Результат чтения JSON-документа, фрагмент которого показан в листинге 1.43, будет выглядеть следующим образом (рис. 1.8).
Рис. 1.8. Потоковое чтение даты из JSON-документа
