实例简介

本例通过IoT提供的OpenAPI接口实现设备的访问，包括设备上报数据的获取和对设备的数据下发。

预期效果

• 调用API可获取设备最后一次上报的数据。
• 调用API可向设备发送数据。

实例设备

使用任意一款支持串口透传的且可以配置连接到IoT系统的DTU均可实现，本例使用模拟软件完成。

OpenAPI使用说明

1.基本说明

• API协议类型为HTTP，使用HTTPS POST方法。
• API使用第一步为用户登录，获取合法TOKEN，后续所有操作需要在头部信息种添加TOKEN。
• API仅对在IoT注册的手机账号开放（短信登录后自动完成注册），在IoT系统创建的经销商账号无法使用API，小程序账号也无法使用API。
• 获取TOKEN后，可以访问此账号录入的设备。

2.头部信息

• X-App-Platform:5 说明：固定值。
• X-App-Key: acacc54ca8196d370e7defd57528f934 说明：使用默认值，如果客户实施了独立部署，请使用独立部署的X-App-Key。
• Content-Type: application/json 说明：数据体均为json格式。
• X-User-Token: d29b75dc82ab4720b1d06b77xxxxxxxx 说明：仅用户登录接口不携带此头部参数，其他API必须携带此头部参数。

3.使用过程

• 需要在IoT系统上注册（短信登录后自动完成注册）且录入了设备后才可正常使用。
• 使用IoT系统的登录账号和密码，调用用户登录API，获取TOKEN。
• 获取某个设备的最后一次数据。
• 向某个设备发送透传数据。

API-1 用户登录API

1. URL

POST https://iot.di-link.com/JCloud/users/logins

2. 头部参数

参考前文头部参数描述，不携带X-User-Token

3. 数据体（BODY)

{

    "username": "1369146xxxx",

    "password": "xxxxxxxx49ba59abbe56e057f20f883e",     //明文密码的md5串 32字节小写串，例如md5（123456）为 e10adc3949ba59abbe56e057f20f883e

    "role_id": "company" 

}

4. 返回值

{
    "result_code": "sis.api.Success",                       //状态码
    "code_message": "successful",                           //返回信息
    "res_data": [
        {
            "uid": "xxxxxxxxe1aafb19ecb7181e9456b427",      //用户ID
            "token": "xxxxxxxx82ab4720b1d06b7757c2cb39",    //用户本地登录TOKEN，有效期7天，顺延
            "role_id": "company",                           //用户角色，只有company角色可使用OpenAPI
            "app_name": "xxxxxxxx"                          //应用名称，OpenAPI不使用
        }
    ]
}

5. 错误码

sis.api.Success                         //成功
sis.api.InvalidParamFormat              //参数错误
sis.api.NotExistDevice                  //设备不存在
sis.sdk.DeviceCommandInvalid            //命令格式错误
sis.sdk.UnknowError                     //其他错误

6. 示意图

用户登录POST数据截图

用户登录头部参数截图

用户登录返回数据截图

API-2 获取设备最后一次上报数据

1. URL

POST https://iot.di-link.com/device/openApi/DeviceGetLastRawData

2. 头部参数

参考前文头部参数描述，携带X-User-Token

3. 数据体（BODY)

{

    "mac": "xxx"            //在IoT系统上录入的设备ID，一般是MAC或者IMEI

}

4. 返回值

{
    "result_code": "sis.api.Success",   //状态码
    "mac": "xxx",                       //查询的设备ID
    "device_status": 0/1,               //设备在线状态，0:离线，1:在线。
    "hex_data": "xxxx",                 //如果设备数据为HEX格式，返回HEX数据base64后的字符串。
    "json_data": {xxx}                  //如果设备数据为json格式，返回json格式的数据
}

5. 错误码

同上

6. 示意图

获取HEX格式的设备数据及返回图

• 说明：raw_array中的串(/v4jrQ==)，进行base64解码后，即为设备发送的原始数据0xFEFE23AD

获取JSON格式的设备数据及返回截图

API-3 向某个设备发送数据

1. URL

POST https://iot.di-link.com/device/openApi/DevicePushRawData

2. 头部参数

参考前文头部参数描述，携带X-User-Token

3. 数据体（BODY)

{
    "mac": "xxx",           //在IoT系统上录入的设备ID，一般是MAC或者IMEI
    "command": "xxx"        //发送给设备的字符串数据。
    "command_hex": "xxx"    //发送给设备的HEX数据，需要base64编码后发送。
}

4. 返回值

{
    "result_code": "sis.api.Success"   //状态码
}

5. 错误码

同上

6. 示意图

6.1、发送HEX数据

6.2、设备收到HEX数据

6.3、发送字符串数据

6.4、设备收到字符串数据