edit

接口说明

前言

氦氪云的整体流程图:

  • D <-> C是设备和云端之间的双向链路,目前支持TCP、WebSocket长连接方式。U <-> C是用户(实际上是APP)和云端之间的双向链路,目前支持TCP、WebSocket长连接方式。U <-> D是设备和APP之间的双向链路,它是虚拟的(局域网控制时除外),实际云端C起到了中转的作用。因为是长连接,U <-> D可以被当做一个双向即时消息通道。在这个通道上,我们实现了一些API,叫做基础通信API
  • 云端对设备提供TCP、WebSocket短连接服务、HTTP服务,主要实现了设备端查询产品信息以实现负载均衡等功能,叫做产品信息查询API
  • 云端实现了一套账户体系,包括手机或邮箱注册、校验码验证、第三方社交账号登录等,账户体系暴露的API叫做认证授权API
  • 云端对APP提供HTTP/HTTPS服务,大量的云端服务被包装成API提供给APP调用,以实现复杂的功能,比如拉取设备列表、设备授权等,这部分API叫做用户API;比如获取厂家信息等,这部分API叫做企业API

下面我们分节对以上几类云端 API做详细说明。

curl说明

本文档从第三章开始的示例中使用的都是curl 命令,如果您没有安装curl,请从curl官方下载。

请注意,Windows下的语法与Linux和OS X下的略有不同。本文中的所有curl示例都是使用Linux和OS X下的语法。如果你使用的是Windows,那么所用的curl binary(比如,Generic、Cygwin 和 MinGW)可能会采用不同的语法。请参考curl技术文档了解语法的差异。

比如,假设使用的是Windows中的Generic curl binary,那么你需要修改如下内容:

  • 当编写跨行的命令时,你需要在行尾使用^而不是\
  • 当发送的请求带有Body时,你需要使用""括起Body而不是''
  • 如果请求的Body中包含", 你需要使用\来转义双引号。

例如:

curl -v -X PUT ^
-H "Authorization: Bearer {JWT_TOKEN}" ^
-H "Content-Type: text/plain" ^
"https://user-openapi.hekr.me/folder/{folderId}" ^
-d "newFolderName"

Tip

HTTP接口返回中会有X-TraceId,为接口调用唯一标识,反馈接口问题时请提供该值。

主要参数说明

参数名 说明 备注
msgId 消息ID 消息ID,0~65535,循环递增
action 指令 用来在消息通道里,标识每个消息的具体含义
devTid 设备ID 即使ID相同,云端也会区分为两个设备
appTid APP ID 即使ID相同,云端也会区分为两个APP
ctrlKey 控制设备时使用的key 云端颁发,32个字节
bindKey 绑定/解绑设备时使用的key 云端颁发,32个字节
prodKey 产品唯一标识(即产品密钥) 开发者在控制台上添加产品时自动生成,32个字节
PPK 产品公共密钥 通过接口列举设备获取
cid 产品类目唯一ID 氦氪云自己维护
mid 产品型号唯一ID 开发者在控制台上添加产品时自动生成
pid 厂家唯一ID 开发者认证申请通过之后自动生成
workMode 设备工作模式 设备工作方式,0.JSON透传、1.JSON主控
tokenType token类型 0\1:保留、2:动态token,现在云端只支持动态token
encryptType 加密类型 "None" :不加密、"SSL" :SSL加密,现在云端支持非加密和加密两种通道
connectType 连接类型 "tcp" :tcp长连接、"websocket" :websocket长连接
code 调用返回码 具体请看下面的返回码表
desc code对应描述 具体请看下面的返回码表

其他参数,在文档中单独说明。

JWT 和 PPK

JSON Web Token (JWT) 是一个基于JSON的在web应用间传递凭证的开放标准协议RFC7519

它具有紧凑、URL安全、可重用等特性,并尤其适用于单点登录的场景。

还客运提供的 User Account and Authentication(UAA) 服务就是利用JWT协议实现的。在用户登录之后的每一个API调用操作中都需要将JWT添加到HTTP请求的header中作为服务识别特定用户的凭证。

Hekr Product Public Key(PPK) 是Hekr产品公共密钥的简称,在某些和具体设备相关的API调用的时候我们需要在header中携带该信息。

注意: 后续的API cURL调用中 {JWT_TOKEN} 和 {PPK} 占位符即意味使用特定的 JWT 和 PPK替换

使用Server Key

对于厂家用户,可以使用Server Key进行权限认证,在console个人中心配置Server Key,调用接口时将Authorization: Bearer {JWT_TOKEN}替换为 Authorization: key={server key}即可以该厂家用户调用相应接口。

注意

Server Key 不会过期,如果泄露请立即删除并替换新的Server Key 。Server-Key的存储请预留128字节。

常见问题解决

您可以通过响应中的错误信息查找错误原因。另外请确认以下几点:

  • 服务器位置是否正确?

请确保所用的服务器 URL 与应用程序所选的服务器位置相匹配。如果使用了错误的 URL,则 Hekr Cloud 返回的 HTTP 状态码为 "404 Not Found" 。

  • HTTP 方法是否正确?

使用错误的 HTTP 方法会导致一些不易被发现的错误。 特定功能的 REST API 使用的是固定的方法(比如,GET、POST、PUT 和 DELETE),所以使用错误的方法可能会执行错误的功能。如果使用了未定义的 方法,则返回的 HTTP 状态码为 "405 Method Not Allowed",这种情况比较容易确定问题的所在。

但是,如果使用了错误的方法且 API 支持该方法,由于返回的状态码不固定,所以错误很难被发现。例如,如果你使用了错误的方法而此方法仅支持特定的 Content-Type,那么 Hekr Cloud 返回的 HTTP 状态码为 "415 Unsupported Media Type" 。所以,请仔细查看示例代码和 REST API 文档确保所使用的方法正确无误。

另外,请注意所有方法的名称都是大写的。

  • 参数的格式是否为 JSON?

当执行 POST 和 PUT 方法时,请确保发送的参数正确无误。如果 Hekr Cloud 返回的 HTTP 状态码是 "400 Bad Request" 那么可能是参数的格式出错了。