Интерфейс управления сервером Asterisk (Asterisk Manager API)
Интерфейс управления сервером 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, используется вот такой простой формат:
