restful接口

restful接口可以查询一些授权的基本信息，比如产品信息，SN信息等。

请求头参数格式

  • application/json：返回json
  • 其他：返回xml

安全验证

调用restful接口时必须使用安全口令进行访问。
认证方式：

  • 将口令写在URL里。实例：ip:port/rest/<pwd>/product，其中<pwd>就是口令。
  • 将口令写在http请求头里。实例：Authorization:<pwd>
    http请求头的优先级高于URL参数的优先级。

口令的生成方式如下：

通过修改bit_service.xml文件

打开集团服务安装目录下的 bit_service.xml 文件，添加 restful 访问密码，此密码会在 URL 中用到，将<License></License>代码拷贝到 bit_service.xml 文件中，然后重启集团服务。以下所有接口pwd均使用该口令返回。

<?xml version="1.0" encoding="UTF-8"?>
<BitAnswerSrvConfig>
  <Users/>
  <RestFul>
  <License did="0" pid="0">bitanswer</License>
  </RestFul>
</BitAnswerSrvConfig>

通过命令行设置安全口令

命令：-r [-d ] [-p ] [-s ] [-c ] [-a ]

参数说明：

随机生成一串口令：bit_service -r

将生成的口令保存到文件：bit_service -r -p /xxx/

显示已有口令：bit_service -r -s

清空已有口令：bit_service -r -c

添加自定义口令：bit_service -r -a xxxx

示例：

./bit_service -r -a bitanswer

注意事项

需要先在集团授权管理中心中开启详细日志，用户使用信息和出错信息才会保存到log中。

接口说明

获取产品列表

  1. 功能介绍
    获取产品列表

  2. URI
    ip:port/rest/<pwd>/product

  3. 请求示例

    GET /rest/123456192.168.1.203:8274/rest/123456/product HTTP/1.1
Host: 192.168.1.203:8274

  4. 响应参数

    名称 类型 描述
    product xml
    name string 产品名称
    pid string 产品编号
    status xml
    code integer 0标识成功，其它是错误码
    errMsg string 错误信息

  5. 响应格式

    <response>
<status>
 <code>0</code>
</status>
<data>
 <product>
   <name>比特安索演示产品</name>
   <pid>DNLA-7BOQ</pid>
    <version>13.6.9.5</version>
  </product>
 </data>
</response>

获取授权码列表

  1. 功能介绍
    获取授权码列表

  2. URI
    ip:port/rest/<pwd>/sn

  3. 请求参数

    名称 必填 类型 描述
    product 否 string 产品编号，获取指定产品下的sn信息
    sn 否 string 获取指定sn的信息

  4. 请求示例

    GET /rest/123456/sn HTTP/1.1
Host: 192.168.1.203:8274

  5. 响应参数

    名称 类型 描述
    snInfo xml
    activateDate string 激活日期
    endDate string 结束日期
    onlineUsers string 在线用户数
    product string 所属产品名称
    sn string 所属SN
    status string 所属SN的状态（错误码）
    users string 总的用户数
    status xml
    code integer 0标识成功，其它是错误码
    errMsg string 错误信息

  6. 响应格式

    <response>
   <status>
       <code>0</code>
   </status>
   <data>
       <snInfo>
           <activateDate>2025-03-18 07:46:11</activateDate>
           <endDate>Unlimited</endDate>
           <onlineUsers>0</onlineUsers>
           <product>比特安索演示产品</product>
           <sn>2SFAXZMJYYXWGGDP</sn>
           <status>0</status>
           <users>1</users>
       </snInfo>
   </data>
</response>

获取特征项列表（建议使用获取分发设备的信息接口）

  1. 功能介绍
    获取特征项列表

  2. URI
    ip:port/rest/<pwd>/feature

  3. 请求参数

    名称 必填 类型 描述
    product 是 string 产品编号，获取指定产品下的特征项

  4. 请求示例

    GET /rest/123456feature HTTP/1.1
Host: 192.168.1.203:8274

  5. 响应参数

    名称 类型 描述
    feature xml
    product string 所属产品名称
    sn string 所属SN
    endDate string 结束日期
    users integer 总的用户数
    onlineUsers integer 在线用户数
    name string 特征项名称
    version string 版本
    status xml
    code integer 0标识成功，其它是错误码
    errMsg string 错误信息

  6. 响应格式

    <response>
   <status>
       <code>0</code>
   </status>
   <data>
       <feature>
           <endDate>Unlimited</endDate>
           <id>6</id>
           <name>STA</name>
           <onlineUsers>0</onlineUsers>
           <product>比特安索演示产品</product>
           <sn>2SFAXZMJYYXWGGDP</sn>
           <users>1</users>
           <version>1.0</version>
       </feature>
   </data>
</response>

获取当前在线用户和排队用户信息

  1. 功能介绍
    获取当前在线用户和排队用户信息

  2. URI
    ip:port/rest/<pwd>/user

  3. 请求参数

    名称 必填 类型 描述
    product 否 string 产品编号
    feature 否 string 特征项名称
    featureVer 否 string 特征项版本
    type 否 string
    • queue获取排队的用户列表

    • all：获取在线和排队的用户列表

    • 不传：只获取在线的用户列表

  4. 请求示例

    GET /rest/123456user HTTP/1.1
Host: 192.168.1.203:8274

  5. 响应参数

    名称 类型 描述
    machine xml
    id integer 用于显示的id
    userName string 用户名
    computerName string 机器名
    account string 返回客户端设置的账号名
    featureName string 特征项名称
    featureVer string 特征项版本
    ip string Ip地址
    loginTime string 登录日期
    status string 用户的状态（online 使用中 || queue 排队中）
    status xml
    code integer 0标识成功，其它是错误码
    errMsg string 错误信息

  6. 响应示例

    <response>
 <status>
   <code>0</code>
 </status>
 <data>
   <machine>
     <account/>
     <computerName>hfm</computerName>
     <featureName>-</featureName>
     <featureVer>-</featureVer>
     <ip>114.246.96.4</ip>
     <loginTime>2025-03-25 06:48:28</loginTime>
     <product>比特安索演示产品</product>
     <sn>2SFAXZMJYYXWGGDP</sn>
     <status>online</status>
     <userName>Administrator</userName>
   </machine>
 </data>
</response>

获取用户使用信息(废弃)

此信息的保存时间为两个月，每次调用接口显示最多不超过50000条数据。

  1. 功能介绍
    获取用户使用信息

  2. URI
    ip:port/rest/<pwd>/statistics

  3. 请求参数

    名称 必填 类型 描述
    product 否 string 产品编号，表示按product筛选
    feature 否 string 特征项名称
    offset 否 string 查询数据的起始位置，不传默认为0
    limit 否 string 查询数据的条数，不传默认为10000，最大不能超过50000
    consumeFeatureVer 否 string 特征项版本
    startTime 否 string 获取这个时间段内login或者logout的用户的记录，此参数必须成对出现
    endTime 否 string 获取这个时间段内login或者logout的用户的记录，此参数必须成对出现

  4. 请求示例

    GET /rest/123456statistics HTTP/1.1
Host: 192.168.1.203:8274

  5. 响应参数

    名称 类型 描述
    record xml
    id integer 当前记录的id
    pid string 产品编号
    sn string 所属SN
    userName string 用户名
    computerName string 机器名
    account string 返回客户端设置的账号名
    ip string Ip地址
    featureName string 特征项名称。如果为NULL，表示SN的使用记录
    featureVer string 客户端请求的特征项版本
    consumeFeatureVer string 客户端实际占用的特征项版本（服务端页面显示的版本）
    loginTime string 开始使用时间。
    logoutTime string 结束使用时间。如果为空，表示还没有退出
    status xml
    code integer 0标识成功，其它是错误码
    errMsg string 错误信息

  6. 响应示例

    <response>
 <status>
   <code>0</code>
 </status>
 <data>
   <record>
     <account/>
     <computerName>HFM</computerName>
     <consumeFeatureVer/>
     <featureId>0</featureId>
     <featureName/>
     <featureVer/>
     <ip>114.246.96.4</ip>
     <loginTime>2025-03-18 07:57:57</loginTime>
     <logoutTime>2025-03-18 07:57:57</logoutTime>
     <pid>DNLA-7BOQ</pid>
     <sn>2SFAXZMJYYXWGGDP</sn>
     <type>Login</type>
     <userName>Administrator</userName>
   </record>
 </data>
</response>

获取log信息

  1. 功能介绍
    获取log信息

  2. URI
    ip:port/rest/<pwd>/log

  3. 请求参数

    名称 必填 类型 描述
    product 否 string 产品编号，表示按产品筛选
    featureName 否 string 特征项名称，如果要传版本，需要加空格
    实例：“feature 2020.2”
    startTime 否 string 传入一个时间段
    endTime 否 string 传入一个时间段
    type 否 string 想要获取上述时间段内信息的类型

  4. 请求示例

    GET /rest/123456log HTTP/1.1
Host: 192.168.1.203:8274

  5. 响应参数

    名称 类型 描述
    record xml
    pid string 产品编号
    sn string 所属SN
    userName string 用户名
    computerName string 机器名
    platform string 平台
    account string 返回客户端设置的账号名
    ip string Ip地址
    featureName string 特征项名称。如果为NULL，表示SN的使用记录
    featureVer string 客户端实际占用的特征项版本
    id integer 当前记录的id
    parentId integer 当前记录的父id
    time string String log的记录时间
    时间格式：“YYYY-MM-DD HH:MM:SS”
    type string log信息的类型，包括Login、Logout、Query、Release、Checkout、Checkin
    status xml
    code integer 0标识成功，其它是错误码
    errMsg string 错误信息 
    type=Login表示获取这段时间内Login的用户信息
type=Logout表示获取这段时间内Logout的用户信息
type=Query表示获取这段时间内Query的用户信息
type=QueryAction表示单次Query请求的用户信息，同时会返回userNum字段，表示这次Query请求的用户数
type=Release表示获取这段时间内Release的用户信息
type=ReleaseAction表示单次Release请求的用户信息
type= Checkout表示获取这段时间内Checkout的用户信息
type=Checkin表示获取这段时间内Checkin的用户信息
type可以多选，以空格的形式追加，不传默认返回当前时间段内上述所有信息

  6. 响应示例

    <response>
 <status>
   <code>0</code>
 </status>
 <data>
   <record>
     <computerName>HFM</computerName>
     <featureId>0</featureId>
     <featureName/>
     <featureVer/>
     <id>191</id>
     <ip>114.246.96.4</ip>
     <parentId>0</parentId>
     <pid>DNLA-7BOQ</pid>
     <platformName>Windows</platformName>
     <sn>2SFAXZMJYYXWGGDP</sn>
     <time>2025-03-18 07:57:57</time>
     <type>Login</type>
     <userName>Administrator</userName>
   </record>
 </data>
</response>

删除log信息

  1. 功能介绍
    删除log信息

  2. URI
    ip:port/rest/<pwd>/log

  3. 请求参数

    名称 必填 类型 描述
    method 是 string delete表示删除数据
    product 否 string 产品编号，表示按product删除，不传表示删除所有产品的log
    startTime 否 string 传入一个时间段，不传代表删除所有数据
    endTime 否 string 传入一个时间段，不传代表删除所有数据

  4. 请求示例

    POST /rest/123456log HTTP/1.1
Host: 192.168.1.203:8274

  5. 响应参数

    名称 类型 描述
    data xml
    numDeleted integer 成功删除数据的条数
    status xml
    code integer 0标识成功，其它是错误码
    errMsg string 错误信息

  6. 响应示例

    <response>
 <status>
   <code>0</code>
 </status>
 <data>
   <numDeleted>202</numDeleted>
 </data>
</response>

获取错误列表

此信息的保存时间为48小时，每次调用接口显示最多不超过10000条数据。

  1. 功能介绍
    获取错误列表

  2. URI
    ip:port/rest/<pwd>/errors

  3. 请求参数

    名称 必填 类型 描述
    product 否 string 产品编号
    feature 否 string
    featureVer 否 string
    startTime 否 string 获取一个时间段内[startTime, endTime]的错误信息，不传表示全部
    endTime 否 string 获取一个时间段内[startTime, endTime]的错误信息，不传表示全部

  4. 请求示例

    GET /rest/123456errors HTTP/1.1
Host: 192.168.1.203:8274

  5. 响应参数

    名称 类型 描述
    record xml
    sn string
    userName string 用户名
    computerName string 机器名
    account string 返回客户端设置的账号名
    type string 类型
    ip string Ip地址
    featureName string 特征项名称
    featureVer string 特征项版本
    time string 出错时间
    result integer result结果
    status xml
    code integer 0标识成功，其它是错误码
    errMsg string 错误信息

  6. 响应示例

    <response>
<status>
  <code>0</code>
</status>
</response>

    可能出现的错误码如下

    错误码 错误信息
    269 参数错误，输入的参数为空
    290 内存分配失败
    317 Query参数错误
    530 该用户被集团服务管理员踢出，几分钟后才能再次登录
    531 授权码由于连接服务器过于频繁被列入黑名单，或集团授权客户端被访问规则禁止
    1283 指定的特征项没有找到
    1289 特征项已过期
    1793 授权码已经过期
    1794 SN的在线设备数超过限制
    1798 指定的授权码没有找到，请确认授权码格式、服务器地址是否正确以及授权码与产品是否一致
    1810 特征项容量已用尽，需要等待其它进程或客户端释放
    1811 特征项还没有被使用，无需释放
    1813 用户数超过最大计数
    2623 授权码已停用

添加访问规则

  1. 功能介绍
    添加访问规则

  2. URI
    ip:port/rest/<pwd>/product/<pid>/rule

  3. 请求参数

    名称 必填 类型 描述
    rules 是 string 多条规则以换行符分隔
    pid string 产品编号

  4. 请求示例

    POST /rest/123456rule HTTP/1.1
Host: 192.168.1.203:8274

  5. 响应参数

    名称 类型 描述
    status xml
    code integer 0标识成功，其它是错误码
    errMsg string 错误信息

删除访问规则

  1. 功能介绍
    删除访问规则

  2. URI
    ip:port/rest/<pwd>/product/<pid>/rule

  3. 请求参数

    名称 必填 类型 描述
    rule 是 string 表示删除指定规则，不传表示删除全部规则
    pid string 产品编号

  4. 请求示例

    DELETE /rest/123456rule HTTP/1.1
Host: 192.168.1.203:8274

  5. 响应参数

    名称 类型 描述
    status xml
    code integer 0标识成功，其它是错误码
    errMsg string 错误信息

添加全局用户组

  1. 功能介绍
    添加全局用户组

  2. URI
    ip:port/rest/<pwd>/ruleGroup

  3. 请求参数

    名称 必填 类型 描述
    name 是 string 组名
    users 是 string 用户标识
    实例：ip（127.0.0.1），或用户名（userName），或（@machineName），一次可以传多个，用\n分隔

  4. 请求示例

    POST /rest/123456ruleGroup HTTP/1.1
Host: 192.168.1.203:8274

  5. 响应参数

    名称 类型 描述
    status xml
    code integer 0标识成功，其它是错误码
    errMsg string 错误信息

删除用户组里的用户

  1. 功能介绍
    删除用户组里的用户

  2. URI
    ip:port/rest/<pwd>/ruleGroup

  3. 请求参数

    名称 必填 类型 描述
    name 是 string 组名
    users 是 string 用户标识
    实例：ip（127.0.0.1），或用户名（userName），或（@machineName），一次可以传多个，用\n分隔

  4. 请求示例

    DELETE /rest/123456ruleGroup HTTP/1.1
Host: 192.168.1.203:8274

  5. 响应参数

    名称 类型 描述
    status xml
    code integer 0标识成功，其它是错误码
    errMsg string 错误信息

查询用户组里的用户

  1. 功能介绍
    查询用户组里的用户

  2. URI
    ip:port/rest/<pwd>/ruleGroup/{name}

    名称 必填 类型 描述
    name 是 string 组名

  3. 请求示例

    GET /rest/123456ruleGroup HTTP/1.1
Host: 192.168.1.203:8274

  4. 响应参数

    名称 类型 描述
    data xml
    users xml
    user string 用户
    status xml
    code integer 0标识成功，其它是错误码
    errMsg string 错误信息

踢出

  1. 功能介绍
    踢出

  2. URI
    ip:port/rest/<pwd>/product/<pid>/killList

    名称 必填 类型 描述
    pid string 产品编号

  3. 请求参数

    名称 必填 类型 描述
    users 是 string 用户标识。
    实例：ip（127.0.0.1），或用户名（userName），或（@machineName），一次可以传多个，用\n分隔

  4. 请求示例

    POST /rest/123456killList HTTP/1.1
Host: 192.168.1.203:8274

  5. 响应参数

    名称 类型 描述
    status xml
    code integer 0标识成功，其它是错误码
    errMsg string 错误信息

在线激活

  1. 功能介绍
    在线激活

  2. URI
    ip:port/rest/<pwd>/product/<pid>/activate/<sn>

    名称 必填 类型 描述
    sn 是 string 要激活的授权
    pid string 产品编号

    sn：要激活的授权

  3. 请求示例

    GET /rest/123456product//activate/ HTTP/1.1
Host: 192.168.1.203:8274

  4. 响应参数

    名称 类型 描述
    status xml
    code integer 0标识成功，其它是错误码
    errMsg string 错误信息

在线升级

  1. 功能介绍
    在线升级

  2. URI
    ip:port/rest/<pwd>/product/<pid>/update/<sn>

    名称 必填 类型 描述
    sn 是 string 要升级的授权
    pid string 产品编号

  3. 请求示例

    GET /rest/123456product//update/ HTTP/1.1
Host: 192.168.1.203:8274

  4. 响应参数

    名称 类型 描述
    status xml
    code integer 0标识成功，其它是错误码
    errMsg string 错误信息

获取请求文件

  1. 功能介绍
    获取请求文件

  2. URI
    ip:port/rest/<pwd>/product/<pid>/requestCode/<sn>

    名称 必填 类型 描述
    sn 是 string 授权码
    pid string 产品编号

  3. 请求示例

    GET /rest/123456product//requestCode/ HTTP/1.1
Host: 192.168.1.203:8274

  4. 响应参数

    名称 类型 描述
    data string 请求码
    status xml
    code integer 0标识成功，其它是错误码
    errMsg string 错误信息

使用升级文件

  1. 功能介绍
    使用升级文件

  2. URI
    ip:port/rest/<pwd>/ product/<pid>/applyUpdateCode

    名称 必填 类型 描述
    pid string 产品编号

  3. 请求参数

    名称 必填 类型 描述
    code 是 string 升级串

  4. 请求示例

    POST /rest/123456product//applyUpdateCode HTTP/1.1
Host: 192.168.1.203:8274

  5. 响应参数

    名称 类型 描述
    data xml
    receipt string 确认码
    status xml
    code integer 0标识成功，其它是错误码
    errMsg string 错误信息

获取设备码

  1. 功能介绍
    获取设备码

  2. URI
    ip:port/rest/<pwd>/product/<pid>/deviceCode

    名称 必填 类型 描述
    pid string 产品编号

  3. 请求示例

    GET /rest/123456product//deviceCode HTTP/1.1
Host: 192.168.1.203:8274

  4. 响应参数

    名称 类型 描述
    data xml
    code string 设备码
    status xml
    code integer 0标识成功，其它是错误码
    errMsg string 错误信息

获取借出串

  1. 功能介绍
    获取借出串

  2. URI
    ip:port/rest/<pwd>/product/<pid>/borrow

    名称 必填 类型 描述
    pid string 产品编号

  3. 请求参数

    名称 必填 类型 描述
    borrowRequest 是 string 借出请求串
    referenceId 否 string 自定义编号

  4. 请求示例

    POST /rest/123456product//borrow HTTP/1.1
Host: 192.168.1.203:8274

  5. 响应参数

    名称 类型 描述
    data string 借出串
    status xml
    code integer 0标识成功，其它是错误码
    errMsg string 错误信息

获取分发的设备信息

  1. 功能介绍
    获取分发的设备信息

  2. URI
    ip:port/rest/<pwd>/product/<pid>/borrowclient

    名称 必填 类型 描述
    pid string 产品编号

  3. 请求参数

    名称 必填 类型 描述
    product 否 string 产品id，获取指定product下的用户使用信息
    startTime 否 string 查询的起始借出日期（包括）
    endTime 否 string 查询的借出日期（不包含）

  4. 请求示例

    GET /rest/123456product//borrowclient HTTP/1.1
Host: 192.168.1.203:8274

  5. 响应参数

    名称 类型 描述
    record xml
    id integer 当前记录的id
    sn string 借出的SN
    userName string 用户名
    computerName string 机器名
    account string 返回客户端设置的账号名
    mid string 借出的指纹
    referenceId string 编号
    durationDays integer 借出的天数
    featured integer 借出的特征项ID
    featureName string 借出的特征项名称
    featureVer string 借出的特征项版本
    time string 借出的时间
    时间格式：“YYYY-MM-DD HH:MM:SS”
    status xml
    code integer 0标识成功，其它是错误码
    errMsg string 错误信息

添加代理

  1. 功能介绍
    添加代理

  2. URI
    ip:port/rest/<pwd>/product/<pid>/addAgent

    名称 必填 类型 描述
    pid string 产品编号

  3. 请求参数

    名称 必填 类型 描述
    fid 否 string 特征项ID
    featureName 否 string 特征项名称（与fid可二选一）
    featureUserNumber 否 string 特征项用户数
    mode 否 string 代理模式（increase：增加，share：共享）
    serviceAddress 是 string 一级集团服务地址

  4. 请求示例

    POST /rest/123456product//addAgent HTTP/1.1
Host: 192.168.1.203:8274

  5. 响应参数

    名称 类型 描述
    status xml
    code integer 0标识成功，其它是错误码
    errMsg string 错误信息

释放代理

  1. 功能介绍
    释放代理

  2. URI
    ip:port/rest/<pwd>/product/<pid>/releaseAgent

    名称 必填 类型 描述
    pid string 产品编号

  3. 请求参数

    名称 必填 类型 描述
    fid 否 string 特征项ID
    featureName 否 string 特征项名称（与fid可二选一）
    featureUserNumber 否 string 特征项用户数
    serviceAddress 是 string 一级集团服务地址

  4. 请求示例

    POST /rest/123456product//releaseAgent HTTP/1.1
Host: 192.168.1.203:8274

  5. 响应参数

    名称 类型 描述
    status xml
    code integer 0标识成功，其它是错误码
    errMsg string 错误信息

获取代理信息

  1. 功能介绍
    获取代理信息

  2. URI
    ip:port/rest/<pwd>/product/<pid>/getAgent

    名称 必填 类型 描述
    pid string 产品编号

  3. 请求示例

    GET /rest/123456product//getAgent HTTP/1.1
Host: 192.168.1.203:8274

  4. 响应参数

    名称 类型 描述
    status xml
    code integer 0标识成功，其它是错误码
    errMsg string 错误信息

获取特征项列表并可查峰值信息

  1. 功能介绍
    获取特征项列表并可查峰值信息

  2. URI
    ip:port/rest/<pwd>/product/<pid>/featuresV2

    名称 必填 类型 描述
    pid string 产品编号

  3. 请求参数

    名称 必填 类型 描述
    peakType 否 string 峰值类型，月峰值或日峰值，month或day
    peakStartDate 否 string 查询起始日期
    peakEndDate 否 string 查询结束日期，不指定则为当月或当日

    以上3个参数均为可选参数，不输入则返回特征项列表，和获取特征项列表接口的返回结果类似，唯一区别是在只指定产品ID时返回聚合的特征项列表。建议用户使用此接口代替获取特征项列表接口

  4. 请求示例

    GET /rest/123456product//getAgent HTTP/1.1
Host: 192.168.1.203:8274

  5. 响应参数

    名称 类型 描述
    feature xml
    product string 所属产品名称
    sn string 所属SN
    endDate string 结束日期
    users integer 总的用户数
    onlineUsers integer 在线用户数
    name string 特征项名称
    version string 版本
    date string 查询峰值的日期
    peak integer 指定月或日的峰值
    status xml
    code integer 0标识成功，其它是错误码
    errMsg string 错误信息

  6. 响应示例

    <feature>
  <endDate>2025-04-30 23:59:59</endDate>
  <id>18086</id>
  <name>计算</name>
  <onlineUsers>0</onlineUsers>
  <product> demo </product>
  <sn>GNT****************Z</sn>
  <users>10</users>// 计算
  <version>2.0</version>
  <peaks>
     <peak date="2025-02">3</peak>
     <peak date="2025-03">2</peak> 
  </peaks>
</feature>