CoAP协议接入

CoAP（Constrained Application Protocol）是一种专为受限环境（例如物联网设备）设计的轻量级通信协议。

协议支持

物联网平台支持以CoAP协议接入，并通过连接模式以提供客户端接入认证功能来限制未授权的CoAP客户端接入系统。

连接步骤

一、客户端认证（获取token）

使用平台指定规则对设备三元组进行组合与签名后，请求服务端进行认证，认证成功后，使用返回的token进行后续的CoAP通信，防止非法用户接入。

::: caution 变量说明
对于认证，有三个重要参数需要作为变量参与到签名认证过程中，分别是设备的ProductId, DeviceId和DeviceSecret，在进行接入前，请事先从物联网平台获取这几个参数。
:::

方法（Method）：POST

请求路径（URI）：mqtt/connection?clientId={clientId}&username={username}&password={password}

消息体（Payload）：空

参数说明：

::: caution 注意
由于相关认证采用Query参数的方式传递，因此连接时使用的参数值与使用MQTT时有所不同，分别用**，*和$代表使用MQTT时的|，=和&。
:::

coapClientId: clientId+"**securemode*3,signmethod*hmacsha1,timestamp*132323232**"
coapUsername: deviceId+"$"+productId
coapPassword: sign_hmac(deviceSecret,content)

变量名	说明
clientId	表示客户端ID，可自定义，长度不可超过64个字符。建议使用设备的MAC地址或SN码，方便您识别区分不同的客户端
securemode	表示目前安全模式，可选值有2（TLS直连模式）和3（TCP直连模式）
signmethod	表示签名算法类型。支持hmacmd5，hmacsha1和hmacsha256，默认为hmacmd5
timestamp	表示当前时间毫秒值，可以不传递
coapPassword	sign签名需把提交给服务器的参数按字典排序后，根据signmethod加签
content	提交给服务器的参数（productId、deviceId、timestamp和clientId），按照参数名称首字母字典排序， 然后将参数值依次拼接

::: caution 变量说明
此处productId和deviceId为必填参数，timestamp和clientId为可选参数。若传入timestamp或clientId，必须与coapClientId中的设置相同。
:::

示例：

假设clientId = 12345，deviceId = device， productId = pk， timestamp = 789，signmethod=hmacsha1，deviceSecret=secret，那么认证时使用的参数如下：

coapClientId=12345**securemode*3,signmethod*hmacsha1,timestamp*789**
coapUsername=device$pk
coapPassword=hmacsha1("secret","clientId12345deviceIddeviceproductIdpktimestamp789").toHexString(); 

加密后的Password为二进制转16制字符串，示例结果为：

dc8f8498a1a115b58f6a3afd526bc62a1665****

返回结果：

返回码（Return Code）	消息体（Payload）	说明
2.01	Token：用于后续请求使用的令牌字符串	连接创建成功，并在消息体中返回本次连接的 Token 字符串
4.00	ErrorMessage：具体错误信息	错误的请求格式
4.01	ErrorMessage：错误说明，例如Login Failed: not_authorized	请求格式正确，但登录鉴权失败

二、消息发布

使用CoAP客户端未指定主题发送消息，需携带客户端认证步骤中获取到的Token。

方法（Method）：POST

请求路径（URI）：ps/{topicName}?clientId={clientId}&token={token}

消息体（Payload）：消息内容

参数说明：

变量名	说明
topicName	消息发布的Topic，仅支持系统Topic，传入值为Topic去掉前置sys，例如数据上报时，传入{productId}/{deviceId}/thing/properties/up
clientId	客户端认证时使用的clientId
token	客户端认证成功时获取到的token

返回结果：

返回码（Return Code）	消息体（Payload）	说明
2.04	空	发送成功
4.00	ErrorMessage：具体错误信息	错误的请求格式
4.01	ErrorMessage：具体错误信息	请求格式正确，但登录鉴权失败

三、消息订阅

使用CoAP客户端订阅指定主题。

方法（Method）：GET

请求路径（URI）：ps/{topicName}?clientId={clientId}&token={token}

消息体（Payload）：空

参数说明：

变量名	说明
topicName	消息发布的Topic，仅支持系统Topic，传入值为Topic去掉前置sys，例如订阅数据下发消息时，传入{productId}/{deviceId}/thing/properties/set
clientId	客户端认证时使用的clientId
token	客户端认证成功时获取到的token

返回结果：

返回码（Return Code）	消息体（Payload）	说明
2.05	空	订阅成功
4.00	ErrorMessage：具体错误信息	错误的请求格式
4.01	ErrorMessage：具体错误信息	请求格式正确，但登录鉴权失败

四、心跳

在一段时间不与平台进行通信（默认为30秒）之后，服务端会删除该客户端的会话、订阅关系，并释放所有的资源。若需要保持clientId，token，以及订阅的活跃，CoAP客户端与服务端需要维持心跳。

方法（Method）：PUT

请求路径（URI）：mqtt/connection?clientId={clientId}&token={token}

消息体（Payload）：空

参数说明：

变量名	说明
topicName	消息发布的Topic，仅支持系统Topic，传入值为Topic去掉前置sys，例如订阅数据下发消息时，传入{productId}/{deviceId}/thing/properties/set
clientId	客户端认证时使用的clientId
token	客户端认证成功时获取到的token

返回结果：

返回码（Return Code）	消息体（Payload）	说明
2.01	空	更新成功
4.00	ErrorMessage：具体错误信息	错误的请求格式
4.01	ErrorMessage：具体错误信息	请求格式正确，但登录鉴权失败