Подключение к ExtSdk2 через OLE - Сценарии ExtSdk2

Материал из razgovorov.ru
Перейти к: навигация, поиск

Краткое описание

Подключение к OLE объекту

Основным способом для подключения к ExtSdk2 из внешних систем является OLE объект "Tensor.SbisPluginClientCOM". Данный OLE объект устанавливается на ПК пользователя при полной установке СБИС3 Плагин. Обновляется OLE объект автоматически вместе с обновлением СБИС3 Плагин. Подключение к OLE объекту аналогично работе с другими OLE объектами.

В момент подключения, OLE объект устанавливает WebSocket соединение с СБИС3 Плагин, по этому до отправки первой команды нужно убедиться, что данное подключение установлено дождавшись событие "connected" (type=Event, data.eventName=connected). . Подробнее см. в разделе Получение и обработка событий.

Подготовительные операции

ExtSdk2 является расширением (модулем) СБИС3 Плагин. При обращении к модулю плагину требуется указывать идентификатор модуля. Получить идентификатор ExtSdk можно при помощи команды ole.GetModule.


Кроме идентификатора модуля, для отправки команд в ExtSdk2 вызывающая сторона (клиент) должен быть аутентифицирован. Для аутентификации в ExtSdk2 доступны несколько вариантов. Результатом аутентификации является полученный идентификатор сессии который следует передавать при каждом вызове ExtSdk2 (допускается на одном соединении вызов команд из разных сессий).

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

Вызов команд

Для взаимодействия с OLE объектом, в зависимости от возможностей Вашей системы, можно использовать либо JSON либо XML (в данном случае XML это безусловно сериализованный в XML JSON). Структура передаваемых данных идентична в обоих вариантах, выбор вариант зависит от наличия в ИС и скорости работы соответствующего парсера. В наших интеграционных модулях для 1С и SAP из-за необходимости поддержки старых версий используется XML.

Все вызовы СБИС3 Плагин асинхронны - вы отправляете команду и ждете сообщения о результатах выполнения команды. Для отправки команды, в зависимости от формата работы, нужно вызвать метод ole.CallMethod или ole.CallMethodXML (исключение составляют команды аутентификации, их следует вызывать при помощи методов CallMethodWithoutAuth и CallMethodWithoutAuthXML). В ответ вы получите идентификатор запроса (UUID), данный идентификатор будет присутствовать в событии ответа и по нему вы сможете понять к какому запросу относится данное событие.

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

Получение и обработка событий

Работа с ExtSdk2 и СБИС3 Плагин осуществляется асинхронно, т.е. в ответ на ваш вызов Вы получите только его идентификатор, а не результат или ошибку. Для получения результата требуется делать периодический вызов функции ole.ReadAllObject или ole.ReadAllXml2 (в зависимости от формата обмена). Данные функции возвращают все события которые поступили от плагина с момента последнего вызова этой функции (или запуска плагина если это первый вызов).

По мимо событий содержащих результат вызова команды, в OLE Объект могут приходить события содержащие прогресс выполнения длительной операции (например загрузки больших файлов) или события произошедшие в СБИС, например распознавание документа и т.п. В интеграционных модулях рекомендуется построить обработку событий на принципах регистрации и вызова обработчика обратного вызова. Интеграционный модуль должен игнорировать не интересующие или неожиданные события.

Кроме асинхронных вызовов, сами команды ExtSdk2 могут выполняться асинхронно. В основном это касается методов отправки. Такие методы в качестве ответа возвращают специальный тип ошибки Error #ASYNC. Результат выполнения приходит отдельным событием Event #ASYNC.

Такой подход обусловлен тем, что изначально предполагалось исключительно синхронное выполнение методов внутри СБИС3 Плагин.

Рекомендуем ознакомиться с примером реализации подключения к ExtSdk2 на python или 1С. Данный пример эмулирует синхронную работу кода информационной системы.



В ответ на команды СБИС3 Плагин отправляет события, кроме этого аналогичным образом передаются события из СБИС. Таким образом в любой момент времени вы можете получать события как на свои вызовы, так и просто событиятак же ExtSdk2 о

Далее Плагин подготавливает необходимые внутренние инструменты для подключения и в случае успеха пробрасывает событие Event в виде json сериализованного в строку. У данного события в объекте 'data' лежит поле 'eventName' со значением 'connected'.

Пример вызовов методов плагина через COM-объект

# Получение модуля

guid_module = ole.GetModule(name)


# Вызов методов модуля через COM-объект

query_id = str(uuid.uuid4())
module_method = "ExtSdk2.AuthByPassword"
parameters_module_method = json.dumps({"Login": "login", "Password": "password"}, ensure_ascii=True)
host = online.sbis.ru

ole.CallMethodWithoutAuth( query_id, guid_module, module_method, parameters_module_method, host )

session_id = ********@plugin.sbis.ru

ole.CallMethod( query_id, guid_module, module_method, parameters_module_method, session_id)

Для вызова методов модуля ExtSdk2 необходимо сначала получить его guid с помощью функции COM-объекта GetModule.

Вызов методов ExtSdk2 выполняется через вызов методов COM-объекта. Метод CallMethodWithoutAuth вызывается для авторизации в плагине и позволяет получить идентификатор сессии - session_id. С данным идентификаторов следует вызывать все остальные методы модуля через CallMethod.

Для интегрируемых систем, работающих с xml, следует использовать CallMethodWithoutAuthXML и CallMethodXML соответственно.

Пример получения ответов от COM-объекта

json_string = ole.ReadAllObject()

ReadAllObject функция COM-объекта, возвращающая json массив событий в виде строки.

Для интегрируемых систем, работающих с xml, следует использовать ReadAllXml2. 


xml_string = ole.ReadAllXml2()

События бывают трех типов: Message, Error, Event, которые следует разобрать и найти ответ по переданному query_id

Примеры событий от модуля

Событие Message

Событие типа Message содержит queryID вызываемого метода и результат работы в поле 'Result'. 

{
  'type': 'Message',
  'queryID': '15e79572-b1be-4dc2-a0e9-3652ecb187c5',
  'data': {
    'Result': ...,
    'Stat': ...
    }
  }
}

Событие Error

Событие типа Error содержит queryID вызываемого метода и объект ошибки в поле 'data'. 

{
  'type': 'Error',
  'queryID': '15e79572-b1be-4dc2-a0e9-3652ecb187c5',
  'data': {
    'code': ...,
    'detail': ...,
    'dump': {},
    'message': ...,
    'method_name': 'ExtSdk2....',
    ...
  }
}

Событие Error #ASYNC

{
  'type': 'Error',
  'queryID': 'b3e310ec-7d85-4026-bfad-228690f38d55',
  'data': {
    'code': 308,
    'detail': '#ASYNC',
    'dump': {},
    'message': 'Ожидайте загрузки документа',
    'method_name': 'ExtSdk2.WriteDocumentEx',
    'stack': [
      {
        'method_name': 'AsyncUploadAttachments b3e310ec-7d85-4026-bfad-228690f38d55'
      }
    ]
  }
}

Событие Event

Событие типа Event содержит queryID вызываемого метода и имя события в поле 'eventName'. 

{
  'type': 'Event',
  'data': {
    'channelName': 'SbisPluginEvent',
    'eventName': 'connected',
    'type': 'object',
    'data': ...
  }
  'queryID': '15e79572-b1be-4dc2-a0e9-3652ecb187c5'
}

Событие Event #ASYNC

{
  'type': 'Event',
  'data': {
    'channelName': 'SbisPluginEvent',
    'eventName': 'extsdk2.async.complete',
    'type': 'object',
    'data': {
      'QueryId': '4fb98709-0264-4e01-a0aa-e4d30b4b65a7',
      'Result': {...},
      'Stat': {...}
    }
  }
}

Пример функции обработки одной страницы событий

    def read_all_object():
        
        # Словарь с функциями обработки событий по типу
        supported_events = {
            'Message': parse_Message,
            'Error': parse_Error,
            'Event': parse_Event
        }

        result = []

        json_string = ole.ReadAllObject()
        events = json.loads(json_string)

        for event in events:
            event_type = event.get('type')
            supported_events[event_type](event)
            result.append(event)
            
        return result

Функция read_all_object может быть модифицирована с добавлением параметра query_id. Тогда она будет постоянно опрашивать плагин на наличие ответа от вызываемого метода, игнорируя все остальные.

Реализация функций parse_Message, parse_Error, parse_Event зависит от потребностей пользователя, например получения только поля 'data' у события, и поэтому может быть описана самостоятельно. В текущем варианте представлен пример для получения полной информации по пришедшим событиям.

Источник — «http://wiki.razgovorov.ru/index.php?title=Подключение_к_ExtSdk2_через_OLE_-_Сценарии_ExtSdk2&oldid=5547»