Бром. Универсальный SOAP сервис обмена данными между 1С и Перфолента.Net

Как ни крути, но в бывших советских республиках большую роль в автоматизации экономики занимает платформа 1С (на Украине переименована в BAF). Поэтому программистам пишущим на других языках программирования очень часто необходимо организовать обмен данными с этой платформой. Есть много вариантов технической реализации обмена, например, можно использовать COM соединение с базой, можно создать HTTP или Web (SOAP) сервис средствами платформы, а можно даже выполнять обмен через файлы по расписанию. В любом из этих способов есть свои достоинства и недостатки. В этой статье мы рассмотрим один из возможных способов обмена данными между базой данных на платформе 1С и программой написанной на языке программирования Перфолента.Net.

Бром – это универсальный Web (SOAP) сервис, реализованный на платформе 1С и предназначенный для обмена данными с программами написанными на других языках. Сервис написан компанией ITworks, подробности о возможностях сервиса можно прочитать на официальном сайте Бром API, там же есть обучающие видеоролики.

Интеграция сервиса Бром и языка программирования Перфолента стала возможна потому, что открытый исходный код библиотек Бром выложен на GitHub. Огромная благодарность Антону Шаганову за помощь при интеграции Перфоленты и Брома. 

Конечно, можно использовать библиотеку, выложенную на сайте, без доработок, однако, при использовании её в программе на Перфоленте выявились неудобства и недостатки, из-за которых было принято решение сделать отдельную библиотеку для Перфоленты, которая была незатейливо названа ПерфоБром.

Рассмотрим сервис Бром подробнее.

 

Возможности.

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

·         Получать, добавлять, удалять и редактировать данные прикладных объектов 1С, констант, справочников, документов и т.д., с учетом сложных условий отбора и сортировки;

·         Получать данные из 1С с помощью произвольных запросов на языке 1С:Предприятие;

·         Вызывать процедуры и функции серверных модулей 1С (общих модулей и модулей менеджеров) с передачей произвольного количества параметров вызова и с передачей полученного значения обратно в качестве результата вызова;

·         Исполнять произвольный код 1С на стороне сервера с возможностью передачи параметров и получения возвращаемого значения;

·         Взаимодействовать с объектами ссылочного типа на клиентской стороне.

В этой статье рассмотрен минимальный набор примеров для понимания принципов работы с веб-сервисом Бром. Больше полезного кода Вы найдете в каталоге примеров Перфоленты.

 

Архитектура.

Сервис делится на две части – платформенную и клиентскую.

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

Клиентская часть — это библиотека ПерфоБром (PerfoBrom.dll), написанная для использования в программах на языке Перфолента. Существуют клиентские библиотеки и для других языков, например, для C#, VB.Net, PHP и Python.

 

Установка и настройка расширения конфигурации.

Процесс установки и настройки расширения конфигурации достаточно подробно описан на официальном сайте Бром API в статье «Установка и настройка». Однако, само расширение лучше взять из комплекта примеров, поставляющихся в дистрибутиве Перфоленты. Это не обязательно, но там сделаны небольшие доработки для лучшей интеграции с Перфолентой, хотя, сервис будет работать и без этих доработок.

Обратите особое внимание на настройку прав пользователей для доступа к элементам базы данных и на выполнение кода клиентом. От правильных настроек зависит безопасность вашей базы данных, особенно, если доступ к сервису Бром будет открыт из внешней сети.

Будет безопаснее, если веб-сервис будет опубликован по протоколу HTTPS, а еще лучше, если внешние клиенты смогут подключаться к веб-сервису только через VPN.

 

Работа с сервисом Бром из Перфоленты.

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

Для начала надо загрузить сборку библиотеки PerfoBrom.dll, которая поставляется в дистрибутиве Перфоленты, с помощью директивы препроцессора #ЗагрузитьСборку.

#ЗагрузитьСборку "PerfoBrom.dll"

Компилятор скопирует сборку библиотеки в каталог создаваемой программы.

Теперь можно создать объект типа БромКлиент и подключиться к веб-сервису. Для подключения понадобится адрес веб-сервиса, а также логин и пароль пользователя, от имени которого будет осуществляться обмен данными с 1С.

//создадим объект типа БромКлиент
Клиент = Новый БромКлиент(@"
Публикация = https://mycompany.com/brombase;
Пользователь = bromclient;
Пароль = qwerty;
"@);
//перед подключением можно настроить параметры соединения
Клиент.АвтоПереподключение = Истина //по умолчанию Истина
Клиент.КоличествоПопытокПодключения = 8 //по умолчанию 3
Клиент.ТаймаутОткрытияСоединения = 30 //по умолчанию 20
Клиент.ТаймаутПолученияДанных = 300   //по умолчанию 120
Клиент.ТаймаутОтправкиДанных = 300     //по умолчанию 120
//теперь подключаемся
Если НЕ Клиент.Подключиться()
    ВыводСтроки "Подключиться к сервису не удалось..."
    ВыводСтроки Клиент.ОписаниеОшибки
    Возврат
КонецЕсли
ВыводСтроки "Сервис Бром подключен..."

Всё! Веб-сервис Бром подключен и можно получать данные из 1С запросами, выполнять на стороне 1С необходимый код, записывать любые данные, в том числе создавать элементы справочников, документы и множество других объектов 1С.

Обратите внимание, что таймауты задаются в секундах, а после каждой неудачной попытки подключения следует пауза в 500 миллисекунд. Поэтому количество попыток подключения выбирайте исходя из того, сколько секунд длится холодный старт сервиса. Например, если холодный старт сервиса длится примерно 3 секунды, то установите с запасом 8-10 попыток подключения.

Если свойству АвтоПереподключение установить значение Ложь, то попытка обмена данными в случае разрыва связи приведет к вызову исключения, а при значении Истина, клиент попытается восстановить соединение и продолжить обмен.

 

Сериализуемые и несериализуемые типы данных.

Сериализация – это процесс преобразования внутренней структуры объекта в поток двоичных данных, которые можно сохранить на устройство хранения или передать по линиям связи.

Десериализация – это процесс восстановления объекта из потока двоичных данных.

Библиотека ПерфоБром автоматически сериализует и десериализует данные при обмене в обе стороны. Однако, не все типы данных 1С могут быть сериализованы, поэтому некоторые запросы могут вернуть специальный тип ИтВоркс.Бром.Типы.НесериализуемыеДанные.

В следующей таблице указаны соответствующие друг другу типы данных 1С и Перфоленты:

Тип 1С	Направление обмена	Тип Перфоленты
Примитивные типы:
Строка	↔	Строка
Число	↔	Число
Булево	↔	Булево
Дата	↔	Дата
Коллекции:
Массив	↔	ИтВоркс.Бром.Типы.Массив
	←	System.Collections.IList
Структура	↔	ИтВоркс.Бром.Типы.Структура
Соответствие	↔	ИтВоркс.Бром.Типы.Соответствие
	←	System.Collections.IDictionary
ТаблицаЗначений	↔	ИтВоркс.Бром.Типы.ТаблицаЗначений
ДеревоЗначений	↔	ИтВоркс.Бром.Типы.ДеревоЗначений
Ссылки:
ОбъектСсылка*	↔	ИтВоркс.Бром.Типы.ОбъектСсылка*
ПеречислениеСсылка	↔	ИтВоркс.Бром.Типы.ПеречислениеСсылка
Системные перечисления:
ВидДвиженияНакопления	↔	ИтВоркс.Бром.Типы.ВидДвиженияНакопления
ВидДвиженияБухгалтерии	↔	ИтВоркс.Бром.Типы.ВидДвиженияБухгалтерии
ВидСчета	↔	ИтВоркс.Бром.Типы.ВидСчета
Прочие типы:
Неопределено	↔	Неопределено
NULL	↔	System.DBNull
УникальныйИдентификатор	↔	System.Guid
ДвоичныеДанные	↔	ИтВоркс.Бром.Типы.ДвоичныеДанные
ХранилищеЗначения	↔	ИтВоркс.Бром.Типы.ХранилищеЗначения
Граница	↔	ИтВоркс.Бром.Типы.Граница
МоментВремени	↔	ИтВоркс.Бром.Типы.МоментВремени
Тип	↔	ИтВоркс.Бром.Типы.Тип
ОписаниеТипов	↔	ИтВоркс.Бром.Типы.ОписаниеТипов
Любые несериализуемые данные	→	ИтВоркс.Бром.Типы.НесериализуемыеДанные

 

*В приведенной таблице тип ОбъектСсылка является базовым для всех ссылочных типов 1С, таких как БизнесПроцессСсылка, ДокументСсылка, ЗадачаСсылка, ПланВидовРасчетаСсылка, ПланВидовХарактеристикСсылка, ПланСчетовСсылка, СправочникСсылка.

 

Получение информации о системе.

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

Инфо = Клиент.ПолучитьИнформациюОСистеме();
ВыводСтроки "Конфигурация: "+Инфо.Синоним
ВыводСтроки "Версия конфигурации: "+Инфо.Версия
ВыводСтроки "Версия Бром: "+Инфо.РасширениеБром.Версия

 

Вызов методов глобального контекста.

Сервис Бром позволяет вызывать любые серверные методы глобального контекста двумя способами: с помощью метода ВызватьМетод или с помощью непосредственного вызова объектным способом через точку.

// Первый способ
ВыводСтроки Клиент.ВызватьМетод("", "ЧислоПрописью", 2547)
// Второй способ
ВыводСтроки Клиент.ЧислоПрописью(2547)

Обратите внимание, что при вызове методов глобального контекста первым способом, в первый параметр метода ВызватьМетод передаётся пустая строка.

 

Вызов методов общих модулей.

Сервис Бром позволяет вызывать экспортные методы общих модулей двумя способами: с помощью метода ВызватьМетод или с помощью непосредственного вызова объектным способом через точку.

// Предварительно получим элемент справочника Валюты
Доллар = Клиент.Справочники.Валюты.НайтиПоКоду("840")
// Первый способ
Перем Курс1 тип Типы.Структура = Клиент.ВызватьМетод("РаботаСКурсамиВалют", "ПолучитьКурсВалюты", Доллар, ТекущаяДата())
ВыводСтроки Курс1.Курс
// Второй способ
Курс2 = Клиент.РаботаСКурсамиВалют.ПолучитьКурсВалюты(Доллар, ТекущаяДата())
ВыводСтроки Курс2.Курс

Обратите внимание, что при вызове методов общего модуля первым способом, в первый параметр метода ВызватьМетод передаётся имя общего модуля.

 

Вызов методов модулей менеджеров прикладных объектов.

Сервис Бром позволяет вызывать экспортные методы модулей менеджеров прикладных объектов двумя способами: с помощью метода ВызватьМетод или с помощью непосредственного вызова объектным способом через точку.

// Первый способ
телевизорСсылка1 = Клиент.ВызватьМетод("Справочники.Номенклатура", "НайтиПоНаименованию", "Телевизор", Истина)
// Второй способ
телевизорСсылка2 = Клиент.Справочники.Номенклатура.НайтиПоНаименованию("Телевизор", Истина)

Обратите внимание, что при вызове методов модуля менеджера прикладного объекта первым способом, в первый параметр метода ВызватьМетод передаётся путь к менеджеру прикладного объекта.

 

Работа с константами.

Чтение и запись значений констант можно выполнить, используя методы ПолучитьЗначениеКонстанты и УстановитьЗначениеКонстанты.

//Прочитаем значение константы
ВыводСтроки Клиент.ПолучитьЗначениеКонстанты("ЗаголовокСистемы")
//Установим значение константы
Клиент.УстановитьЗначениеКонстанты("ЗаголовокСистемы", "Моя система")

Получение ссылки на объект.

Для многих операций с элементами базы данных 1С могут понадобиться ссылки на объекты, например, на значения перечислений, элементы справочников или документы. Бром позволяет делать это очень простыми способами почти эквивалентными тому, как это делается в 1С.

// Получим ссылку на элемент перечисления
НДС18 = Клиент.Перечисления.СтавкиНДС.НДС18
// Создадим пустую ссылку для конкретного справочника
ПустаяСсылкаСпрВалюты = Клиент.Справочники.Валюты.ПустаяСсылка()
// Генерируем ссылку с новым уникальным идентификатором
НоваяСсылкаСпрВалюты = Клиент.Справочники.Валюты.ПолучитьСсылку(Новый УникальныйИдентификатор)
// Получаем ссылку на существующий элемент справочника
Гривня = Клиент.Справочники.Валюты.НайтиПоНаименованию("Гривня")

 

Работа со справочниками.

Для чтения и записи элементов справочника используйте ту же самую объектную технику, которую Вы используете на языке 1С.

// Получаем ссылку на существующий элемент справочника
Гривня = Клиент.Справочники.Валюты.НайтиПоНаименованию("Гривня")
// Получаем значение реквизита
ВыводСтроки Гривня.Курс
// Получаем контекст объекта
Гривня = Гривня.ПолучитьОбъект()
// Изменяем значения реквизита
Гривня.Курс = 27.3456
// Записываем объект справочника
Гривня.Записать()

 

Работа с документами.

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

ЗаказОбъект = Клиент.Документы.ЗаказКлиента.СоздатьДокумент();
ЗаказОбъект.Дата = ТекущаяДата();
ЗаказОбъект.Контрагент = Клиент.Справочники.Контрагенты.НайтиПоНаименованию("ЧП Пупкин");
НовСтр = ЗаказОбъект.Товары.Добавить();
НовСтр.Товар = Клиент.Справочники.Товары.НайтиПоНаименованию("Тумбочка");
НовСтр.Количество = 5;
НовСтр.Сумма = 5000;
Попытка
    ЗаказОбъект.Записать();
Исключение Ош
    ВыводСтроки "Ошибка записи "+Ош.ОписаниеОшибки();
КонецПопытки

 

Работа с другими типами объектов 1С.

Работа с такими объектами как БизнесПроцесс, Задача, ПланВидовРасчета, ПланВидовХарактеристик, ПланСчетов, принципиально не отличается от работы со справочниками и документами.

 

Выборка объектов БД с помощью объекта Селектор.

Библиотека ПерфоБром имеет специальный объект Селектор, которого в платформе 1С нет. Этот объект позволяет выбрать элементы справочника или документы задавая простые условия, отборы и сортировку.

// создадим объект Селектор
текСелектор = Клиент.СоздатьСелектор()
// зададим настройки селектора
текСелектор.УстановитьКоллекцию("Справочник.Товары")
текСелектор.АвтозагрузкаПолей = АвтозагрузкаПолейОбъектов.ТолькоРеквизиты
текСелектор.Лимит = 30

Для текСсылка Из текСелектор
    ВыводСтроки $"Наименование: {текСсылка.Наименование}; Код: {текСсылка.Код}; Артикул: {текСсылка.Артикул};"
КонецЦикла

// Добавляем отбор и дозапрашиваем данные производителя
текСелектор.ДобавитьОтбор("ЭтоГруппа", Ложь)
текСелектор.ДобавитьСортировку("Наименование")
текСелектор.ДобавитьПоля("Производитель, Производитель.ИНН")

ВыводСтроки "Отсортировано по наименованию:"
Для текСсылка Из текСелектор
    ВыводСтроки $"Наименование: {текСсылка.Наименование}; Производитель: {текСсылка.Производитель}; ИНН: {текСсылка.Производитель.ИНН};"
КонецЦикла

// Сохраняем результат выборки в массив для последующего использования
МассивСсылок = текСелектор.ВыгрузитьРезультат()
ВыводСтроки "В массиве ссылок "+МассивСсылок.Количество+" элементов"

текСелектор.ДобавитьОтбор("Наименование", "Теле", ВидСравнения.Содержит)
ВыводСтроки "Только телевизоры:"
Для текСсылка Из текСелектор
    ВыводСтроки $"Наименование: {текСсылка.Наименование}; Код: {текСсылка.Код};"
КонецЦикла

 

Выполнение запросов.

На языке Перфолента.Net с помощью сервиса Бром можно писать запросы к базе данных 1С почти так же, как и в самой 1С.

Запрос = Клиент.СоздатьЗапрос(@"
    ВЫБРАТЬ
        Товары.Ссылка КАК Ссылка,
        Товары.Код КАК Код,
        Товары.Наименование КАК Наименование,
        Товары.Артикул КАК Артикул
    ИЗ
        Справочник.Товары КАК Товары
    ГДЕ
        Товары.ЭтоГруппа = ЛОЖЬ
    УПОРЯДОЧИТЬ ПО
        Наименование            
"@)

//выполним запрос и получим результат в виде таблицы значений
ТЗ = Запрос.Выполнить()

//поработаем с таблицей значений
ВыводСтроки "Результат запроса:"
//обход для каждого
Для СтрокаТЗ Из ТЗ
    ВыводСтроки $"Наименование: {СтрокаТЗ.Наименование}; Код: {СтрокаТЗ.Код}; Артикул: {СтрокаТЗ.Артикул};"
КонецЦикла

Обратите внимание, что библиотека ПерфоБром содержит множество классов аналогичных классам стандартной библиотеки, например, ТаблицаЗначений, Массив, Соответствие и т.д. Набор свойств и методов у этих классов может отличаться как от объектов стандартной библиотеки, так и от объектов 1С. Поэтому при необходимости уточняйте наличие того или иного свойства или метода у объекта в справочной системе языка Перфолента.

 

 

Выполнение фрагмента кода на стороне 1С.

Метод Выполнить объекта БромКлиент позволяет запустить на выполнение фрагмент кода на языке 1С.

Если необходимо, во второй параметр метода Выполнить можно передать значение, которое во время выполнения на стороне 1С будет доступно через переменную Параметр.

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

Примеры:   

// Данный код не принимает параметров и не возвращает результата
Клиент.Выполнить(@"
    ТекСсылка = Справочники.Товары.НайтиПоНаименованию("Тумбочка");
    ТекОбъект = ТекСсылка.ПолучитьОбъект();
    ТекОбъект.Наименование = ВРег(ТекОбъект.Наименование);
    ТекОбъект.Записать();
"@)

//получим результат выполнения из переменной Результат
ВыводСтроки Клиент.Выполнить(@"Результат = СокрЛП(Справочники.Товары.НайтиПоНаименованию("Тумбочка"));"@)

//передадим значение в переменную Параметр
Клиент.Выполнить(@"
    ТекСсылка = Справочники.Товары.НайтиПоНаименованию("Тумбочка");
    ТекОбъект = ТекСсылка.ПолучитьОбъект();
    ТекОбъект.Наименование = Параметр;
    ТекОбъект.Записать();
"@,
"Тумбочка") //это передаваемое значение

//проверим, что регистр букв названия восстановился
ВыводСтроки Клиент.Выполнить(@"Результат = СокрЛП(Справочники.Товары.НайтиПоНаименованию("Тумбочка"));"@)

Обратите внимание, что в приведенных примерах используются литералы строк вида @"…"@, что позволяет НЕ дублировать двойные кавычки в коде, предназначенном для 1С.

Фрагменты кода для выполнения можно генерировать налету или по шаблонам.

 

Обработка ошибок.

Как и любые другие сетевые операции, операции с сервисом Бром могут неожиданно завершиться исключением из-за неполадок в сети или ошибках на стороне 1С.

Ваша программа должна знать, что делать, если данные от веб-сервиса получить не удалось.

Одно из самых простых решений - оборачивать логические блоки запросов к сервису Бром оператором Попытка.

Попытка
    //Блок операций с веб-сервисом Бром
Исключение Ош
    //обработка ошибки
КонецПопытки

Как именно действовать в случае возникновения ошибки, придется решать в каждом конкретном случае отдельно. Главное – избежать потери и порчи данных.

В случае ошибки при чтении данных можно несколько раз повторить попытку чтения с небольшой паузой между попытками.

А вот при записи данных надо использовать транзакции на стороне 1С или выполнять контрольное чтение, чтобы убедиться, что данные записались корректно и в полном объёме.

 

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