1С:Предприятие 8. Веб-сервисы. XDTO
Программист 1С, разрабатывая свой веб-сервис в большинстве случаев работает не с простыми типами, а с типами свой конфигурации, либо с типами данных другой информационной системы. Потому программист сталкивается с проблемой перевода одного типа данных в другой. Для решения этой проблемы в 1С существует механизм XDTO.
XDTO (XML Data Transfer Objects) это механизм позволяющий создавать модель данных и переводить ее в формат XML. Простыми словами, вы можете сделать модель документа поступления товаров и услуг через XDTO и выгрузить любой документ в XML файл, не работая с файлом напрямую.
Этот механизм применяется при обмене файлами XML и при работе с типами в веб-сервисах.
Давайте попробуем разобраться с XDTO. У нас уже есть конфигурация с веб-сервисом и веб операцией Plus2(). Пусть теперь эта операция будет возвращать сообщения о ошибках. Например, если входящий параметр функции меньше нуля, мы будем выдавать ошибку "Error", в остальных случаях будем выдавать "ОК". То есть теперь функция Plus2 будет возвращать структуру:
1. Результат - число - результат выполнения сложения. 0 если есть ошибка;
2. Ошибка - строка - "Ok" или "Передано отрицательное значение".
Для создания такой структуры мы будем использовать тип ОбъектXDTO, так как он может описать сложную структуру с несколькими реквизитами различных типов. Помимо ОбъектXDTO существует тип ЗначениеXDTO, но данный тип не позволяет описывать сложные структуры, потому использовать мы его не можем.
Для этого нам надо:
1. Создать модель XDTO для нашей структуры;
2. В модуле веб-сервиса создать ОбъектXDTO для для того что бы возвратить как результат функции.
Приступим. Откроем базу в режиме конфигурирования. Найдем в дереве метаданных XDTO и создадим новый пакет XDTO.
Откроется окно свойств, назовем этот пакет "ТипыВебСервиса". В свойство "URI пространства имен" укажем "http://codenotes-1c.blogspot.com". Как я уже писал в статье " 1С:Предприятие 8. Веб-сервисы. Реализация веб-сервиса" нет особого значения что вы укажете в этом поле и даже не особо важно (для 1С) что эта строка будет ссылкой URI.
После этого пакет можно открыть, щелкнув в дереве метаданных по пакету "ТипыВебСервиса" и в новом окне добавим "Тип объекта".
Дадим ему имя "РезультатОперации", остальные свойства можно не менять.
У объекта создадим свойство. Для этого нажмем на него правой кнопкой и выберем "Добавить - Свойство".
И в окне свойств заполним его свойства. Укажем имя "Результат" и тип int из пространства имен http://www.w3.org/2001/XMLSchema как показано на рисунке.
И создадим второе свойство "Ошибка" как на картинке ниже.
На этом завершено создание пакета XDTO. Теперь можно приступить к написанию кода обработки ошибки и возврата результата веб-операции.
У нашего веб-сервиса WebService в свойство "Пакет XDTO" укажем только что созданный пакет. Иначе не сможем указать у веб-операции Plus2 тип "РезультатОперации".
Откроем свойства веб-операции Plus2 в поле "Тип возвращаемого значения" выберем тип "РезультатОперации" из пакета с пространства имен "http://codenotes-1c.blogspot.com" как на рисунке.
Теперь функция Plus2 будет возвращать не число, а структуру с двумя полями "Результат" и "Ошибка". Давайте откроем модуль веб-сервиса. Так как созданная нами структура не является стандартным типом то необходимо создать переменную типа "РезультатОперации", конечно на самом деле это будет ОбъектXDTO.
ТипXDTOРезультатОперации = ФабрикаXDTO.Тип("http://codenotes-1c.blogspot.com", "РезультатОперации");
Этой строкой мы с помощью Фабрики XDTO в конфигурации создали ТипОбъектаXDTO, указав пространство имен пакета и имя типа.
РезультатОперации = ФабрикаXDTO.Создать(ТипXDTOРезультатОперации);
Эта строка создает уже сам ОбъектXDTO, с которым можно уже будет работать привычным способом (обращение к реквизитам через точку). Далее мы перепишем код, добавив проверку на отрицательные значения, и код веб-операции будет выглядеть так:
Функция Plus2(Параметр)
ТипXDTOРезультатОперации = ФабрикаXDTO.Тип("http://codenotes-1c.blogspot.com", "РезультатОперации");
РезультатОперации = ФабрикаXDTO.Создать(ТипXDTOРезультатОперации);
Если Параметр < 0 Тогда
РезультатОперации.Результат = 0;
РезультатОперации.Ошибка = "Передано отрицательное значение";
Иначе
РезультатОперации.Результат = Параметр+2;
РезультатОперации.Ошибка = "Ok";
КонецЕсли;
Возврат РезультатОперации;
КонецФункции
Если вызвать эту операцию с отрицательным значением то получим следующий результат:
<Результат xmlns="http://codenotes-1c.blogspot.com">0
<Ошибка xmlns="http://codenotes-1c.blogspot.com">Передано отрицательное значение
О том как вызвать операцию веб-сервиса и просмотреть результат вы можете прочитать в статье " 1С:Предприятие 8. Веб-сервисы. Публикация и тестирование".
Вы видите что в результате сообщение веб-операции содержит два поля - Результат и Ошибка.
В данном примере описана работа с ОбъектомXDTO. Как я уже говорил, его отличие от ЗначениеXDTO в том, что ЗначениеXDTO не может описывать структурированные типы, вы не сможете, используя ЗначениеXDTO создать тип передающий какой либо документ или справочник. Но! ЗначениеXDTO имеет большие возможности по описанию ограничений примитивных типов и нашу задачу с проверкой на отрицательное значение параметра можно было решить более изящно. Если создать в пакете XDTO ТипЗначения "ПоложительноеЧисло" и указать его минимум,
то этот тип можно использовать как тип входного параметра:
Теперь при вызове веб-операции с отрицательным значением в ответ мы получим сообщение об ошибке:
soap:Sender
Неизвестная ошибка. Ошибка проверки данных XDTO:
Значение: '-2' не соответствует простому типу: {http://codenotes-1c.blogspot.com}ПоложительноеЧисло
Несоответствие фасету MinInclusive = '0'
по причине:
Ошибка проверки данных XDTO:
Значение: '-2' не соответствует простому типу: {http://codenotes-1c.blogspot.com}ПоложительноеЧисло
Несоответствие фасету MinInclusive = '0'
Таким образом используя описание ЗначенияXDTO мы можем указать ограничения к типам и не задумываться о программной обработке значений. Вы можете использовать ЗначениеXDTO в полях ОбъектаXDTO, тем самым можете создавать очень сложные структуры типов данных.
Смотрите также:
Электронный учебник по программированию в 1С
Рекомендации по изучению программирования 1С с нуля
Игра "Кто хочет стать миллионером?" с вопросами на определенную тематику (язык программирования JavaScript, английские, немецкие, французские, испанские, португальские, нидерландские, итальянские слова, электробезопасность, промышленная безопасность, бокс и т.п.), написанная на 1С
Программирование в 1С 8.3 с нуля - краткий самоучитель
Комплексная подготовка программистов 1С:Предприятие 8.2
Сайты с уроками программирования и со справочниками
Youtube-каналы с уроками программирования
Сайты для обучения программированию
Лекции и уроки
XDTO (XML Data Transfer Objects) это механизм позволяющий создавать модель данных и переводить ее в формат XML. Простыми словами, вы можете сделать модель документа поступления товаров и услуг через XDTO и выгрузить любой документ в XML файл, не работая с файлом напрямую.
Этот механизм применяется при обмене файлами XML и при работе с типами в веб-сервисах.
Давайте попробуем разобраться с XDTO. У нас уже есть конфигурация с веб-сервисом и веб операцией Plus2(). Пусть теперь эта операция будет возвращать сообщения о ошибках. Например, если входящий параметр функции меньше нуля, мы будем выдавать ошибку "Error", в остальных случаях будем выдавать "ОК". То есть теперь функция Plus2 будет возвращать структуру:
1. Результат - число - результат выполнения сложения. 0 если есть ошибка;
2. Ошибка - строка - "Ok" или "Передано отрицательное значение".
Для создания такой структуры мы будем использовать тип ОбъектXDTO, так как он может описать сложную структуру с несколькими реквизитами различных типов. Помимо ОбъектXDTO существует тип ЗначениеXDTO, но данный тип не позволяет описывать сложные структуры, потому использовать мы его не можем.
Для этого нам надо:
1. Создать модель XDTO для нашей структуры;
2. В модуле веб-сервиса создать ОбъектXDTO для для того что бы возвратить как результат функции.
Приступим. Откроем базу в режиме конфигурирования. Найдем в дереве метаданных XDTO и создадим новый пакет XDTO.
Откроется окно свойств, назовем этот пакет "ТипыВебСервиса". В свойство "URI пространства имен" укажем "http://codenotes-1c.blogspot.com". Как я уже писал в статье " 1С:Предприятие 8. Веб-сервисы. Реализация веб-сервиса" нет особого значения что вы укажете в этом поле и даже не особо важно (для 1С) что эта строка будет ссылкой URI.
После этого пакет можно открыть, щелкнув в дереве метаданных по пакету "ТипыВебСервиса" и в новом окне добавим "Тип объекта".
Дадим ему имя "РезультатОперации", остальные свойства можно не менять.
У объекта создадим свойство. Для этого нажмем на него правой кнопкой и выберем "Добавить - Свойство".
И в окне свойств заполним его свойства. Укажем имя "Результат" и тип int из пространства имен http://www.w3.org/2001/XMLSchema как показано на рисунке.
И создадим второе свойство "Ошибка" как на картинке ниже.
На этом завершено создание пакета XDTO. Теперь можно приступить к написанию кода обработки ошибки и возврата результата веб-операции.
У нашего веб-сервиса WebService в свойство "Пакет XDTO" укажем только что созданный пакет. Иначе не сможем указать у веб-операции Plus2 тип "РезультатОперации".
Откроем свойства веб-операции Plus2 в поле "Тип возвращаемого значения" выберем тип "РезультатОперации" из пакета с пространства имен "http://codenotes-1c.blogspot.com" как на рисунке.
Теперь функция Plus2 будет возвращать не число, а структуру с двумя полями "Результат" и "Ошибка". Давайте откроем модуль веб-сервиса. Так как созданная нами структура не является стандартным типом то необходимо создать переменную типа "РезультатОперации", конечно на самом деле это будет ОбъектXDTO.
ТипXDTOРезультатОперации = ФабрикаXDTO.Тип("http://codenotes-1c.blogspot.com", "РезультатОперации");
Этой строкой мы с помощью Фабрики XDTO в конфигурации создали ТипОбъектаXDTO, указав пространство имен пакета и имя типа.
РезультатОперации = ФабрикаXDTO.Создать(ТипXDTOРезультатОперации);
Эта строка создает уже сам ОбъектXDTO, с которым можно уже будет работать привычным способом (обращение к реквизитам через точку). Далее мы перепишем код, добавив проверку на отрицательные значения, и код веб-операции будет выглядеть так:
Функция Plus2(Параметр)
ТипXDTOРезультатОперации = ФабрикаXDTO.Тип("http://codenotes-1c.blogspot.com", "РезультатОперации");
РезультатОперации = ФабрикаXDTO.Создать(ТипXDTOРезультатОперации);
Если Параметр < 0 Тогда
РезультатОперации.Результат = 0;
РезультатОперации.Ошибка = "Передано отрицательное значение";
Иначе
РезультатОперации.Результат = Параметр+2;
РезультатОперации.Ошибка = "Ok";
КонецЕсли;
Возврат РезультатОперации;
КонецФункции
Если вызвать эту операцию с отрицательным значением то получим следующий результат:
<Результат xmlns="http://codenotes-1c.blogspot.com">0
<Ошибка xmlns="http://codenotes-1c.blogspot.com">Передано отрицательное значение
О том как вызвать операцию веб-сервиса и просмотреть результат вы можете прочитать в статье " 1С:Предприятие 8. Веб-сервисы. Публикация и тестирование".
Вы видите что в результате сообщение веб-операции содержит два поля - Результат и Ошибка.
В данном примере описана работа с ОбъектомXDTO. Как я уже говорил, его отличие от ЗначениеXDTO в том, что ЗначениеXDTO не может описывать структурированные типы, вы не сможете, используя ЗначениеXDTO создать тип передающий какой либо документ или справочник. Но! ЗначениеXDTO имеет большие возможности по описанию ограничений примитивных типов и нашу задачу с проверкой на отрицательное значение параметра можно было решить более изящно. Если создать в пакете XDTO ТипЗначения "ПоложительноеЧисло" и указать его минимум,
то этот тип можно использовать как тип входного параметра:
Теперь при вызове веб-операции с отрицательным значением в ответ мы получим сообщение об ошибке:
soap:Sender
Неизвестная ошибка. Ошибка проверки данных XDTO:
Значение: '-2' не соответствует простому типу: {http://codenotes-1c.blogspot.com}ПоложительноеЧисло
Несоответствие фасету MinInclusive = '0'
по причине:
Ошибка проверки данных XDTO:
Значение: '-2' не соответствует простому типу: {http://codenotes-1c.blogspot.com}ПоложительноеЧисло
Несоответствие фасету MinInclusive = '0'
Таким образом используя описание ЗначенияXDTO мы можем указать ограничения к типам и не задумываться о программной обработке значений. Вы можете использовать ЗначениеXDTO в полях ОбъектаXDTO, тем самым можете создавать очень сложные структуры типов данных.
Смотрите также:
Электронный учебник по программированию в 1С
Рекомендации по изучению программирования 1С с нуля
Игра "Кто хочет стать миллионером?" с вопросами на определенную тематику (язык программирования JavaScript, английские, немецкие, французские, испанские, португальские, нидерландские, итальянские слова, электробезопасность, промышленная безопасность, бокс и т.п.), написанная на 1С
Программирование в 1С 8.3 с нуля - краткий самоучитель
Комплексная подготовка программистов 1С:Предприятие 8.2
Сайты с уроками программирования и со справочниками
Youtube-каналы с уроками программирования
Сайты для обучения программированию
Лекции и уроки