CommuniGate Pro
+7 (499) 271-31-54 обратный звонок


CommuniGate Pro платформа APIs

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

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

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

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

Доступ по HTTP

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

Бибилиотеки

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

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

Выполнение команд CLI также возможно по протоколу XIMSS (команда "cliExecute")и в языке CG/PL (функция ExecuteCLI()).

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

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

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

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

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

У каждого правила есть имя и приоритет, у сигнальных правил есть дополнительное условие "Когда". При одинаковых условиях правило сработает раньше, если его приоритет выше. Условие "Когда" определяет в какой момент сработает правило. Это может быть определенная секунда обработки сигнала или факт возникновении ошибки с определенным кодом (Не отвечает, Занято и т.д.):




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

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


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

Ограничение пересылки в рамках домена:



Все звонки с адресатами вне определенных доменов перенаправляются на заданный адрес:



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 заканчивает сессию, * — это информационное сообщение на которое сервер не реагирует, но записывает в лог.

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

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

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

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

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



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

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

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

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

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

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

Хелперы баннерной системы предоставляют серверу банеры для XIMSS, HTTP и других клиентов.

RADIUS хелперы позволяют добавить в процесс аутентификации дополнительные проверки по RADIUS протоколу.

Хелперы распределения нагрузки управляют Балансировщиком нагрузки в кластерной конфигурации Communigate Pro.

WSSP

WSSP (Web Server-side Pages) — это язык для шаблонов Web страниц.

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

Вместе с дистрибутивом 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) с некоторыми дополнительными элементами:

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

<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;



XIMSS

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

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

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

C:<callRedirect id="A018" callLeg="inp003" >
        <To>user1@example.com</To><To>user2@example.com</To>
  </callRedirect>
S:<response id="A018"/>

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

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

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

В качестве примеров возможностей XIMSS клиентов рекомендуем ознакомиться с приложением Samoware. Демонстрационная Web-версия этого приложения есть на нашем стенде demo.communigate.ru.

Один протокол вместо 10

В Communigate Pro любые задачи можно решать через один протокол - XIMSS. Просмотр почты, календарей и контактов, осуществление звонков и даже администрование сервера без необходимости изучать многочисленные международные стандарты.

  • SMTP (Simple Mail Transfer Protocol)
  • SIP (Session Initiation Protocol)
  • XMPP (Extensible Messaging and Presence Protocol)
  • SMPP (Short Message Peer to Peer Protocol)
  • IMAP (Internet Message Access Protocol)
  • POP and RPOP (Post Office Protocol)
  • FTP (File Transfer Protocol)
  • WebDAV (WWW Distributed Authoring and Versioning)
  • LDAP (Lightweight Directory Access Protocol)
  • SNMP (Simple Network Management Protocol)