Дмитрий Рашевский
25.06.2019
30715

Обзор Asterisk REST Interface (ARI)

Введение История Asterisk API и Основные понятия в ARI Операции и их категории Настройка ARI на стороне Asterisk Введение С появлением Asterisk 12 в 2013 году был представлен Asterisk REST Interface – набор правил REST API для создания своих правил обработки вызовов на базе Asterisk. Данная статья поможет вам разобраться с Asterisk API, а также […]

  1. Введение
  2. История Asterisk API и Основные понятия в ARI
  3. Операции и их категории
  4. Настройка ARI на стороне Asterisk

Введение

С появлением Asterisk 12 в 2013 году был представлен Asterisk REST Interface – набор правил REST API для создания своих правил обработки вызовов на базе Asterisk. Данная статья поможет вам разобраться с Asterisk API, а также настроить и запустить его на PBX.

История Asterisk API

Изначально Asterisk разрабатывался, как самостоятельный программный комплекс соединения телефонных линий. Настройка такой конструкции осуществлялась с помощью конфигурационных файлов, а управление вызовами — через определенный conf файл (extensions.conf), вся логика сокращенно называется «диалпланом». Пока пользовались АТС, возникали потребности, требующие нестандартного подхода, выходящего за рамки использования встроенных функций и приложений диалплана. Для этого программистами разрабатывались отдельные модули на языке C, получающие доступ к данным каналов, медиа, бриджей и конечных устройств. При разработке многих нюансов — не предусмотришь, поэтому возникали баги и недочеты в кастомных модулях, что приводило к краху системы. Для этого были разработаны два интерфейса, AMI и AGI, управления приложениями диалплана, а также получения мета-данных с каналов, устройств и т. д.

AGI – аналог CGI в Apache. AGI является прослойкой между диалпланом Asterisk и внешней программой, управляющей каналом. Это синхронный интерфейс выполняющий действия на канале и возвращающий результаты, пока не завершится процесс.

AMI – асинхронный событийный интерфейс, позволяющий отслеживать информацию о происходящих процессах в Asterisk, также выполнять и изменять объекты Asterisk. В отличии от AGI. Сессия подключения стороннего приложения устанавливается по протоколу TCP/IP. В конфигурационных файлах Asterisk по умолчанию — это порт подключения 5038. Что позволяет отправлять астериску запрос, на что склиенсткая программа получает ответ-событие.

Из этого следует вывод:

  • AGI блокирует поток в Астериске, пока не закончится действие.
  • В AGI невозможно отслеживание событий DTMF, состояния канала и т. д.
  • Интерфейсы AMI и AGI морально устарели.

Поэтому было принято решение объединить AGI и AMI, так и появился Asterisk REST Interface (ARI).

Основной замысел ARI интерфейса заключается в следующем:

  • Использование как остлеживания и изменения состояния звонка, так и вызов функций диалплана
  • Интерфейс работает асинхронно
  • Выдает значения по типам — каналы, медиа-потоки, бриджы, устройства и т. д.
  • Данные отображаемых групп передаются через WebSocket в формате JSON
Интерфейс используется не для вызова/заворота приложения  диалплана VoiceMail, а для создания своего собственного приложения VoiceMail

Существует три основных понятия в ARI, они как аксиомы в математике:

  • RESTful интерфейс, используемый клиентской стороной для управления вызовами
  • WebSocket, передающий события клиенту в JSON формате
  • Приложение, используемое в диалплане, Stasis. Управление вызовом передаётся клиентскому приложению.

Пример использования приложения Stasis:

exten => _X.,1,Stasis(extended_app,${arg1},${arg2})
exten => _X.,n,NoOp(Завершение Stasis)

RESTful — архитектурный стиль для взаимодействия с программными компонентами.(вики)

  • Обращения базируются на клиент-серверной архитектурой
  • Сервер не хранит состояние клиентской стороны перед отправкой сообщения
  • Единый интерфейс. Все ресурсы идентифицируются в запросах

WebSocket —относительноновый протокол связи клиентской стороны с сервером в режиме realtime. В случае с ARI, вебсокет используется для асинхронной передачи событий от астериска к киенту.

Stasis – позволяет через диалплан астериска передать управление каналом внешнему приложению.

ARI не может изменять каналы, не вызванные в приложение диалплана Stasis. Целью ARI является создание собственного приложения диалплана, а не манипулирование существующим.

Группы и их категории

  1. Asterisk REST API
  2. Bridges REST API
  3. Channels REST API
  4. Devicestates REST API
  5. Endpoints REST API
  6. Events REST API
  7. Mailboxes REST API
  8. Playbacks REST API
  9. Recordings REST API
  10. REST Data Models
  11. Sounds REST API

Рассмотрим каждую группу подробнее:

  • Asterisk REST API

Обращения к различным категориям делятся на несколько типов:

  • GET
  • PUT
  • DELETE
  • POST

Рассмотрим методы по порядку

  • Методы GET
1 GET /asterisk/info Возвращает информацию о системе
2 GET /asterisk/ping Возвращает сообщение pong
3 GET /asterisk/modules Выдает список подключенных и не подключенных модулей
4 GET /asterisk/modules/{moduleName} Возвращает информацию о модуле
5 GET /asterisk/logging Выдается информация настройке логирования
6 GET /asterisk/variable Отдается значение глобальной переменной
Пример /asterisk/info
  • Методы POST:
1 POST /asterisk/modules/{moduleName} Загружает модуль в систему
2 POST /asterisk/logging/{logChannelName} Добавляет логирование канала
3 POST /asterisk/variable Устанавливает значение глобальной переменной
Загрузка модуля в систему
  • Методы DELETE:
1 DELETE /asterisk/modules/{moduleName} Выгружает модуль из системы
2 DELETE /asterisk/logging/{logChannelName} Удаляет логирование канала
Выгрузка модуля
  • Методы PUT:
1 PUT /asterisk/modules/{moduleName} Перезагрузка модуля
2 PUT /asterisk/logging/{logChannelName}/rotate Ротация логирования канала
  • Bridges REST API
1 GET /bridges Список всех активных бриджей
2 POST /bridges Создает новый бридж
3 POST /bridges/{bridgeId} Создает новый бридж или обновляет существующий
4 GET /bridges/{bridgeId} Выдает информацию по бриджу
5 DELETE /bridges/{bridgeId} Удаляет указанный бридж
6 POST /bridges/{bridgeId}/addChannel Добавляет новый канал в бридж
7 POST /bridges/{bridgeId}/removeChannel Удаляет канал из бриджа
8 POST /bridges/{bridgeId}/moh Воспроизводит moh в бридже или изменяет класс MOH на бридже
9 DELETE /bridges/{bridgeId}/moh Останавливает moh в бридже
10 POST /bridges/{bridgeId}/play Воспроизводит запись в бридже
11 POST /bridges/{bridgeId}/play/{playbackId} Воспроизводит запись в бридже
12 POST /bridges/{bridgeId}/record Начинает запись разговора в бридже
Информация по всем бриджам
Информация по определенному бриджу
  • Channels REST API
1 GET /channels Показывает список всех активных каналов
2 POST /channels Создает новый канал (originate)
3 GET /channels/{channelId} Детализация по каналу
4 POST /channels/{channelId} Создание канала с id
5 DELETE /channels/{channelId} Удалить канал (hangup)
6 POST /channels/{channelId}/continue Закончить выполенение приложения
7 POST /channels/{channelId}/move Перенести выполнение приложения с одного Stasis на другой
8 POST /channels/{channelId}/redirect Перенаправить канал на другое направление
9 POST /channels/{channelId}/answer Ответ в канал
10 POST /channels/{channelId}/ring Индикация звонка в статусе ring
11 DELETE /channels/{channelId}/ring Прекращение индикации в канале статуса ring
12 POST /channels/{channelId}/dtmf Отправить в DTMF в канал
13 POST /channels/{channelId}/mute Заглушить ганал
14 DELETE /channels/{channelId}/mute Включить звук на канале
15 POST /channels/{channelId}/hold Удержание канала
16 DELETE /channels/{channelId}/hold Снятие канала с удержания
17 POST /channels/{channelId}/moh Воспроизведение moh на канале
18 DELETE /channels/{channelId}/moh Выключение moh на канале
19 POST /channels/{channelId}/silence Включение тишины на канале
20 DELETE /channels/{channelId}/silence Выключение тишины на канале
21 POST /channels/{channelId}/play Воспроизвести запись на канале
22 POST /channels/{channelId}/play/{playbackId} Воспроизвести запись на канале
23 POST /channels/{channelId}/record Начало записи в файл на канале
24 GET /channels/{channelId}/variable Получить значения переменной или функции на канале
25 POST /channels/{channelId}/variable Установить значение переменной или функции на канале
26 POST /channels/{channelId}/snoop Начало прослушки на канале
27 POST /channels/{channelId}/snoop/{snoopId} Начало прослушки с id на канале
28 GET /channels/{channelId}/rtp_statistics Статистика RTP на канале
  • Devicestates REST API
1 GET /deviceStates Список всех контролируемым ARI устройств
2 GET /deviceStates/{deviceName} Текущий статус устройства
3 PUT /deviceStates/{deviceName} Изменение статуса устройства
4 DELETE /deviceStates/{deviceName} Удалить состояние устройства, контролируемого ARI
  • Endpoints REST API
1 GET /endpoints Список всех устройств
2 PUT /endpoints/sendMessage Отправка сообщения устройству
3 GET /endpoints/{tech} Список устройств указанной технологии
4 GET /endpoints/{tech}/{resource} Информация по устройству
5 PUT /endpoints/{tech}/{resource}/sendMessage Отправка сообщения устройству
Информация по устройству
  • Events REST API
1 GET /events События на вебсокете
2 POST /events/user/{eventName} Создание события на вебсокете
  • StasisStart/StasisEnd — информирование по попадании/исключении канала в(из) Stasis
  • ChannelCreated/ChannelDestroyed — создание/завершение канала
  • BridgeCreated/BridgeDestroyed — создание/завершение бриджа
  • ChannelDtmfReceived — получение DTMF событий.
  • ChannelStateChange — смена состояния канала.
  • ChannelUserevent — сгенерированное пользователем событие с доп. информацией
  • DeviceStateChanged — смена состояния устройства
  • EndpointStateChange — смена состояние конечного устройства.
  • PlaybackStarted/PlaybackFinished — начало/окончания проигрывания файла.
  • TextMessageReceived — получение сообщение.
  • TextMessageVariable – имя переменной/значение переменной

Более детальную информацию можно посмотреть тут

  • Playbacks REST API:
1 GET /playbacks/{playbackId} Детали по записи
2 DELETE /playbacks/{playbackId} Остановить воспроизведение
3 POST /playbacks/{playbackId}/control Управление записью

Настройка ARI

  1. Первоначально выполним настройку файла httpd.conf в директории конфигурационных файлов астериска.
[general]
enabled = yes
bindaddr = 127.0.0.1
http.conf
Если у вас установлен freepbx 12 и выше версии настройки находят в разделе Settings → Advanced Settings
Настройка web-server Freepbx
  • Теперь создадим файл ari.conf и занесем туда данные
[general]
enabled = yes
pretty = yes

[ARI_USER]
type = user
read_only = no
password = ARI_PASSWORD
Настройка ari.conf
  • Теперь для работы нужно проверить подключены ли модули ari в астериске командой module show like ari,необходимо обратить внимание на столбец Status
Подключенные модули ARI
  • Если в файле /etc/asterisk/modules.conf не загружены эти модули, добавляем в загрузку, добавив строку load = <имя модуля> и выполняем применение настроек командой fwconsole reload
Подключение модулей
Кейсы внедрения
Asterisk от VoxLink
Узнайте, какие крупные компании уже используют Asterisk в работе.
Скачать
Подписаться
Уведомить о
guest
0 комментариев
Межтекстовые Отзывы
Посмотреть все комментарии

Остались вопросы?

Я - Кондрашин Игорь, менеджер компании Voxlink. Хотите уточнить детали или готовы оставить заявку? Укажите номер телефона, я перезвоню в течение 3-х секунд.

VoIP оборудование


ближайшие курсы

10 доводов в пользу Asterisk

Распространяется бесплатно.

Asterisk – программное обеспечение с открытым исходным кодом, распространяется по лицензии GPL. Следовательно, установив один раз Asterisk вам не придется дополнительно платить за новых абонентов, подключение новых транков, расширение функционала и прочие лицензии. Это приближает стоимость владения станцией к нулю.

Безопасен в использовании.

Любое программное обеспечение может стать объектом интереса злоумышленников, в том числе телефонная станция. Однако, сам Asterisk, а также операционная система, на которой он работает, дают множество инструментов защиты от любых атак. При грамотной настройке безопасности у злоумышленников нет никаких шансов попасть на станцию.

Надежен в эксплуатации.

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

Гибкий в настройке.

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

Имеет огромный функционал.

Во многом именно Asterisk показал какой должна быть современная телефонная станция. За многие годы развития функциональность Asterisk расширилась, а все основные возможности по-прежнему доступны бесплатно сразу после установки.

Интегрируется с любыми системами.

То, что Asterisk не умеет сам, он позволяет реализовать за счет интеграции. Это могут быть интеграции с коммерческими телефонными станциями, CRM, ERP системами, биллингом, сервисами колл-трекинга, колл-бэка и модулями статистики и аналитики.

Позволяет телефонизировать офис за считанные часы.

В нашей практике были проекты, реализованные за один рабочий день. Это значит, что утром к нам обращался клиент, а уже через несколько часов он пользовался новой IP-АТС. Безусловно, такая скорость редкость, ведь АТС – инструмент зарабатывания денег для многих компаний и спешка во внедрении не уместна. Но в случае острой необходимости Asterisk готов к быстрому старту.

Отличная масштабируемость.

Очень утомительно постоянно возвращаться к одному и тому же вопросу. Такое часто бывает в случае некачественного исполнения работ или выбора заведомо неподходящего бизнес-решения. С Asterisk точно не будет такой проблемы! Телефонная станция, построенная на Asterisk может быть масштабируема до немыслимых размеров. Главное – правильно подобрать оборудование.

Повышает управляемость бизнеса.

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

Снижает расходы на связь.

Связь между внутренними абонентами IP-АТС бесплатна всегда, независимо от их географического расположения. Также к Asterisk можно подключить любых операторов телефонии, в том числе GSM сим-карты и настроить маршрутизацию вызовов по наиболее выгодному тарифу. Всё это позволяет экономить с первых минут пользования станцией.