API 事件推送

本文介绍 千量级 IPPBX 两种不同的事件推送方式及其通信协议、通信端口和交互流程。

事件推送方式配置

千量级 IPPBX 支持 TCP 长连接向应用服务器推送 TCP 事件报告，也支持 TCP 短连接向应用服务器推送 HTTP 事件报告。你可以在 PBX API 网页设置页面，选择发送事件报告的方式。

HTTP 事件推送

通信协议
PBX 采用 TCP 短连接的方式发送 HTTP 事件报告。
短连接时，PBX 每次推送事件都会新建 TCP 连接，应用服务器收到事件后应断开连接。
通信端口
应用服务器请求 获取 API token，登录 PBX 时，需要带 port 参数。port 表示事件报告监听端口。PBX 将事件报告通过该端口发送到应用服务器。
事件报告格式
JSON 格式。
推送前提
选用此方式推送事件报告，应用服务器必须先获取 API token 连接到 PBX，并且保持 token 的有效性，否则应用服务器无法接收到事件报告。
交互流程
下图为 HTTP 事件推送流程示例图。

TCP 事件推送

通信协议
PBX 采用 TCP 长连接的方式发送 TCP 事件报告。

长连接时，PBX 会一直推送事件，直到 TCP 连接断开。网络异常或应用服务器断开了连接，应用服务器需要重新建立 TCP 连接到 PBX。

通信端口
在 PBX 二次开发接口 页面设置 TCP 端口，PBX 会通过该 TCP 端口发送 TCP 事件到应用服务器。
事件报告格式
报告的格式为 JSON。
推送前提
选用此方式推送事件报告，应用服务器先建立 TCP 连接到 PBX，并发送 login 数据包连接到 PBX，PBX 授权后才会推送事件报告。
TCP login 数据包格式如下：
Action: login
Username: {username}
Secret: {password}
Version: {version}
  • {username}：在 PBX 二次开发接口 页面配置的 API 访问用户名。
  • {password}：在 PBX 二次开发接口 页面设置的 API 访问密码明文。
  • {version}：API 版本号。本次版本为 2.0.0。
交互流程
PBX 向应用服务器推送 TCP 事件时，应用服务器作为 TCP 客户端，PBX 作为 TCP 服务器。下图为 TCP 事件的交互流程图。
注： 流程图中的 login 数据包为示例，你需要根据 PBX 的 二次开发接口设置的用户名和密码发送 TCP login 数据包。