источник: http://www.voip-info.org/wiki/view/Asterisk+AGI


AGI (Asterisk Gateway Interface) - интерфейс взаимодействия с внешними скриптами


AGI - это встроенный в Asterisk метод выполнения внешних скриптов (по аналогии с CGI для http серверов), который может расширить функциональность asterisk при помощи других языков программирования. Таких, как: Perl, PHP, C, Pascal, Bourne Shell - все зависит от Вашего желания и умения.

  • AGI скрипты: могут управлять вызовом в плане набора, вызываются из файла: extensions.conf
  • EAGI скрипты: дают приложению возможности доступа и управления звуковыми каналами, в дополнение к управлению вызовами в плане набора.
  • FastAGI могут быть использованы для выполнения обработки на удаленной машине
  • deadagi скрипты: имеют доступ к "мертвым" (отключенным) каналам, т.е. могут продолжать работать после окончания вызова.

Новое в Asterisk v1.2.11: GET VARIABLE может теперь находить глобальные переменные (смотри баг 7609)
Новое в Asterisk v1.2: CallerID, возвращаемый в agi_callerid и agi_calleridname, вместо одного параметра, содержат оба.

В целях отладки AGI скриптов Вы можете использовать CLI команду: "agi debug".

Команды

  • Команда AGI и EAGI: Функции, для использования в файле extensions.conf
  • FastAGI: Работа AGI программ на удаленной машине (улучшена эффективность для Asterisk)

Совершение исходящих вызовов

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

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

Использование интерфейса AGI

Работа Agi скрипта начинается с передачи списка переменных, связанных с екстеншеном, через поток стандартного ввода (stdin) AGI приложения. После этого, это приложение отправляет серверу Asterisk специальные команды AGI интерфейса через стандартный поток вывод (stdout) и получает результаты выполнения этих команд, через поток стандартного ввода (stdin).

Вызываемому Вами AGI скрипту вы можете передать один или несколько аргументов. Для этого используйте синтаксис: AGI(script.agi|arg1|arg2|..).

Команды AGI


  • answer: Перевести вызов в отвеченное состояние.
  • channel status: Возвращает статус подключенного канала.
  • control stream file: Отправка в канал заданного звукового файла, с возможностью управления его проигрывания (пауза/перемотка/возобновление проигрывания) с помощью получаемых от абонента DTMF цифр, если заданы. (Asterisk 1.2)
  • database del: Удаление ключа/значения из базы данных.
  • database deltree: Удаление дерева ключей/значений из базы данных.
  • database get: Получить значение из базы данных.
  • database put: Добавление/изменение значения в базе данных.
  • exec: Выполнение заданной Команды. (Команды - это функции, которые Вы используете при описании плана набора в файле extensions.conf ).
  • get data: Получить данные из канала.
  • get option: Ведет себя аналогично команде "STREAM FILE", но используется с заданным значением для таймаута. (Asterisk 1.2)
  • get variable: Получить значение переменной канала.
  • hangup: Разорвать соединение (Hangup) на текущем канале.
  • noop: Пустая команда. Ничего не делает.
  • receive char: Принимает один символ из канала, если он поддерживает эту возможность.
  • receive text: Принимает текстовую строку из канала, если он поддерживает эту возможность.
  • record file: Производит запись в заданный файл.
  • say alpha: Проговаривает заданную строку символов. (Asterisk 1.2)
  • say date: Проговаривает дату. (Asterisk 1.2)
  • say datetime: Проговаривает дату и время, согласно заданному формату. (Asterisk 1.2)
  • say digits: Проговаривает заданную строку цифр.
  • say number: Проговаривает заданный номер.
  • say phonetic: Проговаривает заданную строку символов.
  • say time: Проговаривает время.
  • send image: Отправляет изображение в канал, если он поддерживает эту возможность.
  • send text: Отправляет текст в канал, если он поддерживает эту возможность.
  • set autohangup: Автоматическое завершение соединение (Autohangup) на канале в заданное время.
  • set callerid: Установка callerid для текущего канала.
  • set context: Установка контекста для текущего канала.
  • set extension: Изменение екстеншена для текущего канала.
  • set music: Включение/Выключение музыки ожидания (Music on hold), например: "SET MUSIC ON default".
  • set priority: Установка значения приоритета для следующей выполняемой команды для канала.
  • set variable: Установка переменной канала.
  • stream file: Отправка звукового файла в канал.
  • tdd mode: Установка режима TDD для канала, который может его поддерживать, для включения возможности взаимодействия с TDD.
  • verbose: Запись сообщения в verbose log сервера asterisk.
  • wait for digit: Ожидание нажатия DTMF кнопки.

Языки программирования для создания AGI скриптов.


Java (не путать с JavaScript smile )

  • В OrderlyCalls, (наследник JAGIServer), объявлена полная поддержка FastAGI и Manager Interface в легком-В-использовании Пространстве Имен. Включая Web Deployer для разработки интегрированных VOIP-HTML приложений.
  • Еще один Java framework для FastAGI: http://tanesha.net/Wiki/JastAgi.html
  • Asterisk-java, теперь так же поддерживает FastAGI, в дополнение к поддержке Manager API. http://asterisk-java.org/

Perl



PHP

  • Asterisk AGI php: Рекомендации по настройке и написанию PHP скриптов для работы с интерфейсом Asterisk AGI.
  • Junghanns.net: Пример на PHP, для организации обратного вызова (callback) на мобильные телефоны: http://www.junghanns.net/en/callback.html
  • Asterisk tips Wake-Up Call PHP - "Make Wakeup Calls" и использованием PHP & BASH скриптов.

Python


Ruby


C


C#


Bash и Ash

  • Bash AGI: Bash скрипт, который устанавливает поле имени в callerID, используя данные из NANPA для NPA-NXX. http://yakko.cs.wmich.edu/~drclaw/asterisk/cidname/
  • MacinTalk AGI: Bash скрипт, который синтезирует речь из текста, используя MacinTalk Asterisk AGI MacinTalk
  • Дистрибуционный пакет LCDial.sh AGI script содержит файл sh-agi.inc, содержащий примитивы для различных нужд, такие как: sh_agi_cmd, sh_agi_getvariable и sh_agi_log, для облегчения создания AGI скриптов для интерпретаторов bash и ash.

Замечания

Вывод в CLI консоль


>>По некоторым причинам, мой AGI perl скрипт не может выводить сообщения в консоль CLI,
>>используя стандартный поток вывода ошибок (stderr). Я запустил тестовый скрипт
>>agi-test.agi, который идет в поставке вместе с asterisk, и выяснил, что проблема
>>не в коде скрипта. Asterisk всегда запускается с четырьмя или более параметрами
>> "-v", но в CLI консоли ничего не выводиться. Имеются ли для этой проблемы
>>какие-нибудь значительные изменения в интерфейсе AGI в cvs-head версии?
>>Я использую Asterisk CVS-D2005.08.05.
>
>Это известная проблема. Сервер Asterisk принимает сообщения через STDERR
>от AGI скриптов только в ту консоль (tty) где запущен сам Asterisk. Вы можете
>переключить актуальную консоль сервера Asterisk, например на tty9 или запустив
>сервер без использования фонового режима, например, так: "asterisk -cvvv".
>
>Это незначительная проблема для большинства пользователей.


Мы запускаем сервер asterisk в отключенном (detached) экране, используя утилиту GNU screen. Мы используем флаг 'L' для ведения логов в текстовый файл, по необходимости.
Выполняя команду "screen -r", мы в любое время можем получить CLI консоль сервера asterisk, если это необходимо.

/usr/bin/screen -L -d -m -S asterisk /usr/sbin/asterisk -vvvvvvvvvvvvvvvvvvvvvgc

Смотри: http://www.gnu.org/software/screen/


Некоторые заметки

  • Используя команду verbose в AGI скрипте, Вы можете отправлять информация обратно в CLI ) консоль таким же образом, как это делают другие приложения. Указывая для различной информации, которую Вы хотите вывести в консоль из Вашего AGI скрипта, различные уровни важности выводимой информации (verbosity levels), Вы получите результат, аналогичный по алгоритму, выводу других приложений сервера Asterisk. Убедитесь, что Вы читаете результат выполнения команды VERBOSE (как впрочем, и результаты всех других AGI команд), перед тем, как выполнить следующую команду AGI. Заметьте, что команда VERBOSE имеет проблемы со строками заключенными в кавычки, к примеру, с CALLERID (команда verbose обрежет строку по первому символу пробела).
  • При использовании расширения EAGI, у Вас появляется возможность получать звуковой поток из канала в Ваше приложение. Но при этом у Вас нет возможности отправки звуковой информации в канал. Расширение EAGI позволяет Вам использовать скрипт для передачи звуковой информации, полученной из канала, во внешние приложения - такие как, Sphinx конвертор речь-текст/приложение для распознавания речи (как в скрипте с примером, поставляемым вместе с asterisk). Ваше EAGI приложение также должно ждать тестового ответа от вызываемого внешнего приложения. В случае с Sphinx - это будет текст, который распознала эта программа из полученного звукового потока.
  • Всегда используйте AGI, если Вам нет надобности в дополнительных возможностях, которые содержаться в расширении EAGI - иначе, Вы можете получить непредсказуемый результат.
  • Команды, такие как: "send text", могут привести к ошибкам выполнения скрипта, если он используется совместно с телефонами, которые не поддерживают запрашиваемый тип медиаданных.
  • GET VARIABLE: не работает с глобальными переменными. Также может не работать с некоторыми переменными, которые создаются загружаемыми модулями.
  • Описание новых команд (PUT SOUNDFILE, GET SOUNDFILE,...) можно найти тут: http://free.oxymium.net/Asterisk/AGIAddOns/

Оригинал: http://www.voip-info.org/wiki/view/Asterisk+AGI