Интерфейс управления сервером Asterisk (Asterisk Manager API)

Интерфейс управления сервером Asterisk (далее Manager API) позволяет клиентским программам соединяться с серверным приложением Asterisk, отправлять ему команды и/или считывать события, происходящие в АТС, используя TCP/IP протокол. Те, кто занимается интеграцией различных задач, могут найти много полезного для себя, например, отслеживая поведение телефонных абонентов и управляя ими на основании каких-либо правил.

Для коммуникации между АТС Asterisk и подсоединенным Manager API клиентом используется простой текстовый построчный протоков вида: "параметр: значение". Окончание строки определяется последовательностью CRLF. Для упрощения дальнейшего описания, мы будем использовать термин "пакет " для описания набора строк вида "параметр: значение", после которых идет пустая строка, содержащая только символы возврата каретки и перевода строки (CRLF).

Описание работы протокола.

Особенности работы протокола:

Перед отправкой команд серверу Asterisk, Вы должны установить manager API сессию (см. ниже).
Пакеты могут передаваться в любом направлении в любое время, после прохождения авторизации.
Первая строка в пакете должна содержать параметр "Action", если она отправляется от клиента серверу и ,соответственно, "Event" или "Response", когда пакет передается от Asterisk клиенту.
Порядок строк в пределах пакета не имеет значения, следовательно, Вы можете использовать для хранения одного пакета библиотеку Вашего языка программирования, где не требуется использования сортировки, тем самым увеличив производительность составления пакета данных.
Последовательность символов CRLF используется для отделения строк друг от друга, а пустая строка (два подряд идущих CRLF) указывает на окончание команды и Asterisk приступает к ее выполнению.

Типы пакетов.

Тип пакета определяется наличием одного из следующих значений параметра в паре “Параметр: значение”:

Action: Пакет отправляется подсоединенным клиентом серверу Asterisk, в значении параметра указывается требуемое действие, которое должно быть выполнено сервером Asterisk. Набор действий является ограниченным (но расширяемым) списком, который доступен клиенту, в зависимости от загруженных модулей сервера Asterisk и прав назначенных пользователю, от имени которого подсоединился клиент. За один раз (в пределах одного пакета) может быть указано только одно действие. Пакет “Action” содержит имя запрашиваемой операции, а также все требуемые параметры команды.
Response: Пакет содержащий ответ, отправленный сервером Asterisk, на последнюю команду, которую клиент отправил серверу.
Event: Пакет с данными относящимися к какому-либо событию сгенерированному сервером Asterisk или его загруженными модулями.

В основном, клиенты отправляют “Action” пакеты Asterisk серверу, Asterisk сервер производит требуемые операции и возвращает результат (часто это только сообщение об успехе или ошибке) в “Response” пакете. Так как нет никакой гарантии, относительно того, что ответы на команды будут приходить в той же последовательности, что и поступающие запросы, клиентские приложения включают в пакет параметр “ActionID” в каждый “Action” пакет запроса. Этот параметр сервер Asterisk вернет без изменений в ответном “Response” пакете. Таким образом, клиентское приложение может просто сопоставить каждому пакету типа “Action” соответствующий ответ “Response”, в том случае, если требуется отсылать несколько запросов сразу, не дожидаясь пока на каждый из отправленных запросов придет соответствующий “Response”ответ.

Пакеты типа “Event”используются в двух разных контекстах: С одной стороны они сообщают клиентам о изменениях различных состояний и событиях в Asterisk (например, создание нового канала или окончание сеанса связи по нему, вход агента в систему и его выход и т.д.) , с другой стороны, они используются для доставки результатов выполнения команд, которые запрашивают данные в виде списка (Запросы, генерирующие события). Когда клиент отправляет запрос, по которому в качестве ответа генерируются ответы в виде “Event” пакетов, тогда Asterisk отправляет ответный пакет, с признаком успешного выполнения команды и содержащий строку: "Response: Follows". После этого asterisk может или вообще не отправить или отправить один или несколько “Event” пакетов, которые, собственно, и содержат запрашиваемую информацию, плюс финальный “Event” пакет, содержащий событие окончания данных, означающий, что все данные были отправлены. Все эти “Event” пакеты, отправляемые в ответ на “Action” запрос, содержат один и тот же ActionID, его значение совпадает с тем, что указанно в этом поле “Action” запроса, который вызвал их генерацию. Таким образом, Вы можете сопоставить все эти “Event”, как часть ответа на свой запрос, который их вызвал. Как пример запроса, в ответ на который вы получите в ответ “Event” пакеты, является запрос “Action: Status”, который вызовет генерацию “Event” пакетов, содержащих статус всех активных каналов. Когда статусы всех каналов будут переданы, будет передан финальный “Event” пакет содержащий значение StatusComplete.

Открытие manager API сессии и авторизация пользователя.

Для доступа к функционалу Asterisk Manager API пользователю необходимо установить TCP/IP соединение на порт, который используется для работы Manager API в asterisk (обычно 5038) и авторизироваться в Интерфейсе управления сервером Asterisk, используя запрос с командой 'Login'. Для этого, сначала необходимо создать учетную запись пользователя на сервере Asterisk. Учетные записи пользователей для доступа к Manager API описываются в файле конфигурации /etc/asterisk/manager.conf. Учетная запись пользователя содержит адреса IP сетей, с которых разрешено подключение, пароль для авторизации и список прав доступа пользователя.

Существует ограниченный набор прав доступа пользователя, каждое из которых может предоставить права на чтение - "read", запись - "write", или на то и другое действие. Если клиент имеет право на чтение указанного класса объектов, то Asterisk будет отправлять ему события, порождаемые этим классом. Если клиент имеет право на запись для какого-либо класса объектов, то он может отправлять команды управления, касающиеся указанного класса.

Для регистрации в manager API, подключившийся клиент должен пройти авторизацию, Вы должны отправить “Action” запрос с типом запроса: "Login" и указав имя пользователя и пароль в качестве параметров. Пример:

Action: login
Username: admin
Secret: god

Если Вы не хотите получать события, которые генерирует сервер Asterisk, Вы можете включить в запрос строку с параметром "Events: off", это выключит отправку ”Event” пакетов в данное соединение. Что эквивалентно запросу с типом запроса "Events", который выключает отправку событий в текущее соединение. Пример:

Action: login
Username: admin
Secret: god
Events: off

Пакеты запросов (Action пакеты)

Когда Вы отправляете команду в Asterisk Manager Api, Вам может потребоваться указать дополнительные параметры, которые необходимы для выполнения команды. Например, это может быть номер телефона, по которому нужно произвести вызов или название канала, который необходимо разъединить и т.д.. Кроме того, если Ваш запрос заставляет сервер Asterisk выполнить команды в какой-либо точке плана набора, Вы можете передать значения переменных канала, которые будут доступны в плане набора (Стало доступно с принятием патча bug 1268). Передача переменных осуществляется таким же образом, как и передача параметров в пакете.

Для отправки команды в Asterisk, используется вот такой простой формат:

Action: <тип запроса><CRLF>
<Key 1>: <Value 1><CRLF>
<Key 2>: <Value 2><CRLF>
...
Variable: <Имя переменной 1>=<Значение переменной 1><CRLF>
Variable: < Имя переменной 2>=< Значение переменной 2><CRLF>
...
<CRLF>

Типы запросов, которые можно осуществлять через Manager API.

Список команд Вы можете получить, выполнив CLI команду: show manager commands:
(В Asterisk версии 1.4 и выше, используйте: manager show commands)

AbsoluteTimeout: Установка абсолютно максимального времени для вызова. ( необходимые привилегии: call,all)
AgentCallbackLogin: Установка статуса агента как зарегистрированного. ( необходимые привилегии: agent,all)
AgentLogoff: Установка статуса агента как _не_ зарегистрированного. (необходимые привилегии: agent,all)
Agents: Список агентов и их статусы. (необходимые привилегии: agent,all)
ChangeMonitor: Изменение имени файла для записи вызова для канала. (необходимые привилегии: call,all)
Command: Выполнение команды. ( необходимые привилегии: command,all)
DAHDIDialOffHook: Набор номера через DAHDI канал, при поднятой трубке.
DAHDIDNDoff: Установка “Do Not Disturb” статуса в OFF. (DAHDI канал)
DAHDIDNDon: Установка “Do Not Disturb” статуса в ON. (DAHDI канал)
DAHDIHangup: Завершение вызова по каналу DAHDI. .
DAHDIRestart: Полный рестарт DAHDI канала (завершение вызова),
DAHDIShowChannel Получение статусов DAHDI каналов.
DAHDITransfer: Перевод вызова (DAHDI канал).
DBGet: Получение значений из astDB. (необходимые привилегии: system,all)
DBPut: Вставка данных в astDB. (необходимые привилегии: system,all)
Events: Управление Manager API событиями поступающими в соединение.
ExtensionState: Проверка состояние екстеншена. ( необходимые привилегии: call,all)
GetVar: Получение значения переменной канала. ( необходимые привилегии: call,all)
Hangup: Завершение соединение на заданном канале. (необходимые привилегии: call,all)
IAXpeers: Список IAX пиров. ( необходимые привилегии: system,all)
ListCommands: Получение списка доступных команд для Manager API.
Logoff: Выход из Manager API.
MailboxCount: Получение числа сообщений в голосовом ящике.( необходимые привилегии: call,all)
MailboxStatus: Получение состояния голосового ящика. ( необходимые привилегии: call,all)
Monitor: Запись разговора на заданном канале. ( необходимые привилегии: call,all)
Originate: Совершение исходящего вызова. ( необходимые привилегии: call,all)
ParkedCalls: Список запаркованных вызовов.
Ping: В ответ получим “Pong”
QueueAdd: Добавление интерфейса в очередь вызовов. ( необходимые привилегии: agent,all)
QueuePause: Отмечает или снимает отметку временной недоступности участника, обрабатывающего очередь вызовов.. (необходимые привилегии: agent,all)
QueueRemove: Удаление интерфейса из очереди вызовов.( необходимые привилегии: agent,all)
Queues: Список очередей вызовов.
QueueStatus: Статус очереди вызова.
Redirect: Перенаправление вызова. ( необходимые привилегии: call,all)
SetCDRUserField: Установка поля UserField в CDR. ( необходимые привилегии: call,all)
SetVar: Установка переменной канала или глобальной переменной. ( необходимые привилегии: call,all)
SIPpeers: Список SIP пиров. (текстовый формат). ( необходимые привилегии: system,all)
SIPshowPeer: Получение данных SIP пира (текстовый формат). ( необходимые привилегии: system,all)
Status: Получение состояний активных каналов. ( необходимые привилегии: call,all)
StopMonitor: Останов записи разговора на заданном канале. ( необходимые привилегии: call,all)

Появилось в Asterisk 1.4.0

GetConfig: Получение заданного файла конфигурации. ( необходимые привилегии: config,all)
MeetmeMute: Выключение микрофона у участника конференции Meetme. ( необходимые привилегии: call,all)
MeetmeUnmute: Включение микрофона у участника конференции Meetme. ( необходимые привилегии: call,all)
Park: Парковка вызова. ( необходимые привилегии: call,all)
PauseMonitor: Временная приостановка записи вызова. ( необходимые привилегии: call,all)
PlayDTMF: Генерация DTMF сигнала на заданном канале. ( необходимые привилегии: call,all)
UpdateConfig: Перезапись файла конфигурации. (необходимые привилегии: config,all)
UnpauseMonitor: Возобновление остановленной записи вызова. ( необходимые привилегии: call,all)
UserEvent: Отправка пользовательского события в AMI (необходимые привилегии: user,all)
WaitEvent: Ожидание определенного события.

События Asterisk Manager API (Events)

Список находиться на отдельной странице: Asterisk AMI Events.

Ссылки по теме

AJAM Доступ к Manager API по http/https протоколу.
manager.conf Файл конфигурации Manager API: manager.conf.
Asterisk cmd UserEvent: Отправка пользовательского события в manager API.
Asterisk-java
Asterisk