Текст книги "Asterisk™: будущее телефонии Второе издание"

Автор книги: Джим Меггелен

Соавторы: Джаред Смит,Лейф Мадсен
сообщить о нарушении

Текущая страница: 20 (всего у книги 41 страниц)

print STDERR "3. Testing 'sendimage'..."; print "SEND IMAGE asterisk-imagen"; my $result = ; &checkresult($result);

Этот тест вызывает команду SEND IMAGE, которая является аналогом приложения SendImage(). Ее единственный аргумент – имя файла изображения, который будет отправляться вызывающему абоненту. Как и команда SEND TEXT, данная команда работает, только если вызывающий канал поддерживает прием изображений. print STDERR "4. Testing 'saynumber'..."; print "SAY NUMBER 192837465 ""n"; my $result = ; &checkresult($result);

Этот тест посылает Asterisk команду SAY NUMBER. Она ведет себя аналогично приложению диалплана SayNumber() и принимает два аргумента:

• Число, которое должно быть воспроизведено.

• Коды, которые могут прервать выполнение команды.

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

print STDERR "5. Testing 'waitdtmf'..."; print "WAIT FOR DIGIT 1000n"; my $result = ; &checkresult($result);

Этот тест демонстрирует применение команды WAIT FOR DIGIT. Эта команда обеспечивает ожидание ввода DTMF-кода вызывающим абонентом заданное количество миллисекунд. Если требуется реализовать бесконечное ожидание ввода цифры, в качестве времени ожидания задается -1. Это приложение возвращает десятичное значение ASCII нажатой цифры.

print STDERR "6. Testing 'record'..."; print "RECORD FILE testagi gsm 1234 3000n"; my $result = ; &checkresult($result);

Этот фрагмент кода демонстрирует команду RECORD FILE. Она используется для записи разговора, аналогично приложению диалплана Record(). RECORD FILE принимает семь аргументов, из которых три последних являются необязательными:

• Имя записываемого файла.

• Формат, в котором выполняется запись.

• Коды, которые могут прервать запись.

• Время ожидания (максимальное время записи) в миллисекундах или -1, если время ожидания бесконечно.

• Число музыкальных фрагментов, которые необходимо пропустить перед началом записи (необязательный).

• Слово BEEP, если требуется, чтобы Asterisk подавала звуковой сигнал перед началом записи (необязательный).

• Количество секунд, которое должно пройти, прежде чем Asterisk решит, что пользователь закончил запись, и продолжит выполнение даже несмотря на то, что время ожидания еще не истекло и DTMF-коды не были введены (необязательный). Этот аргумент должен следовать за s=.

В данном конкретном случае записывается файл testagi (в формате GSM), любой DTMF-код от 1 до 4 может прервать запись и максимальное время записи – 3000 мс.

print STDERR "6a. Testing 'record' playback..."; print "STREAM FILE testagi ""n"; my $result = ; &checkresult($result);

Вторая часть этого теста воспроизводит записанный ранее аудиофайл, используя команду STREAM FILE. Команда STREAM FILE уже рассматривалась, поэтому данный фрагмент кода не требует дополнительных пояснений.

print STDERR «================== Complete ======================n»;

print STDERR "$tests tests completed, $pass passed, $fail failedn"; print STDERR "==================================================n";

В конце сценария AGI результаты тестирования записываются в STDERR, который должен быть выведен в консоли Asterisk.

Итак, при написании AGI-программ на Perl необходимо помнить следующее:

• Должен быть активирован строгий контроль выполнения правил языка программирования с помощью команды use strict[102]102
  Приносим извинения читателям, которые живут не в США, за использование сервиса погоды, предоставляющем информацию только о городах США. Если вы сможете найти хороший международный погодный сервис, который предоставляет свои данные в XML, вам не должно составить особого труда изменить этот сценарий AGI для работы с тем конкретным сервисом. Как только мы найдем такой сервис, мы внесем поправки в этот сценарий для будущих изданий данной книги.


[Закрыть].

• Должна быть отключена буферизация вывода через задание $|=1.

• Данные, поступающие от Asterisk, принимаются с помощью цикла

while().

• Значения записываются командой print.

• Для записи отладочной информации в консоль Asterisk используется команда print STDERR.

Библиотека AGI для Perl

Тем, кто собирается создавать собственные сценарии AGI на языке Perl, вероятно, будет интересен модуль на Perl – Asterisk::AGI, написанный Джеймсом Головичем (James Golovich), который можно найти по адресуhttp://asterisk.gnuinter.net. Модуль Asterisk::AGI еще больше упрощает написание сценариев AGI на Perl.

Создание сценариев AGI на PHP

Мы обещали обсудить несколько языков программирования, поэтому пойдем дальше и рассмотрим, как выглядит сценарий AGI на PHP. Основные правила программирования AGI те же, изменился только язык программирования. В данном примере мы напишем сценарий AGI для загрузки из Интернета сводки погоды и предоставления вызывающему абоненту информации о температуре, направлении и скорости ветра.

#!/usr/bin/php -q

Первая строка указывает системе использовать для выполнения сценария интерпретатор PHP. Опция -q отключает HTML-сообщения об ошибках. Необходимо убедиться в отсутствии дополнительных строк между первой строкой и открывающим тегом PHP, поскольку это собьет Asterisk с толку.

# внесите соответствующие изменения для получения

# данных по интересующему вас городу

# полный список городов США можно найти по адресу

# http://www.nws.noaa.gov/data/current_obs/

$weatherURL="http://www.nws.noaa.gov/data/current_obs/KMDQ.xml"; Тем самым вы указываете сценарию AGI, где можно получить информацию о текущих погодных условиях. В данном примере предоставляются данные для Хантсвилла, штат Алабама. Вы можете свободно посетить указанный сайт, на котором найдете полный список станций по всем Соединенным Штатам Америки¹.

# не допускайте, чтобы этот сценарий выполнялся дольше 60 с set_time_limit(60);

Здесь мы указываем PHP, что данная программа не должна выполняться более 60 с. Таким образом, сценарий будет гарантированно завершен, если по какой-то причине время его выполнения превысит 60 с.

# отключить буферизацию вывода ob_implicit_flush(false);

Эта команда отключает буферизацию вывода, то есть все данные будут отправляться в интерфейс AGI немедленно и не станут накапливаться в буфере.

# отключите сообщения об ошибках, поскольку, скорее всего,

# они будут пересекаться с сообщениями интерфейса AGI error_reporting(0);

Эта команда отключает все сообщения об ошибках, поскольку они могут пересекаться с сообщениями интерфейса AGI. (Вероятно, полезно будет закомментировать эту строку при тестировании.)

# создать описатели файла в случае необходимости if (!defined('STDIN'))

define('STDIN', fopen('php://stdin', 'r'));

if (!defined('STDOUT'))

define('STDOUT', fopen('php://stdout', 'w'));

if (!defined('STDERR'))

define('STDERR', fopen('php://stderr', 'w'));

Этот фрагмент кода гарантирует открытие описателей файла для потоков STDIN, STDOUT и STDERR, которые будут обрабатывать все взаимодействия между Asterisk и нашим сценарием.

# извлекаем все переменные AGI из Asterisk

while (!feof(STDIN)) {

$temp = trim(fgets(STDIN,4096));

if (($temp == "") || ($temp == "n")) {

break;

i

$s = split(":",$temp);

$name = str_replace("agi_","",$s[0]);

$agi[$name] = trim($s[1]);

}

Далее считываем все AGI-переменные, передаваемые нам Asterisk. Использование в PHP команды fgets для чтения данных из STDIN обеспечит сохранение каждой переменной в хеше $agi. Эти переменные могли бы использоваться в логике сценария AGI, но в данном примере мы не будем этого делать.

# вывести все переменные AGI в целях отладки

foreach($agi as $key=>$value) {

fwrite(STDERR,"– $key = $valuen"); fflush(STDERR);

}

Здесь переменные возвращаются в STDERR для целей отладки.

# извлечь эту веб-страницу $weatherPage=file_get_contents($weatherURL);

Эта строка кода обеспечивает извлечение XML-файла с сайта National Weather Service (Национальная метеорологическая служба) и помещение его содержимого в переменную $weatherPage. Эта переменная будет использована позже для получения необходимых частей сводки погоды.

# получить температуру в градусах по Фаренгейту

if (preg_match("/([0-9]+)/i",$weatherPage,$matches)) {

$currentTemp=$matches[1];

}

Данный фрагмент кода извлекает данные о температуре (в градусах по Фаренгейту) из сводки погоды с помощью команды preg_match. Для получения необходимых данных эта команда использует совместимые с Perl регулярные выражения[103]103
  Полный справочник по регулярным выражениям – Джеффри Фридл «Регулярные выражения», 3-е издание. – Пер. с англ. – СПб: Символ-Плюс, 2008.
  В противоположность Asterisk Gateway Interface (AGI), который обеспечивает Asterisk возможность запускать внешнюю программу из диалплана. Интерфейсы AGI и AMI во многом дополняют друг друга.


[Закрыть].

# получить направление ветра

if (preg_match("/North/i",$weatherPage)) {

$currentWindDirection='northerly';

elseif (preg_match("/South/i",$weatherPage))

$currentWindDirection='southerly'; elseif (preg_match("/East/i",$weatherPage))

$currentWindDirection='easterly'; elseif (preg_match("/West/i",$weatherPage))

$currentWindDirection='westerly'; elseif (preg_match("/Northwest/i",$weatherPage))

$currentWindDirection='northwesterly'; elseif (preg_match("/Northeast/i",$weatherPage))

$currentWindDirection='northeasterly'; elseif (preg_match("/Southwest/i",$weatherPage))

$currentWindDirection='southwesterly'; elseif (preg_match("/Southeast/i",$weatherPage)) $currentWindDirection='southeasterly';

Направление ветра извлекаем посредством команды preg_match, а полученное значение (заключенное в теги wind_dir) присваиваем переменной $currentWindDirection.

# получаем скорость ветра

if (preg_match("/([0-9.]+)/i",$weatherPage,$matches)) {

$currentWindSpeed = $matches[1];

}

Наконец получаем текущую скорость ветра и присваиваем ее значение переменной $currentWindSpeed.

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

if ($currentTemp) {

fwrite(STDOUT,"STREAM FILE temperature ""n"); fflush(STDOUT);

$result = trim(fgets(STDIN,4096)); checkresult($result); fwrite(STDOUT,"STREAM FILE is ""n"); fflush(STDOUT);

$result = trim(fgets(STDIN,4096));

checkresult($result);

fwrite(STDOUT,"SAY NUMBER $currentTemp ""n"); fflush(STDOUT);

$result = trim(fgets(STDIN,4096)); checkresult($result);

fwrite(STDOUT,"STREAM FILE degrees ""n"); fflush(STDOUT);

$result = trim(fgets(STDIN,4096)); checkresult($result);

fwrite(STDOUT,"STREAM FILE fahrenheit ""n"); fflush(STDOUT);

$result = trim(fgets(STDIN,4096)); checkresult($result);

}

if ($currentWindDirection && $currentWindSpeed) {

fwrite(STDOUT,"STREAM FILE with ""n"); fflush(STDOUT);

$result = trim(fgets(STDIN,4096)); checkresult($result);

fwrite(STDOUT,"STREAM FILE $currentWindDirection ""n"); fflush(STDOUT);

$result = trim(fgets(STDIN,4096)); checkresult($result);

fwrite(STDOUT,"STREAM FILE wx/winds ""n"); fflush(STDOUT);

$result = trim(fgets(STDIN,4096)); checkresult($result); fwrite(STDOUT,"STREAM FILE at ""n";) fflush(STDOUT);

$result = trim(fgets(STDIN,4096)); checkresult($result);

fwrite(STDOUT,"SAY NUMBER $currentWindSpeed ""n"); fflush(STDOUT);

$result = trim(fgets(STDIN,4096)); checkresult($result);

fwrite($STDOUT,"STREAM FILE miles-per-hour ""n"); fflush(STDOUT);

$result = trim(fgets(STDIN,4096)); checkresult($result);

}

Теперь, собрав все необходимые данные, можно отправить AGI-коман– ды в Asterisk (проверяя результаты по ходу), которые доставят информацию о текущих погодных условиях вызывающему абоненту. Это будет реализовано с помощью AGI-команд STREAM FILE и SAY NUMBER. Мы говорили об этом раньше, повторим еще раз: при вызове команд AGI в них должны передаваться все необходимые аргументы. В данном случае обе команды, STREAM FILE и SAY NUMBER, требуют второго аргумента. Передадим пустые кавычки, экранированные символом обратного слэша.

Также следует обратить внимание, что при каждой записи в STDOUT вызывается команда fflush. Вероятно, это лишнее, но не будет вреда в том, чтобы гарантировать немедленную отправку AGI-команды в Asterisk, без буферизации.

function checkresult($res) {

trim($res);

if (preg_match('/"200/',$res)) {

if (! preg_match('/result=(-?d+)/',$res,$matches)) {

fwrite(STDERR,"FAIL ($res)n");

fflush(STDERR);

return 0;

}

else {

fwrite(STDERR,"PASS (".$matches[1].")n");

fflush(STDERR);

return $matches[1];

}

}

else {

fwrite(STDERR,"FAIL (unexpected result '$res')n");

fflush(STDERR);

return -1;

}

}

Назначение функции checkresult аналогично подпрограмме checkresult из нашего примера на Perl. Как следует из ее имени, она проводит проверку

результатов, возвращаемых Asterisk, при каждом вызове команды AGI.

?>

В конце файла располагается закрывающий тег PHP. После закрывающего тега PHP не должно быть никаких пробелов, поскольку это может сбить с толку интерфейс AGI.

Теперь мы уже рассмотрели два разных языка программирования с целью продемонстрировать, что общего в написании сценария AGI на PHP и Perl и чем они отличаются. При создании сценария AGI на PHP помните, что необходимо:

• Запускать PHP с ключом -q; это отключает HTML в сообщениях об ошибках.

• Отключить ограничение по времени или задать для него приемлемое значение (более новые версии PHP автоматически отключают ограничение по времени при запуске PHP из командной строки).

• Отключить буферизацию вывода с помощью команды ob_implicit_ flush(false).

• Открыть описатели файла для STDIN, STDOUT и STDERR (в более новых версиях PHP один или более этих описателей файла уже могут быть открыты; в предыдущем фрагменте кода показано, как сделать это красиво для большинства версий PHP).

• Прочитать переменные из STDIN, используя функцию fgets.

• Использовать функцию fwrite для записи данных в STDOUT и STDERR.

• Всегда вызывать функцию fflush после записи в STDOUT или STDERR.

Библиотека AGI для PHP

Для более продвинутого программирования AGI на PHP, вероятно, пригодится проект PHPAGI, который можно найти по адресу http:// phpagi.sourceforge.net. Изначально он был написан Мэттью Ашамом (Matthew Asham) и дорабатывался несколькими членами сообщества разработчиков Asterisk.

Написание сценариев AGI на Python

Сценарий AGI, который мы напишем на Python, называется «Игра в вычитание». Источником идей для его написания стала программа на Perl, созданная Эдом Гаем (Ed Guy) и представленная им на конференции AstriCon в 2004 году. Эд рассказывал, в какой восторг он пришел от мощи и простоты Asterisk, когда обнаружил, что может написать короткий сценарий на Perl, чтобы помочь своей дочери с математикой. Поскольку мы уже написали Perl-программу, использующую AGI и Эд создал свою математическую программу на Perl, мы решили заняться реализацией этой задачи на Python! Итак, разберем наш сценарий на Python: #!/usr/bin/python

Данная строка указывает системе выполнять этот сценарий в интерпретаторе Python. Для небольших сценариев в эту строку можно добавить опцию -u, что обеспечит выполнение Python в режиме без буферизации. Однако это не рекомендуется для больших или часто используемых сценариев AGI, поскольку может сказаться на производительности системы. import sys import re import time import random

Здесь импортируются несколько библиотек, которые будут использоваться в сценарии AGI.

# Читаем и игнорируем среду AGI (читать до пустой строки)

env = {} tests = 0;

while 1:

line = sys.stdin.readline().strip()

if line == '': break

key,data = line.split(':') if key[:4] <> 'agi_':

# игнорируем ввод, который начинается не с agi_ sys.stderr.write("Did not work!n"); sys.stderr.flush() continue key = key.strip() data = data.strip() if key <> '':

env[key] = data

sys.stderr.write("AGI Environment Dump:n");

sys.stderr.flush()

for key in env.keys():

sys.stderr.write(" – %s = %sn" % (key, env[key])) sys.stderr.flush()

Данный фрагмент кода читает переменные, передаваемые в сценарий из Asterisk, и сохраняет их в словарь env. Затем эти значения записываются в STDERR для целей отладки.

def checkresult (params): params = params.rstrip() if re.search('"200',params): result = re.search('result=(d+)',params) if (not result):

sys.stderr.write("FAIL ('%s')n" % params) sys.stderr.flush() return -1 else:

result = result.group(1)

#debug("Result:%s Params:%s" % (result, params)) sys.stderr.write("PASS (%s)n" % result) sys.stderr.flush() return result

else:

sys.stderr.write("FAIL (unexpected result '%s')n" % params)

sys.stderr.flush()

return -2

Функция checkresult по своему назначению практически идентична подпрограмме checkresult в примере AGI-сценария на Perl, который рассматривался ранее в этой главе. Она читает результат выполнения команды Asterisk, проводит синтаксический разбор результата и сообщает, была команда выполнена успешно или нет. def sayit (params):

sys.stderr.write("STREAM FILE %s ""n" % str(params)) sys.stderr.flush()

sys.stdout.write("STREAM FILE %s ""n" % str(params)) sys.stdout.flush()

result = sys.stdin.readline().strip() checkresult(result)

Функция sayit – это просто оболочка для команды STREAM FILE.

def saynumber (params):

sys.stderr.write("SAY NUMBER %s ""n" % params) sys.stderr.flush()

sys.stdout.write("SAY NUMBER %s ""n" % params) sys.stdout.flush()

result = sys.stdin.readline().strip() checkresult(result)

Функция saynumber – это просто оболочка для команды SAY NUMBER.

def getnumber (prompt, timelimit, digcount):

sys.stderr.write("GET DATA %s %d %dn" % (prompt, timelimit, digcount)) sys.stderr.flush()

sys.stdout.write("GET DATA %s %d %dn" % (prompt, timelimit, digcount)) sys.stdout.flush()

result = sys.stdin.readline().strip() result = checkresult(result) sys.stderr.write("digits are %sn" % result) sys.stderr.flush() if result:

return result else:

result = -1

Функция getnumber вызывает команду GET DATA для получения DTMF-вво– да от вызывающего абонента. Она используется в нашей программе для получения ответов абонента на поставленные задачи по вычитанию.

limit=20

digitcount=2

score=0

count=0

ttanswer=5000

Здесь выполняется задание исходных значений нескольким переменным, которые будут использоваться в программе.

starttime = time.time() t = time.time() – starttime

В этих строках переменной starttime задается текущее время, а переменной t – начальное значение 0. Переменная t будет использоваться для отсчета времени с момента запуска сценария AGI в секундах.

sayit("subtraction-game-welcome")

Далее, мы рады приветствовать абонента в нашей игре на вычитание.

while ( t < 180 ):

big = random.randint(0,limit+1) big += 10

subt= random.randint(0,big) ans = big – subt count += 1

#постановка задачи:

sayit("subtraction-game-next");

saynumber(big);

sayit("minus");

saynumber(subt);

res = getnumber("equals",ttanswer,digitcount);

if (int(res) == ans) : score+=1

sayit("subtraction-game-good"); else :

sayit("subtraction-game-wrong"); saynumber(ans);

t = time.time() – starttime Это сердце сценария AGI. При циклическом выполнении данного фрагмента кода абоненту в течение 180 с предлагаются задачи на вычитание. В начале цикла берутся два случайных числа и вычисляется их разность. Затем абоненту предлагается решить эту задачу. Читается ответ абонента. Если ответ неверен, дается правильный ответ. pct = float(score)/float(count)*100; sys.stderr.write("Percentage correct is %dn" % pct) sys.stderr.flush() sayit("subtraction-game-timesup") saynumber(score) sayit("subtraction-game-right") saynumber(count) sayit("subtraction-game-pct") saynumber(pct)

После того как абонент закончил решение примеров, ему сообщается, сколько баллов он набрал.

Как видите, при написании сценариев AGI на Python следует помнить такие основные моменты:

• Выходной буфер должен очищаться после каждой записи. Это гарантирует, что AGI-программа не зависнет из-за того, что Asterisk будет ожидать освобождения буфера для записи, а Python – ответа от Asterisk.

• Чтение данных из Asterisk осуществляется с помощью команды sys.stdin.readline.

• Запись команд в Asterisk выполняется с помощью команды sys. stdout.write. После записи не забывайте вызывать sys.stdout.flush.

Библиотека AGI для Python

Если вы планируете много работать с Python для AGI, вероятно, вам пригодится модуль Python Pyst, созданный Карлом Патлэндом (Karl Putland). Его можно найти по адресуhttp://sourceforge.net/projects/pyst.

Отладка в AGI

Отладка программ AGI, как и любых других программ, может приводить в уныние. К счастью, при отладке сценариев AGI есть два преимущества. Во-первых, поскольку весь обмен информацией между Asterisk и программой AGI происходит через STDIN и STDOUT (и конечно, STDERR), у вас должно получиться выполнять сценарий AGI непосредственно из операционной системы. Во-вторых, в Asterisk есть удобная команда для отображения всех взаимодействий между ним и сценарием AGI – agi debug.

Отладка из операционной системы

Как упоминалось выше, у вас должно получиться запустить свою программу прямо из операционной системы, чтобы проверить ее поведение. Хитрость здесь в том, чтобы действовать подобно Asterisk, предоставляя сценарию следующее:

• Список переменных и их значений, таких как agi_test:1.

• Символы перевода строки (n), указывающие на то, что передача переменных завершена.

• Ответы на каждую из команд AGI, поступающую из вашего сценария AGI. Обычно достаточно ввести 200 response=1.

При тестировании программы непосредственно из операционной системы, возможно, проще замечать ошибки в ней.

Использование команды Asterisk agi debug

В интерфейсе командной строки Asterisk есть очень полезная команда для отладки сценариев AGI, которая называется (вполне уместно) agi debug. Если ввести в консоли Asterisk agi debug и затем запустить AGI– сценарий, вы увидите нечто подобное:

– Executing AGI("Zap/1-1", "temperature.php") in new stack

– Launched AGI Script /var/lib/asterisk/agi-bin/temperature.php AGI Tx >> agi_request: temperature.php AGI Tx >> agi_channel: Zap/1-1 AGI Tx >> agi_language: en AGI Tx >> agi_type: Zap AGI Tx >> agi_uniqueid: 1116732890.8 AGI Tx >> agi_callerid: 101 AGI Tx >> agi_calleridname: Tom Jones

AGI Tx >> agi_callingpres: 00

AGI Tx >> agi_callingani2: 0

AGI Tx >> agi_callington: 0

AGI Tx >> agi_callingtns: 0

AGI Tx >> agi_dnid: unknown

AGI Tx >> agi_rdnis: unknown

AGI Tx >> agi_context: incoming

AGI Tx >> agi_extension: 141

AGI Tx >> agi_priority: 2

AGI Tx >> agi_enhanced: 0.0

AGI Tx >> agi_accountcode:

AGI Tx >>

AGI Rx << STREAM FILE temperature

AGI Tx >> 200 result=0 endpos=6400

AGI Rx << STREAM FILE is ""

AGI Tx >> 200 result=0 endpos=5440

AGI Rx << SAY NUMBER 67 ""

– Playing 'digits/60' (language 'en')

– Playing 'digits/7' (language 'en')

AGI Tx >> 200 result=0

AGI Rx << STREAM FILE degrees ""

AGI Tx >> 200 result=0 endpos=6720

AGI Rx << STREAM FILE fahrenheit ""

AGI Tx >> 200 result=0 endpos=8000

– AGI Script temperature.php completed, returning 0

Во время выполнения сценария AGI будут выведены строки трех типов. Первый тип – строки, начинающиеся с AGI TX >>. Это строки, которые Asterisk передает в STDIN вашей программы. Второй тип – строки, начинающиеся с AGI RX <<. Это команды, которые ваша AGI-программа записывает в Asterisk через STDOUT. Третий тип – строки, начинающиеся с –. Это стандартные сообщения Asterisk, выводимые при выполнении определенных команд.

Чтобы отключить отладку AGI после запуска, просто введите в консоли Asterisk agi no debug.

Используя команду agi debug, можно увидеть взаимодействие между Asterisk и своей программой, что может быть очень полезным при отладке. Надеемся, эти два совета помогут вам создавать и отлаживать мощные AGI-программы.

Заключение

AGI для разработчика – это один из наиболее революционных и веских аргументов в пользу Asterisk, а не закрытой узкоспециализированной офисной АТС. Но AGI – это только часть картины. В главе 10 будет рассмотрен другой мощный интерфейс программирования, известный как Asterisk Manager Interface.10

Интерфейс Asterisk Manager (AMI) и Adhearsion

Лучше позаботьтесь о том, чтобы все слова ваши были понятны, пристойны и правильно расположены, чтобы каждое предложение и каждый ваш период, затейливый и полнозвучный, с наивозможною и доступною вам простотою и живостью передавали то, что вы хотите сказать; выражайтесь яснее, не запутывая и не затемняя смысла. – Мигель де Сервантес, предисловие к книге «Дон Кихот»

Интерфейс Manager

Asterisk Manager Interface (AMI) – мощный программный интерфейс. Он позволяет внешним программам как управлять, так и контролировать систему Asterisk¹. Этот интерфейс часто используется для интеграции Asterisk с существующими бизнес-процессами и системами, программным обеспечением CRM (Customer Relationship Management – управление взаимоотношениями с клиентами). Он также может применяться для разнообразных приложений, таких как программы автоматического набора номера и системы click-to-call (звонок-по-щелчку). Интерфейс Asterisk Manager слушает соединения, устанавливаемые по сетевому порту. Клиентская программа может соединяться с интерфейсом Asterisk Manager через этот порт, аутентифицироваться и передавать команды в Asterisk. После этого Asterisk будет отвечать на запрос, а также обновлять в клиентской программе информацию о статусе системы.

Чтобы использовать интерфейс Manager, необходимо задать учетную запись в файле /etc/asterisk/manager.conf. Этот файл будет выглядеть примерно так:

[general] enabled = yes port = 5038 bindaddr = 0.0.0.0

[oreilly]

secret = notvery

;deny=0.0.0.0/0.0.0.0

;permit=209.16.236.73/255.255.255.0

read = system,call,log,verbose,command,agent,user

write = system,call,log,verbose,command,agent,user

В разделе [general] необходимо активировать сервис, задав параметр enabled = yes. Чтобы эти изменения вступили в силу, понадобится перезагрузить интерфейс Manager (команда module reload manager из консоли Asterisk). По умолчанию используется TCP-порт 5038. Далее вы создаете по разделу для каждого пользователя, который будет присылать запрос на аутентификацию в системе. Для пользователя задается имя пользователя в квадратных скобках ([ ]), за которым следует пароль этого пользователя (secret), все IP-адреса, которым вы желаете запретить (deny) доступ, все IP-адреса, которым вы хотите разрешить (permit) доступ, и права на чтение (read) и запись (write) для этого пользователя.

Очень важно понимать, что, кроме незашифрованного пароля и возможности ограничить доступ для определенных IP-адре– сов, в интерфейсе Manager нет других средств обеспечения безопасности. Если вы запускаете Manager в ненадежной сети (или существуют любые другие сложные требования), для обработки всех соединений с API интерфейса Manager следует использовать замечательный пакет AstManProxy Дэвида Троя (David Troy).

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

Важно помнить, что интерфейс Manager создан для использования программами, а не пользователями. Дело здесь не в том, что не получится направлять команды к нему напрямую, просто не следует ожидать увидеть обычный консольный интерфейс – назначение интерфейса Manager не в этом.

Команды в интерфейс Manager доставляются в пакетах, имеющих следующий синтаксис (строки завершаются CR+LF)[104]104
  Возврат каретки с переводом строки (Carriage Return + Line Feed). Как правило, это обеспечивается нажатием клавиши Enter, но может отличаться для различных платформ ОС и языков программирования, поэтому, если имеются какие-то проблемы с передачей команд в интерфейс, вероятно, нелишним будет точно указать необходимое сочетание клавиш. На момент написания данной книги в Википедии имеется подробное описание этой концепции (http://en.wikipedia.org/wiki/Newline).


[Закрыть]:

Действие: <тип действия> Ключ 1: Значение 1 Ключ 2: Значение 2 и т. д. ... Переменная: Значение Переменная: Значение и т. д. ...

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

Action: login Username: oreilly Secret: notvery

Дополнительная CR+LF в пустой строке обеспечит передачу в интерфейс Manager пакета целиком.

Пройдя аутентификацию, вы сможете запускать действия, а также видеть события, сформированные Asterisk. В сильно загруженной системе может быть очень сложно или практически невозможно отслеживать все это «невооруженным глазом». Чтобы отключить для Asterisk возможность посылать события, можно добавить параметр Events в команду на регистрацию: Action: login Username: oreilly Secret: notvery Events: off

Если вы боитесь передавать свой пароль по сети незашифрованным (и это нормально), можно осуществить аутентификацию, используя систему запрос/ответ и алгоритм MD5, принцип работы которого очень похож на краткую аутентификацию HTTP. Для этого сначала вызывается действие Challenge (Запрос), которое предоставит вам маркер запроса:

Action: Challenge AuthType: MD5

Response: Success Challenge: 840415273

После этого можно взять маркер запроса, присоединить в конце него незашифрованный секрет и вычислить контрольную сумму результирующей строки по алгоритму MD5. Результат может использоваться для регистрации без необходимости передачи секрета открытым текстом.

Action: Login AuthType: MD5 Username: Admin

Key: e7a056e1488882c6c509bbe71a049978

Response: Success

Message: Authentication accepted

Передача команд

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

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

Действие Redirect (Перенаправить) может использоваться для перенаправления вызова. После регистрации необходимо послать такое действие:

Action: Redirect Channel: SIP/John-ae201e78 Context: Lab Exten: 6001 Priority: 1

ActionID: 2340981650981

Каждое действие, передаваемое по интерфейсу Manager, может сопровождаться произвольным значением ActionID. Это позволит распознавать, к какому действию относится ответ Asterisk. Настоятельно рекомендуется передавать уникальный ActionID с каждой командой AMI.

Этот URL переносит заданный канал в другой добавочный номер и приоритет диалплана. Ответ на это действие такой:

Response: Success ActionID: 2340981650981 Message: Redirect Successful

Чтение конфигурационного файла

Чтобы прочитать конфигурационный файл Asterisk через интерфейс Manager, можно использовать действие GetConfig. GetConfig возвращает содержимое конфигурационного файла или его часть. Следующая команда извлекает содержимое файла users.conf:

Action: GetConfig Filename: users.conf ActionID: 9873497149817

После этого Asterisk возвращает содержимое файла users.conf. Ответ

выглядит так:

Response: Success ActionID: 987397149817 Category-000000: general

Line-000000-000000: fullname=New User

Line-000000-000001: userbase=6000

Line-000000-000002: hasvoicemail=yes

Line-000000-000003: hassip=yes

Line-000000-000004: hasiax=yes

Line-000000-000005: hasmanager=no

Line-000000-000006: callwaiting=yes

Line-000000-000007: threewaycalling=yes

Line-000000-000008: callwaitingcallerid=yes

Line-000000-000009: transfer=yes

Line-000000-000010: canpark=yes

Line-000000-000011: cancallforward=yes

Line-000000-000012: callreturn=yes

Line-000000-000013: callgroup=1

Line-000000-000014: pickupgroup=1

Line-000000-000015: host=dynamic

Обновление конфигурационных файлов

Часто полезно иметь возможность обновлять конфигурационный файл Asterisk через интерфейс Manager. Для обновления одной или более настроек конфигурационного файла используется действие Update Config. Например, чтобы удалить из users.conf пользователя под именем 6003, можно использовать следующую команду: