Интерфейс управления Asterisk (AMI)

Джон Малкович: Я видел мир, который

НЕ должен видеть человек!

Крейг Шварц: Правда? Потому что для большинства людей

это довольно приятный опыт.

— Будучи Джоном Малковичем

Asterisk Manager Interface (AMI) — это интерфейс системного мониторинга и управления системой, предоставляемый Asterisk. Он позволяет осуществлять живой мониторинг событий, происходящих в системе, а также разрешать запросам к Asterisk выполнять некоторые действия. Доступные действия широко распространены и включают такие вещи, как возврат информации о статусе и появлении новых вызовов. Многие интересные приложения были разработаны поверх Asterisk и используют AMI в качестве основного интерфейса для Asterisk.

Эта глава также включает документацию по использованию файлов вызовов. Файлы вызовов Asterisk — это простой способ инициировать несколько вызовов. Как только объем вызовов увеличивается или ваши потребности становятся более серьезными, вы можете перейти к использованию AMI. Подробности можно найти в разделе “Файлы вызовов”.

Быстрый старт

Этот раздел предназначен для того, чтобы испачкать руки с помощью AMI как можно быстрее. Сначала поместите следующую конфигурацию в /etc/asterisk/manager.conf:

;

; Включите AMI и попросите его принимать соединения только с localhost.

;

[general]

enabled = yes

webenabled = yes

bindaddr = 127.0.0.1

;

; Создайте учетную запись «hello» с паролем «world»

;

[hello]

secret = world

read = all ; Получать все типы событий

write = all ; Разрешить этому пользователю выполнять все действия.

Эта типовая конфигурация настроена так, чтобы разрешать только локальные подключения к AMI. Если вы намерены сделать этот интерфейс доступным по сети, настоятельно рекомендуется использовать его только с помощью TLS. Использование TLS обсуждается более подробно далее в этой главе.

После тогоконфигурирования AMI готова, включите встроенный сервер HTTP, поместив следующее содержимое в /etc/asterisk/http.conf:

;

; Включить встроенный HTTP-сервер и слушать только соединения на localhost.

;

[general]

enabled = yes

bindaddr = 127.0.0.1

AMI через TCP

Существует несколько способов подключения к AMI, но наиболее распространенным является TCP-сокет. Мы будем использовать telnet для демонстрации подключения AMI. В этом примере показаны следующие шаги:

• Подключитесь к AMI через сокет TCP на порт 5038.
• Войдите в систему, используя действие Login.
• Выполните действие Ping.
• Выйдите из системы, используя действие Logoff.

Вот как AMI отвечает на эти действия:

$ telnet localhost 5038

Trying 127.0.0.1…

Connected to localhost.

Escape character is ‘^]’.

Asterisk Call Manager/1.1

Action: Login

Username: hello

Secret: world

Response: Success

Message: Authentication accepted

Action: Ping

Response: Success

Ping: Pong

Timestamp: 1282739190.454046

Action: Logoff

Response: Goodbye

Message: Thanks for all the fish.

Connection closed by foreign host.

После того, как вы это сделаете, вы убедитесь, что AMI принимает соединения через TCP-соединение.

AMI через HTTP

Также возможно использовать AMI по HTTP. В этом разделе мы будем выполнять те же действия, что и раньше, но через HTTP вместо собственного TCP интерфейса к AMI. AMI по HTTP раскрыт более подробно в “AMI через HTTP”.

Учетные записи, используемые для подключения к AMI через HTTP — это те же учетные записи, которые настроены в файле /etc/asterisk/manager.conf.

В этом примере показано как получить доступ к AMI через HTTP, войти в систему, выполнить действие Ping и выйти из системы:

$ wget «http://localhost:8088/rawman?action=login&username=hello&secret=world» \

> —save-cookies cookies.txt -O —

—2010-08-31 12:34:23—

Resolving localhost… 127.0.0.1

Connecting to localhost|127.0.0.1|:8088… connected.

HTTP request sent, awaiting response… 200 OK

Length: 55

Saving to: `STDOUT’

Response: Success

Message: Authentication accepted

2010-08-31 12:34:23 (662 KB/s) — written to stdout [55/55]

$ wget «http://localhost:8088/rawman?action=ping» —load-cookies cookies.txt -O —

—2010-08-31 12:34:23—

Resolving localhost… 127.0.0.1

Connecting to localhost|127.0.0.1|:8088… connected.

HTTP request sent, awaiting response… 200 OK

Length: 63

Saving to: `STDOUT’

Response: Success

Ping: Pong

Timestamp: 1283258063.040293

2010-08-31 12:34:23 (775 KB/s) — written to stdout [63/63]

$ wget «http://localhost:8088/rawman?action=logoff» —load-cookies cookies.txt -O —

—2010-08-31 12:34:23—

Resolving localhost… 127.0.0.1

Connecting to localhost|127.0.0.1|:8088… connected.

HTTP request sent, awaiting response… 200 OK

Length: 56

Saving to: `STDOUT’

Response: Goodbye

Message: Thanks for all the fish.

2010-08-31 12:34:23 (696 KB/s) — written to stdout [56/56]

Интерфейс HTTP для AMI позволяет интегрировать управление вызовами Asterisk в веб-службу.

Конфигурация

Раздел «Быстрый старт» показал очень простой набор конфигурационных файлов, чтобы вы начали. Однако для AMI доступно еще много вариантов.

manager.conf

Основным конфигурационным файлом для AMI является /etc/asterisk/manager.conf. Раздел [general] содержит параметры (перечисленные в Таблице 20-1), которые контролируют общую работу AMI. Любые другие разделы в файле manager.conf будут определять учетные записи для входа в систему и использования AMI.

Таблица 20-1. Опции в разделе manager.conf [general]

^a Чтобы получить доступ к AMI через HTTP, встроенный HTTP-сервер также должен быть настроен в /etc/asterisk/http.conf.

^b Пакет разработки OpenSSL должен быть установлен для того, чтобы Asterisk использовал шифрование. На Ubuntu, пакет libssl-dev. На RHEL пакет называется openssl-devel.

Файл конфигурации manager.conf также содержит конфигурацию учетных записей пользователей AMI. Учетная запись создается путем добавления раздела с именем пользователя в квадратных скобках. В каждом разделе [username] есть опции, которые можно установить и они будут применяться только к этой учетной записи. В Таблице 20-2 перечислены параметры, доступные в разделе [username].

Таблица 20-2. Параметры для разделов [username]

^a Если фильтры не заданы — будут доставлены все события, разрешенные на основе параметра read. Если указаны только фильтры белого списка — будут доставлены только события, соответствующие одному из фильтров. Если есть только фильтры в стиле черного списка, будут доставлены все события, которые не соответствуют ни одному из фильтров. Наконец, если существует сочетание фильтров в стиле белого и черного списка, сначала будут обработаны фильтры белого списка, а затем фильтры черного списка.

Как обсуждалось в Таблице 20-2, параметры read и write задают какие действия и события AMI доступны определенному пользователю. Таблица 20-3 показывает доступные значения разрешений, которые могут быть указаны для этих параметров.

Обратите особое внимание на разрешения system, command и originate. Эти разрешения предоставляют значительные возможности внешнему приложению. Предоставьте эти разрешения только тем приложениям, над которыми у вас есть полный контроль.

Таблица 20-3. Доступные значения для параметров read/write учетной записи пользователя AMI

^a Этот уровень определен, но в настоящее время не используется нигде в Asterisk.

^b Этот уровень определен, но в настоящее время не используется нигде в Asterisk.

^c Действие UserEvent является полезным механизмом для доставки сообщений другим клиентам AMI.

^d События DTMF не будут генерироваться в мостовом вызове между двумя каналами, если не используется универсальное мостовое соединение в ядре Asterisk. Например, если DTMF передается с потоком мультимедиа, а поток мультимедиа течет непосредственно между двумя конечными точками, Asterisk не сможет сообщить о событиях DTMF.

http.conf

Как мы видели, AMI можно получить через HTTP, а также TCP. Для выполнения этой работы в Asterisk встроен очень простой HTTP-сервер. Все параметры, относящиеся к AMI, находятся в разделе [general] файла /etc/asterisk/http.conf.

Для включения доступа к AMI через HTTP требуются оба параметра /etc/asterisk/manager.conf и /etc/asterisk/http.conf. AMI должен быть включен в manager.conf опцией enabled установленной в yes, и manager.conf опция webenabled должна иметь значение yes, чтобы разрешить доступ через HTTP. Наконец, опция enabled в http.conf должна быть установлена в yes для включения самого сервера HTTP.

Доступные параметры перечислены в Таблице 20-4.

Таблица 20-4. Параметры в разделе http.conf [general]

^a Чтобы Asterisk мог использовать шифрование — необходимо установить пакет разработки OpenSSL. Для Ubuntu пакет libssl-dev. На RHEL пакет называется openssl-devel.

Обзор протокола

В AMI есть два основных типа сообщений: диспетчер событий и диспетчер действий.

Диспетчер событий — это односторонние сообщения, отправляемые от Asterisk к клиентам AMI для отчета о происходящем в системе. См. Рисунок 20-1 для графического представления передачи управляющих событий.

Диспетчер действий — это запросы от клиента, у которого есть связанные ответы, приходящие обратно от Asterisk. То есть, действие диспетчера может быть запросом к Asterisk на выполнение какого-либо действия и возврат результата. Например, есть действие AMI для инициирования нового вызова. См. Рисунок 20-2. для графического представления клиента, отправляющего действия диспетчеру и получающего ответы.

Другие действия диспетчера — это запросы данных, о которых знает Asterisk. Например, существует действие диспетчера для получения списка всех активных каналов в системе: сведения о каждом канале доставляются как событие диспетчера. Когда список результатов будет завершен, будет отправлено сообщение о том, что конец достигнут. См. Рисунок 20-3 для графического представления клиента, отправляющего этот тип действия диспетчера и получающего список ответов.

Кодировка сообщений.

Все сообщения AMI, включая события диспетчера, действия и ответы на действия кодируются одинаково. Сообщения основаны на тексте, а строки заканчиваются возвратом каретки и символом перевода строки. Сообщение заканчивается пустой строкой:

Header1: Это первый заголовок<CR><LF>

Header2: Это второй заголовок<CR><LF>

Header3: это последний заголовок этого сообщения<CR><LF>

<CR><LF>

События

События диспетчера всегда имеют заголовок Event и заголовок Privilege. Заголовок Event дает имя события, в то время как заголовок Privilege перечисляет уровни разрешений, связанные с событием. Любые другие заголовки, включенные в событие, зависят от типа события. Вот пример:

Event: Hangup

Privilege: call,all

Channel: SIP/0004F2060EB4-00000000

Uniqueid: 1283174108.0

CallerIDNum: 2565551212

CallerIDName: Russell Bryant

Cause: 16

Cause-txt: Normal Clearing

Asterisk 11 представила команды CLI manager show events и manager show event <event>. Выполните эти команды в CLI Asterisk, чтобы получить список событий или узнать подробности конкретного события.

Обратите внимание, что документация диспетчера событий доступна только из CLI Asterisk, если Asterisk был собран с помощью команды make full, а не просто make.

Действия

При выполнении действия диспетчера он должен включать заголовок Action. Заголовок Action определяет какой диспетчер действий выполняется. Остальные заголовки являются аргументами для действия и могут потребоваться или нет в зависимости от действия.

Чтобы получить список заголовков, связанных с определенным действием диспетчера, введите в командной строке Asterisk команду manager show command <Action>. Чтобы получить полный список действий диспетчера, поддерживаемых используемой версией Asterisk — введите команду manager show commands в CLI Asterisk.

Окончательным ответом на действие диспетчера обычно является сообщение, содержащее заголовок Response. Значение заголовка Response будет иметь значение Success, если действие диспетчера было выполнено успешно. Если действие диспетчера не было выполнено успешно, значением заголовка ответа будет Error. Например:

Action: Login

Username: russell

Secret: russell

Response: Success

Message: Authentication accepted

AMI через HTTP

В дополнение к собственному интерфейсу TCP можно также получить доступ к AMI по протоколу HTTP. Программисты, имеющие опыт написания приложений с использованием веб-API, вероятно, предпочтут родное подключение TCP. Хотя интерфейс TCP предлагает только один тип структуры сообщений, AMI через HTTP предлагает несколько вариантов кодирования. Вы можете получать ответы в том же формате, что и интерфейс TCP — в формате XML или в виде базовой HTML-страницы. Тип кодировки выбирается на основе поля в URL-адресе запроса. Параметры кодирования обсуждаются более подробно далее в этом разделе.

Аутентификация и обработка сеанса

Существует два метода выполнения аутентификации для AMI через HTTP. Во-первых, необходимо использовать действие Login, аналогичное аутентификации с собственным интерфейсом TCP. Этот метод, который использовался в примере быстрого старта, как замечено в «AMI через HTTP«.

После успешной аутентификации Asterisk предоставит файл cookie, который идентифицирует аутентифицированный сеанс. Вот пример ответа на действие Login, который включает cookie сеанса от Asterisk:

$ curl -v «http://localhost:8088/rawman?action=login&username=hello&secret=world»

* About to connect() to localhost port 8088 (#0)

* Trying 127.0.0.1… connected

* Connected to localhost (127.0.0.1) port 8088 (#0)

> GET /rawman?action=login&username=hello&secret=worlda HTTP/1.1

> User-Agent: curl/7.19.7 (x86_64-pc-linux-gnu) libcurl/7.19.7

OpenSSL/0.9.8k zlib/1.2.3.3 libidn/1.15

> Host: localhost:8088

> Accept: */*

>

< HTTP/1.1 200 OK

< Server: Asterisk/SVN-branch-11-r378376

< Date: Tue, 07 Sep 2010 11:51:28 GMT

< Connection: close

< Cache-Control: no-cache, no-store

< Content-Length: 55

< Content-type: text/plain

< Cache-Control: no-cache;

< Set-Cookie: mansession_id=»0e929e60″; Version=1; Max-Age=60

< Pragma: SuppressEvents

<

Response: Success

Message: Authentication accepted

* Closing connection #0

Второй вариант аутентификации — это дайджест аутентификации HTTP. В этом примере запрошенным типом кодировки на основе URL-адреса запроса является rawman. Чтобы указать, что следует использовать дайджест-проверку подлинности HTTP, префикс типа кодировки в URL-адресе запроса с a:

$ curl -v —digest -u hello:world http://127.0.0.1:8088/arawman?action=ping

* About to connect() to 127.0.0.1 port 8088 (#0)

* Trying 127.0.0.1…

* connected

* Connected to 127.0.0.1 (127.0.0.1) port 8088 (#0)

* Server auth using Digest with user ‘hello’

> GET /arawman?action=ping HTTP/1.1

> User-Agent: curl/7.27.0

> Host: 127.0.0.1:8088

> Accept: */*

>

< HTTP/1.1 401 Unauthorized

< Server: Asterisk/SVN-branch-11-r378376

< Date: Thu, 17 Jan 2013 13:19:05 GMT

< Connection: close

< Cache-Control: no-cache, no-store

< Content-Length: 210

< WWW-authenticate: Digest algorithm=MD5, realm=»asterisk», nonce=»55b30b6d»,

< qop=»auth», opaque=»55b30b6d»

< Content-type: text/html

<

* Closing connection #0

* Issue another request to this URL: ‘http://127.0.0.1:8088/arawman?action=ping’

* About to connect() to 127.0.0.1 port 8088 (#0)

* Trying 127.0.0.1…

* connected

* Connected to 127.0.0.1 (127.0.0.1) port 8088 (#0)

* Server auth using Digest with user ‘hello’

> GET /arawman?action=ping HTTP/1.1

> Authorization: Digest username=»hello», realm=»asterisk», nonce=»55b30b6d»,

> uri=»/arawman?action=ping», cnonce=»MTQ0MTQ5″, nc=00000001,

> qop=auth, response=»df8edf75f3571ad425cacb975d09280b»,

> opaque=»55b30b6d», algorithm=»MD5″

> User-Agent: curl/7.27.0

> Host: 127.0.0.1:8088

> Accept: */*

>

< HTTP/1.1 200 OK

< Server: Asterisk/SVN-branch-11-r378376

< Date: Thu, 17 Jan 2013 13:19:05 GMT

< Connection: close

< Cache-Control: no-cache, no-store

< Content-Length: 63

< Content-type: text/plain

<

Response: Success

Ping: Pong

Timestamp: 1358428745.481800

* Closing connection #0

Кодирование /rawman

Тип кодировки rawman — это то, что до сих пор использовалось во всех примерах AMI через HTTP в этой главе. Ответы, полученные от запросов с использованием rawman, форматируются точно так же, как если бы запросы отправлялись через прямое TCP-подключение к AMI.

Кодирование /manager

Тип кодировки manager предоставляет ответ в простой HTML-форме. Этот интерфейс в первую очередь полезен для экспериментов с AMI. Вот пример Login с использованием этого типа кодировки:

$ curl -v «http://localhost:8088/manager?

> «action=login&username=hello&secret=world»

* About to connect() to localhost port 8088 (#0)

* Trying 127.0.0.1… connected

* Connected to localhost (127.0.0.1) port 8088 (#0)

> GET /manager?action=login&username=hello&secret=world HTTP/1.1

> User-Agent: curl/7.19.7 (x86_64-pc-linux-gnu) libcurl/7.19.7

OpenSSL/0.9.8k zlib/1.2.3.3 libidn/1.15

> Host: localhost:8088

> Accept: */*

>

< HTTP/1.1 200 OK

< Server: Asterisk/SVN-branch-11-r378376

< Date: Tue, 07 Sep 2010 12:19:05 GMT

< Connection: close

< Cache-Control: no-cache, no-store

< Content-Length: 881

< Content-type: text/html

< Cache-Control: no-cache;

< Set-Cookie: mansession_id=»139deda7″; Version=1; Max-Age=60

< Pragma: SuppressEvents

<

<title>Asterisk&trade; Manager Interface</title><body bgcolor=»#ffffff»>

<table align=center bgcolor=»#f1f1f1″ width=»500″>

<tr><td colspan=»2″ bgcolor=»#f1f1ff»><h1>Manager Tester</h1></td></tr>

<tr><td colspan=»2″ bgcolor=»#f1f1ff»><form action=»manager» method=»post»>

Action: <select name=»action»>

<option value=»»>——&gt;</option>

<option value=»login»>login</option>

<option value=»command»>Command</option>

<option value=»waitevent»>waitevent</option>

<option value=»listcommands»>listcommands</option>

</select>

or <input name=»action»><br/>

CLI Command <input name=»command»><br>

user <input name=»username»> pass <input type=»password» name=»secret»><br>

<input type=»submit»>

</form>

</td></tr>

<tr><td>Response</td><td>Success</td></tr>

<tr><td>Message</td><td>Authentication accepted</td></tr>

<tr><td colspan=»2″><hr></td></tr>

* Closing connection #0

</table></body>

Кодирование /mxml

Тип кодирования mxml предоставляет ответы на действия диспетчера, закодированные в XML. Вот пример Login с помощью типа кодирования mxml:

$ curl -v «http://localhost:8088/mxml?action=login&username=hello&secret=world»

* About to connect() to localhost port 8088 (#0)

* Trying 127.0.0.1… connected

* Connected to localhost (127.0.0.1) port 8088 (#0)

> GET /mxml?action=login&username=hello&secret=world HTTP/1.1

> User-Agent: curl/7.19.7 (x86_64-pc-linux-gnu) libcurl/7.19.7

OpenSSL/0.9.8k zlib/1.2.3.3 libidn/1.15

> Host: localhost:8088

> Accept: */*

>

< HTTP/1.1 200 OK

< Server: Asterisk/SVN-branch-11-r378376

< Date: Tue, 07 Sep 2010 12:26:58 GMT

< Connection: close

< Cache-Control: no-cache, no-store

< Content-Length: 146

< Content-type: text/xml

< Cache-Control: no-cache;

< Set-Cookie: mansession_id=»536d17a4″; Version=1; Max-Age=60

< Pragma: SuppressEvents

<

<ajax-response>

<response type=’object’ id=’unknown’>

<generic response=’Success’ message=’Authentication accepted’ />

</response>

* Closing connection #0

</ajax-response>

События диспетчера

При подключении к собственному интерфейсу TCP для AMI события диспетчера доставляются асинхронно. При использовании AMI через HTTP события должны быть получены путем опроса. События загружаются через HTTP, выполнив WaitEvent диспетчера действий. В следующем примере показано как события могут быть получены с помощью WaitEvent диспетчера действий. Шаги:

1. Запустите сеанс AMI HTTP с помощью действия Login.
2. Зарегистрируйте SIP-телефон на Asterisk для создания события диспетчера.
3. Извлеките событие диспетчера с помощью действия WaitEvent.

Взаимодействие выглядит так:

$ wget —save-cookies cookies.txt \

> «http://localhost:8088/mxml?action=login&username=hello&secret=world» -O —

<ajax-response>

<response type=’object’ id=’unknown’>

<generic response=’Success’ message=’Authentication accepted’ />

</response>

</ajax-response>

$ wget —load-cookies cookies.txt \

< «http://localhost:8088/mxml?action=waitevent» -O —

<ajax-response>

<response type=’object’ id=’unknown’>

<generic response=’Success’ message=’Waiting for Event completed.’ />

</response>

<response type=’object’ id=’unknown’>

<generic event=’PeerStatus’ privilege=’system,all’

channeltype=’SIP’ peer=’SIP/0000FFFF0004′

peerstatus=’Registered’ address=’172.16.0.160:5060′ />

</response>

<response type=’object’ id=’unknown’>

<generic event=’WaitEventComplete’ />

</response>

</ajax-response>

Файлы вызовов

Перед приведением примеров использования AMI, стоит поговорить о файлах вызовов. Часто AMI рассматривают для исходящих вызовов, однако, во многих ситуациях проще использовать файлы вызовов. Файл вызова — это простой текстовый файл, описывающий вызов, который вы хотите совершить с Asterisk. После создания файла вызова вы перемещаете его в каталог /var/spool/asterisk/outgoing. Asterisk обнаружит, что файл был помещен туда и будет обрабатывать вызов.

Чтобы использовать файлы вызовов в Asterisk должен быть загружен модуль pbx_spool. Выполните следующую команду в CLI Asterisk, чтобы убедиться, что он загружен. Если это не так, проверьте конфигурационный файл модулей /etc/asterisk/modules.conf:

*CLI> module show like spool

Module Description Use Count

pbx_spool.so Outgoing Spool Support 0

1 modules loaded

Asterisk поставляется с образцом файла вызова. Его можно найти как sample.call в корневом каталоге исходников Asterisk.

У файлов вызовов простой синтаксис. Вы можете размещать комментарии в файле, помещая перед ними символ #. Параметры, указанные в файле, представляют собой пары ключ/значение, разделенные двоеточием. Например:

# Это комментарий

Option: Value

Таблица 20-5 описывает параметры, которые могут быть указаны в файле вызова.

Таблица 20-5. Параметры файла вызова

Ниже приведен пример создания файла вызова, а затем его размещение в соответствующем каталоге, чтобы Asterisk обработал его:

$ cat > demo-congrats.call << EOF

> Channel: SIP/[email protected]

> Application: Playback

> Data: demo-congrats

> CallerID: Asterisk <(555) 555-1212>

>

> EOF

$ mv demo-congrats.call /var/spool/asterisk/outgoing/

Использование mv вместо cp здесь важно. Asterisk следит за тем, чтобы содержимое отображалось в каталоге спула. Если вы используете копирование, Asterisk может попытаться прочитать новый файл до того, как содержимое будет полностью скопировано в него. Создание файла, а затем его перемещение позволяет избежать этой проблемы.

Использованием файлов вызовов для совершения исходящих вызовов легко и невероятно полезно. Оно отлично подходит для малого объема вызовов. Если вы хотели бы надежно инициировать много вызовов сразу, AMI является более подходящим. “Инициирование вызова с помощью Python и StarPy” дает пример инициирования вызова с помощью AMI.

Пример использования

Большинство из этой главы до сих пор обсуждали концепции и настройки, связанные с AMI. В этом разделе приведен пример использования.

Инициирование вызова

AMI имеет действие диспетчера Originate, которое может использоваться для инициирования вызова. Многие из принятых заголовков совпадают с параметрами, размещенными в файлах вызовов. Таблица 20-6 перечисляет заголовки, принятые действием Originate.

Таблица 20-6. Заголовки для действия Originate

Простейший пример использования действия Originate осуществляется через telnet:

$ telnet localhost 5038

Trying 127.0.0.1…

Connected to localhost.

Escape character is ‘^]’.

Asterisk Call Manager/1.3

Action: Login

Username: hello

Secret: world

Response: Success

Message: Authentication accepted

Action: Originate

Channel: Local/loop@test

Application: Playback

Data: demo-congrats

Response: Success

Message: Originate successfully queued

^]

telnet> quit

Connection closed

Перенаправление вызова

Перенаправление (или перевод) вызова из AMI — еще одна функция, заслуживающая упоминания. Действие AMI Redirect может использоваться для отправки одного или двух каналов на любой другой внутренний номер в диалплане Asterisk. Если вам нужно перенаправить два канала, которые соединены вместе, сделайте это для них обоих одновременно. В противном случае, как только один канал был перенаправлен, другой будет завершен.

Перенаправление одного канала:

Action: Redirect

Channel: SIP/myphone-0011223344

Exten: 1234

Context: default

Priority: 1

Для перенаправления двух каналов:

Action: Redirect

Channel: SIP/myphone-0011223344

Context: default

Exten: 1234

Priority: 1

ExtraChannel: SIP/otherphone-0011223344

ExtraContext: default

ExtraExten: 5678

ExtraPriority: 1

Одним довольно распространенным использованием действия перенаправления от внешнего приложения состоит в том, чтобы перенаправить обе стороны вызова в мост конференции. Поместите этот контекст в диалплан:

[confbridge]

exten => _X.,1,ConfBridge(${EXTEN})

Информацию о настройке поведения приложения ConfBridge см. в разделе «Расширенные возможности конференц-связи» в Главе 11.

Теперь можно перенаправить любых двух вызывающих абонентов в мост конференции, используя что-то вроде этого:

Action: Redirect

Channel: SIP/myphone-0011223344

Context: confbridge

Exten: 1234

Priority: 1

ExtraChannel: SIP/otherphone-0011223344

ExtraContext: confbridge

ExtraExten: 1234

ExtraPriority: 1

Теперь другие абоненты могут присоединиться к этой конференции, или внешнее приложение с помощью AMI может продолжить перенаправлять другие каналы сюда же.

Инициирование вызова с использованием Python и StarPy

Чтобы еще больше продемонстрировать использование действия Originate, мы предоставили скрипт, который его использует. Полный сценарий приведен в Примере 20-1. Его можно загрузить с https://github.com/russellb/amiutils. Чтобы получить представление об использовании примера приложения, вот вывод справки:

$ ./amioriginate.py —help

Usage: amioriginate.py [options] <channel>

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

Options:

-h, —help Показать это сообщение справки и выйти

-d, —debug Включить вывод отладочной информации

-u USERNAME, —username=USERNAME

Имя пользователя AMI

-p PASSWORD, —password=PASSWORD

пароль AMI

-H HOST, —host=HOST Hostname или IP-адрес сервера Asterisk

-t PORT, —port=PORT Номер порта для AMI

-a APPLICATION, —application=APPLICATION

Приложение для подключения вызова. При использовании

этого параметра можно также указать аргументы приложения

с параметром-D/—data. Не используйте этот параметр и

параметры context, extension, и priority одновременно.

-D DATA, —data=DATA Аргументы для передачи приложению диалплана, указанному

с помощью-a/—application.

-c CONTEXT, —context=CONTEXT

Контекст в dialplan для отправки вызова, как только

получен ответ. При использовании этого параметра

необходимо также указать extension и priority. Не

указывайте параметры Application или Data при

использовании этого параметра.

-e EXTEN, —extension=EXTEN

Добавочный номер для подключения вызова. Cледует

использовать вместе с параметрами context и proirity.

-P PRIORITY, —priority=PRIORITY

Приоритет добавочного номера для подключения вызова.

Должен использоваться вместе с параметрами context и

extension.

Если вы запустите утилиту в режиме отладки, то увидите сообщение об обмене сырыми AMI-сообщениями. Во-первых, вот пример использования скрипта для инициирования вызова и подключения его к приложению. MSG OUT и Line In в выводе определяют обмен AMI. Строки MSG OUT указывают приложению действие AMI во внутреннем формате вместо исходного формата AMI, но заголовки и их значения по-прежнему видны. Строки Line In показывают только ответ TCP от Asterisk. Вывод показывает:

1. Приложение запрашивает вход в AMI.
2. Asterisk отвечает, принимая запрос аутентификации.
3. Приложение отправляет запрос на инициирование вызова.
4. Asterisk отвечает, указывая, что запрос инициирования успешно обработан. Вызов будет выполняться асинхронно, так как запрос originate включает Async: True. В противном случае мы не получили бы ответа, пока исходящий вызов или не будет отвечен или не отклонен по какой-либо причине.

$ ./amioriginate.py -d -u hello -p world \

> -a playback -D demo-congrats SIP/myphone

DEBUG:AMI:MSG OUT: {‘action’: ‘login’, ‘username’: ‘hello’, ‘secret’: ‘world’,

‘actionid’: ‘rhel6.3-server-28064728-1’}

DEBUG:AMI:Line In: ‘Asterisk Call Manager/1.3’

DEBUG:AMI:Line In: ‘Response: Success’

DEBUG:AMI:Line In: ‘ActionID: rhel6.3-server-28064728-1’

DEBUG:AMI:Line In: ‘Message: Authentication accepted’

DEBUG:AMI:Line In: »

DEBUG:AMI:MSG OUT: {‘application’: ‘playback’,

‘actionid’: ‘rhel6.3-server-28064728-2’,

‘variable’: », ‘async’: ‘True’, ‘data’: ‘demo-congrats’,

‘action’: ‘originate’, ‘channel’: ‘SIP/myphone’}

DEBUG:AMI:Line In: ‘Response: Success’

DEBUG:AMI:Line In: ‘ActionID: rhel6.3-server-28064728-2’

DEBUG:AMI:Line In: ‘Message: Originate successfully queued’

DEBUG:AMI:Line In: »

Этот скрипт использует два сторонних модуля Python: twisted и starpy. Модуль twisted широко используется и должен быть доступен в виде дистрибутива. Модуль starpy используется не так часто и его нужно установить вручную. См. “Разработка фреймворков”.

Пример 20-1. amioriginate.py

#!/usr/bin/env python

#

# Copyright (C) 2012, Russell Bryant

#

# Licensed under the Apache License, Version 2.0 (the «License»); you may

# not use this file except in compliance with the License. You may obtain

# a copy of the License at

#

# http://www.apache.org/licenses/LICENSE-2.0

#

# Unless required by applicable law or agreed to in writing, software

# distributed under the License is distributed on an «AS IS» BASIS, WITHOUT

# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the

# License for the specific language governing permissions and limitations

# under the License.

# Если иное не требуется применимым законодательством или не согласовано в

# письменной форме, программное обеспечение, распространяемое по лицензии,

# распространяется на условиях «КАК ЕСТЬ», БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ ИЛИ УСЛОВИЙ,

# явных или подразумеваемых. См. Лицензию для конкретного языка, регулирующего

# разрешения и ограничения в рамках Лицензии.

#

»’Originate вызов на сервере Asterisk

Разработан в качестве примера для «Asterisk: The Definitive Guide»

»’

import getpass

import logging

import optparse

import sys

import starpy.manager

from twisted.internet import reactor

LOG = logging.getLogger(__name__)

class OriginateCall(object):

def __init__(self, options, channel):

self.options = options

self.channel = channel

self.ami = starpy.manager.AMIFactory(self.options.username,

self.options.password)

def _on_login(self, ami):

kwargs = dict(channel=self.channel, async=True)

if self.options.application:

kwargs[‘application’] = self.options.application

kwargs[‘data’] = self.options.data

else:

kwargs[‘context’] = self.options.context

kwargs[‘exten’] = self.options.exten

kwargs[‘priority’] = self.options.priority

def _on_success(ami):

reactor.stop()

def _on_error(reason):

LOG.error(‘Originate failed: %s’ % reason.getErrorMessage())

reactor.stop()

ami.originate(**kwargs).addCallbacks(_on_success, _on_error)

def connect_and_call(self):

def _on_login_error(reason):

LOG.error(‘Failed to log in: %s’ % reason.getErrorMessage())

reactor.stop()

df = self.ami.login(self.options.host, self.options.port)

df.addCallbacks(self._on_login, _on_login_error)

def main(argv=None):

if argv is None:

argv = sys.argv

logging.basicConfig(level=logging.INFO)

description = (‘Эта программа используется для инициирования вызова на ‘

‘сервере Asterisk с помощью AMI. Аргумент канала для этого’

‘приложения сообщает Asterisk, какой исходящий вызов следует

‘выполнить. Существуют различные параметры, с помощью которых

‘можно указать, к чему будет подключен исходящий вызов после

‘ответа.’)

usage = ‘%prog [options] <channel>’

parser = optparse.OptionParser(description=description, usage=usage)

parser.add_option(‘-d’, ‘—debug’, action=’store_true’,

dest=’debug’, help=’Enable debug output’)

parser.add_option(‘-u’, ‘—username’, action=’store’, type=’string’,

dest=’username’, default=None, help=’AMI username’)

parser.add_option(‘-p’, ‘—password’, action=’store’, type=’string’,

dest=’password’, default=None, help=’AMI password’)

parser.add_option(‘-H’, ‘—host’, action=’store’, type=’string’,

dest=’host’, default=’localhost’,

help=’Hostname or IP address of the Asterisk server’)

parser.add_option(‘-t’, ‘—port’, action=’store’, type=’int’,

dest=’port’, default=5038,

help=’Port number for the AMI’)

parser.add_option(‘-a’, ‘—application’, action=’store’, type=’string’,

dest=’application’, default=»,

help=’Приложение для подключения вызова. При’

‘использовании’ этого параметра можно также указать’

‘аргументы приложения с параметром-D/—data. Не’

‘используйте этот параметр и параметры context,’

‘extension и priority одновременно.’)

parser.add_option(‘-D’, ‘—data’, action=’store’, type=’string’,

dest=’data’, default=»,

help=’Аргументы для передачи приложению диалплана,’

‘указанному с помощью-a/—application.’)

parser.add_option(‘-c’, ‘—context’, action=’store’, type=’string’,

dest=’context’, default=»,

help=’Context in the dialplan to send the call to ‘

‘once it answers. If using this option, you ‘

‘must also specify an extension and priority. ‘

‘Do not specify the application or data options ‘

‘if using this option.’)

parser.add_option(‘-e’, ‘—extension’, action=’store’, type=’string’,

dest=’exten’, default=»,

help=’Extension to connect the call to. This should ‘

‘be used along with the context and priority ‘

‘options.’)

parser.add_option(‘-P’, ‘—priority’, action=’store’, type=’string’,

dest=’priority’, default=»,

help=’Priority of the extension to connect the call ‘

‘to. This should used along with the context ‘

‘and extension options.’)

(options, args) = parser.parse_args(argv)

if options.debug:

LOG.setLevel(logging.DEBUG)

starpy.manager.log.setLevel(logging.DEBUG)

if len(args) != 2 or not len(args[1]):

LOG.error(‘Please specify a single outbound channel.’)

parser.print_usage()

return 1

channel = args[1]

valid_application = len(options.application)

valid_extension = (len(options.context) and len(options.exten) and

len(options.priority))

if not valid_application and not valid_extension:

LOG.error(‘Укажите допустимую точку для подключения вызова после ответа’

‘Укажите приложение или контекст, расширение и приоритет.’)

parser.print_usage()

return 1

if valid_application and valid_extension:

LOG.error(‘Пожалуйста, укажите только одно расширение или приложение.’)

parser.print_usage()

return 1

if not options.username:

user = raw_input(‘Username [%s]: ‘ % getpass.getuser())

if not user:

user = getpass.getuser()

options.username = user

if not options.password:

options.password = getpass.getpass()

o = OriginateCall(options, channel)

reactor.callWhenRunning(o.connect_and_call)

reactor.run()

return 0

if __name__ == ‘__main__’:

sys.exit(main())

Разработка фреймворков

Многие разработчики приложений пишут код, который напрямую взаимодействует с AMI. Тем не менее, существует ряд библиотек, целью которых является упрощение написания приложений AMI. Таблица 20-7 содержит некоторые списки из которых часть успешно используются. Если вы ищете библиотеки для Asterisk на любом популярном языке программирования по вашему выбору, вы, скорее всего, найдете их.

Таблица 20-7. Фреймворки разработки AMI

CSTA

Телекоммуникационные приложения с компьютерной поддержкой (CSTA) — это стандарт интеграции компьютерной телефонии (CTI), используемый несколькими производителями. Некоторые из тех, что предоставлены CSTA, могут быть сопоставлены с операциями, доступными в AMI. Было нескольких усилий, чтобы обеспечить интерфейс CSTA для Asterisk, в том числе проект Open CSTA. Хотя ни один из авторов не имеет опыта работы с этим интерфейсом CSTA для Asterisk, его, безусловно, стоит рассмотреть, если у вас есть опыт CSTA или существующее приложение CSTA вы хотели бы интегрировать с Asterisk.

Интересные приложения

Было разработано много полезных приложений, которые используют преимущества AMI. Вот один из примеров.

Flash-панель оператора

Flash Operator Panel — это приложение, которое запускается в веб-браузере с помощью Flash. Оно используется в основном в качестве интерфейса, чтобы видеть какие внутренние номера в настоящее время звонят или используются. Оно также включает в себя возможность мониторинга состояния конференц-зала и очередей вызовов. Также могут быть выполнены некоторые действия вызова, такие как врывание (barging) и передача (transfer) вызовов. На Рисунке 20-4 показан интерфейс Flash-панели оператора.

Загрузить и получить более подробную информацию о Flash-панели оператора можно по адресу http://www.asternic.org и http://www.fop2.com.

Заключение

Интерфейс управления Asterisk (AMI) предоставляет API для мониторинга событий из системы Asterisk, а также запрашивает у Asterisk выполнение широкого спектра действий. Был представлен интерфейс HTTP и разработан ряд платформ, которые облегчают разработку приложений. Вся эта информация, а также примеры, которые мы рассмотрели в конце этой главы, должны заставить вас задуматься о том, какие новые приложения вы могли бы создать с помощью AMI.