Основной способ подключения к ExtSdk2 из внешних систем — OLE-объект «Tensor.SbisPluginClientCOM». Он устанавливается на компьютер пользователя во время полной установки Saby Plugin. Обновляется OLE-объект автоматически вместе с обновлением Saby Plugin. Подключение к OLE-объекту аналогично работе с другими OLE-объектами.
В момент подключения OLE-объект устанавливает WebSocket соединение с Saby Plugin. Поэтому до отправки первой команды нужно убедиться, что подключение установлено — дождитесь события «connected»(type=Event, data.eventName=connected).
Подготовительные операции
ExtSdk2 — это расширение(модуль) Saby Plugin. Плагину нужно указывать идентификатор модуля, при обращении к нему. Получить идентификатор ExtSdk можно при помощи команды ole.GetModule.
Кроме идентификатора модуля, для отправки команд в ExtSdk2 вызывающая сторона(клиент) должна быть аутентифицирована. Для аутентификации в ExtSdk2 доступны несколько вариантов. Результатом аутентификации будет идентификатор сессии, который нужно передавать при каждом вызове ExtSdk2 (допускается на одном соединении вызов команд из разных сессий).
Сохраняйте идентификатор сессии между подключениями. Вызывать аутентификацию только при получении ошибки аутентификации.
Вызов команд
Для взаимодействия с OLE-объектом используется JSON или XML (XML это сериализованный в XML JSON). Выбор зависит от возможностей вашей системы. Структура передаваемых данных идентична в обоих вариантах, выбор варианта зависит от наличия в ИС и скорости работы соответствующего парсера. В наших интеграционных модулях для 1С и SAP из-за необходимости поддержки старых версий используется XML.
Все вызовы Saby Plugin асинхронны — вы отправляете команду и ждете сообщения о результатах выполнения. Для отправки команды, в зависимости от формата работы, нужно вызвать метод ole.CallMethod или ole.CallMethodXML. Команды аутентификации вызываются при помощи методов CallMethodWithoutAuth и CallMethodWithoutAuthXML. В ответ вы получите идентификатор запроса — UUID. Он будет присутствовать в событии ответа и по нему можно понять, к какому запросу относится данное событие.
Получение и обработка событий
Работа с ExtSdk2 и Saby Plugin осуществляется асинхронно — в ответ на вызов приходит его идентификатор, а не результат или ошибка. Чтобы получить результат, нужно делать периодический вызов функции ole.ReadAllObject или ole.ReadAllXml2, в зависимости от формата обмена. Эти функции возвращают все события, которые поступили от Плагина с момента последнего вызова этой функции или запуска Плагина, если это первый вызов. Между вызовами ReadAllObject и ReadAllXml2 делайте таймаут 100-500мс, например, с помощью метода ole.Sleep
В OLE-объект могут приходить события с прогрессом выполнения длительной операции. Например, загрузка больших файлов или распознавание документа. Рекомендуем построить обработку таких событий на принципах регистрации и вызова обработчика обратного вызова. Игнорируйте не интересующие или неожиданные события.
Кроме асинхронных вызовов, команды ExtSdk2 тоже могут выполняться асинхронно. Например, методы отправки. В ответе они возвращают специальный тип ошибки, а результат выполнения приходит отдельным событием.
Пример реализации подключения к ExtSdk2, аутентификация и вызов одного метода на python. Приведен для понимания работы с модулем, не является образцом.