一、介绍

该文档对设备影子的HTTP通讯协议进行介绍，MQTT通讯协议请看：01. 设备影子数据流。

二、通讯协议

2.1 通讯方式

传输协议 HTTP
1 序列化方式 JSON
2 编码格式 UTF-8

2.2 获取设备影子信息

请求路径 /iot-platform/device-shadow-server/v1/get
1 请求方法 GET
2 描述 使用该接口获取设备当前的设备影子信息
3 参数传递方式 URL传递

请求参数描述：

参数名称 参数类型 是否必须 描述
1 productId String 是 产品ID，最大长度为10
2 deviceId String 是 设备ID，最大长度为32

返回值描述：

字段名称 字段类型 是否必须 描述
1 code int 是 状态码，为0时表示接口调用成功，不为0时表示接口调用失败
2 err_code int 是 错误码，当code为0时，返回10000，否则返回对应错误码
3 msg String 是 错误的具体消息
4 result Object 否 返回的结果，当失败时为空

result返回值描述：

字段名称 字段类型 是否必须 描述
1 state Object 是 设备影子的当前状态
2 metadata Object 是 设备影子的当前状态的元数据，目前为表示设备当前状态的更新时间
3 timestamp Long 是 设备影子的最后更新时间,毫秒值，应当保存该值，在后续更新时进行传递

state返回值描述：

字段名称 字段类型 是否必须 描述
1 desired Object 否 当前设备影子属性的期望状态，当没有期望状态时为空
2 reported Object 否 当前设备影子属性的上报状态，当没有上报状态时为空

metadata返回值描述：

字段名称 字段类型 是否必须 描述
1 desired Object 否 当前设备影子属性期望状态的元数据，目前为描述属性期望状态的更新时间，毫秒值，没有期望状态时为空
2 reported Object 否 当前设备影子属性上报状态的元数据，目前为描述属性上报状态的更新时间，毫秒值，当没有上报状态时为空

返回值示例：

{
    "code":0,
    "msg":"ok",
    "err_code":10000,
    "result":{
        "state":{
            "desired":{
                "color":"blue",
                "power":"off"
            },
            "reported":{
                "color":"red",
                "power":"on"
            }
        },
        "metadata":{
            "desired":{
                "color":{
                    "timestamp":1679300280000
                },
                "power":{
                    "timestamp":1679300280000
                }
            },
            "reported":{
                "color":{
                    "timestamp":1679300280000
                },
                "power":{
                    "timestamp":1679300280000
                }
            }
        },
        "timestamp":1679300280000
    }
}

2.3 设置设备影子上报值

请求路径 /iot-platform/device-shadow-server/v1/reported
1 请求方法 POST
2 描述 使用该接口进行设置设备影子上报值
3 参数传递方式 body传递

请求参数描述：

参数名称 参数类型 是否必须 描述
1 productId String 是 产品ID，最大长度为10
2 deviceId String 是 设备ID，最大长度为32
3 timestamp Long 是 设备影子的本地当前最后更新时间，如果该设备影子最后更新时间不等于设备影子服务中的设备影子最后更新时间，则判断是否大于等于该上报字段的metadata中的最后更新时间戳，如不满足，则提示版本冲突，不进行保存。
4 stateReported Object 是 设备影子上报更新值，key为属性名称，value为属性上报值
5 messageId String 否 消息的ID，最大长度为32，如不传将生成随机的消息ID使用

请求示例：

{
  "productId":"Py35WQalC5",
  "deviceId":"7ab02910ab3341c88053f0a82f80a1b9",
  "timestamp":1679300280000,
  "stateReported":{
      "power":"on"
  }
}

返回值描述：

字段名称 字段类型 是否必须 描述
1 code int 是 状态码，为0时表示接口调用成功，不为0时表示接口调用失败
2 err_code int 是 错误码，当code为0时，返回10000，否则返回对应错误码
3 msg String 是 错误的具体消息
4 result Object 是 返回值
5 result.timestamp Long 否 如成功更新，则返回该影子最新的时间戳

返回值示例：

{
    "code": 0,
    "msg": "ok",
    "err_code": 10000,
    "result": {
      "timestamp":1679300281000
    }
}

2.4 设置设备影子期望值

请求路径 /iot-platform/device-shadow-server/v1/desired
1 请求方法 POST
2 描述 使用该接口进行设置设备影子期望值
3 参数传递方式 body传递

请求参数描述：

参数名称 参数类型 是否必须 描述
1 productId String 是 产品ID，最大长度为10
2 deviceId String 是 设备ID，最大长度为32
3 timestamp Long 是 设备影子的本地当前最后更新时间，如果该设备影子最后更新时间不等于设备影子服务中的设备影子最后更新时间，则判断是否大于等于该期望字段的metadata中的最后更新时间戳，如不满足，则提示版本冲突，不进行保存。
4 stateDesired Object 是 设备影子期望更新值，key为属性名称，value为属性期望值
5 messageId String 否 消息的ID，最大长度为32，如不传将生成随机的消息ID使用

请求参数示例：

{
  "productId":"Py35WQalC5",
  "deviceId":"7ab02910ab3341c88053f0a82f80a1b9",
  "timestamp":1679300280000,
  "stateDesired":{
      "power":"on"
  }
}

返回值描述：

字段名称 字段类型 是否必须 描述
1 code int 是 状态码，为0时表示接口调用成功，不为0时表示接口调用失败
2 err_code int 是 错误码，当code为0时，返回10000，否则返回对应错误码
3 msg String 是 错误的具体消息
4 result Object 是 返回值
5 result.timestamp Long 否 如成功更新，则返回该影子最新的时间戳

返回值示例：

{
    "code": 0,
    "msg": "ok",
    "err_code": 10000,
    "result": {
      "timestamp":1679300281000
    }
}

2.5 清除设备影子

请求路径 /iot-platform/device-shadow-server/v1/clean
1 请求方法 DELETE
2 描述 使用该接口清除取设备当前的设备影子信息
3 参数传递方式 url传递

请求参数描述：

参数名称 参数类型 是否必须 描述
1 productId String 是 产品ID，最大长度为10
2 deviceId String 是 设备ID，最大长度为32

返回值描述：

字段名称 字段类型 是否必须 描述
1 code int 是 状态码，为0时表示接口调用成功，不为0时表示接口调用失败
2 err_code int 是 错误码，当code为0时，返回10000，否则返回对应错误码
3 msg String 是 错误的具体消息
4 result Object 是 返回值
5 result.timestamp Long 否 如成功更新，则返回该影子最新的时间戳

返回值示例：

{
    "code": 0,
    "msg": "ok",
    "err_code": 10000,
    "result": {
      "timestamp":1679300281000
    }
}

2.6 更新期望值中JSON对象的属性

请求路径 /iot-platform/device-shadow-server/v1/desired/json/filed/update
1 请求方法 PUT
2 描述 使用该接口进行更新字段值类型为JSON Object 的值，该接口支持添加和更新JSON Object对应的部分值，修改该JSO OBJECT后，将JSON OBJECT值全量下发
3 参数传递方式 body传递

请求参数描述：

参数名称 参数类型 是否必须 描述
1 productId String 是 产品ID，最大长度为10
2 deviceId String 是 设备ID，最大长度为32
3 timestamp Long 是 设备影子的本地当前最后更新时间，如果该设备影子最后更新时间不等于设备影子服务中的设备影子最后更新时间，则判断是否大于等于该期望字段的metadata中的最后更新时间戳，如不满足，则提示版本冲突，不进行保存。
4 desiredFiledKey String 是 设备影子期望字段的Key名称，如果不存在，则新增保存该字段，如果key已经存在，但值不为JSON对象类型，则提示错误，不进行保存
5 jsonPath String 是 JSON Object值中的JSON路径表达式,例子： setting.battery.open
6 value Object 是 更新的值
7 messageId String 否 消息的ID，最大长度为32，如不传将生成随机的消息ID使用

请求参数示例：

{
  "productId":"Py35WQalC5",
  "deviceId":"7ab02910ab3341c88053f0a82f80a1b9",
  "timestamp":1679300280000,
  "desiredFiledKey":"power",
  "jsonPath":"setting.battery.state",
  "value":"on"
}

返回值描述：

字段名称 字段类型 是否必须 描述
1 code int 是 状态码，为0时表示接口调用成功，不为0时表示接口调用失败
2 err_code int 是 错误码，当code为0时，返回10000，否则返回对应错误码
3 msg String 是 错误的具体消息
4 result Object 是 返回值
5 result.timestamp Long 否 如成功更新，则返回该影子最新的时间戳

返回值示例：

{
    "code": 0,
    "msg": "ok",
    "err_code": 10000,
    "result": {
      "timestamp":1679300281000
    }
}

2.7 删除期望值中JSON对象的属性

请求路径 /iot-platform/device-shadow-server/v1/desired/json/filed/delete
1 请求方法 PUT
2 描述 使用该接口进行删除字段值类型为JSON Object 类型的对应字段，修改该JSON OBJECT后，将JSON OBJECT值全量下发
3 参数传递方式 body传递

请求参数描述：

参数名称 参数类型 是否必须 描述
1 productId String 是 产品ID，最大长度为10
2 deviceId String 是 设备ID，最大长度为32
3 timestamp Long 是 设备影子的本地当前最后更新时间，如果该设备影子最后更新时间不等于设备影子服务中的设备影子最后更新时间，则判断是否大于等于该期望字段的metadata中的最后更新时间戳，如不满足，则提示版本冲突，不进行保存。
4 desiredFiledKey String 是 设备影子期望字段的Key名称，如果对应值不存在或对应值不为JSON对象类型，则提示错误，不进行保存
5 jsonPaths Array 是 JSON Object值中的JSON路径表达式列表,JSON路径表达式例子： setting.battery.open
6 messageId String 否 消息的ID，最大长度为32，如不传将生成随机的消息ID使用

请求参数示例：

{
  "productId":"Py35WQalC5",
  "deviceId":"7ab02910ab3341c88053f0a82f80a1b9",
  "timestamp":1679300280000,
  "desiredFiledKey":"power",
  "jsonPaths":[
      "setting.battery.state"
  ]
}

返回值描述：

字段名称 字段类型 是否必须 描述
1 code int 是 状态码，为0时表示接口调用成功，不为0时表示接口调用失败
2 err_code int 是 错误码，当code为0时，返回10000，否则返回对应错误码
3 msg String 是 错误的具体消息
4 result Object 是 返回值
5 result.timestamp Long 否 如成功更新，则返回该影子最新的时间戳

返回值示例：

{
    "code": 0,
    "msg": "ok",
    "err_code": 10000,
    "result": {
      "timestamp":1679300281000
    }
}

2.8 更新上报值中JSON对象的属性

请求路径 /iot-platform/device-shadow-server/v1/reported/json/filed/update
1 请求方法 PUT
2 描述 使用该接口进行更新上报值中字段值类型为JSON Object 的值，该接口支持添加和更新JSON Object对应的部分值，修改该JSO OBJECT后，将JSON OBJECT值全量下发
3 参数传递方式 body传递

请求参数描述：

参数名称 参数类型 是否必须 描述
1 productId String 是 产品ID，最大长度为10
2 deviceId String 是 设备ID，最大长度为32
3 timestamp Long 是 设备影子的本地当前最后更新时间，如果该设备影子最后更新时间不等于设备影子服务中的设备影子最后更新时间，则判断是否大于等于该期望字段的metadata中的最后更新时间戳，如不满足，则提示版本冲突，不进行保存。
4 reportedFiledKey String 是 设备影子上报字段的Key名称，如果不存在，则新增保存该字段，如果key已经存在，但值不为JSON对象类型，则提示错误，不进行保存
5 jsonPath String 是 JSON Object值中的JSON路径表达式,例子： setting.battery.open
6 value Object 是 更新的值
7 messageId String 否 消息的ID，最大长度为32，如不传将生成随机的消息ID使用

请求参数示例：

{
  "productId":"Py35WQalC5",
  "deviceId":"7ab02910ab3341c88053f0a82f80a1b9",
  "timestamp":1679300280000,
  "reportedFiledKey":"power",
  "jsonPath":"setting.battery.state",
  "value":"off"
}

返回值描述：

字段名称 字段类型 是否必须 描述
1 code int 是 状态码，为0时表示接口调用成功，不为0时表示接口调用失败
2 err_code int 是 错误码，当code为0时，返回10000，否则返回对应错误码
3 msg String 是 错误的具体消息
4 result Object 是 返回值
5 result.timestamp Long 否 如成功更新，则返回该影子最新的时间戳

返回值示例：

{
    "code": 0,
    "msg": "ok",
    "err_code": 10000,
    "result": {
      "timestamp":1679300281000
    }
}

2.9 删除上报值中JSON对象的属性

请求路径 /iot-platform/device-shadow-server/v1/reported/json/filed/delete
1 请求方法 PUT
2 描述 使用该接口进行删除上报值中字段值类型为JSON Object 类型的对应字段，修改该JSON OBJECT后，将JSON OBJECT值全量下发
3 参数传递方式 body传递

请求参数描述：

参数名称 参数类型 是否必须 描述
1 productId String 是 产品ID，最大长度为10
2 deviceId String 是 设备ID，最大长度为32
3 timestamp Long 是 设备影子的本地当前最后更新时间，如果该设备影子最后更新时间不等于设备影子服务中的设备影子最后更新时间，则判断是否大于等于该期望字段的metadata中的最后更新时间戳，如不满足，则提示版本冲突，不进行保存。
4 reportedFiledKey String 是 设备影子上报字段的Key名称，如果对应值不存在或对应值不为JSON对象类型，则提示错误，不进行保存
5 jsonPaths Array 是 JSON Object值中的JSON路径表达式列表,JSON路径表达式例子： setting.battery.open
6 messageId String 否 消息的ID，最大长度为32，如不传将生成随机的消息ID使用

请求参数示例：

{
  "productId":"Py35WQalC5",
  "deviceId":"7ab02910ab3341c88053f0a82f80a1b9",
  "timestamp":1679300280000,
  "reportedFiledKey":"power",
  "jsonPaths":[
      "setting.battery.state"
  ]
}

返回值描述：

字段名称 字段类型 是否必须 描述
1 code int 是 状态码，为0时表示接口调用成功，不为0时表示接口调用失败
2 err_code int 是 错误码，当code为0时，返回10000，否则返回对应错误码
3 msg String 是 错误的具体消息
4 result Object 是 返回值
5 result.timestamp Long 否 如成功更新，则返回该影子最新的时间戳

返回值示例：

{
    "code": 0,
    "msg": "ok",
    "err_code": 10000,
    "result": {
      "timestamp":1679300281000
    }
}

2.10 删除设备影子上报值

请求路径 /iot-platform/device-shadow-server/v1/reported
1 请求方法 DELETE
2 描述 使用该接口进行删除上报值
3 参数传递方式 URL传递

请求参数描述：

参数名称 参数类型 是否必须 描述
1 productId String 是 产品ID，最大长度为10
2 deviceId String 是 设备ID，最大长度为32
3 timestamp Long 是 设备影子的本地当前最后更新时间，如果该设备影子最后更新时间不等于设备影子服务中的设备影子最后更新时间，如不满足，则提示版本冲突，不进行保存。
4 reportedFiledKey String 是 设备影子上报字段的Key名称，如果key不存在则忽略
5 messageId String 否 消息的ID，最大长度为32，如不传将生成随机的消息ID使用

返回值描述：

字段名称 字段类型 是否必须 描述
1 code int 是 状态码，为0时表示接口调用成功，不为0时表示接口调用失败
2 err_code int 是 错误码，当code为0时，返回10000，否则返回对应错误码
3 msg String 是 错误的具体消息
4 result Object 是 返回值
5 result.timestamp Long 否 如成功更新，则返回该影子最新的时间戳

返回值示例：

{
    "code": 0,
    "msg": "ok",
    "err_code": 10000,
    "result": {
      "timestamp":1679300281000
    }
}

2.11 删除设备影子期望值

请求路径 /iot-platform/device-shadow-server/v1/desired
1 请求方法 DELETE
2 描述 使用该接口进行删除上报值
3 参数传递方式 URL传递

请求参数描述：

参数名称 参数类型 是否必须 描述
1 productId String 是 产品ID，最大长度为10
2 deviceId String 是 设备ID，最大长度为32
3 timestamp Long 是 设备影子的本地当前最后更新时间，如果该设备影子最后更新时间不等于设备影子服务中的设备影子最后更新时间，则提示版本冲突，不进行保存。
4 desiredFiledKey String 是 设备影子期望字段的Key名称，如果key不存在则忽略
5 messageId String 否 消息的ID，最大长度为32，如不传将生成随机的消息ID使用

返回值描述：

字段名称 字段类型 是否必须 描述
1 code int 是 状态码，为0时表示接口调用成功，不为0时表示接口调用失败
2 err_code int 是 错误码，当code为0时，返回10000，否则返回对应错误码
3 msg String 是 错误的具体消息
4 result Object 是 返回值
5 result.timestamp Long 否 如成功更新，则返回该影子最新的时间戳

返回值示例：

{
    "code": 0,
    "msg": "ok",
    "err_code": 10000,
    "result": {
      "timestamp":1679300281000
    }
}

2.12 批量更新期望值中JSON对象的属性

请求路径 /iot-platform/device-shadow-server/v1/desired/json/filed/update/batch
1 请求方法 PUT
2 描述 使用该接口进行批量更新字段值类型为JSON Object 的值，该接口支持添加和更新JSON Object对应的部分值，修改该JSO OBJECT后，将JSON OBJECT值全量下发
3 参数传递方式 body传递

请求参数描述：

参数名称 参数类型 是否必须 描述
1 productId String 是 产品ID，最大长度为10
2 deviceId String 是 设备ID，最大长度为32
3 timestamp Long 是 设备影子的本地当前最后更新时间，如果该设备影子最后更新时间不等于设备影子服务中的设备影子最后更新时间，则判断是否大于等于该期望字段的metadata中的最后更新时间戳，如不满足，则提示版本冲突，不进行保存。
4 updateInfos Array 是 更新的信息数组，每个元素为更新的期望值信息
5 updateInfos.{index}.desiredFiledKey String 是 设备影子期望字段的Key名称，如果不存在，则新增保存该字段，如果key已经存在，但值不为JSON对象类型，则提示错误，不进行保存
6 updateInfos.{index}.jsonPath String 是 JSON Object值中的JSON路径表达式,例子： setting.battery.open
6 updateInfos.{index}.value Object 是 更新的值
7 messageId String 否 消息的ID，最大长度为32，如不传将生成随机的消息ID使用

请求参数示例：

{
  "productId":"Py35WQalC5",
  "deviceId":"7ab02910ab3341c88053f0a82f80a1b9",
  "timestamp":1679300280000,
  "updateInfos":[{
      "desiredFiledKey":"power",
      "jsonPath":"setting.battery.state",
      "value":"on"
  }
  ]
}

返回值描述：

字段名称 字段类型 是否必须 描述
1 code int 是 状态码，为0时表示接口调用成功，不为0时表示接口调用失败
2 err_code int 是 错误码，当code为0时，返回10000，否则返回对应错误码
3 msg String 是 错误的具体消息
4 result Object 是 返回值
5 result.timestamp Long 否 如成功更新，则返回该影子最新的时间戳

返回值示例：

{
    "code": 0,
    "msg": "ok",
    "err_code": 10000,
    "result": {
      "timestamp":1679300281000
    }
}

2.8 批量更新上报值中JSON对象的属性

请求路径 /iot-platform/device-shadow-server/v1/reported/json/filed/update/batch
1 请求方法 PUT
2 描述 使用该接口批量进行更新上报值中字段值类型为JSON Object 的值，该接口支持添加和更新JSON Object对应的部分值，修改该JSO OBJECT后，将JSON OBJECT值全量下发
3 参数传递方式 body传递

请求参数描述：

参数名称 参数类型 是否必须 描述
1 productId String 是 产品ID，最大长度为10
2 deviceId String 是 设备ID，最大长度为32
3 timestamp Long 是 设备影子的本地当前最后更新时间，如果该设备影子最后更新时间不等于设备影子服务中的设备影子最后更新时间，则判断是否大于等于该期望字段的metadata中的最后更新时间戳，如不满足，则提示版本冲突，不进行保存。
4 updateInfos Array 是 更新的信息数组，每个元素为更新的期望值信息
5 updateInfos.{index}.reportedFiledKey String 是 设备影子上报字段的Key名称，如果不存在，则新增保存该字段，如果key已经存在，但值不为JSON对象类型，则提示错误，不进行保存
5 updateInfos.{index}.jsonPath String 是 JSON Object值中的JSON路径表达式,例子： setting.battery.open
6 updateInfos.{index}.value Object 是 更新的值
7 messageId String 否 消息的ID，最大长度为32，如不传将生成随机的消息ID使用

请求参数示例：

{
  "productId":"Py35WQalC5",
  "deviceId":"7ab02910ab3341c88053f0a82f80a1b9",
  "timestamp":1679300280000,
  "updateInfos":[{
      "reportedFiledKey":"power",
      "jsonPath":"setting.battery.state",
      "value":"on"
  }
  ]
}

返回值描述：

字段名称 字段类型 是否必须 描述
1 code int 是 状态码，为0时表示接口调用成功，不为0时表示接口调用失败
2 err_code int 是 错误码，当code为0时，返回10000，否则返回对应错误码
3 msg String 是 错误的具体消息
4 result Object 是 返回值
5 result.timestamp Long 否 如成功更新，则返回该影子最新的时间戳

返回值示例：

{
    "code": 0,
    "msg": "ok",
    "err_code": 10000,
    "result": {
      "timestamp":1679300281000
    }
}

三、鉴权方式

该接口可使用开放API方式进行接入，接入文档请看：应用鉴权

四、错误码

errorCode errorMessage
900010 影子版本冲突。
900013 缺少参数
900014 参数格式错误
900015 字段值不为JSON 对象类型
900016 字段值不存在
500 服务端处理异常。
 创建时间：2023-03-23 20:53
最后编辑：admin  更新时间：2024-10-18 16:29