В начале времен единственным "поставщиком" функционала Asterisk были модули, многие из которых расширяли арсенал приложений и функций плана набора.
Тогда, в начале времен, все эти команды и функции далеко опережали свое время, и благодаря им Asterisk "уделывал" по функционалу многие коммерческие продукты.
Если возникала какая-нибудь необходимость в выходе за пределы имеющихся приложений и функций, можно было написать свой собственный модуль на языке С, и это был единственный способ расширения функционала и выхода из имеющейся "клетки", какой бы просторной она ни была.
Но разработку модуля Астериск на языке С сложно назвать тривиальной задачей. Это весьма тернистый путь, к тому же весьма рискованный, ведь критическая ошибка в своем модуле запросто приводила к полному падению Asterisk в core.
Нужны были более "мягкие" и простые способы для расширения функций и интеграции с другими системами.
Так появились интерфейсы AGI и AMI.
Asterisk Gateway Interface (AGI) — это синхронный интерфейс выполнения диалплана, архитектурно "слизанный" с CGI. Команда диалплана AGI запускала процесс, и использовала стандартный ввод и вывод для получения команд и передачи результатов. При помощи AGI можно решать задачи интеграции с внешними системами, например, можно отправиться в корпоративную базу данных и найти имя звонящего клиента по его номеру.
По сути, AGI предоставлял способ написать план набора Asterisk не в формате extensions.conf, а на своем языке программирования, используя поставляемые модулями команды и функции, вокруг которых строится своя бизнес-логика.
Asterisk Manager Interface (AMI) — это асинхронный (событийный) интерфейс, позволяющий контролировать внутреннее состояние объектов в Asterisk, и получать информацию о происходящих событиях. Если AGI архитектурно напоминает CGI интерфейс, то AMI сессия похожа на телнет-сессию, в рамках которой стороннее приложение подключается по TCP/IP к AMI порту Asterisk, и может отправлять свои команды, ответ на которые приходит через некоторое время в виде события-ответа. Помимо ответов на команды в AMI соединение "валятся" всевозможные события, происходящие в Asterisk, и дело клиента определить, относятся они к нему или их можно просто игнорировать.
Про AGI можно сказать, что это call execution механизм, а про AMI — что это call control механизм. Чаще всего для построения своего телекоммуникационного приложения необходимо использовать сразу AGI и AMI вместе. Происходит "размазывание" бизнес логики по разным приложениям, что затрудняет его понимание и дальнейшее сопровождение и развитие.
Помимо этого, существует еще несколько ограничений:
- AGI: блокирует поток, обслуживающий канал.
- AGI: реакция на события (DTMF, изменение состояния) невозможна или затруднена только с AGI.
- Фундаментальные операции ограничены тем, что выполняется на канале. Но есть и другие примитивы: мосты, устройства, состояния, индикации сообщений и медиа на каналах, недоступные в AGI/AMI.
- AMI & AGI — морально устарели. REST, XML/JSON RPC более привычны и удобны в сегодняшнем мире.
В результате, чтобы вырваться за рамки существующих ограничений команд и функций, надо и писать свой С-модуль, реализующий низкоуровневый телефонный примитив, и интегрироваться с внешними системами при помощи AGI & AMI.
Так было до появления Asterisk REST Interface.
Основные концепции ARI:
- ARI позволяет как управлять состоянием звонка (call control), так и выполнять логику (call execution).
- ARI асинхронен.
- ARI «выставляет» «сырые» примитивы — каналы, мосты, устройства и т.п. через REST интерфейс.
- Состояния объектов доступны через JSON события поверх WebSocket.
- ARI — не для того, чтобы «зарулить» звонок в приложение VoiceMail, а для того, чтобы создать свое собственное приложение VoiceMail!
"Три кита" ARI:
- RESTful интерфейс.
- WebSocket подключение, по которому передаются события о контролируемых ресурсах в JSON формате.
- Приложение диалплана — Stasis, передающее управление каналом в ARI приложение.
Пример диалплана, передающего управление в Stais:
exten => _X.,1,Stasis(myapp,arg1,arg2) exten => _X.,n,NoOp(Left Stasis)
ARI имеет некоторые ограничения
- ARI не имеет доступа к любым объектам, а только к тем, которые контролирует. Это значит, что нельзя сделать answer на канале, которые не зарулен в Stasis приложение. Однако, channel list вернет все активные каналы, а не только те, что зарулены в Stasis
- Доступны только те операции, которые определены на стороне Asterisk (что понятно, ведь это Asterisk определяет все REST операции).
- Stasis приложение доступно только при установленном клиентском соединении. Если нет соединения на WebSocket с именем данного приложения, Stasis выдаст ошибку и пойдет дальше по диалплану.
Рассмотрим категории операций, доступных в ARI:
- Asterisk
- Мосты (bridges)
- Каналы (channels)
- Устройства (endpoints)
- Состояния устройств (device states)
- События (events)
- Почтовые ящики (mailboxes)
- Воспроизведения (playbacks)
- Записи (recordings)
- Звуки (sounds)
И остановимся на каждой категории подробнее.
Asterisk
- Динамическая конфигурация (sorcery, pjsip)
- Информация о сборке
- Управление модулями (список, загрузка, выгрузка)
- Управление логированием и ротацией логов
- Глобальные переменные (чтение и установка)
Мосты
- Получение, создание, удаление мостов
- Добавление / удаление каналов
- Проигрывание музыки на ожидании
- Включение записи
Каналы
- Список активных каналов и подробные данные канала.
- Создание канала (originate) и удаление (hangup) канала.
- Выход в диалплан
- Редирект канала
- Answer, Ring, DTMF, Mute, Hold, MoH, Silence, Play, Record, Variable, Snoop
Каналы
- Список активных каналов и подробные данные канала.
- Создание канала (originate) и удаление (hangup) канала.
- Выход в диалплан
- Редирект канала
- Answer, Ring, DTMF, Mute, Hold, MoH, Silence, Play, Record, Variable, Snoop
Устройства
- Список всех устройств
- Отправка сообщения на устройство (SIP, PJSIP, XMPP)
Состояние устройств
- Список статусов контролируемых устройств
- Установка статуса (NOT_INUSE, INUSE, BUSY, INVALID, UNAVAILABLE, RINGING, RINGINUSE, ONHOLD)
Полный список возможных операций смотрите на wiki asterisk — https://wiki.asterisk.org/wiki/display/AST/Asterisk+13+ARI
События
Приведу частичный список событий, которые доступны на веб-сокете подключенного приложения:
- StasisStart / StasisEnd — посылается в сокет сразу при попадании звонка в Stasis, и последним при выходе звонка из Стасиса.
- ChannelCreated / ChannelDestroyed — при создании и разрушении канала.
- BridgeCreated / BridgeDestroyed — при создании и разрушении моста.
- ChannelDtmfReceived — при получении DTMF.
- ChannelStateChange — изменилось состояние канала.
- ChannelUserevent — пользовательское событие. Очень удобная штука, которая позволяет надстраиваться над событийной моделью ARI.
- DeviceStateChanged — изменилось состояние устройства (NOT_INUSE, INUSE, BUSY, INVALID, UNAVAILABLE, RINGING, RINGINUSE, ONHOLD).
- EndpointStateChange — изменилось состояние конечной точки.
- PlaybackStarted / PlaybackFinished — началось и закончилось проигрывание файла.
- TextMessageReceived — получено сообщение.
- и другие (https://wiki.asterisk.org/wiki/display/AST/Asterisk+13+REST+Data+Models)
Что нового в Asterisk 14 ARI
- Получение записей
- Проигрывание медиа из HTTP источников.
- Медиа-плейлист (асинхронность требовала ожидания окончания одного звука для запуска следующего).
Пример
Ну и в заключение приведу пример оригинации вызова при помощи Python ARI библиотеки.
В этом примере делается оригинация по указанному пиру, и возвращается cause code:
#!/usr/bin/env python2.7 # Requirements: pip install ari gevent import argparse import ari import gevent from gevent.monkey import patch_all; patch_all() from gevent.event import Event import logging from requests.exceptions import HTTPError, ConnectionError import socket import time logging.basicConfig() # Important! # Otherwise you get No handlers could be found for # logger "ari.client" ARI_URL = 'http://192.168.56.101:8088/ari' ARI_USER = 'test' ARI_PASSWORD = 'test' client = ari.connect(ARI_URL, ARI_USER, ARI_PASSWORD) def run(): try: client.run('originator') except socket.error as e: if e.errno == 32: # Broken pipe as we close the client. pass except ValueError as e: if e.message == 'No JSON object could be decoded': # client.close() pass def originate(endpoint=None, callerid=None, context=None, extension=None, priority=None, timeout=None): # Go! evt = Event() # Wait flag for origination result = {} gevent.sleep(0.1) # Hack to let run() arrange all. start_time = time.time() try: channel = client.channels.originate( endpoint=endpoint, callerId=callerid, app='originator', timeout=timeout ) def state_change(channel, event): state = event['channel']['state'] if state == 'Up': channel = channel.continueInDialplan( context=context, extension=extension, priority=priority) def destroyed(channel, event): end_time = time.time() result['status'] = 'success' result['message'] = '%s (%s)' % ( event.get('cause_txt'), event.get('cause')) result['duration'] = '%0.2f' % (end_time - start_time) evt.set() channel.on_event('ChannelDestroyed', destroyed) channel.on_event('ChannelStateChange', state_change) # Wait until we get origination result evt.wait() client.close() return except HTTPError as e: result['status'] = 'error' try: error = e.response.json().get('error') result['message'] = e.response.json().get('error') except Exception: result['message'] = e.response.content finally: print result client.close() def parse_args(): parser = argparse.ArgumentParser() parser.add_argument('endpoint', type=str, help='Endpoint, e.g. SIP/operator/123456789') parser.add_argument('callerid', type=str, help='CallerID, e.g. 111111') parser.add_argument('context', type=str, help='Asterisk context to connect call, e.g. default') parser.add_argument('extension', type=str, help='Context\'s extension, e.g. s') parser.add_argument('priority', type=str, help='Context\'s priority, e.g. 1') parser.add_argument('timeout', type=int, help='Originate timeout, e.g. 60') return parser.parse_args() if __name__ == '__main__': args = parse_args() runner = gevent.spawn(run) originator = gevent.spawn(originate, endpoint=args.endpoint, callerid=args.callerid, context=args.context, extension=args.extension, priority=args.priority, timeout=args.timeout ) gevent.joinall([originator, runner])
Комментарии по скрипту
- Используется асинхронный фреймворк gevent для того, чтобы в рамках одного потока как установить соединение на websocket и принимать входящие сообщения, так и для того чтобы соригинировать вызов.
- Чтобы получить статус звонка и его продолжительность, необходимо подключенный звонок зарулить в Stasis приложение originator, в рамках которого будет вызвано событие ChannelDestroyed, уже в рамках которого произойдет обработка кода завершения.
- После соединения канал перейдет в состояние up, и в этом случае будет переброшен на указанный context, extension, priority.
- После завершения звонка закрывается client соединение.
Данный скрипт можно запустить из консоли, и вот что он вернет:
(env)MacBook-Pro-Max:barrier max$ ./ari_originate.py SIP/operator 11111 default s 1 4 {'status': 'success', 'duration': '2.54', 'message': u'Normal Clearing (16)'}
Обозначения параметров:
(env)MacBook-Pro-Max:barrier max$ ./ari_originate.py -h usage: ari_originate.py [-h] endpoint callerid context extension priority timeout positional arguments: endpoint Endpoint, e.g. SIP/operator/123456789 callerid CallerID, e.g. 111111 context Asterisk context to connect call, e.g. default extension Context's extension, e.g. s priority Context's priority, e.g. 1 timeout Originate timeout, e.g. 60 optional arguments: -h, --help show this help message and exit
Чтобы запустить данный скрипт, надо установить библиотеки ari и gevent:
pip install ari gevent
P.S. Написано по материалам выступления автора на Asterconf 2016.
P.P.S. Скрипт находится тут — https://gist.github.com/litnimax/2b0f9d99e49e49a07e59c45496112133
