XTP
通过 DolphinDB 的 XTP 插件,用户可以接收上交所、深交所以及北交所的实时行情,并将数据存储于 DolphinDB 的共享表中。可接收的数据如下表所示:
指数 | 股票 | 基金 | 债券 | 期权 | |
---|---|---|---|---|---|
快照 | 有 | 有 | 有 | 有 | 有 |
逐笔 | 无 | 有 | 有 | 有 | 无 |
订单簿 | 无 | 有 | 有 | 有 | 无 |
本插件依赖中泰证券提供的第三方库 libxtpquoteapi.so,可参见文档链接 xtp-中泰证券 。
安装插件
版本要求
DolphinDB Server 2.00.10 及更高版本,支持 Linux x64。
安装步骤
在 DolphinDB 客户端中使用
listRemotePlugins
命令查看插件仓库中的插件信息。注意:仅展示当前操作系统和 server 版本支持的插件。若无预期插件,可自行编译(请选择对应分支下的插件)或在 DolphinDB 用户社区进行反馈。
login("admin", "123456") listRemotePlugins()
使用
installPlugin
命令完成插件安装。installPlugin("XTP")
使用
loadPlugin
命令加载插件。loadPlugin("XTP")
接口说明
setGlobalConfig
语法
XTP::setGlobalConfig(clientId, saveFilePath, logLevel)
详情
设置一些全局配置项。在创建句柄前必须调用至少一次。无返回值。
参数
clientId INT 类型标量,1-99 之间取值,表示账户 ID。如果需要在多个 DolphinDB 进程中使用同一个账户去连接,则需要使用不同的 clientId。
saveFilePath STRING 类型标量,表示存储日志文件的目录,要求必须存在且有可写权限。
logLevel INT 类型标量,表示 xtp 记录日志的级别,0-5 之间取值,分别对应 FATAL ERROR WARNING INFO DEBUG TRACE 级别,默认是 3。
createXTPConnection
语法
XTP::createXTPConnection(name, config)
详情
返回一个连接句柄,可用于登录,订阅数据。
参数
name STRING 类型标量,连接句柄的唯一标识符,不能为空,也不能重复。
config 一个 key 类型为 STRING 的字典,包含如下所示的配置项:
配置项 | 值类型 | 说明 |
---|---|---|
receiveTime | 整型 | 可选参数,用于设定是否将接收到数据的时间并为表的最后一列,类型为 NANOTIMESTAMP。1:增加该列;其它不增加;默认不增加。 |
OutputElapsed | BOOL | 可选参数,用于设定是否为行情表增加最后一列。该列数据类型为 LONG,表示插件从收到行情开始到准备插入流表为止的延时,单位为纳秒。true 表示增加该列;默认为 false,表示不增加。 |
ciphertext | INT | 可选参数,用于设定在登陆时是否密码使用密文传输和传递 IV 值。(加密采用 AES-256-CFB 算法)默认为 1,表示开启;若为其他值,则为关闭。 |
login
语法
XTP::login(conn, config)
详情
连接 XTP 服务器并登录。无返回值。
注意事项(摘自 XTP 官方文档):
- 测试环境使用 TCP 的方式推送行情。由于带宽的限制,建议客户只订阅少量股票,否则会出现推送延时、断线等问题。
- XPT 提供的 API 的默认日志级别是 DEBUG,需要调整到 INFO(或 ERROR),否则可能会导致丢包。本插件已将默认级别调整到 INFO,在调试时可以设置为 DEBUG。
参数
conn 由 createXTPConnection
接口返回的句柄。
config 一个 key 类型为 STRING 的字典,包含一些配置项:
配置项 | 值类型 | 说明 |
---|---|---|
ip | 字符串 | 服务器 IP 地址 |
port | 整型 | 服务器端口号 |
localIP | 字符串 | 可选参数,本地网卡地址,不能为空字符串 |
user | 字符串 | 登录用户名 |
password | 字符串 | 登录密码 |
protocalType | 整型 | 1: TCP;2: UDP |
heartBeatInterval | 整型 | 可选参数,设置心跳检测时间间隔,单位为秒。默认填 30 |
udpBufferSize | 整型 | 可选参数,UDP 方式连接时的缓冲区大小,可填 64,128,256,512,单位 MB,默认填 512 |
udpRecvCPUId | 整型数组 | 可选参数,UDP 方式接收行情时,接受行情的线程绑定的 CPU 集合。绑核时,将从数组前面的核开始使用。不超过 10 个 |
udpParseCPUId | 整型数组 | 可选参数,UDP 方式接收行情时,解析行情的线程绑定的 CPU 集合。绑核时,将从数组前面的核开始使用。不超过 10 个 |
udpOutputFlag | 整型 | 可选参数,设定 UDP 方式接收行情时,是否输出异步日志。1:输出;其它不输出;默认不输出 |
注意:如果在 createXTPConnection
中开启了配置项 ciphertext,则在登陆时传递的密码和 IV 值的类型也要求是 INT 类型数组。
subscribe
语法
XTP::subscribe(conn, quotationType, marketType, codeList, tableDic)
详情
订阅行情数据,收到数据后存储到目标表中。无返回值。
注意事项:
- 订阅同一个行情类型时,在多次订阅上证、深证市场时,要求传入的 tableDic 相同,如果不同,则以第一次订阅传入的 tableDic 为准。
- 订阅同一个行情类型时,在多次订阅新三板市场时,要求传入的 tableDic 相同,如果不同,则以第一次订阅传入的 tableDic 为准。
- 订阅同一个行情类型时,市场类型如果已订阅了 4(上证+深证)则不能再次订阅 1(上证)或 2(深证)。
- 订阅同一个行情类型时,市场类型如果已订阅了 1(上证)或 2(深证)则不能再次订阅 4(上证+深证)。
- 如果 marketType 填为 4,则不能填 codeList。
- 各目标表的 schema 可以通过
getSchema
接口获取。 - 目标表要求是共享表。
- 公网测试环境仅供客户调试 API 接口,没有订单薄 OB 行情。
参数
conn 由 createXTPConnection
接口返回的句柄。
quotationType INT 类型标量,表示行情类型。1:快照,2:逐笔,3:订单簿。
marketType INT 类型标量,表示市场类型。1:上证, 2:深证,3:新三板,4:上证+深证。
codeList STRING 类型向量,表示合约 ID 数组。如果不填或者填空,则订阅全市场数据。
tableDic 一个字典,key 类型是 STRING,value 必须是共享表,用来指定输出表。根据行情类型的不同,输出表的数量也不同。如果空缺其中若干表,则相对应的行情会被丢弃,详情如下表所示:
行情类型 | key | 说明 |
---|---|---|
快照 | indexTable、optionTable、actualTable、bondTable | 指数快照表、期权快照表、现货快照表(股票/基金等)、债券快照表 |
逐笔 | entrustTable、tradeTable、statusTable、TickByTickTable | 逐笔委托表、逐笔成交表、逐笔状态表、逐笔合并表 |
订单簿 | orderBookTable | 订单簿表 |
注意:自 3.00.0.2/2.00.12.5 版本起,支持 TickByTickTable 即逐笔合并表,其包含收到的三种逐笔数据(委托、成交、状态),该表可以做为 orderbookSnapshotEngine 的输入表。在订阅逐笔数据时,tableDic 如果指定了 “TickByTickTable”,就会忽略其它的表。当 key 为 ”TickByTickTable” 时,value 分成两种情况:
- value 为一个表,即包含收到的所有数据。
- value 为一个字典,该字典的键为整形,表示channelNo,值是共享表,会将收到数据按照 channelNo 进行分类,放到不同的表中。
unsubscribe
语法
XTP::unsubscribe(conn, quotationType)
详情
取消订阅某个类型的行情数据。无返回值。
参数
conn 由 createXTPConnection
接口返回的句柄。
quotationType INT 类型标量,表示行情类型。1:快照;2:逐笔;3:订单簿。
getStatus
语法
XTP::getStatus([conn])
详情
获取订阅的状态信息。返回一个表,表结构如下所示:
列名 | 含义 | 类型 |
---|---|---|
conn | 连接名称 | STRING |
quotationType | 订阅类型 | STRING |
startTime | 订阅开始的时间 | NANOTIMESTAMP |
endTime | 订阅结束的时间 | NANOTIMESTAMP |
lastMsgTime | 最后一条消息收到的时间 | NANOTIMESTAMP |
processedMsgCount | 已经处理的消息数 | LONG |
lastErrMsg | 最后一条错误信息 | STRING |
failedMsgCount | 处理失败的消息数 | LONG |
lastFailedTimestamp | 最后一条错误消息发生的时间 | NANOTIMESTAMP |
参数
conn 由 createXTPConnection
接口返回的句柄,可选参数。如果不填,则返回当前所有连接的状态信息。
getHandle
语法
XTP::getHandle(name)
详情
返回由 name 指定的连接句柄。
参数
name STRING 类型标量,表示连接句柄的唯一标识符 。
closeXTPConnection
语法
XTP::closeXTPConnection(conn)
详情
断开连接,销毁句柄。
参数
conn 由 createXTPConnection
接口返回的句柄。
getSchema
语法
XTP::getSchema(type, [needReceiveTime], [needElapsedTime])
详情
返回可存储相应行情类型数据的表的结构。可选的 type 如下表所示:
type | 含义 |
---|---|
indexMarketData | 指数快照表 |
optionMarketData | 期权快照表 |
actualMarketData | 现货快照表 |
bondMarketData | 债券快照表 |
BSEMarketData | 北交所数据表 |
entrust | 逐笔委托表 |
trade | 逐笔成交表 |
state | 逐笔状态表 |
orderBook | 订单簿表 |
TickByTickTable | 逐笔合并表 |
参数
type STRING 类型标量,表示类型。
needReceiveTime BOOL 类型标量,可选参数,默认为 false,,表示是否需要包含 receiveTime 列。如果在 createXTPConnection
时指定了 receiveTime 配置,那么该参数须设置为 true。
needElapsedTime BOOL 类型标量,可选参数,表示返回的 shcmea 是否包含 elapsedTime 列。默认为 false,表示不包含。
generateCiphertextAndIV
语法
XTP::generateCiphertextAndIV(password)
详情
对传入的明文密码进行加密,并返回加密后的密码和 IV 值,可用于登录。加密算法为 AES-256-CFB。返回一个元组,第一个元素是密文密码,第二个元素是 IV 值,这两个元素的类型都是 INT 类型数组。
参数
password STRING类型标量,表示明文密码。
使用示例
XTP::setGlobalConfig(11, "/path/to/log", 5)
stockConn = XTP::createXTPConnection("stockConn")
stockConfig = dict(STRING, ANY);
stockConfig["ip"] = "1.2.3.4";
stockConfig["port"] = 6002;
stockConfig["user"] = "3225";
stockConfig["password"] = "225";
stockConfig["protocalType"] = 1; //1 是 TCP 2 是 UDP, 测试环境只有TCP
stockConfig["heartBeatInterval"] = 60;
XTP::login(stockConn, stockConfig)
tableDic = dict(STRING, ANY);
share table(1:0, `exchangeID`ticker`lastPrice`qty`turnover`tradesCount`bids`asks`bidQty`askQty`dataTime, [INT, SYMBOL,DOUBLE, LONG,DOUBLE, LONG, DOUBLE[],DOUBLE[],LONG[],LONG[],TIMESTAMP]) as orderBookTable
tableDic["orderBookTable"] = orderBookTable
XTP::subscribe(stockConn, 3, 1, ["600250", "010504"], tableDic)
XTP::getStatus()
XTP::unsubscribe(stockConn, 3)
附录
在使用 createXTPConnection
接口时,可参考如下使用建议(请以 XTP 官方文档描述为准):
- 如果需要连接多个 XTP 服务器,则需要创建多个句柄,用每个句柄连接不同的服务器。
- 在登录任一个 XTP 服务器之前,必须创建完毕所有句柄,即在登录后就不允许创建新的句柄,否则会抛出异常。