1C HTTP сервис
В платформе версии 8.3.5 появилась возможность создавать HTTP-сервисы. Как и «старые» SOAP web-сервисы, HTTP-сервис позволяет получать/изменять данные, но при этом, как утверждает компания 1С, HTTP-сервисы потенциально позволяют упростить создание клиентских приложений, уменьшить объем передаваемых данных и вычислительную нагрузку, все это особенно для мобильных устройств.
В этой статья я постараюсь рассказать о том, как создавать, отлаживать и использовать HTTP-сервисы в 1С.
Начнем с того, что для создания HTTP-сервиса нам необходим веб-сервер, например Apache 2.2 (начиная с версии 8.3.8 и Apache 2.4 подойдет). Описывать установку веб-сервера думаю нет необходимости.
Содержание
- Создание HTTP-сервиса
- Публикация и проверка HTTP-сервиса
- Отладка HTTP-сервисов
- Общие сведения
- 1. Примеры получения данных. HTTP-метод GET
- Веб-сервисы в 1С
- Риски использования веб-сервисов 1С
- Правила построения сервисов по продаже
- Использование внешних SOAP-сервисов
- Загрузка WSDL
- Обработка для тестирования работающего внешнего веб-сервиса
- Стандартные средства отладки сервисов
- SOAP и HTTPS
- Правила разработки сервиса на базе 1С
- Публикация веб-сервиса
- Авторизация к веб-сервису 1С
- Тестирование веб-сервиса 1С
- Использование сервисов в Рознице
- Организация служебных данных в 1С
- Использование обработок на языке 1С
- Использование программ, интегрируемых с 1С
- XDTO в платформе 1С
- Частые проблемы с XDTO
- Сопровождение сервисов
- Протоколирование запросов
- Ссылки
Создание HTTP-сервиса
Итак, создаем новый HTTP-сервис:
Корневой URL — важный параметр, входит в адрес по которому сервис будет доступен после публикации.
В соответствующем разделе создаем новый шаблон URL и метод:
У шаблона URL есть единственное свойство — шаблон. Этим свойством можно задать путь по которому будет происходить обращение к HTTP-сервису. В шаблоне можно использовать параметризованные сегменты, как на рисунке ниже (об их использовании ниже).
При обращении к HTTP-сервису, платформа пытается сопоставить адрес, по которому произошло обращение с одним из имеющихся шаблонов и методов. Если сопоставить удалось, то будет выполнен обработчик метода, если же сопоставить не удалось, то будет возвращен код ответа 404.
Перейдем к примеру обработчика метода, в нем я возвращаю содержимое переменной «Запрос», которая передается в обработчик:
Публикация и проверка HTTP-сервиса
Наш HTTP-сервис готов к публикации, в этом нет ничего сложного (вероятно потребуется запустить конфигуратор от имени администратора):
Публикация HTTP-сервиса
- localhost — адрес сервера;
- HTTPTest — имя указанное при публикации;
- hs — обязательный сегмент пути, дающий понять, что работаем мы именно с HTTP-сервисом;
- Obmen — корневой URL HTTP-сервиса;
- test-paramenter/Test — путь к методу внутри сервиса, определяется шаблоном;
- GetInfo — название метода;
- ?param=value — необязательный пример передачи методу параметров.
Результат выполнения метода
Параметры URL, параметры запроса и заголовки представлены в виде фиксированных структур.
Вероятнее всего, при обращение к HTTP-сервису нужно будет авторизоваться (если в базе есть хоть один пользователь), есть несколько способов решения этой проблемы.
Первый — изменить файл default.vrd, который находится в каталоге публикации. В этом файле нужно дополнить строку подключения к базе, например, было:
ib=»File="C:\Base\TEST";»,
стало:
ib=»File="C:\Base\TEST";Usr=Логин;Pwd=Пароль».
В этом случае любые обращения к HTTP-сервису не будут требовать логина и пароля.
Во-вторых, можно указывать логин и пароль при подключении к HTTP-сервису:
В других языках программирования аналогично.
Кроме этого можно использовать windows-авторизацию.
Отладка HTTP-сервисов
Для того чтобы иметь возможность отлаживать HTTP-сервисы нужно, во-первых, опубликовать HTTP-сервис со следующими настройками:
Отладка HTTP-сервисов
Во-вторых, в конфигураторе, в меню «Отладка»->»Подключение…» нужно настроить автоматическое подключение:
Настройка автоматического подключения
И, наконец, в-третьих, нужно перезапустить веб-сервер.
Кроме этого для полноценной отладки могут потребоваться сторонние программы, так как браузер всегда старается использовать метод GET. Для тестирования всех остальных HTTP-методов можно использовать бесплатный Fiddler2 (http://www.telerik.com/fiddler).
Печать (Ctrl+P)
Вторая часть можно посмотреть
Общие сведения
В версии платформы 8.3.5.1068, опубликованной в сентябре 2015 появился механизм интеграции 1С с внешними программами через технологию REST интерфейс. В качестве протокола доступа платформа использует протокол OData . Это открытый веб-протокол для запроса и обновления данных. Он позволяет оперировать данными, используя в качестве запросов HTTP-команды. Получать ответы в версии 8.3.5.1068 можно было только в формате Atom/XML . Однако, начиная с релиза 8.3.8.1652 в августе 2017 г. появился второй вариант получения данных в формате JSON(англ. JavaScript Object Notation) . По сравнению с XML он легко читается людьми занимает меньше места. Кроме этого все браузеры имеют встроенные средства для работы с JSON.
Работу с протоколом OData на платформе 1С: предприятие можно посмотреть в книге 1С: Руководства разработчика в главе 17 Механизмы интернет-сервисов , параграф 17.2.1 Cтандартный интерфейс OData. Можно также посмотреть примеры расширения поддержки протокола OData ,
Преимущество использования REST интерфейс. заключает в том , что для получения доступа к данным системы из внешнего приложения не требуется модификации кода прикладного решения (например, если прикладное решение стоит на поддержке). Для получения такого доступа необходимо особым образом опубликовать приложение на веб-сервере и указать, какие объекты конфигурации будут использоваться таким образом. После этого сторонние системы могут обращаться к вашему приложению с помощью HTTP запросов.
Публикация стандартного интерфейса OData выполняется с помощью диалога публикации на веб-сервере (Администрирование – Публикация на веб- сервере) и описано в книге 1С:Предприятие 8.3. «Руководство администратора”.
Важно! Для того чтобы объекты конфигурации стали доступны через стандартный интерфейс OData, необходимо разрешить это с помощью метода глобального контекста УстановитьСоставСтандартногоИнтерфейсаOData().
Механизм установки состава объектов, доступных с помощью стандартного интерфейса OData, можно выполнить в виде внешней обработки. Для этого не требуется модифицировать прикладное решение.
Для взаимодействия с внешним REST- веб-сервер из 1С:Предприятия используется имеющиеся в платформе средства работы с HTTP: объекты HTTPСоединение, HTTPЗапрос и HTTPОтвет.
В этой цикле статьей я буду показывать примеры типовых операций, использующих соответствующий HTTP-метод ;
- Получение данных – метод GET;
- Создание объекта – метод POST;
- Обновление данных : метод PATCH – в этом случае можно указывать только те свойств, которые необходимо обновить; метод PUT – в этом случае необходимо указывать все свойства сущности;
- Удаление данных – метод DELETE.
1. Примеры получения данных. HTTP-метод GET
В качестве сервера будет выступать опубликованная на веб-сервере БД с именем WebBuh (Демо-база «Бухгалтерия Предприятия 3.0”). В качестве формата обмена данных я буду использовать формат JSON. Подробнее о работе с JSON написано в документации, доступной . Для получения данных из сервера HTTP-методом GET требуется создать объект ЧтениеJSON для последовательного чтения JSON-данных из файла или строки. Для организации последовательной записи объектов и текстов на сервере HTTP-методом POST PATCH PUT требуется создать объект ЗаписьJSON. Отметим, для метода DELETE не требуется JSON.
В качестве иллюстрации потокового чтения и записи JSON при обращении к REST интерфейсу я буду вызывать следующую пользовательскую функцию общего назначения ВызватьHTTPМетодНаСервере :
&НаСервере // <Описание функции> // // Параметры: // <HTTPМетод> — Строка, содержащая имя HTTP-метода для запроса («POST».»PATCH», «PUT» ,»GET»,»DELETE» // <HTTPСоединение> — объект HTTPСоединение // <АдресРесурса> — Строка http-ресурса, к которому будет отправлен HTTP запрос. // <ОтправляемыеДанные> — Структура или соответствие, содержащие данные, отправляемые на указанный адрес для обработки // на сервер с использованием указанного HTTP-метода «POST» или «PATCH» или «PUT» // Возвращаемое значение: // Структура ответа сервера в зависимости от HTTPМетод // Функция ВызватьHTTPМетодНаСервере(HTTPМетод,HTTPСоединение,АдресРесурса,ОтправляемыеДанные = Неопределено) // Создание HTTPЗапрос Заголовки = Новый Соответствие(); Заголовки.Вставить(«Content-Type», «application/json»); ЗапросHTTP = Новый HTTPЗапрос( АдресРесурса, Заголовки); // ЗаписьJson толка для создания и обновление данных Если HTTPМетод= «POST» или HTTPМетод=»PATCH» или HTTPМетод=»PUT» Тогда ЗаписьJSON = Новый ЗаписьJSON; ПараметрыJSON = Новый ПараметрыЗаписиJSON(ПереносСтрокJSON.Авто,»»,Истина); ЗаписьJSON.УстановитьСтроку(ПараметрыJSON); ЗаписатьJSON(ЗаписьJSON, ОтправляемыеДанные); // ОтправляемыеДанные обязательны в этом случае СтрокаДляТела = ЗаписьJSON.Закрыть(); ЗапросHTTP.УстановитьТелоИзСтроки(СтрокаДляТела,КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать); КонецЕсли; // Вызов Метода HTTPСоединение ОтветHTTP = HTTPСоединение.ВызватьHTTPМетод(HTTPМетод, ЗапросHTTP); СтруктураОтвета = Новый Структура; СтруктураОтвета.Вставить(«КодСостояния», ОтветHTTP.КодСостояния); // ЧтениеJSON только для метода GET Если HTTPМетод= «GET» Тогда Попытка ЧтениеJSON = Новый ЧтениеJSON; ОтветСервера = ОтветHTTP.ПолучитьТелоКакСтроку(«UTF-8»); ЧтениеJSON.УстановитьСтроку(ОтветСервера); Соответствие = ПрочитатьJSON(ЧтениеJSON,Истина); СтруктураОтвета.Вставить(«ОтветСервера», Соответствие); СтруктураОтвета.Вставить(«ОтветСервераНеРасшифрованный», ОтветСервера); Исключение Сообщить(ОписаниеОшибки()); Возврат Неопределено; КонецПопытки; Конецесли; Возврат СтруктураОтвета; КонецФункции // ВызватьHTTPМетодНаСервере()
Для получения от сервера в формате JSON при обращении к REST интерфейсу прикладного решения нужно в адресе ресурса указать $format=json. Либо указать MIME тип «application/json” в заголовке :
Заголовки = Новый Соответствие(); Заголовки.Вставить(«Content-Type», «application/json»); АдресРесурса =»WebBuh/odata/standard.odata/?$format=json» ЗапросHTTP = Новый HTTPЗапрос(АдресРесурса, Заголовки);
Особенность глобального контекста ПрочитатьJSON(ЧтениеJSON, Истина)
Подробнее о синтаксисе ПрочитатьJSON можно посмотреть в документации платформы. Отметим здесь некоторые особенности :
- Если значение второго параметра установлено Истина, чтение объекта JSON будет выполнено в Соответствие.Если установлено Ложь, объекты будут считываться в объект типа Структура.
- При десериализации объектов JSON в структуру необходимо помнить о требованиях к ключам структуры. Если при десериализации объекта будет найдено имя свойства, недопустимое для ключа структуры, то будет вызвано исключение.
1. 1 Настройка параметров HTTP соединения
Для организации клиентской части взаимодействия с внешним REST- веб-сервер, я создал «с нуля” конфигурацию клиента на базе БСП. На этой конфигурации я создал справочник настройки параметров подключения (см Рис 1)
Рис 1 Справочник настройки параметров HTTP соединения к внешней ИБ через rest интерфейс
После нажатия кнопки Проверить ответ сервера, вызывается процедура, по которой клиент попытается получать ответ сервера. Программный код процедуры написан ниже :
&НаКлиенте Процедура ПроверитьПодключение(Команда) Адрес = Объект.АдресСервера; Пользователь = Объект.Пользователь; Пароль= Объект.Пароль; ИмяБазы = Объект.Наименование; Порт = ?(Объект.Порт <> 0,Объект.Порт,80); HTTPСоединение = Новый HTTPСоединение(Адрес,Порт,Пользователь, Пароль); АдресРесурса = ИмяБазы+ «/odata/standard.odata/$metadata»; //Вызов пользовательской функции СтруктураОтвета = ВызватьHTTPМетодНаСервере(«GET»,HTTPСоединение,АдресРесурса); Если СтруктураОтвета <> Неопределено Тогда ОбщегоНазначенияКлиентСервер.СообщитьПользователю(«Код состояния «+СтруктураОтвета.КодСостояния); Конецесли; КонецПроцедуры
Цель этой процедуры – Это проверка работы сервиса и правильно ли пользователь ввел параметры соединения. Для этого достаточно выполнить GET-запрос:
HTTPСоединение.ВызватьHTTPМетод(«GET”, ЗапросHTTP) ;
с использованием адреса ресурса:
АдресРесурса = ИмяБазы+ «/odata/standard.odata/»;
Проверить работы сервиса можно также в браузере с использованием
URL http://host/WebBuh/odata/standard.odata. В результате такого запроса получается только список сущностей . Для получения полного описания стандартного интерфейса OData (список доступных сущностей, их атрибутов и функций в виде XML-
документа.) необходимо выполнить GET-запрос с использованием параметра $metadata. URL http://host/WebBuh/odata/standard.odata/$metadata. Подробное описание документа можно получить по адресу http://www.odata.org/documentation/ (на английском языке).
Получать ответы можно в формате Atom/XML или JSON. Коды статусов ответа по протоколу HTTP можно посмотреть Ответы в диапазонах:
- 100-199 – информационные ответы, показывающие, что запрос клиента принят и обрабатывается.
- 200-299 – означают, что запрос клиента обработан успешно.
- 300-399 означает, что запрос не выполнен и клиенту нужно предпринять некоторые действия для удовлетворения запроса.
- 400-499 – информирует об ошибках на стороне клиентского приложения. Эти коды могут также означать, что от клиента требуется дополнительная информация.
- 500-599 – информирует об ошибке на стороне сервера, показывают, что сервер столкнулся с ошибкой и, вероятно, не сможет выполнить запрос клиента.
1.2 Поиск объекта по идентификатору
Следующая функция предназначена для поиска справочника или документа по уникальному идентификатора на сервере . Если объект найден, то функция возвращает строковое значение идентификатора (Ref_Key ) , иначе возвращает неопределено. В функцию передаются следующие параметры:
- HTTPСоединение – Объект типа HTTPСоединение
- ИмяПубликации – Имя опубликованной базы базы данных сервера
- Элемент – идентификатор сущности объекта , например, Catalog_Организации или Document_- справочник Организации.
- Идентификатор – Идентификатор объекта, который нужно искать на сервере, например, Организация.УникальныйИдентификатор()
&НаСервере Функция ПоискОбъектПоGUID (HTTPСоединение,ИмяПубликации,Элемент,УникальныйИдентификатор) GUID = Строка(УникальныйИдентификатор); // преобразуем в строку АдресРесурса = ИмяПубликации+ «/odata/standard.odata/» + Элемент+ «(guid'»+ GUID+ «‘)?$format=json»; //Вызов моей пользовательской функции СтруктураОтвета = ВызватьHTTPМетодНаСервере(«GET»,HTTPСоединение,АдресРесурса); Если СтруктураОтвета.КодСостояния >= 400 Тогда //ОбщегоНазначенияКлиентСервер.СообщитьПользователю(Элемент+ » Ошибка «+СтруктураОтвета.КодСостояния+ //ОбщегоНазначенияКлиентСервер.СообщитьПользователю(СтруктураОтвета.ОтветСервераНеРасшифрованный); Возврат неопределено; КонецЕсли; Соответствие = СтруктураОтвета.ОтветСервера; Массив= Соответствие; Если Массив = Неопределено Тогда Возврат Соответствие Иначе Возврат Массив; КонецЕсли; КонецФункции
Параметр АдресРесурса используется для обращения к REST-сервису. Для проверки работы сервиса можно указать ресурс в браузере таким образом
- АдресВебСервера – Адрес веб-сервера, на котором опубликован сервис, например Localhost
- ИмяПубликации – имя информационной базы указанное при публикации решения
- /odata/standard.odata/ – Признак обращения к стандартному интерфейсу OData
- Элемент – идентификатор ресурса или предопределенные ресурсы. Например, Catalog_Контрагент(guid’value’).
- Параметры – параметры ресурса. Используются, например, для отбора, в принятом для HTTP-запросов: ?ключ=значение&ключ2=значение2
1.3 Поиск объекта по полям поиска
Следующая пользовательская функция предназначена для поиска объекта по полям поиска в том случае, когда объект по идентификационному номеру. Функция возражает строку Ref_Key – идентификационный номер.
&НаСервере Функция ПоискОбъектПоПолямПоиска(HTTPСоединение,ИмяПубликации, Элемент,ПоляПоиска ) Условие = «»; Для Каждого КлючЗначение из ПоляПоиска Цикл Условие = Условие + КлючЗначение.Ключ + » eq ‘» + КлючЗначение.Значение + «‘ and «; КонецЦикла; ТекстЗапроса = Лев(Условие, СтрДлина(Условие)-5); // удаляем последние 5 символов АдресРесурса= ИмяПубликации+ «/odata/standard.odata/» +Элемент+ «?$filter=» + ТекстЗапроса + «&$format=json&$select=Ref_Key»; //Вызов моей пользовательской функции СтруктураОтвета = ВызватьHTTPМетодНаСервере(«GET»,HTTPСоединение,АдресРесурса); Если СтруктураОтвета.КодСостояния >= 400 Тогда //ОбщегоНазначенияКлиентСервер.СообщитьПользователю(Элемент+ » Ошибка «+СтруктураОтвета.КодСостояния); //ОбщегоНазначенияКлиентСервер.СообщитьПользователю(СтруктураОтвета.ОтветСервераНеРасшифрованный); Возврат неопределено; КонецЕсли; Соответствие = СтруктураОтвета.ОтветСервера; Массив= Соответствие; Если Массив = Неопределено Тогда Возврат Соответствие Иначе Возврат Массив; КонецЕсли; КонецФункции
Как видно из тела процедуры ПоискОбъектПоПолямПоиска , отбор начинается с ключевого слова $filter в адресе ресурса. Формальный параметр ПоляПоиска – это соответствие, которое содержит наименования и значения реквизитов.
Отметим, что наименование реквизитов порой не очевидно. Необходимо запомнить, что для справочников:
- Code – код,
- Description – Наименование
- DeletionMark – пометка удаления,
- IsFolder – признак группы,
- Parent_Key – родитель.
- Если реквизит ссылочного типа, к его имени следует добавить суффикс _Key, например Контрагент_Key.
Для документов:
- Number – номер документа,
- Date – дата документа.
Логические операции отбора
Отметим, также, что значение фактического параметра Элемент ( или сущность)) , который я передаю на функцию формируется по следующему правилу:
ПрефиксИмени_ИмяОбъектаКонфигурации_СуффиксИмени.
С помощью стандартного интерфейса OData можно получить доступ к следующим объектам (ПрефиксИмени):
- Справочник — Catalog;
- Документ — Document;
- Журнал документов — DocumentJournal;
- Константа — Constant;
- План обмена — ExchangePlan;
- План счетов — ChartOfAccounts
- План видов расчета — ChartOfCalculationTypes;
- План видов характеристик — ChartOfCharacteristicTypes;
- Регистр сведений — InformationRegister;
- Регистр накопления — AccumulationRegister;
- Регистр расчета — CalculationRegister;
- Регистр бухгалтерии — AccountingRegister;
- Бизнес-процесс — BusinessProcess;
- Задача — Task.
ИмяОбъектаКонфигурации — свойство «Имя» объекта конфигурации так, как оно задано в конфигураторе.
СуффиксИмени — нужен для уточнения имени ресурса, необязателен, может принимать следующие значения:
- Имя табличной части объекта;
- Имя виртуальной таблицы объекта;
- RowType — строка табличной части объекта;
- RecordType — отдельная запись регистра.
Параметры обращения к ресурсам
- $filter — отбор при получении данных
- $format — указывает формат возвращаемых данных,
- $select — перечисление свойств сущности, которые попадут в результат запроса;
- $metadata — возвращает описание стандартного интерфейса OData (используется без указания суффикса имени, пример на одном из изображений выше);
- $top — ограничение количества возвращаемых записей ;
- $skip — убирает из результата запроса указанное количество записей ;
- $count — возвращает количество записей в выборке запроса;
- $inlinecount=allpage(=none) — добавляет в результат запроса информацию о количестве записей
- $orderby=<Реквизит1> asc, <Реквизит2> desc — сортировка результата запроса
- alloweOnly — только разрешенные (используется без знака «$»).
1.4 Получить массив записей регистра сведений
Посмотрим пример получения массив записей регистра сведения ФИОФизическихЛиц, например историю изменения ФИО физического лица
ИмяПубликации =»WebBuh»; Элемент = «InformationRegister_ФИОФизическихЛиц»; Период = Неопределено; ДанныеСсылочногоТипа = Новый Структура(); ДанныеСсылочногоТипа.Вставить(«ФизическоеЛицо»,ФизическоеЛицо_Key); ДанныеНЕСылочногоТипа= Новый Структура(); ДанныеНЕСылочногоТипа.Вставить(«ФизическоеЛицо_Type», «StandardODATA.Catalog_ФизическиеЛица») Массив = ПолучитьНаборЗаписиРегистраСведений(HTTPСоединение,ИмяПубликации,Элемент, Период ,ИзмеренияСсылочногоТипа, ИзмеренияНЕСылочногоТипа )
Тело функции ПолучитьНаборЗаписиРегистраСведений, которая вызывается в этом примере показано ниже
&НаСервере Функция ПолучитьНаборЗаписиРегистраСведений(HTTPСоединение,ИмяПубликации,Элемент, Период =Неопределено ,ИзмеренияСсылочногоТипа= Неопределено, ИзмеренияНЕСылочногоТипа = Неопределено) ТекстЗапроса =»»; Если Период <> Неопределено Тогда ФорматированныйПериод = Формат(Период,»ДФ=yyyy-MM-ddTHH:mm:ss»); ТекстЗапроса = «Period = datetime'»+ ФорматированныйПериод + «‘» ; КонецЕсли; Если ИзмеренияСсылочногоТипа <> Неопределено Тогда Для Каждого КлючЗначение из ИзмеренияСсылочногоТипа Цикл Запитая = ?(ЗначениеЗаполнено(ТекстЗапроса), «,» ,»»); ТекстЗапроса = ТекстЗапроса + Запитая + КлючЗначение.Ключ + «=guid(‘»+ КлючЗначение.Значение + «‘)»; КонецЦикла; КонецЕсли; Если ИзмеренияНЕСылочногоТипа<> Неопределено Тогда Для Каждого КлючЗначение из ИзмеренияНЕСылочногоТипа Цикл Запитая = ?(ЗначениеЗаполнено(ТекстЗапроса), «,» ,»»); ТекстЗапроса = ТекстЗапроса + Запитая + КлючЗначение.Ключ + «=» + КлючЗначение.Значение; КонецЦикла; КонецЕсли; АдресРесурса= ИмяПубликации+ «/odata/standard.odata/» + Элемент + «(«+ ТекстЗапроса+ + «)?$format=json»; //Вызов моей пользовательской функции СтруктураОтвета = ВызватьHTTPМетодНаСервере(«GET»,HTTPСоединение,АдресРесурса); Если СтруктураОтвета.КодСостояния >= 400 Тогда //ОбщегоНазначенияКлиентСервер.СообщитьПользователю(Элемент+ » Ошибка «+СтруктураОтвета.КодСостояния); //ОбщегоНазначенияКлиентСервер.СообщитьПользователю(СтруктураОтвета.ОтветСервераНеРасшифрованный); Возврат неопределено; КонецЕсли; Соответствие = СтруктураОтвета.ОтветСервера; Массив= Соответствие; Если Массив = Неопределено Тогда Возврат Соответствие; Иначе Возврат Массив; КонецЕсли; КонецФункции
REST интерфейс и HTTP запросы. Часть 2 Создание и изменение объекта
Веб-сервисы в 1С
В данной статье будет рассмотрены вопросы интеграции 1С с уже существующими веб-сервисами и использование самой 1С как веб-сервиса.
При этом под веб-сервисами будет пониматься системы, работающие в интернете и обеспечивающие взаимодействие с ними не только по SOAP (что является именно веб-сервисом), но и другими способами, включая обычные HTTP(S)-запросы.
Далее для экономии веб-сервис будет именоваться просто сервис.
Риски использования веб-сервисов 1С
В платформе 1С81 появилась реализация веб-сервисов.
Но их использование чревато рисками:
- 1С8 плохо работает через HTTPS, средства диагностики отсутствуют, поэтому понять, почему при наличии сертификата сервис не хочет работать через HTTPS порой невозможно. Выход – реализация веб-сервисов через CURL или поднятие HTTPS-туннеля.
- 1С8 придерживается своих правил валидации WSDL-схем. Порой по необъяснимым причинам WSDL-схема не хочет загружаться в WS-ссылку. Узнать причину можно только на партнерском форуме у одного специалиста. Средства диагностики WSDL-схемы отсутствуют, не указывается даже причина или строка, на которой прерывается загрузка схемы.
Правила построения сервисов по продаже
Клиенту выдается документ о продаже (чек) только в том случае, если транзакция по сервису прошла успешно. Иначе возможна ситуация, когда клиент получит чек и будет пребывать в уверенности, что получил услугу, а на самом деле это не так.
Использование внешних SOAP-сервисов
Веб-сервисы SOAP используют WSDL схемы и объекты XDTO для представления данных.
Загрузка WSDL
Для того, чтобы использовать внешний сервис, нужно загрузить его WSDL-схему.
Проверка валидности WSDL-схемы
Нужно загрузить схему на какой-нибудь http-сайт (можно по ftp) и указать адрес файла, в который загружена схема:
Особенности загрузки WSDL в 1С
Особенность загрузки WSDL в 1С в том, что валидные схемы могут не загружаться. Никакого встроенного валидатора нет, поэтому приходится искать ошибку методом деструктивного анализа, последовательно уменьшая количество элементов в схеме. Можно, например, удалить описание веб-сервиса.
1С не любит слово «policies». Если WS-ссылка не загружается, нужно убрать все, что связано с этим словом в любом XML-редакторе.
Обработка для тестирования работающего внешнего веб-сервиса
Для тестирования работающего внешнего веб-сервиса используйте обработку «ТестПроизвольногоВебСервиса.epf» из пакета к этой статье.
Таким способом можно протестировать любой сервис, который имеет простые точки входа, содержащие параметры простых типов: число, дата, строка.
В обработке можно указать также логин и пароль, которые требуются для авторизации доступа к веб-сервису.
Стандартные средства отладки сервисов
Для отладки можно использовать программу SoapUI, который может передать произвольный запрос веб-сервису и получить от него ответ.
SOAP и HTTPS
К сожалению, SOAP в 1С достаточно капризно ведет себя при работе через протокол HTTPS, практика показывает, что добиться HTTPS соединения невозможно, хотя возможность и продекларирована в платформе. Сказывается отсутствие средств диагностики и отладки для выяснения причин, из-за которых не устанавливается соединение. Поэтому удобно использовать SOAP через CURL.
Встроенный механизм использования HTTPS подразумевает, что все сертификаты должны быть опубликованы в общем файле pem в каталоге программы 1С.
Правила разработки сервиса на базе 1С
Операция «Hello»
Правилом хорошего тона является создание в сервисе операцию, которая информирует о том, что сервис доступен. Это облегчает жизнь интеграторов, им будет проще проверять, налажена ли связь с сервисом.
Например, можно использовать операцию Hello без параметров, которая просто возвращает булево значение Истина.
Публикация веб-сервиса
Процедура хорошо описана в документации: file:///C:/Program%20Files/1cv81/AddDoc/RU/V8AddDoc81.htm#_Toc176167634 :
Задача публикации Web-сервисов сводится к размещению конфигурационных файлов *.1cws Web-сервисов в соответствующем каталоге веб-сервера с соответствующими настройками для веб сервера. Для того, чтобы выполнить публикацию Web-сервисов, следует выполнить команду меню «Администрирование | Публикация Web-сервисов».
В результате выполнения этой команды будет открыто окно публикации Web-сервисов.
Окно публикации Web-сервисов содержит путь к веб-серверу и два списка:
- «Web-сервисы» – список Web-сервисов конфигурации;
- «Публикация» – список Web-сервисов, опубликованных на указанном веб-сервере.
С помощью кнопки «Соединение…» следует указать веб-сервер, на котором требуется опубликовать Web-сервисы.
Окно выбора пути к веб-серверу позволяет указать путь двумя способами:
- на закладке «Файлы» – этот способ используется в том случае, когда публикация выполняется на том же компьютере, на котором установлен веб-сервер. В качестве пути указывается локальный каталог, соответствующий интернет-странице, с которой будет выполняться вызов публикуемого Web-сервера;
- на закладке «FTP сайт» – этот способ используется в том случае, когда требуется опубликовать Web-сервис на удаленном компьютере. Для выполнения публикации необходимо указать параметры FTP-соединения с удаленным компьютером и каталог, в котором будет опубликован Web-сервис.
Публикация выбранного Web-сервиса осуществляется с помощью кнопки «Опубликовать»
Для отмены публикации Web-сервиса используется кнопка «Удалить».
Для обновления списка опубликованных Web-сервисов используется кнопка «Обновить текущий список».
Публиковать можно в локальном каталоге или по FTP. Можно публиковать и на удаленный сервер по UNC-пути, если удаленный сервер входит в локальную сеть.
После публикации веб-сервис доступен по адресу «http://localhost/test.1cws» или «http://xxx.ru/test.1cws», где xxx.ru – адрес удаленного сервера а localhost – типовой адрес локального сервера.
Авторизация к веб-сервису 1С
Для доступа к сервису нужно пройти аутентификацию.
Обычно веб-сервис работает под одним конкретным пользователем (чаще — специально созданным). Можно пользователя 1С «прикрепить» средствами Windows-аутентификации к пользователю Windows IUSR_ (для пользователя отключить авторизацию 1С). Как вариант, можно очистить список пользователей 1С, тогда авторизация не требуется.
Если требуется несколько пользователей, то можно создать несколько логинов для веб-сервера, к каждому из них привязать пользователя Windows и соответственно, прописать в 1С доступ к пользователям Windows.
В свойствах Пользователь и Пароль объекта WSПрокси используется не логин 1С, а логин пользователя веб-сервера.
Тестирование веб-сервиса 1С
Для тестирования 1С как веб-сервиса используйте обработку «ТестПроизвольногоВебСервиса.epf», как описано в разделе «Тестирование работающего внешнего веб-сервиса».
Файл 1cws и является WSDL-описанием веб-сервиса 1С.
Использование сервисов в Рознице
Обычно в рознице сервисы используются для оказания различных услуг населению – прием платежей, погашение кредитов, денежные переводы, покупка программного обеспечения и т.п.
При этом по оказанной услуге в 1С формируется чек, в котором сохраняются параметры транзакции. После чего этот чек распечатывается клиенту с подробной информацией об оказанной услуге. Возможна печать предварительного чека, для того, чтобы клиент подтвердил введенные с его слов данные своей подписью.
Сервис может быть по-разному интегрирован в розничную программу, написанную на языке 1С (УТ, Розница и другие):
- Может быть написана обработка или код на языке 1С, который выполняет всю работу с сервисом.
- Может использоваться программа, которая работает с сервисом, а в 1С передает только информацию для пробития чеков.
Организация служебных данных в 1С
Для хранения информации о транзакции в чеке необходимо создать дополнительную табличную часть «Сложные продажи» с реквизитами:
- Номенклатура – привязка к номенклатуре чека.
- Параметр — ссылка на справочник «Сложные продажи: Параметры».
- Значение – значение параметра, составного типа. Строковое представление должно быть довольно длинным (1024 символа), чтобы помещался текст чека.
Справочник «Сложные продажи: Параметры» содержит перечень параметров транзакции.
Табличную часть выгоднее использовать, чем набор реквизитов, т.к. у транзакции их может быть очень много, а в других чеках, не связанных с сервисом, эти реквизиты не будут использоваться, и будут занимать лишнее место. Кроме того, такое решение универсально для любого сервиса и не требует реструктуризации данных после внедрения нового сервиса.
Продавцу делается отдельная закладка (или печатная форма, чтобы не менять конфигурацию), в которой он может посмотреть табличку реквизитов транзакции для чека.
Использование обработок на языке 1С
Рассмотрим на примере условной услуги Paym для конфигурации «Розница».
- Заведем в 1С предопределенный элемент справочника номенклатуры «Paym». В режиме 1С:Предприятия после обновления конфигурации ему нужно назначить вид товара «Услуга».
- В процедуре «Добавить номенклатуру в таб. часть» модуля формы «Регистрация продаж» вызываем обработку работы с сервисом, написанную на языке 1С. В случае успешного осуществления платежа записываем и проводим чек:
Если (Номенклатура = Справочники.Номенклатура.Paym) И (ВидОперации Перечисления.ВидыОперацийЧекККМ.Возврат) Тогда ОбработкаПлатежа = Функции.ДатьВнешнююОбработку(«Paym»); ФормаПлатежа = ОбработкаПлатежа.ПолучитьФорму(); Результат = ФормаПлатежа.ОткрытьМодально(); Если Результат = Неопределено Тогда Возврат; КонецЕсли; ЭтотОбъект.Записать(РежимЗаписиДокумента.Проведение); КонецЕсли;
- Обработка должна напечатать предчек (если требуется), заполнить табличную часть сложных продаж и подготовить текст печати чека в предопределенном реквизите «PaymТекстЧека».
- В процедуре «Провести и распечатать чек» модуля чека подменяем наименование товара на сохраненное в реквизите для чека. Текст подменяется только для продажи, для возврата печатается просто название услуги, как обычно.
ИначеЕсли ВидОперации Перечисления.ВидыОперацийЧекККМ.Возврат И Выборка.НомеклатураСсылка = Справочники.Номенклатура.Paym Тогда //Осипов PaymMaster СтрокаСложныхПродаж = СложныеПродажи.Найти(Справочники.СложныеПродажиПараметры.PaymТекстЧека, «Реквизит»); Если СтрокаСложныхПродаж Неопределено Тогда Товар.Наименование = СокрЛП(СтрокаСложныхПродаж.Значение); КонецЕсли;
Отдельный вопрос – как обеспечить завершенность транзакции. Т.е. если транзакция прошла в сервисе, как сделать, чтобы она не потерялась в 1С. Наиболее оптимальный путь – сверка реестров. Но это предмет отдельного рассмотрения.
Использование программ, интегрируемых с 1С
Часто в веб-сервисах используется XDTO. Приведем наиболее важные советы и рецепты по использованию XDTO в 1С.
XDTO в платформе 1С
XDTO-пакеты, описанные в ветке «XDTO-объекты» конфигурации, доступны для создания типов и объектов в глобальной фабрике Фабрика XDTO. Это не сразу становится очевидным.
Некоторые типы в схеме не имеют имени, чтобы их получить, надо пройтись по иерархии типов.
В примере был описан список System, содержавший структуры XDTO. Чтобы создать саму структуру, нужно было получить ее тип таки вот образом:
Тип = Фабрика.Тип(«urn:my.ru:MasterData:Business», «Business»).Свойства.Получить(«System»).Тип;
Частые проблемы с XDTO
Разные форматы XSD-схем
В некоторых форматах теги называются xs:, в некоторых xsd:, но 1С благополучно понимает оба формата. Однажды была ситуация, что XSD нормально без ошибок импортировалась в 1С, но не создавала ни одного пакета. Причина была в отсутствии атрибута targetNamespace у тега , соответственно 1С не знала, в какой пакет помещать схему, но ошибок не выдавала.
Сопровождение сервисов
Учитывая, что сервис – это совокупность двух систем – 1С и внешней, ошибки могут быть в обоих системах, что снижает общую надежность работы.
Для того, чтобы проще было разбираться в причинах отказов в работе сервисов, рекомендуется использовать комплекс мер.
Протоколирование запросов
Рекомендуется сохранять все запросы и ответы на них в каталог программы, файлы сохранять в папки вида ГГГГММДД по дням. Это очень способствует пониманию причин проблем.
Ссылки
- XDTO
- Хорошее описание XDTO http://pro1c.org.ua/index.php?showtopic=214
- Бесплатные интересные веб-сервисы:
- Аэрофлот – информация о расписании самолетов
- Морфер – склонение имен http://www.morpher.ru/WebServices/Morpher.aspx
- Неразобранные:
- Установка и использование Веб-сервисов
- v8: как изменить конфигурационный файл апача?
- v8: продолжение темы с web-сервисами — не могу подключить web-сервис
- Книга знаний: v8: Использование внешних web-сервисов в 1С:Предприятие 8;
- Установка и использование Веб-сервисов