物联网平台支持接入业务场景为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为将所有提交给服务器的参数（除version、sign和signmethod外），按照英文字母升序，依次拼接排序（无拼接符号）的结果。

    签名示例：

    假设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客户端接入示例。