帮助文档

# 使用API

该功能主要面向需要使用API接口获取数据的用户。

  • 前期准备

需要使用API的用户，请向商务部门说明原因，请求添加API数据访问的权限。管理员完成添加后，该功能即可正常使用。

  • 获取密钥

已添加API数据访问权限的用户可查看设备管理平台相关页面，获取密钥信息。

API

API

若用户没有调用API的权限，则会出现如下提示。

API

每组密钥由公钥（PubKey）和私钥（PriKey）组成。API认证需要使用“公钥+私钥”签名认证方式，故用户需要妥善保管好自己的密钥信息。在“用户API”界面中点击私钥右侧形似眼睛的“隐藏 / 显示”按钮，可以查看私钥。

用户亦可手动重置自己的私钥，该操作需要输入短信验证码，验证通过即可完成私钥重置。

API

如因密钥泄露导致API调用出现异常，请立即重置私钥，并及时联系管理员作进一步处理。

  • API接口列表
    目前对外开放API开放的接口如下

设备信息 (opens new window)

  1. 查询设备信息

设备历史数据 (opens new window)

  1. 查询设备历史数据配置
  2. 查询设备历史数据

设备报警数据 (opens new window)

  1. 查询设备报警数据配置
  2. 查询设备实时报警数据
  3. 查询设备历史报警数据

设备实时数据 (opens new window)

  1. 查询设备实时数据配置
  2. 查询设备实时数据
  3. 写入实时数据
  • SDK与示例代码

为了方便用户开发、调试API接口，我们提供了SDK和示例代码，包含解决API签名认证、统一返回值等功能，可以快速实现业务对接。 点击下方的链接即可下载对应编程语言的SDK或示例代码。

程序设计语言 下载地址
Java SDK：点此下载 (opens new window)
示例代码：点此下载 (opens new window)
  • 操作示例

我们亦提供了签名生成和API调用示例，方便用户在不进行程序设计的前提下也能直接调试API接口。

详细操作说明请点此查看 (opens new window)，如返回结果出现异常，请参照本文档API异常返回码 (opens new window)一节进行处理。

# 使用签名认证方式

使用“公钥+私钥”签名认证方式更安全，请求头中只包含用户的公钥和利用私钥制作的签名，因此不会在请求地址或请求头中直接暴露私钥。

以下介绍签名的生成方式：

  1. 构造认证参数字符串

需要用到的认证参数如下所示

名称 含义 是否必填
PubKey 平台生成的公钥 是
TS 发起调用时的时间戳（单位为秒，10位纯数字字符串，不要用毫秒） 是
TTL 签名的有效时间（单位为秒，整数类型） 是

将上述请求参数按照参数名字典升序排列后，把PubKey、TS、TTL参数以[key]=[value]的形式用&连接起来。例如

PubKey=YOUR_PUBLIC_KEY&TS=1564544848&TTL=300
  1. 使用HMAC-SHA1方式，用私钥对认证参数字符串进行加密

常见程序设计语言通常会内置加密函数，或者通过扩展依赖库提供支持。在这一步，我们需要使用HMAC-SHA1方式，利用平台生成的私钥对上一步得到的认证参数字符串进行加密。

例如在Java语言中，我们可以引入类似下面的代码

SecretKeySpec signingKey = new SecretKeySpec(key.getBytes(), "HmacSHA1");
Mac mac = Mac.getInstance("HmacSHA1");
mac.init(signingKey);
byte[] rawHmac = mac.doFinal(data.getBytes());
  1. 将加密结果用Base64编码，并做URLEncode，得到签名sig

对于步骤1中的例子，完成加密后用Base64的方式进行编码，可以得到类似下面的结果

FuKA3yoJNQlMCLaKtIMl3I37ERw=

对该结果做一次URLEncode，得到最终的签名sig

FuKA3yoJNQlMCLaKtIMl3I37ERw%3D
  1. 构造请求头

调用API接口时，请求头（Request Header）中请务必包含以下所有参数，以步骤1中的请求认证字符串为例

名称 含义 是否必填 示例
PubKey 平台生成的公钥 是 YOUR_PUBLIC_KEY
TS 发起调用时的时间戳（单位为秒，10位纯数字字符串） 是 1564544848
TTL 签名的有效时间（单位为秒，整数类型） 是 300
SIG 步骤3中生成的签名sig 是 FuKA3yoJNQlMCLaKtIMl3I37ERw%3D

注意

较短的TTL可以使签名更难被盗用，提高安全性，但请务必保证请求到达后台服务器的时间在签名有效期内，否则会鉴权失败。

# 接口调用限制

因频繁调用API接口会导致服务器负载压力过大，所有功能接口都设置了一定的调用频率限制。如果在一段时间内（比如当前这一分钟 / 小时）接口调用次数超过最大限制，则会被拒绝访问，需要等下一个时间段方可继续正常调用。

在“用户API”界面中，用户可以查看每种类型接口的调用频率限制。

API

用户能调用的接口种类也是有限制的。在“用户API”界面中，用户可以查看自己能调用的接口名称、请求方法、请求频率限制等。

API

点击上方的“显示未授权API”按钮，可以查看未被授权的所有接口。

API

除此之外，如果发送请求时，请求头中的SIG为空（或者有错误），后台会记录相关异常活动的频率，频率达到一定值后，异常活动相关IP将会被禁止访问。

请用户按照文档说明进行API接口调用，以免影响正常业务。如遇接口权限被停用、禁止访问等异常情况，请及时联系管理员处理。

← 统一请求地址&返回值 →