Skip to content

接口说明

前言

氦氪云的整体流程图：

  • 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" 那么可能是参数的格式出错了。