WebSocket Внешняя компонента NativeAPI для 1С:Предприятие 8.3

Руководство пользователя: ws_client_audit

• Поддержка протоколов ws:// и wss:// (SSL/TLS)
• Полностью асинхронные методы — не блокируют интерфейс 1С
• Автоматическое переподключение с прогрессивной задержкой (1-2-3-5-10 сек)
• Поддержка передачи сообщений до 50 МБ
• Множественные экземпляры одновременно (для разных серверов)
• Произвольные HTTP-заголовки в формате JSON (для авторизации, CORS и др.)
• Стандартизированные коды ошибок в формате TYPE:CODE
• Полная поддержка UTF-8 и кириллицы
• Защита от дубликатов событий ошибок
• Тонкая настройка интервалов ping и переподключения
• Совместимость с любым стандартным WebSocket-сервером (RFC 6455)

1. Типовые сценарии использования

1. Аудит-сервер: уведомления о новых документах между подразделениями
2. E-Imzo: интеграция с локальным сервисом электронной подписи Узбекистана
3. Чат-серверы: обмен сообщениями между пользователями 1С
4. Real-time мониторинг: получение обновлений курсов валют, остатков и т.п.
5. IoT-устройства: связь с оборудованием через WebSocket
6. Push-уведомления: получение уведомлений с серверов в реальном времени

2. Системные требования

3. Установка

3.1. Структура поставки

После распаковки архива поставки вы получите следующие файлы:

• ws_client_audit/
  • ws_client_audit.dll       # Сама компонента (отдельно)
  • _ INFO.XML                    # Информация о компоненте
  • _MANIFEST.XML             # Манифест внешней компоненты
  • _ MANUAL_RU.md           # Это руководство
• LICENSE.txt

3.2. Установка компоненты

Существует два способа использования компоненты:

Способ 1: Через общий макет конфигурации (рекомендуется)

1. Откройте Конфигуратор 1С
2. В дереве объектов конфигурации найдите ветку «Общие макеты»
3. Создайте новый макет с именем, например, «WsClientAuditКомпонент»
4. Тип макета: «Двоичные данные»
5. Загрузите файл ws_client_audit.zip
6. Сохраните конфигурацию (Ctrl+S) и обновите конфигурацию базы данных (`F7`)
7. Перезапустите 1С

Способ 2: Загрузка напрямую из файла (для отладки)

Файл ws_client_audit.dll размещается в любой папке, и в коде указывается прямой путь к нему.

4. Загрузка компоненты в 1С

4.1. Подключение через макет

&НаКлиенте
Процедура ЗагрузитьКомпоненту()

    Результат = ПодключитьВнешнююКомпоненту(
        "ОбщийМакет.WsClientAuditКомпонент",   // Путь к макету
        "WsAudit",                              // Псевдоним (любой)
        ТипВнешнейКомпоненты.Native
    );

    Если НЕ Результат Тогда
        Сообщить("Ошибка загрузки компоненты!");
        Возврат;
    КонецЕсли;

    // Создание экземпляра компоненты
    // Формат: AddIn.<Псевдоним>.<Имя класса>
    WS = Новый("AddIn.WsAudit.WsClientAudit");

    Если WS = Неопределено Тогда
        Сообщить("Ошибка создания объекта!");
        Возврат;
    КонецЕсли;
   
    Сообщить("Компонента успешно загружена. Версия: " + WS.Version);

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

4.2. Подключение из файла

&НаКлиенте
Процедура ЗагрузитьКомпонентуИзФайла()

    Результат = ПодключитьВнешнююКомпоненту(
        "C:\Components\ws_client_audit.dll",
        "WsAudit",
        ТипВнешнейКомпоненты.Native
    );

    Если Результат Тогда
        WS = Новый("AddIn.WsAudit.WsClientAudit");
    КонецЕсли;

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

5. Свойства

Все свойства компоненты доступны только для чтения.

5.1. Connected (Подключён)

Тип: Булево

Назначение: Возвращает текущее состояние подключения.

Если WS.Connected Тогда
    Сообщить("Соединение активно");
Иначе
    Сообщить("Соединение отсутствует");
КонецЕсли;

5.2. LastError (ПоследняяОшибка)

Тип: Строка

Назначение: Возвращает текст последней произошедшей ошибки в формате TYPE:CODE.

Сообщить("Последняя ошибка: " + WS.LastError);
// Пример: "AUTH_ERROR:4401"

5.3. Version (Версия)

Тип: Строка

Назначение: Возвращает версию компоненты.

Сообщить("Версия: " + WS.Version);  // "1.0.0"

5.4. ClientUserID (ИДПользователя)

Тип: Строка

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

6. Методы

6.1. Connect(url, headersJson) — Подключение к серверу

Назначение: Асинхронно устанавливает соединение с WebSocket-сервером.

Параметры:

Возвращает: Булево — Истина, если задача подключения принята (не означает успешного подключения!)

Важно: Метод асинхронный. Реальный результат подключения сообщается через событие OnConnected или OnError.

// Простое подключение без авторизации
WS.Connect("wss://server.com/ws", "");

// Подключение с Bearer-токеном
Заголовки = Новый Структура;
Заголовки.Вставить("Authorization", "Bearer eyJhbGc...");
ЗаписьJSON = Новый ЗаписьJSON;
ЗаписьJSON.УстановитьСтроку();
ЗаписатьJSON(ЗаписьJSON, Заголовки);
HeadersJson = ЗаписьJSON.Закрыть();

WS.Connect("wss://server.com/ws", HeadersJson);

6.2. Disconnect() — Отключение от сервера

Назначение: Асинхронно закрывает соединение с сервером.

Возвращает: Булево — Истина.

Важно: Метод немедленно возвращает управление, не блокируя интерфейс 1С. Реальное завершение подтверждается событием OnDisconnected.
 

WS.Disconnect();
// Интерфейс не блокируется!
// Через ~100 мс придёт событие OnDisconnected

6.3. SendMessage(message) — Отправка сообщения

Назначение: Асинхронно отправляет произвольное сообщение на сервер.

Параметры:

Возвращает: Булево — Истина, если задача отправки принята.
 

// Простой текст
WS.SendMessage("Привет, сервер!");

// JSON
WS.SendMessage('{"action":"create_invoice","amount":50000}');

// JSON с массивом получателей (если сервер так требует)
WS.SendMessage('{"recipients":["AS001","AS002"],"data":"..."}');

6.4. SendRaw(message) — Прямая отправка сообщения

Назначение: Эквивалентно методу SendMessage. Введён для семантического разделения: используйте SendRaw для диагностических, тестовых или специальных сообщений (например, для E-Imzo).

// Запрос списка сертификатов у E-Imzo
WS.SendRaw('{"plugin":"pfx","name":"list_all_certificates"}');