物联网平台支持接入业务场景为HTTPS协议的设备。本文介绍使用HTTPS连接通信的接入流程。

使用与限制

  • 仅华东2(上海)地域支持HTTPS协议通信。
  • 仅华东2(上海)地域支持设备使用HTTPS短连接状态接入物联网平台。使用HTTPS短连接的设备,在物联网平台控制台也有在线和离线状态变化。您可通过AMQP服务端订阅设备上下线状态变化时通知的消息。
  • 仅直连设备支持使用HTTPS协议通信,网关设备与网关子设备不支持使用HTTPS协议通信。
  • 适合单纯的数据上报场景,数据上行接口传输的数据大小限制为128 KB。
  • Topic规范和MQTT的Topic规范一致,可以复用MQTT连接通信的Topic。使用HTTPS协议连接,上报数据请求:${endpoint}/topic/${topic}。不支持以?query_String=xxx格式传参。
  • HTTPS协议接入仅支持POST请求方法。
  • 设备认证返回的token会在一定周期后失效。目前token有效期是7天,请务必考虑token失效逻辑的处理。

接入流程

接入流程主要包含:进行设备认证以获取设备token、使用获取的token进行持续地数据上报。

  1. 认证设备,获取设备的token。

    认证设备请求:

    POST /auth HTTP/1.1
    Host: ${YourEndpoint}
    Content-Type: application/json
    Content-Length: 214
    body: {"version":"default","clientId":"mylight1000002","signmethod":"hmacsha1","sign":"4870141D4067227128CBB4377906C3731CAC221C","productKey":"ZG1EvTE****","deviceName":"NlwaSPXsCpTQuh8FxBGH","timestamp":"1501668289957"}
    表 1. 参数说明
    参数 说明
    Method 请求方法,只支持POST方法。
    URL URL地址,只支持HTTPS,取值:/auth。
    Host HTTP接入地址:公共实例和企业版实例中,HTTP的接入域名,请参见查看实例终端节点
    Content-Type 设备发送给物联网平台的上行数据的编码格式,目前只支持application/json。若使用其他编码格式,会返回参数错误。
    Content-Length HTTP消息体body的传输长度。
    重要
    • 对于字段Content-Length,HTTP/1.1及之后版本协议中,默认已携带,HTTP/1.0及之前版本协议中,默认未携带。使用HTTP协议认证设备时,必须传入字段Content-Length
    • 字段Content-Length值必须与body传输长度完全一致,否则无法正确解析body内容,设备认证会失败。
    body 设备认证信息。JSON数据格式。具体信息,请参见下表body参数
    表 2. body参数
    字段名称 是否必需 说明
    productKey 设备所属产品的ProductKey。可从物联网平台控制台对应实例下设备详情页面获取。
    deviceName 设备名称。可从物联网平台控制台对应实例下设备详情页面获取。
    clientId 客户端ID。长度为64字符内,建议以MAC地址或SN码作为clientId
    timestamp 时间戳。校验时间戳15分钟内的请求有效。时间戳格式为数值,值为自GMT 1970年01月01日0时0分到当前时间点所经过的毫秒数。
    sign 签名。

    签名计算格式为hmacmd5(DeviceSecret,content)

    其中,content为将所有提交给服务器的参数(除versionsignsignmethod外),按照英文字母升序,依次拼接排序(无拼接符号)的结果。

    签名示例:

    假设clientId = 127.0.0.1,deviceName = http_test,productKey = a1FHTWxQ****,timestamp = 1567003778853,signmethod = hmacmd5,deviceSecret = 89VTJylyMRFuy2T3sywQGbm5Hmk1****,签名计算为:

    hmacmd5("89VTJylyMRFuy2T3sywQGbm5Hmk1****","clientId127.0.0.1deviceNamehttp_testproductKeya1FHTWxQ****timestamp1567003778853").toHexString();

    其中,toHexString()是将计算结果二进制数据的每个byte按4 bit转化为十六进制字符串,大小写不敏感。例如,计算结果byte数组是:[60 68 -67 -7 -17 99 30 69 117 -54 -58 -58 103 -23 113 71],转换后得到的字符串为:3C44BDF9EF631E4575CAC6C667E97147。

    signmethod 算法类型,支持hmacmd5和hmacsha1。

    若不传入此参数,则默认为hmacmd5。

    version 版本号。若不传入此参数,则默认default。

    设备认证返回结果示例:

    body:
    {
      "code": 0,
      "message": "success",
      "info": {
        "token":  "6944e5bfb92e4d4ea3918d1eda39****"
      }
    }
    说明
    • 请将返回的token值缓存到本地。
    • 每次上报数据时,都需要携带token信息。如果token失效,需要重新认证设备获取token。
    表 3. 错误码说明
    code message 备注
    10000 common error 未知错误。
    10001 param error 请求的参数异常。
    20000 auth check error 设备鉴权失败。
    20004 update session error 更新失败。
    40000 request too many 请求次数过多,流控限制。
  2. 上报数据。

    设备发送数据到某个Topic,只支持发布权限的Topic,支持自定义Topic。

    例如:Topic为/${YourProductKey}/${YourDeviceName}/pub,假设当前设备名称为device123,产品的ProductKey为a1GFjLP****,那么您可以调用 https://iot-as-http.cn-shanghai.aliyuncs.com/topic/a1GFjLP****/device123/pub地址来上报数据。

    上报数据请求:

    POST /topic/${topic} HTTP/1.1
    Host: ${YourEndpoint}
    password:${token}
    Content-Type: application/octet-stream
    Content-Length: 53
    body: ${your_data}
    表 4. 上报数据参数说明
    参数 说明
    Method 请求方法,只支持POST方法。
    URL /topic/${topic}。其中,变量${topic}需替换为数据发往的目标Topic。只支持HTTPS。
    Host Endpoint地址。
    password 放在Header中的参数,取值为调用设备认证接口auth返回的token值。
    Content-Type 设备发送给物联网平台的上行数据的编码格式,目前仅支持application/octet-stream。若使用其他编码格式,会返回参数错误。
    Content-Length HTTP消息实体的传输长度。
    body 发往${topic}的数据内容。数据格式说明,请参见Topic分类和通信说明

    返回结果示例:

    body:
    {
      "code": 0,
      "message": "success",
      "info": {
        "messageId": 892687****47040
      }
    }
    表 5. 错误码说明
    code message 备注
    10000 common error 未知错误。
    10001 param error 请求的参数异常。
    20001 token is expired token失效。需重新调用auth进行鉴权,获取token。
    20002 token is null 请求header中无token信息。
    20003 check token error 根据token获取identify信息失败。需重新调用auth进行鉴权,获取token。
    30001 publish message error 数据上行失败。
    40000 request too many 请求次数过多,流控限制。

示例

使用HTTP客户端接入物联网平台的示例,请参见HTTP客户端接入示例