Melezh: ваш персональный центр интеграций с внешними API и сервисами

Принцип работы

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