帮助文档

# 使用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接口调用，以免影响正常业务。如遇接口权限被停用、禁止访问等异常情况，请及时联系管理员处理。

# 统一请求地址

调用API时，请使用统一请求地址：https://www.gongyeyuniot.com/api/${FunctionURL}

需要填入的请求参数如下

参数位置 参数名 说明 是否必填
请求头 PubKey 平台生成的公钥 是
请求头 TS 发起调用时的时间戳（单位为秒，10位纯数字字符串） 是
请求头 TTL 签名的有效时间（单位为秒，整数类型） 是
请求头 SIG “开始使用 (opens new window)-使用签名认证方式” 步骤3中生成的签名sig 是
请求地址 FunctionURL 需要请求的功能路径，详见API接口文档 是

# 统一返回值

API接口会根据用户请求，返回统一格式的JSON字符串。

正常返回结果的格式如下

{
  "meta": {
    "success": true,
    "message": "100001"
  },
  "data": ...
}

返回值的含义如下表所示

名称 含义 数据类型
meta 元数据，包含请求是否成功的标志参数 (success) ，以及异常编码或信息 (message) object
success 请求是否成功 (true：成功；false：失败) boolean
message 返回定义编码，可以用于判断请求是否成功，以及请求失败原因，详见API异常状态码 (opens new window) string
data 返回数据，详见API接口文档 object

# API异常状态码

当API请求由于权限不足、请求次数超过限制等原因导致错误时，API会返回如下结构的错误信息。您的程序可以根据message中记录的状态码来进行相应的处理。

{
  "meta": {
    "success": false,
    "message": "100003"
  },
  "data": "Internal Server error"
}

可能出现的异常状态码说明如下：

状态码 含义 备注
100001 操作成功 该状态码不是异常状态码
100003 内部服务异常
100016 请求参数错误 请检查请求参数是否符合规范
110509 设备不存在 用户未持有该设备(自己注册或分享)、设备使用旧固件
110539 没有写数据的权限
110556 设备离线，无法处理当前操作
100015 用户没有操作权限
100020 请求头参数异常 请检查请求头参数是否符合规则
100021 禁止访问 IP已被加入黑名单，请联系管理员
100007 不支持该请求方法
120005 API请求失败，API权限已停用 请联系管理员
120006 API请求失败，无法获取API权限 请联系管理员
120007 API请求失败，获取请求信息异常 请联系管理员
120008 API请求失败，签名sig验证不通过
120009 API请求失败，请求时间过期
120010 API请求失败，超过每分钟最大请求次数
120011 API请求失败，超过每小时最大请求次数
120012 API请求失败，没有该接口访问权限 请联系管理员

# API操作调试示例

在开始下面的步骤之前，请先确认自己在设备管理平台的账号开通了API使用权限。如页面提示暂无权限，请与商务部门联系，申请开通相关服务。

API

API

# 1. 生成签名

1.1 构造认证参数字符串

认证参数字符串由三个部分组成，分别是公钥PubKey、发起调用时的时间戳TS、签名有效期TTL。

  • 获取公钥

登录设备管理平台，点击左上角的头像图标，选择“API”，在弹出的模态框中即可查询到自己的公钥。

API

  • 获取时间戳

请访问此网站 (opens new window)，点击页面中“现在”右侧的10位数字，再选择下方“时间戳”右侧的第一个输入框，复制框中所有内容，即为时间戳TS。

注意：时间戳TS的单位为秒，复制时间戳时请确保单位和数字位数均正确。

API

  • 设置签名有效期

为了调试方便，签名有效期TTL可设置为1800秒（30分钟），即签名在生成后的1800秒内都是有效的。后续调试过程中如果API接口返回签名已过期，则需要重新生成签名。

  • 拼接认证参数字符串

仿照下面的示例，将三个认证参数拼接好，复制粘贴至空白的记事本上，备用。

PubKey=72ffc453b6184cdfaf61ef1820858bcd&TS=1637647655&TTL=1800

API

1.2 用私钥对认证参数字符串加密

我们需要使用HMAC-SHA1方式，用私钥对认证参数字符串进行加密，并用Base64进行编码。

打开在线计算工具 (opens new window)，在“消息”中填写上一步我们在记事本中做好的认证参数字符串，算法选择“sha1”，密钥填写从设备管理平台用户API界面中获取的私钥，下方两个选项不勾选。

API

API

点击“计算”，结果B即为使用私钥加密后用Base64进行编码的结果。我们将结果B中的所有内容也复制粘贴至记事本，备用。

1.3 生成最终的签名字符串SIG

打开URLEncode在线编码工具 (opens new window)，将上一步得到的结果（在线计算工具返回的结果B）复制到输入框中。

API

点击下方的“UrlEncode编码”按钮，输入框中的内容即被替换为URLEncode编码后的结果，这就是我们最终获得的签名字符串SIG。因后续进行API接口调试时将会用到这个签名，故请在签名有效期内妥善保存。

# 2. 调试接口

打开对外开放API在线调试页面 (opens new window)，在“设备操作接口汇总”中选择要调试的接口，点击参数列表右上方的“Try it out”进入调试模式。

API

此处以调试查询设备信息接口为例。点击“Try it out”按钮，按照下图说明填写请求参数和请求头参数。

API

点击“Execute”按钮，下方返回正常的JSON格式数据、success显示为true则说明请求成功。

API

如果返回结果中success显示为false，请参照API使用手册 (opens new window)中“API异常返回码”一节的内容进行排查，必要时请联系管理员。

← 平台用户注册 →