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

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

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

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

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

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

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

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

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

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

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

• Методы POST:

• Методы DELETE:

• Методы PUT:

• Bridges REST API

• Channels REST API

• Devicestates REST API

• Endpoints REST API

• Events REST API

• StasisStart/StasisEnd — информирование по попадании/исключении канала в(из) Stasis
• ChannelCreated/ChannelDestroyed — создание/завершение канала
• BridgeCreated/BridgeDestroyed — создание/завершение бриджа
• ChannelDtmfReceived — получение DTMF событий.
• ChannelStateChange — смена состояния канала.
• ChannelUserevent — сгенерированное пользователем событие с доп. информацией
• DeviceStateChanged — смена состояния устройства
• EndpointStateChange — смена состояние конечного устройства.
• PlaybackStarted/PlaybackFinished — начало/окончания проигрывания файла.
• TextMessageReceived — получение сообщение.
• TextMessageVariable – имя переменной/значение переменной

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

• Playbacks REST API:

Настройка ARI

1. Первоначально выполним настройку файла httpd.conf в директории конфигурационных файлов астериска.

[general]
enabled = yes
bindaddr = 127.0.0.1

• Теперь создадим файл ari.conf и занесем туда данные

[general]
enabled = yes
pretty = yes

[ARI_USER]
type = user
read_only = no
password = ARI_PASSWORD

• Теперь для работы нужно проверить подключены ли модули ari в астериске командой module show like ari,необходимо обратить внимание на столбец Status

• Если в файле /etc/asterisk/modules.conf не загружены эти модули, добавляем в загрузку, добавив строку load = <имя модуля> и выполняем применение настроек командой fwconsole reload