# 影子服务管理
对于您自己的应用开发,可以使用 API 来获取影子服务的相关信息。
# API 列表
URL | 方法 | 说明 |
---|---|---|
/shadows | POST | 新建影子模型 |
/shadows | GET | 获取影子模型列表 |
/shadows/${shadow_id} | GET | 获取指定影子模型信息 |
/shadows/${shadow_id} | PUT | 更新指定影子模型信息 |
/shadows/${shadow_id} | DELETE | 删除指定影子模型 |
/shadows/${shadow_id}/json | GET | 获取指定影子模型 JSON |
/shadows/${shadow_id}/json | PUT | 全量更新指定影子模型 JSON |
/shadows/${shadow_id}/json | PATCH | 增量更新指定影子模型 JSON |
# 获取影子模型列表
# URL
GET /shadows
# 请求消息
名称 | 类型 | 描述 |
---|---|---|
_page | Integer | 页码 |
_limit | Integer | 每页显示的数据条数 |
# 响应消息
名称 | 类型 | 描述 |
---|---|---|
items | Array of Objects | 所有影子模型信息 |
items[].description | String | 影子模型描述 |
items[].updatedAt | String | 影子模型更新时间(UTC) |
items[].shadowID | String | 影子模型 ID |
items[].createdAt | String | 影子模型创建时间(UTC) |
items[].shadowName | String | 影子模型名称 |
meta | Object | 分页信息 |
meta.page | Integer | 页码 |
meta.limit | Integer | 每页显示的数据条数 |
meta.count | Integer | 数据总条数 |
# 请求示例
curl -u app_id:app_secret -X GET {api}/shadows/?_page=1&_limit=10
1
# 响应示例
{
"items": [
{
"description": "123",
"updatedAt": "2022-06-10 03:20",
"shadowID": "test_shadow",
"createdAt": "2022-06-10 03:20",
"shadowName": "test"
}
],
"meta": {
"limit": 10,
"page": 1,
"count": 1
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 获取指定影子模型信息
# URL
GET /shadows/${shadow_id}
# 请求消息
无
# 响应消息
名称 | 类型 | 描述 |
---|---|---|
description | String | 影子模型描述 |
updatedAt | String | 影子模型更新时间(UTC) |
shadowID | String | 影子模型 ID |
createdAt | String | 影子模型创建时间(UTC) |
shadowName | String | 影子模型名称 |
# 请求示例
curl -u app_id:app_secret -X GET {api}/shadows/${shadow_id}
1
# 响应示例
{
"description": "123",
"updatedAt": "2022-06-10 03:20",
"shadowID": "test_shadow",
"createdAt": "2022-06-10 03:20",
"shadowName": "test"
}
1
2
3
4
5
6
7
2
3
4
5
6
7
# 获取指定影子模型 JSON
# URL
GET /shadows/${shadow_id}/json
# 请求消息
无
# 响应消息
名称 | 类型 | 描述 |
---|---|---|
createdAt | Integer | JSON 创建时间毫秒时间戳(UTC) |
lastTime | Integer | JSON 更新时间毫秒时间戳(UTC) |
version | Integer | JSON 修改的版本号 |
data | String | 消息正文 |
# 响应消息示例格式
名称 | 类型 | 描述 |
---|---|---|
data[].color | String | 颜色 |
data[].state | Integer | 状态 |
data[].power | Integer | 电量 |
# 请求示例
curl -u app_id:app_secret -X GET {api}/shadows/${shadow_id}/json
1
# 响应示例
{
"data": {
"color": "blue",
"power": 0,
"state": 1
},
"createAt": 1660618831979,
"lastTime": 1660631951790,
"version": 1
}
1
2
3
4
5
6
7
8
9
10
2
3
4
5
6
7
8
9
10
# 创建影子模型
# URL
POST /shadows
# 请求消息
提示
影子模型 ID 为非必填,系统会自动生成,同时也支持用户自定义。
名称 | 类型 | 描述 |
---|---|---|
description | String | 影子模型描述 |
shadowID | String | 影子模型 ID |
shadowName | String | 影子模型名称 |
# 响应消息
名称 | 类型 | 描述 |
---|---|---|
description | String | 影子模型描述 |
updatedAt | String | 影子模型更新时间(UTC) |
shadowID | String | 影子模型 ID |
createdAt | String | 影子模型创建时间(UTC) |
shadowName | String | 影子模型名称 |
# 请求示例
curl -u app_id:app_secret -X POST -d '{"description": "123","shadowID": "test_shadow","shadowName": "test"}' {api}/shadows
1
# 响应示例
{
"description": "123",
"updatedAt": "2022-06-10 03:39",
"shadowID": "test_shadow",
"createdAt": "2022-06-10 03:39",
"shadowName": "test"
}
1
2
3
4
5
6
7
2
3
4
5
6
7
# 更新指定影子模型信息
# URL
PUT /shadows/${shadow_id}
# 请求消息
提示
影子模型一旦创建,就无法对 ID 进行修改
名称 | 类型 | 描述 |
---|---|---|
description | String | 影子模型描述 |
shadowName | String | 影子模型名称 |
# 响应消息
名称 | 类型 | 描述 |
---|---|---|
description | String | 影子模型描述 |
updatedAt | String | 影子模型更新时间(UTC) |
shadowID | String | 影子模型 ID |
createdAt | String | 影子模型创建时间(UTC) |
shadowName | String | 影子模型名称 |
# 请求示例
curl -u app_id:app_secret -X PUT -d '{"description": "","shadowName": "test"}' {api}/shadows/${shadow_id}
1
# 响应示例
{
"description": "",
"updatedAt": "2022-06-10 03:39",
"shadowID": "test_shadow",
"createdAt": "2022-06-10 03:39",
"shadowName": "test"
}
1
2
3
4
5
6
7
2
3
4
5
6
7
# 全量更新指定影子模型 JSON
# URL
PUT /shadows/${shadow_id}/json
# 请求消息
名称 | 类型 | 描述 |
---|---|---|
data | String | 消息正文 |
# 请求消息示例格式
名称 | 类型 | 描述 |
---|---|---|
data[].color | String | 颜色 |
data[].state | Integer | 状态 |
data[].power | Integer | 电量 |
# 响应消息
名称 | 类型 | 描述 |
---|---|---|
createdAt | Integer | JSON 创建时间毫秒时间戳(UTC) |
lastTime | Integer | JSON 更新时间毫秒时间戳(UTC) |
version | Integer | JSON 修改的版本号 |
data | String | 消息正文 |
# 请求示例
curl -u app_id:app_secret -X PUT -d '{"color": "blue","state": 1,"power": 0}' {api}/shadows/${shadow_id}/json
1
# 响应示例
{
"data": {
"color": "blue",
"power": 0,
"state": 1
},
"createAt": 1660618831979,
"lastTime": 1660631951770,
"version": 9
}
1
2
3
4
5
6
7
8
9
10
2
3
4
5
6
7
8
9
10
# 增量更新指定影子模型 JSON
# URL
PATCH /shadows/${shadow_id}/json
# 请求消息
名称 | 类型 | 描述 |
---|---|---|
data | String | 消息正文 |
# 请求消息示例格式
名称 | 类型 | 描述 |
---|---|---|
data[].specs | Integer | 规格 |
# 响应消息
名称 | 类型 | 描述 |
---|---|---|
createdAt | Integer | JSON 创建时间毫秒时间戳(UTC) |
lastTime | Integer | JSON 更新时间毫秒时间戳(UTC) |
version | Integer | JSON 修改的版本号 |
data | String | 消息正文 |
# 请求示例
curl -u app_id:app_secret -X PATCH -d '{"specs": 2}' {api}/shadows/${shadow_id}/json
1
# 响应示例
{
"data": {
"color": "blue",
"power": 0,
"specs": 2,
"state": 1
},
"createAt": 1660618831979,
"lastTime": 1660631880990,
"version": 10
}
1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
# 增量更新指定影子模型 JSON 多层对象
# URL
PATCH /shadows/${shadow_id}/json
# 请求消息
名称 | 类型 | 描述 |
---|---|---|
data | String | 消息正文 |
# 响应消息
名称 | 类型 | 描述 |
---|---|---|
createdAt | Integer | JSON 创建时间毫秒时间戳(UTC) |
lastTime | Integer | JSON 更新时间毫秒时间戳(UTC) |
version | Integer | JSON 修改的版本号 |
data | String | 消息正文 |
# 请求示例
提示
如果需要增量更新多层新对象,请逐层添加,不可直接添加多层新对象,会失败并返回 500 状态码。
# 错误请求示例
curl -u app_id:app_secret -X PATCH -d '{"key": {"a":100}}' {api}/shadows/${shadow_id}/json
1
2
2
# 正确请求示例
curl -u app_id:app_secret -X PATCH -d '{"key": {}}' {api}/shadows/${shadow_id}/json
curl -u app_id:app_secret -X PATCH -d '{"key": {"a":100}}' {api}/shadows/${shadow_id}/json
1
2
3
4
2
3
4
# 响应示例
{
"data": {
"color": "blue",
"key": {},
"power": 0,
"specs": 2,
"state": 1
},
"createAt": 1662087412285,
"lastTime": 1662106829205,
"version": 12
}
1
2
3
4
5
6
7
8
9
10
11
12
2
3
4
5
6
7
8
9
10
11
12
{
"data": {
"color": "blue",
"key": {
"a": 100
},
"power": 0,
"specs": 2,
"state": 1
},
"createAt": 1662087412285,
"lastTime": 1662106900812,
"version": 13
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
2
3
4
5
6
7
8
9
10
11
12
13
14
# 删除指定影子模型
# URL
DELETE /shadows/${shadow_id}
# 请求消息
无
# 响应消息
无
# 请求示例
curl -u app_id:app_secret -X DELETE {api}/shadows/${shadow_id}
1