Asterisk Manager API(AMI) 中文文档

### Asterisk Manager Interface (AMI) 中文文档概览 #### 一、引言 Asterisk Manager Interface (AMI) 是一款强大的工具，它允许开发者通过TCP/IP协议与Asterisk PBX系统进行交互，实现远程管理和监控功能。本文档旨在为用户提供关于AMI的基本概念、协议细节、以及如何通过AMI来执行特定管理任务的指南。 #### 二、AMI概述 Asterisk Manager Interface (AMI) 提供了一个基于文本的协议，使管理客户端能够与Asterisk实例进行通信。这种通信是双向的，客户端不仅可以发送命令给Asterisk，还能够接收来自Asterisk的事件通知。通过这种方式，开发者能够轻松地监控和管理Asterisk系统中的各种活动，包括但不限于电话呼叫的状态、设备的状态以及系统的配置等。 #### 三、协议特性 AMI采用了一种简单但高效的“键值对”协议来进行信息的传递。每个数据包都是由一系列键值对组成的，每行数据以回车换行(\r\n)结尾。协议的主要特点是： - **连接建立**：在发送任何命令之前，必须先建立连接。 - **数据传输**：一旦完成认证，数据包可以在任意时刻从任一方向传输。 - **数据包分类**： - **Action**：由管理客户端发送到Asterisk的数据包，用于请求执行特定的操作。 - **Response**：Asterisk对管理客户端动作的响应。 - **Event**：与Asterisk核心或扩展模块发生的事件相关的信息。 - **结束标志**：空行(两个连续的回车换行)表示命令的结束，Asterisk开始处理命令。 - **数据包顺序**：数据包内的各行顺序可以变化，不影响数据包的意义。 #### 四、建立管理连接与身份验证 为了与Asterisk进行管理通信，客户端需要建立到Asterisk服务器监听端口(通常是5038)的TCP/IP连接，并通过发送“Login”动作进行身份验证。身份验证通常需要预先在Asterisk服务器上配置一个用户账户，账户信息存储在`/etc/asterisk/manager.conf`文件中。 示例登录命令： ``` Action: login Username: admin Secret: secret ``` 如果需要关闭事件数据包的发送，可以在登录命令中添加`Events: off`： ``` Action: login Username: admin Secret: secret Events: off ``` #### 五、动作数据包 动作数据包是由客户端发送到Asterisk的数据包，用于请求执行特定的操作。这些操作包括但不限于挂断特定通道、改变监控设置等。数据包的格式如下： ``` Action: <actiontype><CRLF> <Key1>: <Value1><CRLF> <Key2>: <Value2><CRLF> ... <CRLF> ``` 其中`<actiontype>`是动作类型，`<Key>`和`<Value>`是动作的具体参数。 #### 六、管理动作详解 下面列举了一些常见的管理动作及其参数示例： 1. **AbsoluteTimeout**：这个命令可以用来要求Asterisk在指定的秒数之后挂断特定的通道。 - 参数： - Channel: 需要挂断的通道名称，如SIP/123-1c20。 - Timeout: 通道应该挂断的秒数。 - 示例： ``` Action: AbsoluteTimeout Channel: SIP/123-1c20 Timeout: 20 ``` 2. **ChangeMonitor**：更改记录某通道信息的文件名。 - 参数： - Channel：通道名称。 - File：文件名。 - 示例： ``` Action: ChangeMonitor Channel: SIP/x7065558529-1c20 File: 20050103-140105_cc51 ``` 3. **Command**：发送Asterisk CLI命令。 - 参数： - Command：Asterisk CLI命令。 - 示例： ``` Action: Command command: ShowChannels ``` #### 七、结论 Asterisk Manager Interface (AMI) 为开发者提供了一个强大而灵活的工具，使其能够通过TCP/IP网络与Asterisk PBX系统进行交互。无论是监控系统状态还是执行特定管理任务，AMI都能胜任。了解并掌握AMI的工作原理和使用方法对于任何从事Asterisk开发和管理工作的人来说都是非常重要的。