API сервера унифицированных коммуникаций CommuniGate Pro

в 6:48, , рубрики: api, ip-телефония, Блог компании Сталкер Софт, ит-инфраструктура, почта, унифицированные коммуникации, метки: , , ,

API сервера унифицированных коммуникаций CommuniGate Pro

Каждый кто устанавливал новые сложные системы в организациях сталкивался с тем, что разработчики программного обеспечения не предусмотрели их специфической потребности в административном или пользовательском интерфейсе.

В случаях с коммуникациями к этому обычно добавляется потребность в дополнительной обработке корреспонденции, звонков и сообщений, как правило, с целью безопасности, контроля сотрудников и сбора статистики.

В этой статье мы рассмотрим набор инструментов, которым располагает сервер CommuniGate Pro для

  • Автоматизации административных задач
  • Обработки писем и звонков
  • Подключения сторонних программ и скриптов
  • Построения HTML интерфейсов
  • Создания UC клиентов и утилит на различных платформах

CLI

Интерфейс командной строки — стандартный способ управления многими продуктами. Удобен для автоматизации административных задач. Формат и полное описание команд выходит за рамки статьи, но их можно посмотреть в мануале, приведем лишь несколько примеров:

Доступ по poppwd

В сервере есть несколько способов доступа к CLI. Одним из самых удобных для ознакомления с командами можно считать модуль PWD. При стандартной конфигурации сервера достаточно набрать в коммандной строке ОС «telnet server.address 8106» (или «telnet server.address 106», в зависимости от ОС и версии). Изначально этот модуль был просто реализацией протокола смены пароля — poppwd:

$ telnet localhost 8106
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
200 mymac.ru CommuniGate Pro PWD Server 6.0.5 ready <1.1381912847@mymac.ru>
user postmaster
300 please send the PASS
pass ******
200 login OK, proceed
newpass ******
200 Password updated

Но нет никакой причины, чтобы останавливаться на одной текстовой команде:

listdomains
200 data follow
(mymac.ru)
listaccounts mymac.ru
200 data follow
{
  pbx =  macnt;
  postmaster =  macnt;
  user1 =  macnt;
  user2 =  macnt;
}

Слово macnt в этом ответе означает Multi-mailbox Account

Доступ по HTTP

CLI команды так же можно выполнить отправив простой POST или GET запрос с параметром «command» по адресу server.name:[http port]/CLI/.
API сервера унифицированных коммуникаций CommuniGate Pro

Бибилиотеки

Поскольку для практических задач «голый» текстовый доступ не очень удобен, мы создали Perl и Java библиотеки для работы с CLI.

На нашем сайте есть специальный раздел, где представлены примеры CLI скриптов для решения часто попадающихся задач.

Выполнение команд CLI также возможно в протоколе XIMSS (команда «cliExecute») и в CG/PL программе (функция ExecuteCLI()), о чем мы поговорим в соответствующих разделах.

Почтовые и сигнальные правила

Наверное, причисление правил к API можно назвать натяжкой, но в Communigate Pro правила применяются не только для перенаправления писем и звонков между учетными записями и ящиками, но и передают письма сторонним программам (например различным фильтрам), запускают CG/PL программы и даже запускают скрипты в операционной системе — вобщем, активно используются для интеграции как сами по себе, так и в связке с другими API.

Сигналами в Communigate Pro называют специальные объекты, которые применяются в коммуникациях «реального времени» (Real-time). Сигнал — это единица Real-time комуникации. Различные участники(SIP, XMPP клиенты, PBX приложения, ...) пересылают друг другу сигналы для организации, обрыва и обновления статусов диалогов и других действий .

Как работают правила

Правила разбиты на три уровня — серверные, доменные и уровень учетной записи (аккаунта). На каждом из этих уровней есть отдельные правила для сигналов и для почты.

У каждого правила есть имя и приоритет, у сигнальных правил есть еще условие «Когда». Чем выше приоритет — тем раньше, при одинаковых остальных условиях, сработает правило. Условие «Когда» определяет в какой момент сработает правило — на какой секунде обработки сигнала или при возникновении ошибки с определенным кодом (Не отвечает, Занято или другие ошибки):

API сервера унифицированных коммуникаций CommuniGate Pro

API сервера унифицированных коммуникаций CommuniGate Pro

Порядок обработки почтовых сообщений:

  • Применяются все серверные правила
  • Те письма, которые в результате маршрутизации попали в локальные учетные записи, обрабатываются доменными правилами и правилами в учетных записях следующим образом:
    • Доменные правила с приоритетом >5
    • Правила в учетной записи
    • Доменные правила с приоритетом <=5

Порядок обработки сигналов:

  • Применяются серверные сигнальные правила с пустым полем «Когда» (это означает, что они применяются сразу)
  • Те сигналы, которые в результате маршрутизации попали в локальные учетные записи, обрабатываются оставшимися серверными правилами (поле Когда не пустое), доменными правилами и правилами в учетных записях следующим образом:
    • Серверные правила с приоритетом >5
    • Доменные правила с приоритетом >5
    • Правила в учетной записи
    • Доменные правила с приоритетом <=5
    • Серверные правила с приоритетом <=5

Примеры использования

Ограничение пересылки в камках домена:
API сервера унифицированных коммуникаций CommuniGate Pro
Все звонки с адресатами вне определенных доменов перенаправляются на заданный адрес:
API сервера унифицированных коммуникаций CommuniGate Pro

Helper

В Communigate Pro реализован Helper протокол, который позволяет пользоваться внешними по отношению к серверу программами для различных задач.

При выполнении определенных условий, например, почтовое правило запускает фильтр для письма, которое обрабатывает или в домене срабатывает внешняя аутентификация, сервер запускает Helper программу. После чего, начинает через стандартный ввод присылать команды Helper протокола и считывает ответы из стандартного вывода.

Пример некоторой обобщенной сессии для хелпер протокола (I — ввод в программу, O — вывод):

O: * My Helper program started
I: 00001 INTF 1
O: 00001 INTF 1
I: 00002 COMMAND parameters
O: 00002 OK
I: 00003 COMMAND parameters
I: 00004 COMMAND parameters
O: * processing 00003 will take some time
O: 00004 ERROR description
O: 00003 OK
I: 00005 QUIT
O: * processed: 5 requests. Quitting.
O: 00005 OK

Здесь команда INTF — согласовывает версию протокола, а QUIT заканчивает сессию, * — это информационное сообщение на которое сервер не реагирует, но записывает в лог.

В рамках этого протокола разработаны более специализированные для:

  • Обработки тела письма
  • Внешней аутентификация
  • Подключения баннерной системы
  • Добавления RADIUS запросов в аутентификацию
  • Управление распределением нагрузки в кластере

Все они подключаются на странице Настройки->Общие->Помощники WebAdmin интерфейса.

Все пути к исполняемым файлам отсчитываются от Базовой директории Communigate Pro (директория с пользовательскими данными).

Обработка тела письма

Обработчики писем запускаются почтовым правилом, например таким:

API сервера унифицированных коммуникаций CommuniGate Pro

Детальное описание команд этого и других хелперов можно найти в мануале. В статье будем приводить лишь общее описание.

Хелперы такого типа используются в основном для подключения к CGPro анти-вирус и анти-спам движков.

Внешняя аутентификация

Хелпер протокол для внешней аутентификации обычно используются если:

  • Нужен метод аутентификации не поддерживаемый сервером напрямую
  • Часть аккаунтов расположена в другой системе (например AD)
  • Нужен сложный роутинг
  • Нужно внешнее управление услугаминастройками учетной записи

Примеры хелперов этого типа можно найти на этой странице.

Остальные помощники

Хелперы баннерной системы предоставляют серверу банеры для XIMSS и других (например HTTP) клиентов.
RADIUS хелперы позволяют добавить в процесс аутентификации дополнительные проверки по RADIUS протоколу.
Хелперы распределения нагрузки управляют Балансировщиком нагрузки в кластерной конфигурации Communigate Pro.

WSSP

WSSP (Web Server-side Pages) — это язык для шаблонов Web страниц.
Перед тем как говорить о WSSP, нужно замолвить пару слов про организацию Web скинов на сервере.

Каждый Web скин состоит из трех видов файлов:

  • Статические файлы — графика, стили, ...
  • WSSP файлы
  • Языковые и строковые файлы

Вместе с дистрибутивом Communigate Pro поставляется небольшой набор стандартных (stock) Web интерфейсов. Один из них безымянный (Unnamed), остальные именнованные. Эти демонстрационные скины хранятся в Application папке сервера (папка в ОС, где находится исполняемый файл) и поэтому они заменяются при обновлении сервера. Администраторы не должны изменять демонстрационные скины в своих конфигурациях, при установке обновления эти изменения могут потеряться. Вместо этого нужно воспользоваться тем, что файлы скинов образуют иерархию.

Иерархия файлов в скинах

Каждый скин может быть серверным, доменным или стандартным.

При обработке запросов от браузера пользователя серверу обычно нужно достать файлы с определенными именами из скина. При этом если файл не найден в доменном скине, то его ищут в серверном скине с таким же именем. А если не нашли в серверном, то ищут в стоковом. Если же файл по прежнему не найден и текщий скин именованный, то файл ищется в безымянных скинах.

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

То есть при таком подходе можно как проделывать небольшие изменения в стандартных скинах, так и разрабатывать свои с нуля.

Строковые файлы

.data файлы содержат текстовые данные (UFT-8) в формате CG/PL словаря эти данные используются различными модулями сервера для формирования строк в интерфейсе или в качестве значений настроек.

Эти файлы также образуют иерархию, но уже на уровне ключей в словаре, то есть если какой-то ключ отсутствует в файле strings.data домена, сервер пытается найтиего в файле strings.data на уровне сервера и т.д.

Английский язык является языком по-умолчанию для строк в интерфейсе. Если же язык пользователя (сессии) отличен от английского, значения ключей из языковых файлов (french.data, russian.data) замещают значения из strings.data файла.

Такая система позволяет включать в слегка модифицированные интерфейсы (файлы strings.data) включать только те ключи значения которых были изменены (например название компании, фирменные бренды), а не их полный набор.

Обработка запросов

Когда браузер соединяется с сервером по HTTP протоколу, сервер извлекает имя хоста из запроса и ищет домен с таким именем. Если домен найден, то сервер находит скин выбранный в качестве Web интерфейса по-умолчанию для пользователей этого домена. Запускается страница login.wssp.

Файлы wssp состоят из кода разметки (обычно HTML) с некоторыми дополнительными элементами:

  • текст ограниченный с двух сторон двойным символом % (%%element%%)
  • структуры такого формата —

Пример такого документа:

<html>
<body>

<h1>Добро пожаловать на %%server%%. Ваш логин %%ID%%.</h1>

<!--%%IF EXISTS(lastLogin)-->
Последний раз вы заходили %%lastLogin%%
<!--%%ENDIF-->


</body>
</html>

После обработки сервером все специальные конструкции будут заменены на строки или массивы строк из «окружения» — значения ключей из .data файлов в скине, имя домена или других объектов в сервере, значения настроек.

Любые другие файлы просто отдаются клиенту.

Базовые демонстрационные web интерфейсы можно рассматривать как отличные иллюстрации возможностей WSSP страниц. Но WSSP довольно ограничены в вопросах преобразования форматов данных или обращения к различным модулям и выполнения каких либо действий на сервере. И тут уже на помощь приходит более мощный инструмент.

CG/PL

Про язык CG/PL и разработку PBX приложений на нем мы уже рассказывали на Хабре в этой статье.

Помимо PBX его активно используют при разработке Web интерфейсов Communigate Pro. Если открыть список файлов даже базового Web скина (Пользователи->Интерфейсы), то там будет 14 файлов с небольшими CG/PL программами, обрабатывающими HTTP запросы.

Чтобы вызвать CG/PL программу для обработки HTTP запроса, нужно записать ее в любом текстовом редакторе, сохранить как .wcgp и загрузить в какой-либо Web скин.

После этого запрос к URL вида:

http://domain.name:[port]/programFile.wcgp/?Skin=skin_name

Запустит программу на выполнение.

http://domain.name:[port]/auth/programFile.wcgp/?Skin=skin_name

Запустит на выполнение от имени аккаунта с предварительной аутентификацией

http://domain.name:[port]/sys/programFile.wcgp

Этот запрос ищет программу только в серверном Unnamed скине и запускает от имени пользователя postmaster (серверный администратор)

В качестве примера рассмотрим небольшой скрипт выполняющий CLI команду «listaccounts» и преобразующий результат в JSON формат:

entry sysEntry is

void(executeCLI("listaccounts mymac.ru"));
accountList = Vars().executeCLIResult;

SetHTTPResponseCode(200);
SetHTTPResponseData(ObjectToJSON(accountList));

end entry;

API сервера унифицированных коммуникаций CommuniGate Pro

XIMSS

При таком большом количестве функциональности на стороне сервера — голос, мгновенные сообщения (включая СМС), календари, контакты, почта, файловый сервер у провайдеров сервиса возникают определенные сложности с написанием унифицированного клиента. Нужно подобрать или разработать библиотеки реализующие SIP, набор *DAV протоколов, SMTP, IMAP, XMPP. При этом нагрузка по разбору сообщений и форматов данных из этих протоколов ложится на клиент.

Как решение этих проблем мы разработали протокол XIMSS — XML Interface to Messaging, Scheduling and Signaling.

Все команды этого протокола — простые XML документы с прозрачными по смыслу атрибутами. Например эта простая команда перенаправит (fork) входящий звонок на двух пользователей:

C:
user1@example.comuser2@example.com

S:/>

Все форматы данных (MIME, vCard) приходят XIMSS клиенту в удобном для использования виде.

Также этот протокол позволяет выполнять все CLI команды доступные на сервере — через него можно регулировать все виды настроек, включая административные

Для ряда платформ нами разработаны готовые XIMSS библиотеки.

В качестве примеров возможностей XIMSS клиентов рекомендуем серию приложений Pronto!, Web версии которых (HTML5 и Flash) можно попробовать на нашем стенде bestvoip.ru.

В заключение

Communigate Pro это платформа, поведение которой можно регулировать на разных уровнях. От клиента до доступа в основные коммуникационные модули и разработки собственной функциональности на базе стандартных протоколов. При этом решение стабильно и выдерживает большие нагрузки.

Несмотря на то, что входной порог во все Communigate API в совокупности может казаться довольно большим, они покрывают большинство задач стоящих перед администраторами коммуникационных сервисов.

Автор: stalkersoft

Источник

Поделиться

* - обязательные к заполнению поля