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

使用与限制

  • 仅华东2(上海)、华北2(北京)、华南1(深圳)地域支持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方法。
    URLURL地址,只支持HTTPS,取值:/auth。
    HostHTTP接入地址:公共实例和企业版实例中,HTTP的接入域名,请参见查看实例终端节点
    Content-Type设备发送给物联网平台的上行数据的编码格式,目前只支持application/json。若使用其他编码格式,会返回参数错误。
    Content-LengthHTTP消息体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. 错误码说明
    codemessage备注
    10000common error未知错误。
    10001param error请求的参数异常。
    20000auth check error设备鉴权失败。
    20004update session error更新失败。
    40000request 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。
    HostEndpoint地址。
    password放在Header中的参数,取值为调用设备认证接口auth返回的token值。
    Content-Type设备发送给物联网平台的上行数据的编码格式,目前仅支持application/octet-stream。若使用其他编码格式,会返回参数错误。
    Content-LengthHTTP消息实体的传输长度。
    body发往${topic}的数据内容。

    数据内容的格式说明如下:

    返回结果示例:

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

示例

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