Реализация протокола удаленного вызова процедур в формате JSON (JSON-RPC)

Общие сведения.

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

Ниже приведено краткое описание JSON-RPC 2.0.

Запрос должен содержать три обязательных свойства:

• method — Строка с именем вызываемого метода.
• params — Массив данных, которые должны передаваться методу, как параметры.
• id — Значение любого типа, которое используется для установки соответствия между запросом и ответом.

Так же должна быть передана версия протокола (в нашем случае "2.0") в параметре jsonrpc. В спецификации протокола этот параметр не указан, как обязательный, но в реализации данной публикации его указание обязательно.

Пример запроса для вызова процедуры ПолучитьСчетаКлиента(ИНН, НачалоПериода, КонецПериода) (данная процедура использована в качестве примера, конкретные процедуры определяет разработчик):

{"jsonrpc": "2.0", "method": "ПолучитьСчетаКлиента", "params": ["7705260674", "2024-09-01", "2024-09-30"], "id": 1}

Сервер (в нашем случае — решение на 1С) отсылает ответ, содержащий следующие свойства:

• result — Результат выполнения метода. Если во время выполнения метода произошла ошибка, то это свойство должно быть установлено в null.
• error — Код ошибки, если произошла ошибка во время выполнения метода, иначе null.
• id — То же значение идентификатора, что и в запросе, к которому относится данный ответ (используется для сопоставления самого запроса и его результата, например, если асинхронно отправляется сразу несколько запросов).

Пример ответа:

{"jsonrpc": "2.0", "result": [{"uid": "422f9d5c-1032-11e5-92f1-0050568b35ac", "num": "ТД00-000001", "date": "2024-09-11T16:06:15", "sum": 127125}], "id": 1}

Более подробно с протоколом JSON-RPC можно ознакомиться на википедии.

В данной публикации удалённый вызов процедур 1С реализован в виде расширения. В этом расширении присутствует HTTP-сервис rpc_JSONRPC2. После публикации http-сервиса на веб-сервере сторонние системы (в качестве которой может выступать и другая база 1С) смогут выполнять запросы по адресу http://<адрес_базы>/hs/jsonrpc2.

Вызываемые удалённые процедуры должны располагаться в общем модуле расширения rpc_УдаленныеПроцедурыПереопределяемый.

Особенности реализации 1С.

Для упрощения создания собственных удалённых процедур были реализованы следующие особенности:

• Передаваемые в запросе JSON строковые значения параметров true и false преобразуются в тип 1С Булево.
• Передаваемые в запросе JSON строковые значения параметров типа 2024-01-10Т10:23:54 (дата в формате XML) преобразуются в тип 1С Дата.
• Передаваемые в запросе JSON строковые значения параметров типа GUID преобразуются в тип 1С УникальныйИдентификатор.
• Удалённая процедура (в 1С функция) должна возвращать только значения, которые могут быть сериализованы в JSON. Исключение составляет тип ТаблицаЗначений. В типовом механизме сериализации JSON этот тип не может использоваться, но в данном решении для упрощения возврата ответа (чтобы разработчик не писал лишний код) таблица значений преобразуется в массив структур.

Для передачи ошибок используется вызов исключения.

Например, вот так можно реализовать обработку ошибок в приведённой выше в качестве примера процедуре ПолучитьСчетаКлиента:

Функция ПолучитьСчетаКлиента(ИНН, НачалоПериода, КонецПериода) Экспорт

Контрагент = НайтиКонтрагентаПоИНН(ИНН);
Если Контрагент.Пустая() Тогда
ТекстСообщения = СтрШаблон(НСтр("ru='Не найден клиент с ИНН: %1'"), ИНН);
ВызватьИсключение ТекстСообщения;
КонецЕсли;

...

КонецФункции

В таком случае, если в запросе будет передан ИНН контрагента, отсутствующего в информационной базе, то клиентом будет получен ответ следующего вида:

{"jsonrpc": "2.0", "error": {"code": -32800, "message": "Не найден клиент с ИНН: 0777123413"}, "id": 1}

Примечание. В данной реализации используются следующие коды ошибок:

• -32600, "Invalid JSON-RPC" — возвращается, если передан неверный формат сообщения (не удалось прочитать JSON) или отсутствуют обязательные параметры;
• -32700, "Parse error" — возвращается, если переданы неверные параметры (например, отсутствует параметр method или параметр params не является массивом и т.п.);
• -32601, "Procedure not found" — вызываемая функция отсутствует в общем модуле rpc_УдаленныеПроцедурыПереопределяемый;
• —32800, <текст ошибки> — ошибка, возникшая во время выполнения метода (см. пример ответа с ошибкой выше).

Перейдём от теории к практике.

В качестве примера будем использовать конфигурацию Управление торговлей, редакция 11 (конкретный релиз для примера не имеет значения).

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

В данном случае порядок действий будет следующим:

1. Добавляем в конфигурацию расширение из этой публикации и публикуем HTTP-сервис rpc_JSONRPC2.

2. Открываем общий модуль расширения rpc_УдаленныеПроцедурыПереопределяемый и реализуем процедуру ПолучитьСчетаКлиента:

Функция ПолучитьСчетаКлиента(ИНН, НачалоПериода, КонецПериода) Экспорт

Контрагент = НайтиКонтрагентаПоИНН(ИНН); // Реализация данной функции не представляет проблем, оставим её "за скобками".
Если Контрагент.Пустая() Тогда
ТекстСообщения = СтрШаблон(НСтр("ru='Не найден клиент с ИНН: %1'"), ИНН);
ВызватьИсключение ТекстСообщения;
КонецЕсли;

ТаблицаСчетов = Новый ТаблицаЗначений;
ТаблицаСчетов.Колонки.Добавить("uid", Новый ОписаниеТипов("УникальныйИдентификатор"));
ТаблицаСчетов.Колонки.Добавить("num", Новый ОписаниеТипов("Строка",, Новый КвалификаторыСтроки(11)));
ТаблицаСчетов.Колонки.Добавить("date", Новый ОписаниеТипов("Дата",,, Новый КвалификаторыДаты(ЧастиДаты.ДатаВремя)));
ТаблицаСчетов.Колонки.Добавить("sum", Новый ОписаниеТипов("Число", Новый КвалификаторыЧисла(15, 2)));

Запрос = Новый Запрос(
"ВЫБРАТЬ
| СчетНаОплатуКлиенту.Ссылка КАК Ссылка,
| СчетНаОплатуКлиенту.Номер КАК num,
| СчетНаОплатуКлиенту.Дата КАК date,
| СчетНаОплатуКлиенту.СуммаДокумента КАК sum
|ИЗ
| Документ.СчетНаОплатуКлиенту КАК СчетНаОплатуКлиенту
|ГДЕ
| СчетНаОплатуКлиенту.Контрагент = &Контрагент
| И СчетНаОплатуКлиенту.Дата МЕЖДУ &НачалоПериода И &КонецПериода");
Запрос.УстановитьПараметр("Контрагент", Контрагент);
Запрос.УстановитьПараметр("НачалоПериода", НачалоДня(НачалоПериода));
Запрос.УстановитьПараметр("КонецПериода", КонецДня(КонецПериода));

Выборка = Запрос.Выполнить().Выбрать();
Пока Выборка.Следующий() Цикл
СтрокаТаблицы = ТаблицаСчетов.Добавить();
ЗаполнитьЗначенияСвойств(СтрокаТаблицы, Выборка);
СтрокаТаблицы.uid = Выборка.Ссылка.УникальныйИдентификатор();
КонецЦикла;

Возврат ТаблицаСчетов;

КонецФункции

3. Важный момент. Чтобы была возможность выполнять удаленный вызов данной функции нужно добавить её имя в процедуру УдаленныеПроцедуры общего модуля rpc_УдаленныеПроцедуры. Ниже приведён пример такой процедуры:

Функция УдаленныеПроцедуры() Экспорт

УдаленныеПроцедуры = Новый Массив;

///////////////////////////////////////////////////////////////////////////////////////////////////////
// Необходимо добавить следующие строки:
//
УдаленныеПроцедуры.Добавить("ПолучитьСчетаКлиента");
УдаленныеПроцедуры.Добавить("АннулироватьСчетКлиента");
///////////////////////////////////////////////////////////////////////////////////////////////////////

Возврат УдаленныеПроцедуры;

КонецФункции

Это сделано для безопасности с целью исключения выполнения произвольного кода, непредусмотренного разработчиком. Дело в том, что для вызова процедур используется метод 1С Выполнить:

Выполнить("Результат = rpc_УдаленныеПроцедурыПереопределяемый." + ИмяМетода + "(" + ... + ")";

Злоумышленник может в параметре JSON params передать строку, например для описанной выше функции

{"jsonrpc": "2.0", "method": "ПолучитьСчетаКлиента("7705260674", ‘20240901’, ‘20240930’); ВредныйМодуль.УдалитьВсе()", …}

В результате чего будет выполнен код:

Выполнить("Результат = rpc_УдаленныеПроцедурыПереопределяемый.ПолучитьСчетаКлиента(""7705260674"", '20240901', '20240930'); ВредныйМодуль.УдалитьВсе() ...

Т.е. после выполнения предусмотренного разработчиком метода "ПолучитьСчетаКлиента" начнёт выполняться произвольный код, который выполняться не должен!

Благодаря добавлению имён процедур в методе УдаленныеПроцедуры общего модуля rpc_УдаленныеПроцедуры такая возможность исключается. Для системы в таком случае имя метода будет не "ПолучитьСчетаКлиента", а ПолучитьСчетаКлиента("7705260674", ‘20240901, ‘20240930); ВредныйМодуль.УдалитьВсе(). Такая строка не определена в методе УдаленныеПроцедуры общего модуля rpc_УдаленныеПроцедуры, поэтому ни какой код выполняться не будет, а будет выдано сообщение об ошибке.

Теперь веб-программисту достаточно будет выполнить POST запрос по адресу http://<адрес_базы>/hs/jsonrpc2 в формате вида

{"jsonrpc": "2.0", "method": "ПолучитьСчетаКлиента", "params": ["7705260674", "2024-09-01", "2024-09-30"], "id": 1}

чтобы получить необходимые данные.

Всё работает, всё хорошо, но возникает новое требование — дать возможность клиенту из личного кабинета аннулировать счёт на оплату. И вот разработчик личного кабинета просит разработчика 1С реализовать такую возможность.

Для этого достаточно вновь открыть общий модуль расширения rpc_УдаленныеПроцедурыПереопределяемый и реализовать новую процедуру АннулироватьСчетКлиента(ИдентификаторСчета).

Процедура АннулироватьСчетКлиента(ИдентификаторСчета) Экспорт

СчетКлиента = Документы.СчетНаОплатуКлиенту.ПолучитьСсылку(ИдентификаторСчета);

МассивСчетов = Новый Массив;
МассивСчетов.Добавить(СчетКлиента);

Попытка
Документы.СчетНаОплатуКлиенту.УстановитьПризнакАннулирован(МассивСчетов);
Исключение
ЗаписьЖурналаРегистрации("JSON-RPC.АнулироватьСчетКлиента",
УровеньЖурналаРегистрации.Ошибка,,,
КраткоеПредставлениеОшибки(ИнформацияОбОшибке()));
КонецПопытки;

КонецПроцедуры

Теперь, когда клиент в личном кабинете в меню, например, выберет команду "Аннулировать счёт", веб-разработчик просто выполнит POST запрос к базе 1С вида

{"jsonrpc": "2.0", "method": "АнулироватьСчетКлиента", "params": ["422f9d5c-1032-11e5-92f1-0050568b35ac"]}

Хочу обратить внимание, что данная процедура не предполагает возвращение результата, поэтому передавать параметр id не нужно (в терминах JSON-RPC это называется уведомлением). Примечание. Использовано для примера, в реальности, конечно, нужно возвращать ошибку, если по какой-то причине не удалось аннулировать счёт, например, если отсутствует счёт с таким уникальным идентификатором.

Расширение предназначено для любой конфигурации на платформе не ниже 8.3.6. Протестировано на платформе версии 8.3.15.1656.