Интерфейс приложений AMI¶

AMI — мощный и удобный программный интерфейс (API) Asterisk для управления системой из внешних программ.
Благодаря AMI внешние программы могут осуществлять соединения с Астериском посредством TCP протокола, инициировать выполнение команд, считывать результат их выполнения, а так же получать уведомления о происходящих событиях в реальном времени.
Этими механизмами можно пользоваться, например в следующих случаях:

Необходимо узнать состояние системы
Количество активных абонентов
Выполнять команды CLI удаленно
Инициировать звонки
итп

AMI часто используют для интеграции с бизнес-процессами и системами, программным обеспечением CRM (Customer Relationship Managment — управление взаимодействия с клиентами).
Он также может применяться для разнообразных приложений, таких как программы автоматического набора номера и системы click-to-call (звонок-по-щелчку).

Управление Астериском часто осуществляется из консоли CLI, но при использовании AMI не требуется прямой доступ к серверу, на котором запущен Астериск.
AMI — это наиболее простой инструмент, который в руках разработчика может оказаться очень мощным и гибким средством для интеграции с другими программными продуктами.
Он дает возможность разработчикам использовать информацию, генерируемую Астериском, в реальном масштабе времени.

Как работает AMI¶

Между сервером Smartswitch и клиентской программой для установления связи используется простой по-строчный протокол, каждая строка сообщения которого состоит из двух строк:

key - ключевое слово, описывающее характер информации, содержащейся в текущей строке. Ключевое слово не является уникальным и может встречаться несколько раз в рамках одной посылки
value - значение параметра

Ключевое слово от значения отделяется двоеточием
Далее мы будем использовать термин «пакет», что будет описывать серию конструкций «key:value», разделенных CRLF и завершеных дополнительной последовательностью CRLF.

Протокол взаимодействия между Астериском и клиентом можно описать следующими характеристиками:

Перед тем как посылать команды в сервер Астериск, необходимо выполнить сессию соединения клиента с сервером Астериск;
Пакеты могут быть переданы в любой последовательности и в любое время после прохождения процедуры аутентификации;
Первая строка пакета должна содержать один из следующих ключей: «Action» (единственный вариант при отправки клиентом), и ключи «Event» (Событие) и «Response» (Ответ) (должны быть отправлены от Астериска к клиенту);
Порядок строк в пакете не имеет значения, вы можете использовать любой язык программирования, которым можно формировать пакеты на стороне клиента;
CRLF используется для разделения каждой из строк в пакете и двух последовательностей CRLF (она же \r\n) для того, чтобы обозначить завершение передачи команды в Астериск

AMI принимает подключения, устанавливаемые на сетевой порт (по умолчанию -- TCP порт 5038). Клиентская программа подключается к AMI через этот порт и аутентифицируется, после этого Астериск будет отвечать на запросы, а также отправлять извещения о изменениях состояния заданных подсистем.

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

Типы пакетов

Пакет, передаваемый от клиента в Астериск сервер и назад определяется следующими ключевыми характеристиками:

Action, пакеты отправляемые клиентом, соединенным с AMI. После обработки сервером такого пакета будет осуществлено некоторое действие. Существуют относительно гибкие ограничения на действия, осуществляемые клиентом. Один пакет - одно действие. В пакете Action должно содержаться имя операции, которую необходимо выполнить, а также все необходимые параметры;
Response, определяет ответ, отсылаемый Астериском клиенту по факту выполнения действия;
Event, данные, относящиеся к событию, которое сгенерировано внутри ядра Астериска или модуля расширения.

Как правило, клиент отсылает пакеты Action в Астериск (они так же называются коммандами). Астериск, в свою очередь, выполняет запрос и возвращает результат (часто результат - успешность действия с кратким описанием в случае неудачи), получаемое в пакете Response. Нет гарантии касательно порядка прихода результатов (пакетов Response), поэтому в клиентском запросе обычно включают параметр ActionID в каждый пакет Action, при этом соответствующий пакет Response будет содержать такое же значение в поле ActionID. Таким образом, клиент может очень легко обрабатывать Action и Response пакеты, в любом желаемом порядке, не ожидая пакетов Response, чтобы произвести следующее действие.

Следующая команда CLI (работает автодополнение Tab'ом) поможет получить полный списко команд AMI, доступных в вашей версии Астериска:

*CLI> manager show commands

Пакеты Response. Как написано выше, служат ответами на переданные команды. Передается один ответ на команду и может нести несколько значений:

"Success" - действие успешно и вся информация содержится в данном пакете
"Error" - произошла ошибка, подробное описание в заголовке "Message"
"Follows" - результат выполнения будет передан в последующих Event пакетах

Event пакеты (события) применяются в двух контекстах. С одной стороны -- они информируют клиента об изменении состояния подсистем Астериска (пр. изменения состояния канала), с другой стороны -- они переносят набор данных, который возвращает Астериск в ответ на действие Action.

Когда клиент отсылает пакет Action, Астериск может (в случаях если требуется вернуть много однородных записей) отправить Response пакет, содержащий толко запись «Response: Follows». Далее Астериск отсылает некоторое количество событий, содержащих набор данных и, наконец, событие, которое сообщает, что все данные были отправлены. Все генерируемые при этом пакеты Event содержат ActionID первоначального пакета Action, который инициировал запрос. Таким образом, можно легко обрабатывать их, как и пакеты Response. Пример события, генерируемого Action'ом — это Action Status, который инициирует событие Status для каждого из активных каналов. После передачи всех событий Status, отправляется событие StatusComplete.

События создаются различными структурными частями Астериска (каналы SIP/IAX2/..., CDR, диалплан, различные части ядра). Основная задача, которая возложена на события, позволить внешней присоединенной системе получить информацию от Астериска, собирая эти все события, анализируя их и выполняя действия в зависимости от полученных результатов.

Подключение к интерфейсу AMI¶

Для подключения к AMI, можно использовать программу telnet. Так выглядит приветствие системы:

$ telnet 127.0.0.1 5038
Trying 127.0.0.1...
Connected to localhost. 

Escape character is '^]'. Asterisk Call Manager/1.1

Далее набираем:

Action: login
Username: admin
Secret: passwd1234

два раза Enter, что равносильно вводу CRLF
После, должны увидеть такой ответ (пакет Response):

Response: Success
Message: Authentication accepted

Увидеть всех пользователей, соединенных в данный момент с интерфейсом AMI, можно из консоли Астериска:

*CLI> manager show connected

Замена пароля и выполнение команды 'manager reload' никак не влияют на права для уже установленных сессий AMI.

Если Вам не нужны события, генерируемые Астериском (их может быть очень много, что затруднить чтение в консоли ответов Астериска), то в параметры, передаваемые во время процедура аутентификации, можно включить еще запись

Events: off

Эта запись предотвратит посылку пакетов Event со стороны сервера в рамках установленного соединения

Чтобы завершить сессию подключения к AMI, необходимо выполнить:

Action: logoff

После чего мы увидим на экране telnet сессии:

Response: Goodbye
Message: Thanks for all the fish.

Во время завершения AMI сессии, в консоли Астериска мы можем увидеть следующее:

asterisk*CLI> == Manager 'admin' logged off from 127.0.0.1

Примечание.
Естественно, AMI интерфейс не предназначен для того, чтобы вручную администратор с помощью клиента telnet и ему подобных, осуществлял соединение с сервером Астериск.
Здесь этот пример показан исключительно как демонстрация возможностей и наглядности работы обмена пакетами Action, Event и Response.
Однако такой подход может пригодиться при обучении и отладке действия той или иной команды.

Примечание Увидеть все команды, относящиеся к CLI интерфейсу управления Астериска AMI, можно набрав в консоли:

asterisk *CLI> help manager

См. также:

English translation