Принцип работы
Melezh - это аддон для Открытого пакета интеграций, а конкретно для его CLI версии. Он умеет принимать HTTP-запросы на выбранном порту и интерпретировать их в команды самого ОПИ, а также в вызовы функций произвольных OneScript-обработчиков, которые вы можете написать сами
Если вы еще не слышали про Открытый пакет интеграций:
Открытый пакет интеграций - это бесплатное и с открытым исходным кодом расширение, представляющее из себя набор общих модулей для работы с разнообразными онлайн-сервисами и технологиями
Узнать больше:
Репозиторий на Github | Основная статья на Инфостарт | Документация
Melezh использует веб-сервер Kestrel (встроен в OneScript 2.0) для приема запросов и возвращает результаты выполнения соответствующих функций в качестве ответов на них. Однако, сервер не дает доступ сразу ко всем доступным функциям любому отправителю запроса: пути URL для вызова конкретных методов, значения параметров по умолчанию и возможность их перезаписи регламентируется гибкой системой настройки в виде отдельных обработчиков
Melezh имеет довольно много функций, аспектов и нюансов работы, подробное описание которых в рамках одной статьи рискует вылиться в невероятную духоту. Поэтому в этой статье моя цель лишь широкими мазками показать вам на простых примерах принципы работы и основной функционал данного проекта. Если это вас заинтересует (или уже заинтересовало), ознакомится со всеми тонкостями работы уже более подробно можно будет в нашей онлайн-документации
Ссылка на нее будет еще несколько раз по ходу и в конце статьи
Начало работы
Начнем с простого примера: вы скачали Melezh и хотите выполнить с его помощью первую задачу - организовать отправку сообщений в бота Telegram из, скажем, 1С конфигурации, где нет никакого функционала для работы с этим мессенджером
- Изначально Melezh - консольное приложение (имеется веб-интерфейс, но его мы рассмотрим чуть позже). Для начала работы с ним, нам необходимо из командной строки создать новый проект - файл на диске, где будут храниться настройки для конкретного решения:
melezh СоздатьПроект --path C:\test_proj.melezh -
Далее необходимо добавить обработчик запросов для нашей задачи - отправки сообщений в Telegram:
melezh ДобавитьОбработчикЗапросов --proj C:\test_proj.melezh --lib telegram --func ОтправитьТекстовоеСообщение --method GETЗдесь мы указываем путь к ранее созданному проекту, имя библиотеки ОПИ в CLI-варианте, имя функции и допустимый HTTP-метод для запросов (т.е. данный обработчик будет принимать GET-запросы от клиента)
-
Дополнительно, мы можем устанавливать значения параметров по умолчанию, чтобы не передавать их в будущих запросах:
melezh УстановитьАргументОбработчика --proj C:\test_proj.melezh --handler 42281f11b --arg token --value "***"Здесь мы передаем все тот же путь к файлу проекта, ключ обработчика (будет в результате выполнения ДобавитьОбработчикЗапросов из предыдущего шага), имя параметра (token) и его значение
-
Остается лишь запустить проект:
melezh ЗапуститьПроект --proj C:\test_proj.melezh --port 7788Так как при настройке мы выбрали HTTP-метод GET, URL для запроса будет выглядеть примерно вот так (с указанием чата и текста сообщения):
http://localhost:7788/42281f11b?chat=123123123&text="Hello world!"
Для доступа к этому и другим обработчикам Melezh извне, необходимо проксировать его при помощи стороннего сервера, вроде nginx, IIS или Apache, как это происходит для сайтов или при организации внешнего доступа к базам 1С
Информацию о доступных библиотеках, функциях и параметрах из набора ОПИ можно найти в его документации
Пример для функции ОтправитьТекстовоеСообщение, которую мы использовали
Таким же образом можно настроить обработчик на основе любой функции ОПИ: выбираете понравившиеся библиотеку и метод, указываете наиболее удобный для себя вид запроса (GET, POST с JSON или form-data телом) и все! Теперь вы можете отправлять на его URL данные из любой системы, не заботясь о реализации сложного обмена на вызывающей стороне. Достаточно простой отправки HTTP-запроса, которая доступна практически везде!
Полный список консольных команд и их назначение можно найти в соответствующем разделе документации Melezh
Веб-интерфейс
Но это была не интересная часть: подобная настройка в командной строке может показаться сложной и не наглядной, в чем, безусловно, есть доля правды. К счастью, кроме CLI, в Melezh есть встроенная веб-консоль, которая позволяет делать то же самое, только удобно и интерактивно:
Веб-интерфейс Melezh
Для того чтобы получить к ней доступ, необходимо только создать и запустить проект, после чего перейти в браузере на localhost:<ваш порт>/ui
melezh СоздатьПроект --path C:\test_proj.melezh
melezh ЗапуститьПроект --proj C:\test_proj.melezh --port 7788
Вас встретит страница авторизации, где нужно будет ввести пароль по умолчанию - admin. Внутри есть несколько панелей с различным функционалом:
- Главная панель, содержащая информацию о последних событиях
- Панель обработчиков, где их можно создать и настроить
- Страница просмотра логов
- Страница с общими настройками проекта
Рассказывать о них можно очень долго, но сегодня у нас лишь обзорная экскурсия. Интерфейс, на мой взгляд, достаточно интуитивный, а подробно о каждой странице и кнопке дополнительно расписано в онлайн-документации
Здесь пока оставлю лишь несколько красивых скриншотов и пойдем дальше
Логирование
Одним из преимуществ использования Melezh по сравнению с привычной организацией обмена "на местах", является единый и централизованный сбор логов об обработанных запросах
Все логи собираются автоматический (с возможностью отключения), в одном формате и могут быть удобно просмотрены в веб-консоли с отбором по обработчику и дате:
Просмотр логов по обработчику
В логи записывается основная информация о запросе, его заголовки, параметры URL, ответ и тело, если таковое имеется. При обработке multipart/form-data запросов, отдельно сохраняются также вложенные файлы из тела запроса
Часть страницы с информацией о конкретном запросе
Изменить некоторые аспекты логирования можно при помощи глобальных настроек:
- logs_path - путь сохранения логов. Для отключения логирования установите пустое значение
- logs_req_headers - логирование заголовков входящих запросов
- logs_req_body - логирование тела входящих запросов
- logs_req_max_size - отключение логирования logs_req_body для запросов, свыше этого размер (в байтах). 0 - без ограничений
- logs_res_body - логирование тела исходящих ответов
- logs_res_max_size - отключение логирования logs_res_body для запросов, свыше этого размер (в байтах). 0 - без ограничений
Расширения
Кроме вызова функций Открытого пакета интеграций, в Melezh также присутствует возможность добавления собственных методов для дальнейшего назначения их обработчикам запросов
Для определения подобных методов-расширений, необходимо добавить новый OneScript-модуль (.os файл с кодом) в подкаталог extensions основного каталога установки Melezh. Каждый метод такого модуля, который должен быть доступен в качестве функции обработчика, должен иметь документирующий комментарий следующего вида:
// Отображаемое имя метода
// Описание метода
//
// Параметры:
// Поле1 - Строка - Значение поля 1 - field1
// Поле2 - Строка - Значение поля 2 - field2
// Поле3 - Строка - Значение поля 3 - field3
//
// Возвращаемое значение:
// Структура Из КлючИЗначение - возвращаемое значение
Пример функций одного из стандартных расширений - RequestEcho.os:
// Эхо полей
// Возвращает в ответе поля, отправленные в запросе
//
// Параметры:
// Поле1 - Строка - Значение поля 1 - field1
// Поле2 - Строка - Значение поля 2 - field2
// Поле3 - Строка - Значение поля 3 - field3
//
// Возвращаемое значение:
// Структура Из КлючИЗначение - Эхо
Функция ЭхоПолей(Знач Поле1, Знач Поле2, Знач Поле3 = "") Экспорт
Возврат Новый Структура("field1,field2,field3", Поле1, Поле2, Поле3);
КонецФункции
Это - практически полная копия документирующего комментария из EDT, но с четвертым блоком у каждого параметра - именем аргумента в CLI стиле. Также, в описании параметров нельзя использовать знак "-", кроме как для разделения блоков
А вот так расширение выглядит в меню создания нового обработчика в веб-интерфейсе:
В качестве возвращаемого значения, подобная функция может возвращать сериализуемую в JSON коллекцию (структуру, массив или соответствие), текст или двоичные данные. Подробнее о стандартной библиотеке и расширениях можно узнать в соответствующем разделе документации
Про установку
Melezh - проект с открытым исходным кодом. Вы можете попробовать его уже прямо сейчас, воспользовавшись одним из доступных способов установки:
- Docker (рекомендуется)
Самый простой способ установки. Достаточно получить образ из облака и запустить:: Вместо -deb можно указать -rpm для использования rpm-based дистрибутива :: Вместо -ru можно указать -en для получения английской версии :: Вместо latest можно указать конкретную версию Melezh :: Порт может быть изменен в аргументе -p docker pull ghcr.io/bayselonarrend/melezh:latest-deb-ru docker run -d -p 1921:1921 --name melezh ghcr.io/bayselonarrend/melezh:latest-deb-ruКроме этого, вы можете воспользоваться локальным Dockerfile, который находится в .zip архиве одного из вариантов релиза на GitHub
-
Windows-установщик
Melezh можно установить из обычного установщика для Windows, который в данном случае совмещен с установщиком OInt - консольного приложения Открытого пакета интеграций. Скачать его можно в последнем релизе репозитория OpenIntegrations
В процессе установки одна из страниц установщика будет посвящена Melezh:
-
Linux
В релизах Melezh есть rpm и deb пакеты для различных Linux-дистрибутивов. Все они зависят от пакета oint, который необходимо предварительно скачать из релизов OpenIntegrations (>= 1.24.0)
-
OneScript
Melezh - это в первую очередь OneScript-пакет, а значит вы легко можете установить его из менеджера пакетов OPM, если уже используете OneScript 2.0
opm install melezh
Подробнее о различных способах установки вы также можете узнать в соответствующем разделе документации
Послесловие
Надеюсь, я смог вас заинтересовать данным проектом. Мне очень нравится, каким он получился, и, надеюсь, вам понравится тоже. На данный момент это первая, пилотная версия, поэтому я буду очень признателен, если вы оставите свою обратную связь о работе с Melezh и, в частности, о найденных багах или недоработках. Сделать это можно в Issues на GitHub или комментариях к данной статье
Также вы можете помочь проектам Melezh и ОПИ, поставив им звездочки на GitHub. При желании поддержать проекты материально, вы всегда сможете найти информацию об этом в конце страницы каждого из этих репозиториев
Спасибо за внимание!
Репозиторий Melezh: github.com/Bayselonarrend/Melezh
Репозиторий ОПИ: github.com/Bayselonarrend/OpenIntegrations
Последний релиз: github.com/Bayselonarrend/Melezh/releases/tag/0.1.0
Документация: openintegrations.dev/docs/Addons/Melezh/Overview
Мой GitHub: https://gitub.com/Bayselonarrend OpenYellow: https://openyellow.org Лицензия MIT: https://mit-license.org
