1С обмен данными через веб сервис

Внимание! Данный функционал доступен в "Библиотеке стандартных подсистем", начиная с версии 2.3.1.62.

Для обмена данными через формат EnterpriseData у конфигураций, использующих "Библиотеку стандартных подсистем", есть два веб-сервиса:

• EnterpriseDataUpload – упрощенный вариант для загрузки данных в информационную базу из сторонних приложений. Не требует специальных настроек на стороне конфигурации (кроме развертывания собственно веб-сервиса); однонаправленный обмен данными – ТОЛЬКО импорт данных в информационную базу.
• EnterpriseDataExchange – для двустороннего обмена данными между конфигурацией и сторонним приложением. Для работы с ним необходима настройка обмена данными на стороне конфигурации.

Т.к. объем передаваемых через веб-сервисы данных ограничен, данные передаются в виде архивов формата ZIP. Если размер архива слишком велик для передачи через веб-сервис – его разбивают на части и передают по частям. Максимальный размер передаваемого через веб-сервис за сообщения зависит от ряда факторов (от пропускной способности сети, от настроек веб-сервера, от объема свободной памяти на передающей и приемной стороне и т.д.). Опыт показывает, что лучше не передавать через веб-сервис данные размером более нескольких мегабайт.

Собственно задача обмена данными включает в себя две подзадачи:

• Составление корректного XML-файла в формате EnterpriseData,
• Вызов веб-методов в правильной последовательности.

Особенности работы методов веб-сервисов

Большинство методов обоих веб-сервисов имеют выходной параметр – строку ErrorMessage. В случае если внутри конфигурации произошла ошибка, связанная с бизнес-логикой – в эту строку будет записана информация об этой ошибке. Если ошибок в процессе работы метода не было – в строку ErrorMessage будет помещена пустая строка. Если же в процессе работы метода возникла системная ошибка (например, на стороне конфигурации не удалось разархивировать полученный архив) – веб-метод сгенерирует исключение (exception).

Большинство методов обоих веб-сервисов возвращают строки, но в текущей версии возвращаемые строки всегда пустые (кроме EnterpriseDataUpload.PutDataActionResult – он возвращает статус обработки данных на стороне конфигурации – “Active”, “Completed” либо “Failed”).

Ниже на примерах мы рассмотрим, как использовать эти веб-сервисы для обмена данными с конфигурациями из языков C# и Java.

Что нужно для работы

На стороне конфигурации

На стороне конфигурации должны быть развернуты веб-сервисы EnterpriseDataUpload и EnterpriseDataExchange соответствующих версий (в данном случае была использована версия 1.0.1.1). При открытии этих двух URL-адресов в браузере (нужно подставить правильное для вашей инсталляции «1С:Предприятия» имя веб-сервера и публикации):

должны выводиться WSDL-описания сервисов:

В примерах использовалась Visual Studio 2012. В ней было создано консольное приложение на C#, в него импортированы веб-сервисы:

• В Solution Explorer в контекстном меню узла References выбрать команду Add Service Reference.
• В нижнем левом углу появившегося диалога нажать кнопку Advanced.
• В нижнем левом углу появившегося диалога нажать кнопку Add Web Reference.

Использовалась среда разработки Eclipse 4.4.2. Для генерации кода по WSDL файлов веб-сервисов применялась утилита wsdl2java из фреймворка Apache CXF 2.7.16.

Простой обмен данными с конфигурациями с помощью формата EnterpriseData

Формат сообщения

Объекты, предназначенные к обмену, «упакованы» в сообщение (Message), структуру в формате XML. Корневой элемент сообщения называется Message и содержит два дочерних элемента:

• Header (тип Header описан в схеме ExchangeMessage.xsd). Описывает заголовок сообщения, подробнее о заголовке – ниже.
• Body. Является коллекцией (sequence) элементов – наследников Object, т.е. объектов, описанных выше. Собственно содержит все объекты, которые нужно синхронизировать. В прикладных решениях фирмы «1С» при импорте данных из сообщения каждый объект из коллекции записывается в базу в отдельной транзакции. Так, если сообщение содержит три новых номенклатуры и при обработке третьей по счету номенклатуры произошла исключительная ситуация, первые две номенклатуры будут внесены в систему, третья – нет.

Объект может содержать в себе ссылки на другие объекты (например, документ «Акт выполненных работ» может содержать в себе одну или несколько ссылок на номенклатуру). В этом случае, если мы импортируем данные в информационную базу, все объекты, на которые мы ссылаемся из «родительского» объекта, должны либо уже существовать в системе, либо их описание должно содержаться в том же XML файле.

Если нам необходимо удалить какой-то объект, в коллекцию Body надо добавить элемент типа «УдалениеОбъекта», и в этом элементе сослаться на удаляемый объект (см. описание типа «УдалениеОбъекта» в схеме EnterpriseData_X_Y_Z.xsd).

С помощью формата EnterpriseData нам доступны операции создания, обновления и удаления объектов. На данный момент для корректной загрузки данных в типовые решения все объекты должны содержать заполненный элемент «Ссылка» из элемента «Ключевые свойства» (GUID в форме строки). Это первичный ключ объекта. Конфигурации ведут себя следующим образом:

• Если в системе нет объекта с ключом из поля «Ссылка» — создается новый объект.
• Если в системе уже есть объект с ключом из поля «Ссылка» — существующий объект обновляется новыми данными, пришедшими в XML.
• Если пришел элемент типа «УдалениеОбъекта» — объект с соответствующим ключом удаляется из системы.

Пример сообщения

В секции — ссылка на формат сообщения, дата создания сообщения и версия формата.

В секции — описание нового контрагента (тип «Справочник.Контрагенты») с полным наименованием «Леннон Джон» и описание удаления объекта по ключу. Ключ в объекте (элемент ) – тот же, что и у нового контрагента. В результате обработки этого сообщения конфигурация создаст нового контрагента и тут же удалит его.

Веб-сервис EnterpriseDataUpload

EnterpriseDataUpload – интерфейс исключительно для импорта данных в формате EnterpriseData в конфигурацию из сторонних приложений. Условия задачи: у нас есть XML файл с данными в формате EnterpriseData, надо передать его в конфигурацию и убедиться в том, что на стороне конфигурации данные успешно получены.

Алгоритм работы следующий:

1. Заархивировать XML-файл с данными. Если размер архива превышает некоторое предельное значение (например, 2Мб) – разбиваем его на части размером не более 2Мб каждая.
2. Проверить соединение с помощью метода TestConnection .
3. Отправить каждую часть архива с помощью метода PutFilePart . Если мы передаем архив одним файлом – второй параметр метода PutFilePart , PartNumber, должен быть равен нулю. Если архив из нескольких частей – параметр PartNumber должен соответствовать номеру части, начиная с единицы.
4. После отправки всех частей архива вызвать метод PutData .
5. Получить результат выполнения метода PutData можно с помощью метода PutDataActionResult . Т.к. обработка полученных данных на стороне конфигурации занимает какое-то время, можно вызывать PutDataActionResult в цикле один раз в, например, 5 секунд, пока он не вернет строку «Completed» (или «Failed», если данные по какой-либо причине обработать не удалось, или «Canceled» если операция отменена).

Пример на C#

Итак, у нас есть архив с данными в формате EnterpriseData (один или несколько файлов). Не будем описывать, как в программе создать архив и разбить его на несколько файлов, чтобы сэкономить время – желающие смогут легко найти примеры подобного кода, используя поисковые сервера и соответствующие запросы.

Реализуем функцию, которая принимает такие входные параметры:

• URL Веб-сервиса,
• Имя пользователя для соединения с Веб-сервисом,
• Пароль.

Путь до архивированного файла с данными. Если архив умещается в одном файле – это имя файла с полным путем, включая расширение (например, “C:Exchangedata.zip”). Если же архив разбит на несколько частей, то это будет имя любого из файлов без расширения и точки (например, “C:Exchangedata”). Предполагается, что это последовательность файлов с расширениями “.001”, “.002” и т.д.

Реализация функции (в виде статического метода) в листинге ниже. Диагностическая информация выводится в консоль.

Пример на Java

Принципиально ничем не отличается от реализации на C#.

Сегодня WEB сервисы используются практически повсеместно – именно они предоставляют нам информацию о рейсах самолетов и поездов, курсах валют и погоде. Неудивительно, что и 1С обладает возможностью создания собственных WEB сервисов, позволяющих выступать как в роли поставщика, так и потребителя. Данный механизм встроен в платформу «1С:Предприятие 8.3» и разработчики могут добавлять даже в типовую конфигурацию собственные объекты типа «WEB-сервисы». Их архитектура построена на наборе сервисов, позволяющих обмениваться информацией с другим программным обеспечением.

Создание веб-сервиса 1С

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

Как создавать веб-сервис в 1С?

Чтобы определенная функция системы 1С стала доступна внешнему ПО, необходимо выполнить следующий алгоритм действий:

1. Зайти в конфигурацию и в определенной ветке дерева добавить объект WEB-сервис;
2. Описать все операции, которые сможет выполнять наш функционал. Описание функций производиться в модуле на встроенном в 1С языке;
3. Добавить описание параметров функций веб-сервиса. Учтите, что типы данных описываются с учетом существующих типов механизма XDTO, появившегося в платформе версии 8.1;
4. Опубликовать созданный WEB-сервис на сервере. Механизм, встроенный в платформу 1С, поддерживает следующие стандарты:

• SOAP
• WSDL
• HTTP
• SSL/TLS
• WS-I BP

Пример создания простого WEB-сервиса

Чтобы наиболее наглядно продемонстрировать работу механизма WEB-сервисов, создадим пример – функционал, определяющий длину введенной строки. Программное обеспечение передаст в качестве параметра запроса строку, а функция, описанная в 1С, вернет число символов. При создании нужно помнить, что публикация этого механизма даст возможность обращения к нему различного ПО. Так как не каждое ПО способно воспринимать кириллицу, будем называть объекты конфигурации, используя латинские знаки.

Открываем конфигуратор, находим в дереве ветку «WEB-сервисы» и добавляем новый сервис «wa_LengthString». Также необходимо на вкладке «Операции» добавить новую операцию. Назовем ее «CalcLengthString», в свойствах укажем тип возвращаемого значения – int или integer и создадим внутри нее параметр «InputString». Тип значения оставляем string.

Теперь необходимо прописать действие функции CalcLengthString в модуле WEB-сервиса. Для этого открываем свойства созданной функции и нажимаем кнопку в виде лупы справа, у поля ввода «Имя процедуры». 1С автоматически создаст функцию в модуле нашего WEB-сервиса и откроет его для того, чтобы мы описали действие CalcLengthString. Воспользуемся этим и напишем действие функции – определение длины вводимой строки.

Фактически на этом создание простейшего WEB-сервиса закончено. Теперь необходимо «выложить» этот сервис в общий доступ, чтобы стороннее ПО или другие системы 1С могли пользоваться данным функционалом.

Публикация веб-сервиса 1С

Для того чтобы мы смогли опубликовать созданный веб-сервис с его функциональностью, нам необходимо иметь доступ на сайт. Перед тем как мы начнем публикацию сервиса, необходимо проверить имя файла в свойствах созданного модуля wa_LengthString. Оно должно быть понятное, простое и иметь расширение «1cws».

Теперь настало время публиковать созданный нами WEB-сервис на сервере. Эта возможность появилась в версии платформы 8.3 и многие компании уже поняли всю пользу этого функционала. Для того чтобы приступить к публикации, необходимо в конфигураторе открыть форму «Администрирование/Публикация на веб-сервере…».

В открывшемся окне нам необходима настройка Web сервисов 1С и заполнение определенных полей:

• Имя. Обозначает папку на веб-сервере, в которой будет храниться описание нашего веб-сервиса. Будьте внимательны к регистрам, так как иногда серверы различают символы большого и малого регистра;
• Веб-сервер. Необходимо выбрать сервер из установленных на компьютере;
• Каталог. Вы должны выбрать путь к папке, где хранятся данные веб-сервера по настройке подключения. Используются исключительно латинские буквы;
• Два признака типа «Булево». Первый нам пригодиться, если необходимо настроить доступ через веб-клиент к конфигурации. Для того чтобы опубликовать сервис 1С, необходимо поставить вторую отметку.

Остается лишь проверить, что у нужного WEB-сервиса установлена галка в первом столбце, и нажать на «Опубликовать».

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

Проверить, опубликован ли ваш WEB-сервис на сервере, достаточно просто. Необходимо открыть любой браузер и в адресную строку вбить строчку типа:

В ответ на такой запрос адреса браузер должен отобразить структуру файла XML. Если же вы видите пустую страницу, ошибку или непонятные символы (проблемы с кодировкой), то нужно еще раз проверить все действия. Также не лишним будет убедиться, что сервер настроен верно, и у вас есть к нему доступ. После успешной публикации WEB-сервис 1С смогут использовать сторонние приложения.

рубрики: Web-Сервисы | Дата: 1 Июль, 2017

Итак, у нас есть работающий веб-сервер. Теперь самое время заняться разработкой и публикацией веб-сервисов.

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

Добавление Web-сервиса в метаданные

Открываем дерево конфигурации, ветка Общие, далее Web-сервисы, добавляем новый веб-сервис (назову его my_ws) и заполняем свойства как показано на рисунке.

Необходимо сделать несколько пояснений о свойствах веб-сервисов

• Пакеты XDTO — в этом поле указывается список пакетов XDTO, типы которых могут использоваться в значении, которое возвращается в результате выполнения операций веб-сервиса.
• URI пространства имен — это строка, которая задает URI пространства имен для данного веб-сервиса. Любой веб-сервис можно однозначно идентифицировать по сочетанию его имени и пространству имен. Необходимо четко понимать, что это свойство не имеет ничего общего ни с физическим адресом веб-сервера, ни с сайтом органицации и т.д. Это просто некий виртуальный адрес. Поэтому присваивать надо внятное имя, которое сможет рассказать, например, об области расположения и применения веб сервиса. В частности может присутствовать аббревиатура типовой конфигурации к которой веб-сервис относится.

Операции веб-сервиса

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

В качестве примера создадим для нашего веб-сервиса операцию, которая будет возвращать классическую фразу «Привет мир!». Назовем ее Hello:

В модуле веб-сервиса создадим функцию ПриветМир(), ссылку на которую вставим в соответствующее свойство операции.

Но у этой операции есть один недостаток. В нее нельзя передавать исходные данные. Для этих целей в операциях веб-сервисов используется подчиненные им объекты — Параметры.

Добавим еще одну операцию — HelloUsr, и создадим для нее параметр Name.

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

Публикация Web-сервиса

Теперь у нас все готово для публикации веб-сервиса. Для этого необходимо зайти в конфигуратор под правами администратора. Щелкаем по ярлыку 1С правой кнопкой и выбираем соответствующий пункт меню:

В меню выбираем Администрирование —> Публикация на веб-сервере

В открывшемся окне прописываем имя публикации, отмечаем пункт Публиковать Web-сервисы и также отмечаем созданный нами веб-сервис:

Нажимаем Опубликовать, после чего надо перезапустить веб-сервер.

WS-ссылки

Для работы с веб-сервисами используется такой объект 1С как WS-ссылка. Она представляет собой WSDL описание веб-сервиса полученное путем импорта из источника на котором расположен веб-сервис. То есть в первую очередь нам надо знать адрес по которому мы сможем получить WSDL описание веб-сервиса. Применительно к нашему примеру в соответствии с настройками, которые мы делали в процессе создания и публикации веб-сервиса этот адрес будет выглядеть следующим образом

Рассмотрим из каких же частей состоит этот адрес.

• http://localhost/ — это адрес указывает на физическое расположение веб-сервера. Так как у меня он находится на локальной машине, то localhost, а на практике это либо IP-адрес сервера, либо его имя
• professia1c — это имя публикации. Мы его вводили в поле Имя в диалоговом окне, когда публиковали веб-сервис
• ws — признак того, что мы обращаемся к веб сервису
• my_ws.1cws — имя файла публикации, которое мы указывали в свойствах при создании веб-сервиса
• ?wsdl — параметр, который указывает, что нам нужно получить WSDL описание

После публикации веб-сервиса, для того чтобы убедиться, что он успешно опубликован, можно ввести адрес его WSDL описания в адресную строку браузера. При этом мы должны получить в окне браузера XML файл примерно вот такого содержания:

Работа с WS-ссылками возможна двумя способами:

1. Использование динамической ws-ссылки.
2. Создание статической ws-ссылки.

Рассмотрим каждый из этих способов

Динамические WS-ссылки

В этом случае WS-ссылка создается программно. Продолжим наш пример и приведем текст процедуры, которая задействует операцию HelloUsr нашего веб сервиса:

Как нетрудно догадаться, результатом выполнения этой процедуры будет текст в окне сообщения «Привет, Вася!»

Статические WS-ссылки

Вместо программного создания объекта WSОпределения мы можем непосредственно в дереве конфигурации создать объект метаданных WS-ссылка. В процессе создания будет выведено окно с предложением указать адрес WSDL определения для его импорта:

После этого мы можем в коде ссылаться непосредственно на эту WS-ссылку. И процедура по обращению к веб-сервису примет вот такой вид: