Asterisk+manager+API(中文文档)

AsteriskmanagerAPI（AMI）文档(中文版)1概述Asterisk控制接口（AMI）允许管理客户端程序连接到一个asterisk实例并且可以通过TCP/IP流发送命令或读取事件。这在试图跟踪asterisk的状态或其中的电话客户端状态时很有用，AMI说明了客户端基于的一般(可能是动态的)规则。一种简单的key:value协议用于已连接的管理客户端和asteriskＰＢＸ之间的信息传递。每行都用回车换行（\r\n）来结束。2命令集功能介绍2.1概述2.1.1协议特点在发送命令前，你必须建立一个连接。下面是以php脚本语言所建立起来的连接#!/usr/bin/php-q?php$timeout=100;$ipaddr=127.0.0.1;$ipport=5038;$socket=fsockopen($ipaddr,$ipport,$errno,$errstr,$timeout);if(!$socket){echo$errstr($errno)br\\n;}else{echoconnectIP:($ipaddr)success;echosocket($socket);fputs($socket,Action:login\r\n);fputs($socket,UserName:admin\r\n);fputs($socket,Secret:admin\r\n);fputs($socket,Events:off\r\n\r\n);while(!feof($socket)){echofgets($socket,128);}}fclose($socket);?程序运行后显示如下：[root@uccp_2test]#./test.phpconnectIP:(127.0.0.1)successsocket(Resourceid#4)AsteriskCallManager/1.1Response:SuccessMessage:Authenticationaccepted在认证后，数据包任何时间都可以在两个方向上互相传输。数据包第一行为Action时表明是由管理客户端发送到asterisk，第一行为Event或Response表明有asterisk发送到管理客户端。数据包内各行顺序可以变化，对数据包没有影响。回车换行由于区分每一行，空行（两个连续回车换行）用于表明命令结束，Asterisk开始处理命令。2.1.2数据包类型数据包的类型通过一下几种关键字来划分Action:一个由管理客户端发送到Asterisk的数据包，请求执行特定的动作。只有有限的几种动作供客户端使用，每个动作是由Asterisk服务器上的模块所决定的。一次只能执行一个动作，该动作数据包包含了动作名称以及执行所必需的参数。Response:Asterisk对管理客户端动作的响应。Event:有关Asterisk核心或扩展模块发生事件的信息。2.1.3建立管理连接和用户身份验证为了与Asterisk进行管理通话，管理客户端必须建立到Asterisk服务器侦听端口（一般是5038）的TCP/IP连接，并使用登陆动作进行身份验证。这就要求在Asterisk服务器上创建用户账户，用户账户在/etc/asterisk/manager.conf中配置。账户由允许登陆的主机，登录密码以及被授予的权限列表组成。登录和身份验证的经理，你必须发送一个登录行动，用您的用户名和秘密（密码作为参数）。Hereisanexample:下面是一个例子：(允许10.0.65.*主机进行连接)Action:loginUsername:adminSecret:secretcatmanager.conf[general]displaysystemname=yesenabled=yeswebenabled=noport=5038;httptimeout=60bindaddr=0.0.0.0displayconnects=yestimestampevents=yes[freeiris]secret=freeirisdeny=0.0.0.0/0.0.0.0permit=10.0.65.0/255.255.255.0writetimeout=100read=system,call,log,verbose,command,agent,userwrite=system,call,log,verbose,command,agent,user你还可以通过Events:off阻止事件数据包发送到你的连接。例如：Action:loginUsername:adminSecret:secretEvents:off动作数据包：向Asterisk发送动作时，额外的关键字可以提供进一步的动作信息。例如，你可能希望指定号码或通道的断开。此外，如果您的操作会导致Asterisk来执行拨号规则中的条目，你可以传递变量给拨号规则。这与你传递关键字的方式是一样的。向Asterisk发送动作数据包时，按照以下格式：Action:actiontypeCRLFKey1:Value1CRLFKey2:Value2CRLF...Variable:Variable1=Value1CRLFVariable:Variable2=Value2CRLF...CRLF2.1.4管理动作（Action）通过CLI命令showmanagercommands的输出结果就是管理动作列表。具体如下：2.2AbsoluteTimeout:设置通道超时这个命令将要求Asterisk在指定秒数后挂断特定的通道，从而有效地结束通话。参数：Channel:哪些渠道挂断，如SIP/123-1c20Timeout:到通道应挂断的秒数例子：请求信息Action:AbsoluteTimeoutChannel:SIP/123-1c20Timeout:20返回成功信息Response:SuccessMessage:TimeoutSet返回失败信息Response:ErrorMessage:Nosuchchannel2.3ChangeMonitor：更改记录文件更改记录某通道信息文件名。参数：Channel：通道名称File：文件名例子：发送请求ACTION:ChangeMonitorChannel:SIP/x7065558529-1c20File:20050103-140105_cc51返回失败信息Response:ErrorMessage:Nosuchchannel返回成功信息Response:SuccessMessage:Stoppedmonitoringchannel2.4Command：发送CLI命令发送AsteriskCLI命令。参数：Command：AsteriskCLI命令。例子：发送请求ACTION:COMMANDcommand:coreShowChannels返回信息Response:FollowsChannel(ContextExtensionPri)StateAppl.Data0activechannel(s)--ENDCOMMAND-注意：返回的事件响应结果并不是发送一个回车换行（\r\n）,而只发送回车（\n）,如果你在中断处理程序中只等待回车换行，那么这条信息将会被被抛弃。例如command返回信息如下：Response:Follows\r\nChannelLocationStateApplication(Data)\nSIP/x7065551212b-1af(None)RingingAppDial((OutgoingLine))\nSIP/x7065551212c-2aa29@default:2RingDial(SIP/x7065551212b)\n2activechannels\n1activecall\r\n--ENDCOMMAND--\r\n\r\n2.5Events：启动/禁用事件控制流事件控制流，用于启用/禁用发送给管理客户端的事件。参数：EventMask:'on'表示所有事件均会被发送到管理客户端。'off'表示所有时间都不会被发送。'system,call,log'用于选择被发送的事件。提示：有些事件是启用或禁已经在.conf文件中配置了，Theymightbedisabledbydefault.他们可能是默认为禁用。例子：注意在此例子中EventMask事件没有立即返回的响应信息，只有在设备注销时才返回相关信息。发送请求：ACTION:EVENTSEVENTMASK:ON返回信息：Event:PeerStatusPeer:SIP/ChannelNamePeerStatus:UnregisteredCause:Expired当EventMask参数为'off'时会立即返回响应信息，如下：发送：ACTION:EVENTSEVENTMASK:OFF返回：Response:EventsOff2.6ExtensionState:检查分机的状态检查分机的状态。参数：Exten，Context，ActionID例子：发送：ACTION:ExtensionStateContext:defaultExten:2001ActionID:1接收：Response:SuccessActionID:1Message:ExtensionStatusExten:2001Context:defaultHint:SIP/2001Status:0Status状态代码：-1=扩展找不到0=空闲1=在使用2=忙4=不可用8=振铃16=正等待2.7GetVar：获取一个通道变量参数：Channel，Variable，actionIDActionID是一个可选的参数匹配信息。例子：发送：ACTION:GetVarChannel:SIP/5060-44d225d0Variable:extension成功返回：Response:SuccessValue:17065551419失败返回：Response:ErrorMessage:Nosuchchannel或Response:Successvarname:(null)2.8Hangup：挂断指定通道参数：Channel例子：发送：ACTION:HangupChannel:SIP/x7065558529-99a0接收：Event:UnlinkChannel1:SIP/127.180.254.109-44df88e8Channel2:SIP/x7065558529-99a0Uniqueid1:1124989110.20473Uniqueid2:1124989110.20474Event:HangupChannel:SIP/x7065558529-99a0Uniqueid:1124989110.20474Cause:16Event:HangupChannel:SIP/127.180.254.109-44df88e8Uniqueid:1124989110.20473Cause:16Response:SuccessMessage:ChannelHungup2.9IAXpeers：显示iax信息列表例子：发送：Action:IAXPeers接收：Name/UsernameHostMaskPortStatus8002(Unspecified)(D)255.255.255.2550UNKNOWN8001192.168.0.91(D)255.255.255.2554569OK(5ms)2iax2peers[1online,1offline,0unmonitored]2.10ListCommands：显示命令列表参数：ActionID例子:发送：Action：ListCommands接收：Response:SuccessAbsoluteTimeout:SetAbsoluteTimeout(Priv:call,all)AgentCallbackLogin:Setsanagentaslo