Wiki документация

Эта страница только для чтения. Вы можете посмотреть её исходный текст, но не можете его изменить. Сообщите администратору, если считаете, что это неправильно.
====== Интерфейс управления сервером 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" и указав имя пользователя и пароль в качестве параметров. Пример:

<code>Action: login
Username: admin
Secret: god</code>


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

<code>Action: login
Username: admin
Secret: god
Events: off</code>



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

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

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

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

===== Список команд AMI интерфейса =====
==== Стандартные команды ====

  * [[kb:asterisk:ami:AbsoluteTimeout|AbsoluteTimeout]]: Установка абсолютно максимального времени для вызова. 
  * [[kb:asterisk:ami:AgentLogoff|AgentLogoff]]: Установка статуса агента как _не_ зарегистрированного. 
  * [[kb:asterisk:ami:Agents|Agents]]: Список агентов и их статусы. 
  * [[kb:asterisk:ami:AGI|AGI]]: Добавление AGI команды в очередь выполнения как Async AGI.
  * [[kb:asterisk:ami:AOCMessage|AOCMessage]]: Генерация предложения об оплате в канал.
  * [[kb:asterisk:ami:atxfer|Atxfer]]: Консультационный перевод. 
  * [[kb:asterisk:ami:Bridge|Bridge]]: Соединение двух существующих каналов. 
  * [[kb:asterisk:ami:Challenge|Challenge]]: Генерация хеша для MD5 аутентификации.
  * [[kb:asterisk:ami:ChangeMonitor|ChangeMonitor]]: Изменение имени файла для записи вызова для канала. 
  * [[kb:asterisk:ami:Command|Command]]: Выполнение команды. 
  * [[kb:asterisk:ami:ConfbridgeKick|ConfbridgeKick]]: Дропнуть пользователя конференции.
  * [[kb:asterisk:ami:ConfbridgeList|ConfbridgeList]]: Список участников конференции.
  * [[kb:asterisk:ami:ConfbridgeListRooms|ConfbridgeListRooms]]: Списки данных обо всех активных конференций.
  * [[kb:asterisk:ami:ConfbridgeLock|ConfbridgeLock]]: Блокировка количества участников конференции. 
  * [[kb:asterisk:ami:ConfbridgeMute|ConfbridgeMute]]: Выключить микрофон участника конференции. 
  * [[kb:asterisk:ami:ConfbridgeSetSingleVideoSrc|ConfbridgeSetSingleVideoSrc]]: Сделать видео участника конференции единственным видео источником для всей конференции.
  * [[kb:asterisk:ami:ConfbridgeStartRecord|ConfbridgeStartRecord]]: Начать запись конференции. Если файл записи уже создан, будет возвращена ошибка, иначе файл записи будет создан в monitor директории. 
  * [[kb:asterisk:ami:ConfbridgeStopRecord|ConfbridgeStopRecord]]: Прекратить запись конференции. 
  * [[kb:asterisk:ami:ConfbridgeUnlock|ConfbridgeUnlock]]: Разблокировать конференцию и разрешить присоединение новых пользователей. 
  * [[kb:asterisk:ami:ConfbridgeUnmute|ConfbridgeUnmute]]: Включить микрофон участника конференции. 
  * [[kb:asterisk:ami:CoreSettings|CoreSettings]]: Отобразить параметры PBX, версию ядра и т.д.
  * [[kb:asterisk:ami:CoreShowChannels|CoreShowChannels]]: Отобразить список активных каналов.
  * [[kb:asterisk:ami:CoreStatus|CoreStatus]]: Отобразить состояние переменных ядра PBX
  * [[kb:asterisk:ami:CreateConfig|CreateConfig]]: Создание пустого конфигурационного файла.
  * [[kb:asterisk:ami:DAHDIDialOffHook|DAHDIDialOffHook]]: Набор номера через DAHDI канал, при поднятой трубке.
  * [[kb:asterisk:ami:DAHDIDNDoff|DAHDIDNDoff]]: Установка “Do Not Disturb” статуса в OFF. (DAHDI канал)
  * [[kb:asterisk:ami:DAHDIDNDon|DAHDIDNDon]]: Установка “Do Not Disturb” статуса в ON. (DAHDI канал)
  * [[kb:asterisk:ami:DAHDIHangup|DAHDIHangup]]: Завершение вызова по каналу DAHDI. .
  * [[kb:asterisk:ami:DAHDIRestart|DAHDIRestart]]: Полный рестарт DAHDI канала (завершение вызова),
  * [[kb:asterisk:ami:DAHDIShowChannel |DAHDIShowChannel ]]: Получение статусов DAHDI каналов.
  * [[kb:asterisk:ami:DAHDITransfer|DAHDITransfer]]: Перевод вызова (DAHDI канал).
  * [[kb:asterisk:ami:DataGet|DataGet]]
  * [[kb:asterisk:ami:DBDel|DBDel]]: Удаление значений из astDB.
  * [[kb:asterisk:ami:DBDelTree|DBDelTree]]: Удаление дерева значений из astDB.
  * [[kb:asterisk:ami:DBGet|DBGet]]: Получение значений из astDB.
  * [[kb:asterisk:ami:DBPut|DBPut]]: Вставка данных в astDB.
  * [[kb:asterisk:ami:Events|Events]]: Управление Manager API событиями поступающими в соединение.
  * [[kb:asterisk:ami:ExtensionState|ExtensionState]]: Проверка состояние екстеншена.
  * [[kb:asterisk:ami:Filter|Filter]]
  * [[kb:asterisk:ami:FilterList|FilterList]]: Показать текущие фильтры событий для этой сессии.
  * [[kb:asterisk:ami:GetConfig|GetConfig]]: Получение заданного файла конфигурации.
  * [[kb:asterisk:ami:GetConfigJSON|GetConfigJSON]]: Получение заданного файла конфигурации в формате JSON.
  * [[kb:asterisk:ami:GetVar|GetVar]]: Получение значения переменной канала.
  * [[kb:asterisk:ami:Hangup|Hangup]]: Завершение соединение на заданном канале.
  * [[kb:asterisk:ami:IAXnetstats|IAXnetstats]]: Отобразить сетевую статистику IAX.
  * [[kb:asterisk:ami:IAXpeerlist|IAXpeerlist]]: Список IAX пиров.
  * [[kb:asterisk:ami:IAXpeers|IAXpeers]]: Список IAX пиров.
  * [[kb:asterisk:ami:IAXregistry|IAXregistry]]: Отобразить зарегистрированных IAX пиров.
  * [[kb:asterisk:ami:JabberSend|JabberSend]]: Команда посылает сообщение Jabber клиенту.
  * [[kb:asterisk:ami:ListCategories|ListCategories]]: Получения списка категорий конфигурационного файла.
  * [[kb:asterisk:ami:ListCommands|ListCommands]]: Получение списка доступных команд для Manager API.
  * [[kb:asterisk:ami:LocalOptimizeAway|LocalOptimizeAway]]: Оптимизировать выход локального канала, когда это возможно.
  * [[kb:asterisk:ami:Login|Login]]: Начало сеанса Asterisk Manager API.
  * [[kb:asterisk:ami:Logoff|Logoff]]: Выход из Manager API.
  * [[kb:asterisk:ami:MailboxCount|MailboxCount]]: Получение числа сообщений в голосовом ящике.
  * [[kb:asterisk:ami:MailboxStatus|MailboxStatus]]: Получение состояния голосового ящика. 
  * [[kb:asterisk:ami:MeetmeList|MeetmeList]]: Список участников конференции.
  * [[kb:asterisk:ami:MeetmeListRooms|MeetmeListRooms]] Список комнат конференций.
  * [[kb:asterisk:ami:MeetmeMute|MeetmeMute]]: Выключение микрофона у участника конференции Meetme.
  * [[kb:asterisk:ami:MeetmeUnmute|MeetmeUnmute]]: Включение микрофона у участника конференции Meetme.
  * [[kb:asterisk:ami:MessageSend|MessageSend]]: Send an out of call message to an endpoint.
  * [[kb:asterisk:ami:MixMonitor|MixMonitor]]: Record a call and mix the audio during the recording. Use of StopMixMonitor is required to guarantee the audio file is available for processing during dialplan execution.
  * [[kb:asterisk:ami:MixMonitorMute|MixMonitorMute]] : Mute / unMute a Mixmonitor recording.
  * [[kb:asterisk:ami:ModuleCheck|ModuleCheck]]: Проверка загружен ли указанный модуль.
  * [[kb:asterisk:ami:ModuleLoad|ModuleLoad]]: Управление модулями Asterisk.
  * [[kb:asterisk:ami:Monitor|Monitor]]: Запись разговора на заданном канале.
  * [[kb:asterisk:ami:MuteAudio|MuteAudio]]: Mute an audio stream.
  * [[kb:asterisk:ami:Originate|Originate]]: Совершение исходящего вызова.
  * [[kb:asterisk:ami:Park|Park]]: Парковка вызова.
  * [[kb:asterisk:ami:ParkedCalls|ParkedCalls]]: Список запаркованных вызовов.
  * [[kb:asterisk:ami:Parkinglots|Parkinglots]]: Get a list of parking lots.
  * [[kb:asterisk:ami:PauseMonitor|PauseMonitor]]: Временная приостановка записи вызова.
  * [[kb:asterisk:ami:ping|Ping]]: В ответ получим “Pong”.
  * [[kb:asterisk:ami:PlayDTMF|PlayDTMF]]: Генерация DTMF сигнала на заданном канале.
  * [[kb:asterisk:ami:PresenceState|PresenceState]]: Check Presence State
  * [[kb:asterisk:ami:PRIShowSpans|PRIShowSpans]]: Функция, аналогичная команде CLI "pri show spans".
  * [[kb:asterisk:ami:QueueAdd|QueueAdd]]: Добавление интерфейса в очередь вызовов. 
  * [[kb:asterisk:ami:QueueLog|QueueLog]]: Добавить произвольную запись в queue_log.
  * [[kb:asterisk:ami:QueueMemberRingInUse|QueueMemberRingInUse]] Set the ringinuse value for a queue member.
  * [[kb:asterisk:ami:QueuePause|QueuePause]]: Отмечает или снимает отметку временной недоступности участника, обрабатывающего очередь вызовов. 
  * [[kb:asterisk:ami:QueuePenalty|QueuePenalty]]: Установка пенальти для участника, обрабатывающего очередь вызовов.
  * [[kb:asterisk:ami:QueueReload|QueueReload]]: Перезагрузка очереди, очередей или любой подгруппы очереди или очередей вызова.
  * [[kb:asterisk:ami:QueueRemove|QueueRemove]]: Удаление интерфейса из очереди вызовов.
  * [[kb:asterisk:ami:QueueReset|QueueReset]]: Сброс статистики очереди вызовов.
  * [[kb:asterisk:ami:QueueRule|QueueRule]]: Правила очереди вызовов.
  * [[kb:asterisk:ami:Queues|Queues]]: Список очередей вызовов.
  * [[kb:asterisk:ami:QueueStatus|QueueStatus]]: Статус очереди вызова.
  * [[kb:asterisk:ami:QueueSummary|QueueSummary]]: Основная информация очереди вызова.
  * [[kb:asterisk:ami:Redirect|Redirect]]: Перенаправление вызова. 
  * [[kb:asterisk:ami:Reload|Reload]]: Отправить команду на перезагрузку указанного модуля Asterisk.
  * [[kb:asterisk:ami:SendText|SendText]]: Отправить текстовое сообщение в канал.
  * [[kb:asterisk:ami:SetVar|SetVar]]: Установка переменной канала или глобальной переменной. 
  * [[kb:asterisk:ami:ShowDialPlan|ShowDialPlan]]: Отобразить диалплан или все диалпланы.
  * [[kb:asterisk:ami:SIPnotify|SIPnotify]]: Отправить уведомление в SIP канал.
  * [[kb:asterisk:ami:SIPpeers|SIPpeers]]: Список SIP пиров. (текстовый формат). 
  * [[kb:asterisk:ami:SIPqualifypeer|SIPqualifypeer]]: Показать состояние SIP пира(текстовый формат).
  * [[kb:asterisk:ami:SIPshowPeer|SIPshowPeer]]: Получение данных SIP пира (текстовый формат). 
  * [[kb:asterisk:ami:SIPshowregistry|SIPshowregistry]]: Отобразить зарегистрированных SIP пиров (текстовый формат).
  * [[kb:asterisk:ami:SKINNYdevices|SKINNYdevices]]: Списки Skinny устройств в текстовом формате c подробной информацией о текущем состоянии.
  * [[kb:asterisk:ami:SKINNYlines|SKINNYlines]]: Списки Skinny линий в текстовом формате с подробной информацией о текущем состоянии. 
  * [[kb:asterisk:ami:SKINNYshowdevice|SKINNYshowdevice]]: Отображает одно Skinny устройство c подробной информацией о текущем состоянии.
  * [[kb:asterisk:ami:SKINNYshowline|SKINNYshowline]]: Отображает все Skinny устройства c подробной информацией о текущем состоянии.
  * [[kb:asterisk:ami:Status|Status]]: Получение состояний активных каналов.
  * [[kb:asterisk:ami:StopMixMonitor|StopMixMonitor]] Stop recording a call through MixMonitor, and free the recording's file handle.
  * [[kb:asterisk:ami:StopMonitor|StopMonitor]]: Останов записи разговора на заданном канале.
  * [[kb:asterisk:ami:UnpauseMonitor|UnpauseMonitor]]: Возобновление остановленной записи вызова.
  * [[kb:asterisk:ami:UpdateConfig|UpdateConfig]]: Перезапись файла конфигурации.
  * [[kb:asterisk:ami:UserEvent|UserEvent]]: Отправка пользовательского события в AMI.
  * [[kb:asterisk:ami:VoicemailUsersList|VoicemailUsersList]]: Команда отображает список всех пользователей голосовой почты.
  * [[kb:asterisk:ami:WaitEvent|WaitEvent]]: Ожидание определенного события.


==== Нестандартные команды ====

  * [[kb:asterisk:ami:SetCDRUserField|SetCDRUserField]]: Установка поля UserField в CDR. ( необходимые привилегии: call,all)
  * [[kb:asterisk:ami:FaxLicenseList|FaxLicenseList]]
  * [[kb:asterisk:ami:FaxLicenseStatus|FaxLicenseStatus]]
  * [[kb:asterisk:ami:G729LicenseList|G729LicenseList]]
  * [[kb:asterisk:ami:G729LicenseStatus|G729LicenseStatus]]
  * [[kb:asterisk:ami:SkypeAccountProperty|SkypeAccountProperty]]
  * [[kb:asterisk:ami:SkypeAddBuddy|SkypeAddBuddy]]
  * [[kb:asterisk:ami:SkypeBuddies|SkypeBuddies]]
  * [[kb:asterisk:ami:SkypeBuddy|SkypeBuddy]]
  * [[kb:asterisk:ami:SkypeChatSend|SkypeChatSend]]
  * [[kb:asterisk:ami:SkypeLicenseList|SkypeLicenseList]]
  * [[kb:asterisk:ami:SkypeLicenseStatus|SkypeLicenseStatus]]
  * [[kb:asterisk:ami:SkypeRemoveBuddy|SkypeRemoveBuddy]]
  
  * [[kb:asterisk:ami:template|Шаблон описания команды]]


 ===== Полезные ссылки =====
  * [[http://wiki.askozia.ru/handbook:ami|Инструкция для подключения к AMI АТС]]
  * Описание протокола Asterisk Manager Interface (AMI) на русском [[http://asterisk.ru/knowledgebase/Asterisk+Manager+API]]
  * Описание протокола Asterisk Manager Interface (AMI) на английском (полное)[[http://www.voip-info.org/wiki/view/Asterisk+manager+API]]
  * Настройка AJAM интерфейса [[http://www.the-asterisk-book.com/unstable/manager-interface-ajam.html#manager-interface-beispiel-ajam]]
  * [[http://www.asterisk.org/asterisknow/developers/gui-guide]]
Внимание! Эта wiki об устаревших версиях Документация к актуальной версии интеграции 1С и телефонии доступна по ссылке

Wiki документация

Инструменты пользователя

Инструменты сайта

Инструменты страницы

Внимание!
Эта wiki об устаревших версиях
Документация к актуальной версии интеграции 1С и телефонии доступна по ссылке
