NGES交易系统交易API和行情API接口规范.doc

NGES 交易系统交易系统 交易交易 API 和行情和行情 API 接口规范接口规范 VersionVersion 1 201 20 发布日期 发布日期 20XX20XX 年年 6 6 月月 2020 日日 I 修订记录 核准记录和审核记录修订记录 核准记录和审核记录 修订记录修订记录 版本编号版本编号修订日期修订日期主要修订摘要主要修订摘要 1 20 R00220XX 5 4技术中心和技术公司 根据会员接入规范和 流程测试结果修改文档 1 20 R00120XX 12 4技术公司 增加灾备接口 增加主题查询接 口说明 1 12 R00320XX 01 28 技术公司 增加 RESTART RESUME 和 QUICK 三种数据流恢复模式 1 12 R00220XX 12 17 技术部 合并 TraderAPI 和 MduserAPI 文档 调整部分章节内容 1 12 R00120XX 12 11 技术公司 增加了错误代码处理 增加了私 有流序列号设置功能 增加了前置机 NameServer 内容 但暂时不开放 1 08 R00120XX 8 31 上海期货交易所技术部 根据 NGES V1 08 交易系统修改部分接口 提高压缩效率 增 加交易员私有流 1 0020XX 8 11上海期货信息技术有限公司制定初稿 核准记录核准记录 核准人员核准人员属于部门 单位 属于部门 单位 核准日期核准日期 严少辉严少辉技术中心技术中心20XX 6 20 审核记录审核记录 审核人员审核人员属于部门 单位 属于部门 单位 审核日期审核日期 邹文军邹文军技术中心技术中心20XX 5 20 文件制作和维护 上海期货交易所技术部 上海期货信息技术有限公司 文件制作和维护 上海期货交易所技术部 上海期货信息技术有限公司 目目 录录 第一部分 第一部分 NGES 交易系统接口介绍交易系统接口介绍 本部分主要介绍 NGES 交易系统的接口 包括 第一章引入 NGES 交易系统的两个接口 TraderAPI 用于会员系统下达交 易 控制和查询指令 接收私有流 含报单插入 报单操作响应和成交回报 公共流 市场控制提示 响应流和查询流 查询结果 MduserAPI 用于会员 系统和行情转发商系统接收行情流 第二章介绍了两个 API 之后使用的通信协议 FTD Futures Trading Data Exchange Protocol 重点说明了数据流 第三章介绍了两个 API 对应于不同类型应用的编程接口 第四章介绍了 API 的工作模式 包括线程之间的通信 心跳机制和私有流 信息传输的可靠性实现 作为 NGES 交易系统的接口基础 TraderAPI 和 MduserAPI 的用户应该仔 细阅读第一部分内容 1 介绍介绍 1 1 背景背景 上海期货交易所于 20XX 年 11 月 3 日成功上线了 新一代交易所系统 简称 NGES 的第一阶段项目 其中包括交易系统 简称 NGES 交易系统 NGES 交易系统使用了开放的主流平台 可以运行在 Unix 和 Windows 操作系 统上 在中国证监会信息中心的统一领导下 上海期货交易所 简称 SHFE 或者 交易所 郑州商品交易所 简称 CZCE 和大连商品交易所 简称 DCE 联合 研究了期货交易数据交换标准 Futures Trading Data Exchange Protocol 简称 FTD 或者 FTD 协议 中国证监会于 20XX 年 3 月 25 日发布了 FTD JR T 0016 20XX 并于同日作为行业标准实施 NGES 交易系统本质上使用 FTD 作为会员远程交易的主接入协议 同时为 保持兼容和会员远程交易系统平稳切换 NGES 交易系统支持原有基于 Stratus 交易主机的 V1 和 V2 版本的接口 分别简称为 OFPV1 和 OFPV2 OFPV1 和 V2 在 NGES 交易系统内部通过前置机实现了到 FTD 的翻译和转换 和 OFPV1 和 V2 不同 FTD 协议体系较为复杂 为简化会员端远程交易系 统的开发难度 同时也为提高交易系统运行的可靠性 SHFE 不建议会员的远 程交易系统 简称会员系统或者会员端 直接使用 FTD 协议接入 NGES 交易系 统 为此 上海期货交易所发布了 NGES 交易系统的交易 API 接口 简称 NGES TraderAPI 或者 TraderAPI 和行情 API 接口 简称 NGES MduserAPI 或 者 MduserAPI 会员系统调用 TraderAPI 即可完成与 NGES 交易系统的对接 接收到交易 所的报单和成交回报后 TraderAPI 将回调 Callback 会员系统 会员系统或者 行情转发商 简称行情商 会员和行情转发商接收交易所行情的系统统称为行 情接收端程序 系统调用 MduserAPI 即可完成与 NGES 交易系统的对接 接收 到交易所的行情后 MduserAPI 将回调 Callback 行情接收端程序 又称为行 情接收系统 TraderAPI 把与 NGES 交易系统之间复杂的协议转换 数据同步和网络通 信进行了封装 TraderAPI 通过建立一个基于 TCP 的虚链路通道与 NGES 交易 系统交易前置机的连接 实现会员系统的报单等交易行为 通过 TraderAPI 建 立的连接通道具有多地址注册 断线自动重连和交易数据自动重传等特点 MduserAPI 与 TraderAPI 类似 建立一个基于 TCP 的虚链路通道与 NGES 交易系统行情前置机的连接 实现行情的订阅和接收 1 2 TraderAPI 简介简介 TraderAPI 是一个基于 C 的类库 通过使用和扩展类库提供的接口来实现 全部的交易功能 包括报单与报价的录入 报单与报价的撤销 报单与报价的 挂起 报单与报价的激活 报单与报价的修改 报单与报价的查询 成交单查 询 会员客户查询 会员持仓查询 客户持仓查询 合约查询 合约交易状态 查询 交易所公告查询 该类库包含以下 5 个文件 文件名版本文件大小文件描述 FtdcTraderApi hV1 20交易接口头文件 FtdcUserApiStruct h V1 20 定义了 UserAPI 所需的一系列数据类 型的头文件 FtdcUserApiDataType h V1 20 定义了一系列业务相关的数据结构的 头文件 traderapi dllV1 20动态链接库二进制文件 traderapi libV1 20导入库文件 支持 MS VC 6 0 MS VC NET 20XX 编译器 需要打开多线程编译选项 MT 注意 注意 NGES 交易系统支持许多新的报单指令 比如市价 最优价 组合 交易等 还支持新的交易品种 比如期权及其报价 但受现有交易规则限制 NGES 交易系统并没有开放上述功能 会员系统在开发过程中需注意 当前版当前版 本不开放的业务本不开放的业务 同时在每个功能描述中的具体描述 1 3 MduserAPI 简介简介 MduserAPI 也是一个基于 C 的类库 通过使用和扩展类库提供的接口来 实现全部的行情订阅和接收功能 该类库包含以下 5 个文件 文件名版本文件大小文件描述 FtdcMduserApi hV1 20行情接口头文件 FtdcUserApiStruct h V1 20 定义了 UserAPI 所需的一系列数据类 型的头文件 FtdcUserApiDataType h V1 20 定义了一系列业务相关的数据结构的 头文件 mduserapi dllV1 20动态链接库二进制文件 mduapi libV1 20导入库文件 支持 MS VC 6 0 MS VC NET 20XX 编译器 需要打开多线程编译选项 MT 1 4 TraderAPI MduserAPI 发行的平台发行的平台 目前发布了以下操作系统平台的版本 Intel X86 WindowsXP 包括 h 文件 dll 文件和 lib 文件 Intel Linux 包括 h 文件和 so 文件 在 RedHat kernel 2 6 9 42 下完成编 译 如果需要其他操作系统版本请和下面相关人员联系 联系人 王君鹏联系人 王君鹏 电话 电话 86 21 68400751 手机 手机 86 0邮箱 邮箱 1 5 修改历史修改历史 1 5 1 版本版本 1 20 本版本基于 NGES 交易系统交易 API 和行情 API 接口规范 V1 12 R003 修改 主要有以下变更 本版本提供了灾备功能 增加 4 10 灾备接口 简要说明了灾备原理 由于登录报文中增加了数据中心代码 TraderAPI MdUserAPI 修 改了 ReqUserLogin 和 OnRspUserLogin 方法的参数 TraderAPI 中增加了 数据流回退通知 OnRtnFlowMessageCancel 方法的说明 本版本提供了数据流长度的查询功能 登录交易系统时 应答中会返回当前会员私有流长度和交易员私有 流长度 TraderAPI MdUserAPI 增加了对 ReqQryTopic 和 RspQryTpoic 方 法说明 用于查询流长度 对以前版本发现问题的修正 TraderAPI MdUserAPI 增加了 GetVersion 方法说明 之前版本虽 提供功能但无文档说明 MdUserAPI 增加了 RegisterNameServer 方法说明 之前版本虽提供 功能但无文档说明 修改了联系人 将周军改成王君鹏 2 FTD 体系结构体系结构 会员和行情商的系统并不直接与 NGES 交易系统的核心主机通信 从安全 隔离角度上看 会员和行情商甚至不能意识到有交易撮合主机和行情主机的存 在 会员和行情商只能连接到上述主机的两个代理服务器 分别是交易前置机 简称交易前置 也被称为交易系统或交易所系统 和行情前置机 简称为行 情前置 交易前置机负责会员系统的交易业务 但不负责发送行情 此项功能 由行情前置机完成 TraderAPI 使用建立在 TCP 协议之上的 FTD 协议与 NGES 交易系统的前置 机通信 MduserAPI 使用建立在 TCP 协议之上的 FTD 协议与 NGES 交易系统的行 情前置机通信 行情前置负责处理行情接收系统的行情订阅请求 并将所订阅 的行情推送到行情接收系统 2 1 通讯模式通讯模式 FTD 协议中的所有通讯都基于某个通讯模式 通讯模式实际上就是通讯双 方协同工作的方式 FTD 涉及的通讯模式共有三种 对话通讯模式 私有通讯模式 广播通讯模式 对话通讯模式是指由会员系统主动发起的通讯请求 该请求被交易系统接 收和处理 并给予响应 例如报单 查询等 这种通讯模式与普通的客户 服务 器模式相同 私有通讯模式是指交易系统主动 向某个特定的会员或者特定会员的某个 特定交易员发出的信息 例如成交回报等 广播通讯模式是指交易系统主动 向市场中的所有会员都发出相同的信息 例如公告 市场公共信息等 通讯模式和网络的连接不一定存在简单的一对一的关系 也就是说 一个 网络连接中可能传送多种不同通讯模式的报文 一种通讯模式的报文也可以在 多个不同的连接中传送 无论哪种通讯模式 其通讯过程都如图 1 所示 会员系统交易所系统 发送请求 如果在对话模式下 给出响应 如果在对话模式下 连接请求 连接确认 身份认证请求 身份认证响应 发出私有信息 如果在私有模式下 发出市场公告 如果在市场模式下 断开请求 断开确认 图表图表 1各通讯模式的工作过程各通讯模式的工作过程 2 2 数据流数据流 交易前置支持对话通讯模式 私有通讯模式 广播通讯模式 行情前置的 行情转发功能支持对话通讯模式 广播通讯模式 1 对话通讯模式 对话通讯模式 对话通讯模式下支持对话数据流和查询数据流 对话数据流是一个双向数据流 会员系统发送交易请求 交易系统反馈应 答 交易系统不维护对话流的状态 系统故障时 对话数据流会重置 在途的 数据可能会丢失 查询数据流是一个双向数据流 会员系统发送查询请求 交易系统反馈应 答 交易系统不维护查询流的状态 系统故障时 查询数据流会重置 在途的 数据可能会丢失 2 私有通讯模式 私有通讯模式 在私有通讯模式下 数据流是可靠的 在一个交易日内 会员系统断线后 恢复连接时 可以请求交易系统发送指定序号之后的私有数据流数据 私有数 据流向会员系统提供报单状态报告 成交回报更等信息 私有数据流分为会员 私有流和交易员私有流两种 交易系统维护每个会员的私有流 有关该会员的回报信息 如报单回报 成交回报等都通过会员私有流下发 交易员要有足够的权限才可以订阅会员私 有流 交易员私有流与会员私有流类似 但只包含该交易员发起的交易引发的回 报信息 每个交易员都可以订阅自已的交易员私有流 3 广播通讯模式 广播通讯模式 广播通讯模式下支持公共数据流 公共数据流是一个单向数据流 由交易系统或者行情系统发向会员系统 用于发送市场公共信息 公共数据流是一个可靠的数据流 交易系统维护整个 系统的公共数据流 在一个交易日内 会员系统断线恢复连接时 可以请求交 易系统发送指定序号之后的公共数据流数据 以行情为例 行情数据流是一个公共数据流 由行情发布系统发向会员系 统 用于发送行情信息 行情流是一个可靠的数据流 交易系统维护整个系统 的行情流 在一个交易日内 行情接收系统断线恢复连接时 可以请求交易系 统发送指定序号之后的行情流数据 交易系统所提供的行情内容是按照主题组织的 每个主题包括一组合约的 行情 还包括了行情发布内容和发布方式 包括行情深度 采样频率 延迟时 间等 交易所会公布各行情主题的具体内容 并设定每个行情用户所能订阅的 行情主题 每个行情主题对应着一个行情流 要获得行情通知 行情接收系统必需在连接行情前置后 订阅一个或多个 行情发布主题 3 接口模式接口模式 3 1 TraderAPI 接口接口 TraderAPI 提供了二个接口 分别为 CShfeFtdcTraderApi 和 CShfeFtdcTraderSpi 这两个接口是对 FTD 协议的封装 会员系统可以通过 CShfeFtdcTraderApi 发出操作请求 通过继承 CShfeFtdcTraderSpi 并重载回调函数来处理交易系统的回复或响应 3 1 1 对话流和查询流编程接口对话流和查询流编程接口 通过对话流进行通讯的编程接口通常如下 请求 请求 int CShfeFtdcTraderApi ReqXXX CShfeFtdcXXXField pReqXXX int nRequestID 响应 响应 void CShfeFtdcTraderSpi OnRspXXX CShfeFtdcXXXField pRspXXX CShfeFtdcRspInfoField pRspInfo int nRequestID bool bIsLast 其中请求接口第一个参数为请求的内容 不能为空 该参数根据请求命令 的不同使用具有不同的类 该类的成员变量的类型和合法的数值请参阅附录中 的 枚举值列表枚举值列表 和 数据类型列表数据类型列表 请求接口的第二个参数为请求号 请求号由会员系统负责维护 交易所建 议每个请求的请求号不会重复 在接收交易系统的响应时 可以得到当时发出 请求时填写的请求号 从而可以将响应与请求对应起来 当收到交易系统应答时 CShfeFtdcTraderSpi 的回调函数会被调用 如果响 应数据不止一个 则回调函数会被多次调用 回调函数一共包含四个参数 其中 第一个参数为响应的具体数据 如果出错或没有结果有可能为 NULL 第二个参数为处理结果 表明本次请求的处理结果是成功还是失败 在发生多次 回调时 除了第一次回调 其它的回调该参数都可能为 NULL 第三个参数为请求号 即原来发出请求时填写的请求号 第四个参数为响应结束标志 表明是否是本次响应的最后一次回调 3 1 2 私有流编程接口私有流编程接口 私有流中的数据为会员或者交易员的私有信息 包括报单回报 成交回报 报价回报 执行宣告回报等 通过私有流接收回报的编程接口通常如下 void CShfeFtdcTraderSpi OnRtnXXX CShfeFtdcXXXField pXXX 或者或者 void CShfeFtdcTraderSpi OnErrRtnXXX CShfeFtdcXXXField pXXX CShfeFtdcRspInfoField pRspInfo 当收到交易系统通过私有流发布的回报数据时 CShfeFtdcTraderSpi 的回调 函数会被调用 回调函数的参数为回报的具体内容 3 1 3 公共流编程接口公共流编程接口 公共流中的数据中交易所的公共信息 包括合约 公告等 通过公共流接收回报的编程接口通常如下 void CShfeFtdcTraderSpi OnRtnXXX CShfeFtdcXXXField pXXX 当收到交易系统通过公共流发布的回报数据时 CShfeFtdcTraderSpi 的回调 函数会被调用 回调函数的参数为通知的具体内容 3 2 MduserAPI 接口接口 与 TraderAPI 类似 MduserAPI 提供了二个接口 分别为 CShfeFtdcMduserApi 和 CShfeFtdcMduserSpi 这两个接口是对 FTD 协议的封装 行情接收系统可以通过 CShfeFtdcMduserApi 发出操作请求 通继承 CShfeFtdcMduserSpi 并重载回调函数来处理交易系统的响应 3 2 1 对话流编程接口对话流编程接口 通过对话流进行通讯的编程接口通常如下 请求 请求 int CShfeFtdcMduserApi ReqXXX CShfeFtdcXXXField pReqXXX int nRequestID 响应 响应 void CShfeFtdcMduserSpi OnRspXXX CShfeFtdcXXXField pRspXXX CShfeFtdcRspInfoField pRspInfo int nRequestID bool bIsLast 其中请求接口第一个参数为请求的内容 不能为空 请求接口的第二个参数为请求号 请求号由行情接收系统应用程序负责维 护 正常情况下每个请求的请求号不会重复 在接收交易系统的响应时 可以 得到当时发出请求时填写的请求号 从而可以将响应与请求对应起来 当收到交易系统应答时 CShfeFtdcMduserSpi 的回调函数会被调用 如果 响应数据不止一个 则回调函数会被多次调用 回调函数一共包含四个参数 其中 第一个参数为响应的具体数据 如果出错或没有结果有可能为 NULL 第二个参数为处理结果 表明本次请求的处理结果是成功还是失败 在发 生多次回调时 除了第一次回调 其它的回调该参数都可能为 NULL 第三个参数为请求号 即原来发出请求时填写的请求号 第四个参数为响应结束标志 表明是否是本次响应的最后一次回调 3 2 2 行情流编程接口行情流编程接口 行情流中的数据包含了交易系统推出的行情信息 通过行情流接收回报的编程接口通常如下 void CShfeFtdcMduserSpi OnRtnXXX CShfeFtdcXXXField pXXX 当收到交易系统通过行情流发布的行情数据时 CShfeFtdcMduserSpi 的回 调函数会被调用 回调函数的参数为通知的具体内容 4 运行模式运行模式 4 1 工作流程工作流程 会员系统 行情接收系统和交易系统的交互过程分为 2 个阶段 初始化阶段 和功能调用阶段 4 1 1 初始化阶段初始化阶段 在初始化阶段 会员系统 行情接收系统的程序必须完成如下步骤 具体代 码请参考开发实例 顺序会员系统行情接收系统 1产生一个 CShfeFtdcTraderApi 实例 产生一个 CShfeFtdcMduserApi 实例 2产生一个事件处理的实例 产生一个事件处理的实例 3注册一个事件处理的实例 注册一个事件处理的实例 4订阅私有流 订阅公共流 订阅行情流 5设置交易前置 NameServer 的网络地址 1 设置行情服务 NameServer 的网络地址 1 6 初始化 初始化 1为了保持与上一版的兼容性 API 仍然提供了注册交易前置 行情服务 的接口 但 交易所建议不要使用这些接口 这些接口将在下一版本中取消 有关 NameServer 的说明参 见 4 9 前置机列表 4 1 2 功能调用阶段功能调用阶段 在功能调用阶段 会员系统可以任意调用交易接口中的请求方法 如 ReqUserLogin ReqOrderInsert 等 同时提供回调函数以响应回报信息 注意事 项 1 API 请求的输入参数不能为 NULL 2 API 请求的返回参数 0 表示正确 其他表示错误 详细错误编码请查 表 4 2 工作线程工作线程 会员 行情接收系统应用程序至少由两个线程组成 一个是应用程序主线程 一个是 API 工作线程 TraderAPI 或者 MduserAPI 应用程序与交易或者行情 前置的通信是由 API 工作线程驱动的 CShfeFtdcTraderApi 和 CShfeFtdcMduserApi 提供的接口是线程安全的 可 以有多个应用程序线程同时发出请求 CShfeFtdcTraderSpi 提供的接口回调是由 TraderAPI 工作线程驱动 通过实 现 SPI 中的接口方法 从交易前置收取所需数据 CShfeFtdcMduserSpi 提供的接口回调是由 MduserAPI 工作线程驱动 通过 实现 SPI 中的接口方法 从行情前置收取所需数据 如果重载的会员系统的应用程序的某个回调函数阻塞 则等于阻塞了 TraderAPI 或者 MduserAPI 工作线程 API 与交易 行情前置的通信会停止 因 此通常应该迅速返回 在 CShfeFtdcTraderSpi 和 CShfeFtdcMduserSpi 派生类的 回调函数中 可以利用将数据放入缓冲区或通过 Windows 的消息机制来实现迅 速返回 SPI对象 API请求的应答 委托修改信息 成交信息 错误委托信息 合约资料修改信息 等等 交易前置 API对象 登陆请求 委托请求 查询请求 等等API请求 会员报盘程序 SPI对象 行情信息 行情前置 API对象 登陆请求 订阅请求 行情接收系统 图表图表 2 TraderAPI工作线程工作线程图表图表 3 MduserAPI工作线程工作线程 4 3 会员系统使用会员系统使用 TraderAPI 与交易系统的交互与交易系统的交互 会员系统通过 TraderAPI 与交易系统交互 会员系统的请求通过 TraderAPI 发送到交易系统 交易系统返回的应答和回报通过 TraderAPI 返回给会员系统 TraderAPI 的交易接口和私有流接口会有相互关联 如用户报单录入 ReqOrderInsert 马上会收到报单响应 OnRspOrderInsert 说明交易系统已经收 到报单 报单进入交易系统后 如果报单的交易状态发生变化 就会收到报单 回报 OnRtnOrder 如果报单被撮合 包括全部成交和部分成交 就会收到成交 回报 OnRtnTrade 其中 一个用户的报单回报和成交回报也会被所属会员下其 他的交易员接收到 如果该用户不使用仅接收交易员私有流方式登录 以交易员日常交易为例 有两个会员系统 A 和 B 发生的事件包括 1 交易员 A 报单 cu0711 买 20 手 64000 元 CShfeFtdcTraderApi ReqOrderInsert 报单录入请求 本函数由会员系统的应 用主线程调用 通过对话流发送到 NGES 交易系统前置机 交易系统报单处理 报单系统编号为 1 由于此时撮合队列中无对手 报单状态为 未成 交还在队列中 NGES 交易系统的前置机发出报单响应给交易员 A 的对话流 发出报单 回报给交易员 A 的私有流和交易员 A 所属会员的私有流 响应和回报的报文由 TraderAPI 工作线程处理并调用 Spi 对象的方法 CShfeFtdcTraderSpi OnRsqOrderInsert 交易所的交易前置给出请求的应答 内容为 录入成功 本地编号为 1 的报单的系统编号为 1 本函数由 TraderAPI 工作线 程在收到交易前置应答后调用 CShfeFtdcTraderSpi OnRtnOrder 交易所的交易前置立即在交易员 A 所属会员的 私有流中或者交易员 A 的私有流中给出报单回报 因其他席位无法获得报单的具体信息 为保持信息同步 因此回报内容包括报单的状态等报单的全部内容 本函数由 TraderAPI 工作线程在收到交易前置的报单回报后调用 如果会员 A 还有其他交易员连 接并登录到交易系统 并且接收会员私有流 将收到相同的报单回报 以下同 2 交易员 B 报单 cu0711 卖 10 手 64000 元 CShfeFtdcTraderApi ReqOrderInsert 报单录入请求 交易系统报单处理 报单系统编号为 2 由于此时撮合队列中无对手 报单状态为 未成 交还在队列中 交易系统报单处理 报单系统编号为 2 尝试撮合并能成交 因此报单状态为 完全成交 NGES 交易系统的前置机发出报单响应给交易员 B 的对话流 发出报单回报给交易员 B 的私有流和交易员 B 所属的会员私有流 发出报单回报给交易员 A 的私有流和交易员 A 所属会员的私有流 提示系统编号为 1 的报单状态交易系统已经修改为 部分成交还在队 列中 报单的 剩余数量 调整为 10 手 发出成交回报给交易员 B 的私有流和交易员 B 所属的会员私有流 发出成交回报给交易员 B 的私有流和交易员 B 所属的会员私有流 NGES 交易系统将确保报单的回报在成交回报之前送达会员系统 并且报单回报中的交易系统将确保报单的回报在成交回报之前送达会员系统 并且报单回报中的 剩剩 余数量余数量 字段已经反映交易系统报单簿中的最新数量 没有必要再根据成交回报的数量再字段已经反映交易系统报单簿中的最新数量 没有必要再根据成交回报的数量再 调整 调整 CShfeFtdcTraderSpi OnRsqOrderInsert 交易所的交易前置给出请求的应答 内容为 录入成功 本地编号为 1 的报单的系统编号为 2 CShfeFtdcTraderSpi OnRtnOrder 交易所的交易前置立即在交易员 B 所属会员的 私有流中或者交易员 B 的私有流中给出报单回报 报单状态为 完全成交 CShfeFtdcTraderSpi OnRtnOrder 交易所的交易前置立即在交易员 A 所属会员的 私有流中或者交易员 A 的私有流中给出报单回报 报单状态为 部分成交还在队列中 剩余数量为 10 手 CShfeFtdcTraderSpi OnRtnTrade 交易所的交易前置立即在交易员 A 所属会员的 私有流中或者交易员 A 的私有流中给出成交回报 CShfeFtdcTraderSpi OnRtnTrade 交易所的交易前置立即在交易员 B 所属会员的 私有流中或者交易员 B 的私有流中给出成交回报 3 交易员 A 撤单 下图说明了会员系统 TraderAPI 和交易系统之间的 UML 交互图 交易员API交易所交易系统交易员API 报单请求 本地号 1 cu0711 买 20手 64000元 报单应答 成功 本地号 1 系统号 1 报单回报 系统号 1 本地号 1 状态 未成交还在队列中 处理报单 报单请求 本地号 1 cu0711 卖 10手 64000元 处理报单 报单应答 成功 本地号 1 系统号 2 报单回报 系统号 1 本地号 1 状态 部分成交还在队列中 成交回报 成交号 1 系统号 1 本地号 1 报单回报 系统号 2 本地号 1 状态 完全成交 成交回报 成交号 1 系统号 2 本地号 1 撤单请求 系统号 1 撤单应答 成功 报单回报 系统号 1 本地号 1 状态 已撤单 处理撤单 说明 会员系统A CShfeFtdcTraderApi ReqOrderInsert CShfeFtdcTraderSpi OnRspOrderInsert CShfeFtdcTraderSpi OnRtnOrder CShfeFtdcTraderSpi OnRtnOrder CShfeFtdcTraderSpi OnRtnTrade CShfeFtdcTraderSpi OnRspOrderAction CShfeFtdcTraderApi ReqOrderAction 会员系统B CShfeFtdcTraderApi ReqOrderInsert CShfeFtdcTraderSpi OnRspOrderInsert CShfeFtdcTraderSpi OnRtnOrder CShfeFtdcTraderSpi OnRtnTrade 响应流私有流 图表图表 4会员系统与交易系统信息交互示例会员系统与交易系统信息交互示例 4 4 与交易所前置系统的连接与交易所前置系统的连接 TraderAPI 和 MduserAPI 使用建立在 TCP 协议之上的 FTD 协议与交易所的 交易 行情前置系统进行通信 TraderAPI 使用 CShfeFtdcTraderApi RegisterFront 方法注册交易所前置系统的网络地址 MduserAPI 使用 CShfeFtdcMduserApi RegisterFront 方法注册交易所行情前置系统的网络通讯地址 交易所拥有多个交易 行情前置系统 用于负载均衡且互为备份 从而提高 系统的性能和可靠性 为保证交易时通信的可靠性 TraderAPI 和 MduserAPI 可以注册多个前置 API 在初始化后 会从已注册的前置中随机挑选一个前置 尝试建立网络连接 如果不成功 则依次逐个尝试其它前置 直到连接成功为 止 如果在交易过程中网络连接出现故障 API 依然使用上述过程 尝试连接 其它前置 上海期货交易所将公布至少两台前置机的网络地址 位于上海期货大厦数 据中心 因此会员系统应该至少注册两个前置机的网络地址以防止所连交易前 置发生故障从而引发单点隐患 上海期货交易所正在建设张江灾备中心 届时 将发布另外至少两台前置机的网络地址 位于张江数据中心 鉴于 FTD 协议 的带宽要求比 OFPV1 和 OFPV2 高 建议会员使用 128K 以上 DDN 专线或者 2M SDH 数字专线 上海期货交易所和中国金融期货交易所将共享会员远程交 易网络接入 直接连接上海期货交易所的链路可以作为备份链路接入中国金融 期货交易所 反之亦然 4 5 本地文件本地文件 TraderAPI 在运行过程中 会将一些数据写入本地文件中 调用 CreateFtdcTraderApi 函数 可以传递一个参数 指明存贮本地文件的路径 该 路径必须在运行前已创建好 本地文件的扩展名都是 con MduserAPI 也与此类似 但函数名称为 CreateFtdcMduserApi 4 6 请求请求 应答日志文件应答日志文件 TraderAPI 提供了两个日志接口 用于记录通信日志 OpenRequestLog 用 于打开请求日志 OpenResponseLog 用于打开应答日志 日志打开后 所有的 业务请求将记入请求日志 所有的业务应答和回报将记入应答日志 注意 为 保密和节约存储空间 登录请求 应答和查询请求 应答不记日志 请求格式为 日期 时间 请求名称 请求结果 请求参数名 请求参数内容 应答格式为 日期 时间 应答名称 响应代码 响应信息 应答参数名 应答参数内容 回报格式为 日期 时间 回报名称 回报参数名 回报参数内容 4 7 可靠数据流的订阅方式可靠数据流的订阅方式 FTD 协议中私有流 公共流 行情流等可以保证数据可靠 有序地传送到 对方 称为可靠数据流 可靠数据流对于保证会员系统的数据正确性和完整性 非常重要 例如 会员系统通过交易系统发出的会员私有流中的各种回报 就 可以得到足够的信息 从而完成会员端的业务操作 为了保证会员系统业务的 正确性 就需要可靠 有序 唯一地接收私有流中的报文 可靠数据流是依靠重传来保证数据可靠 有序地传送的 即客户端负责管 理数据流的序号 如果出现传输中断 可以从指定序号开始 重新订阅数据流 来保证数据的完整性 对话流和查询流不支持重传 是不可靠的数据流 交易系统接口提供了两种管理可靠数据流的方式 API 维护重传报文序号 和会员系统维护重传报文的序号 4 7 1 API 维护重传报文的序号维护重传报文的序号 每当 API 收到一个可靠数据流报文 则 a 先调用 SPI 的回调函数通知会 员系统 b 将该报文的序号记入本地文件中 扩展名为 con 如果会员系统 退出后再重新订阅数据流 则可以使用本地文件中记录的报文序号来订阅数据 流 CShfeFtdcTraderApi 的 SubscribePrivateTopic 方法 SubscribePublicTopic 方 法 SubscribeUserTopic 方法和 CShfeFtdcMduserApi 的 SubscribeMarketDataTopic 方法用于订阅可靠数据流 通过接口参数可以指定重传方式 重传方式有三种 重发 RESTART 续传 RESUME 和快照 QUICK 重发 RESTART 方式从数据流中的第一个报文开始传输 这时 API 将忽略本地文件中记录的数据流报文序号 续传 RESUME 方式从本地文件中记录的数据流报文序号之后开始 传输 如果是行情流 则先传输该主题上各合约的那一时刻的行情快 照 再开始从指定的序号开始传输行情 为保持会员交易数据的完整 性 对于会员或者交易员私有流 交易所建议使用 RESUME 重传方式 快照 QUICK 方式从订阅这一时刻数据流最大序号开始传输 如果 是行情流 则先传输该主题上各合约的当前行情快照 快照方式主要 用于不需要保证数据完整性的场合 例如通讯或者软件故障后迅速接 收和恢复行情 对于会员或者交易员私有流 交易所不建议使用 QUICK 方式 API 维护重传报文的序号存在一定数据一致性的风险 例始 如果 a 完 成后 b 未完成 则会造成同一个报文两次回调到会员系统 从而导致会员 系统处理上比较困难 另外 如果记录数据流序号的本地文件损坏 则不得不 重传数据流 可能会影响会员系统的效率 如果使用 API 维护重传报文的序号 则 API 会将上次登录返回的 TradingDay 和 DataCenterID 这两个字段记录在文件中 resume con 登录时 API 会使用文件中的值覆盖会员系统所填的这两个字段 4 7 2 会员系统维护重传报文的序号会员系统维护重传报文的序号 每当 API 收到一个可靠数据流的报文 则 a 先调用 SPI 的 OnPackageStart 函数通知会员系统收到一个报文 b 调用 SPI 的回调函数通 知会员系统业务数据 c 最后调用 SPI 的 OnPackageEnd 函数通知会员系统该 报文的回调结束 在 OnPackageStart 和 OnPackageEnd 接口中 会员系统可以得 到当前回调的报文的序号 会员系统可以记录该序号 在重传可靠数据流时 将该序号做为 CShfeFtdcTraderApi ReqSubscribeTopic 方法的参数 与 RESUME 方式类似 通过 CShfeFtdcTraderApi ReqSubscribeTopic 方法 会员系统可以指定数据 流重传报文的序号 如果指定序号为 0 则重发整个数据流 与 RESTART 方 式类似 如果指定序号为 1 则从订阅这一时刻数据流最大序号开始传输 与 QUICK 方式类似 如果订阅的是行情流 则如果指定的重传序号不为 0 则先传输该序号报 文产生之前的各个合约的行情的快照 传输行情快照时 OnPackageStart 和 OnPackageEnd 回调函数的 nSequenceNo 参数值为 0 会员系统重传维护报文的序号比 API 维护重传报文的序号有更好的一致性 和可靠性 对事务完整性要求高的会员系统应尽量使用这个方法 注意登录时 TradingDay 和 DataCenterID 应填写为上次登录应答的返回值 如果是第一次登录或不需要续传 则 TradingDay 可以填空字符串 DataCenterID 可以填 0 或交易所公布的主数据中心代码 4 8 心跳机制心跳机制 Heartbeat 会员系统和交易所的前置机之间使用 TCP 虚链路进行通信 假设通讯链路 发生故障 并且在这段时间内会员系统和前置机没有数据通信 或者更确切地 说 双方都没有调用 Socket recv 和 Socket send 函数 则双方无法辨别目前系 统的工作状态 需等待 Socket 超时 一般而言操作系统定义的超时时间较长 不利于通信双方进行监测以提高响应速度和自动恢复处理 可以通过增加附加的心跳信息来监测通信双方的工作状态 其原理非常简 单 并且不会增加双方的通讯成本 在有业务数据传送时 双方能够检测出链 路和通信状态 如果没有业务数据传送 则需给对方发送心跳 Heartbeat 信 息 此时链路上无传输数据 增加的心跳信息不会对带宽带来压力和成本 虽 然没有增加通讯成本 但对于服务器 比如交易所前置机 而言 随着连接数 量增加 其巡检成本 每秒监测是否需要发送心跳信息和维护连接表 也将线 性增加 增设心跳报文用于检测连接是否有效 连接的一端如果在规定超时时间 timeout 内未收到对方的任何报文 则认为 TCP 虚链路失效 应主动断开 如果一方在一定的时间间隔 interval 内未向对方发送任何报文 则应向对方 发送心跳报文 以维持 TCP 虚链路的正常状态 通常 timeout 是 interval 的三 倍 API 提供了 void SetHeartbeatTimeout unsigned int timeout 方法 用于设定会 员系统检测 TCP 虚链路有效性的超时时间 交易系统在空闲时会每隔 timeout 1 3 秒向 API 发送心跳报文 若超过 timeout 2 秒未收到交易系统的任何报文时 将触发回调 CShfeFtdcTraderApi OnHeartBeatWarning 若超过 timeout 秒未收 到交易系统的任何报文时 TCP 连接将会中断 并且触发回调 CShfeFtdcTraderApi OnFrontDisconnected 例如 会员端将心跳超时设置为 16 秒 则交易系统在空闲时会每 5 秒向 API 发送一个心跳报文 如果 API 在 8 秒内未收到交易系统的任何报文 则触 发回调 CShfeFtdcTraderApi OnHeartBeatWarning 如果超过 16 秒未收到交易 系统的任何报文 API 会主动断开网络连接 并且触发回调 CShfeFtdcTraderApi OnFrontDisconnected 此时会员端可以选用备用专线链路重连交易所前置机 交易所前置机也通过心跳方式监测会员端系统的 TCP 连接 如果会员系统 未调用 SetHeartbeatTimeout 方法 则心跳超时目前固定设置为 120 秒 如果会 员系统调用 SetHeartbeatTimeout 方法 timeout 参数将同步用于前置机对会员端 的监测 这个机制非常有用 在链路中断后前置机将可在大致可用时间内 timeout 参数 5 秒左右 主动断开与会员端 TCP 连接 这样会员可以使用备 用线路 不同 IP 地址 登录 否则前置机将认为原地址的 TCP 连接仍然有效 并拒绝备用地址登录 对于 OFPv2 的会员系统而言将无法享受此便利 必须等 待 60 至 90 秒后方可使用备用地址登录 若会员系统未调用过若会员系统未调用过 SetHeartbeatTimeout 方法 在方法 在 V1 20 之前 不含 之前 不含 版本版本 API 的缺省的的缺省的 timeout 设置为设置为 120 秒 缺省的警告时间为秒 缺省的警告时间为 80 秒 为加快会秒 为加快会 员端交易系统监测专线链路中断的速度 从员端交易系统监测专线链路中断的速度 从 V1 20 版本开始 版本开始 API 将在初始化将在初始化 建立与前置机建立与前置机 TCP 连接后将主动调用连接后将主动调用 SetHeartbeatTimeOut 方法将方法将 timeout 设置为设置为 10 秒 参数秒 参数 timeout 允许的最小值为允许的最小值为 4 参数 参数 timeout 设置过高 发生设置过高 发生 链路中断情况下会员端系统切换时间将很长 设置过小 将可能发生非预期切链路中断情况下会员端系统切换时间将很长 设置过小 将可能发生非预期切 换 需要综合考虑会员端应用情况和网络情况合理设置 换 需要综合考虑会员端应用情况和网络情况合理设置 交易所建议会员系统将交易所建议会员系统将 timeout 值设置为值设置为 10 至至 30 秒之间 秒之间 4 9 前置机列表前置机列表 会员系统连接交易所前置机后方能接入 NGES 交易系统 为了容错和负载 均衡 交易所将在主用数据中心和备用数据中心部署两组 每组多台前置机 交易所将公布各前置机的网络地址的列表 会员系统从列表中随机选出一个尝 试与其建立连接 会员系统在某一时刻只与一个前置机相连 如果由该前置机 出现故障导致连接中断或者超时 则会员系统需尝试连接列表中的其它前置机 会员系统得到前置列表的方式有两种 交易所公布前置列表 会员系统通过 API 的 RegisterFront 接口 将前 置机逐一注册进 API 交易系统提供 NameServer 其功能是向 API 公布前置机列表 交易所 首先公布 NameServer 列表 会员系统通过 API 的 RegisterNameServer 接口 将 NameServer 注册进 API API 先尝试从 NameServer 中得到前 置列表 再尝试根据前置列表来连接前置机 使用 NameServer 的优点在于 增加交易所前置机部署的灵活性 可以根据业务需要和负载短期内新 增前置机并无需对会员系统做任何修改 NameServer 可以较好地完成主用系统和灾备系统的切换 NameServer 功能单一 结构简单 负载也很低 不用考虑负载均衡 可以灵活部署 会员系统可以同时使用 RegisterFront 方法注册前置机列表和使用 RegisterNameServer 方法注册 NameServer 列表 API 会首先尝试连接已注册的 前置 如果连接不成功 再尝试连接 NameServer API 连接前置的流程图 连接成功 随机从前置列表中 选取一个前置进行 连接 创建与前置的会话 已经遍历整个前置 列表 是 否 结束 是 开始 否 随机从NameServer列 表中选取一个 NameServer