# 服务调用和通信

# MQTT 通信

设备通过 topic 和 broker 之间做 MQTT 的通信,这和其他常规的 topic 通信没有区别,影子服务额外 提供了存储(数据缓存)能力。设备端或者应用端可通过影子服务包含的两个 topic 进行通信,即用于设备端的数据上报的发布主题,以及用于设备端做数据接收的订阅主题。

# 主题和方法

Topic说明
shadow/${shadow_id}发布主题全局唯一,用于设备端/客户端发布更新消息,或者获取最新的影子模型。
shadow/${shadow_id}/reply订阅主题全局唯一,用于设备端/客户端接收最新的消息。

主题中除了 payload 存放消息之外,还需定义 method 来告知服务应该如何更新消息。

method类型说明
PUT请在发布主题中使用该方法,对应 HTTP 的 PUT 方法,用于全量更新 影子模型 data 的数据,用法请见调用示例。
PATCH请在发布主题中使用该方法,对应 HTTP 的 PATCH 方法,用于增量更新 影子模型 data 的数据,用法请见调用示例。
GET请在发布主题中使用该方法,对应 HTTP 的 GET 方法,用于在订阅主题中获得最新的 影子模型 JSON 数据。

在使用 PATCH 方法更新 paylaod 的情况下,不能新增多层级对象,请见调用示例。

影子服务 JSON

字段类型说明
dataObject主题或者 API 发布的消息主体
createAtNumberJSON 创建时间
lastTimeNumber最新一次更新的时间
versionNumber该影子模型更新的次数
{
    "data": {},
    "createAt": 1660201961567,
    "lastTime": 1660204233317,
    "version": 3
}
1
2
3
4
5
6

# 调用示例

# 全量(全局)更新

使用全量更新的方法更新影子模型数据,使用 PUT 方法以及 payload 存放消息

影子模型 data

{
    "Key01": {
        "a": 100
    }
}
1
2
3
4
5

发布主题(shadow/${shadow_id})全量更新

{
    "method": "PUT",
    "payload": {
        "Key01": {
            "b": 200,
            "c": 300
        },
        "Key02": {
            "d" : 400
        }
    }
}
1
2
3
4
5
6
7
8
9
10
11
12

影子模型 data 将更新为

{
    "Key01": {
        "b": 200,
        "c": 300
    },
    "Key02": {
        "d": 400
    }
}
1
2
3
4
5
6
7
8
9

# 增量(局部)更新

使用增量更新的方法更新影子模型数据,使用 PATCH 方法以及 payload 存放消息

影子模型 data

{
    "Key01": {
        "a": 100
    }
}
1
2
3
4
5

发布主题(shadow/${shadow_id})增量更新

{
    "method": "PATCH",
    "payload": {
        "Key01": {
            "b": 200,
            "c": 300
        }
    }
}
1
2
3
4
5
6
7
8
9

影子模型 data 将更新为

{
    "Key01": {
        "a": 100,
        "b": 200,
        "c": 300
    }
}
1
2
3
4
5
6
7

# 增量更新新增多层对象的方法

由于增量更新的方法不支持一步新增多层对象,因而需要一层一层进行添加。

影子模型 data

{
    "Key01": {
        "a": 100
    }
}
1
2
3
4
5

以下直接添加多层新对象的方式都会报错

{
    "method": "PATCH",
    "payload": {
        "Key01": {
            "a": 100
        },
        "Key02": {
            "b": 200
        }
    }
}

{
    "method": "PATCH",
    "payload": {
        "Key01": {
            "a": 100,
            "Key02": {
                "b": 200
            }
        }
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

如果需要多层新对象,请逐层添加,或者使用全量更新方法来添加

//第一步
{
    "method": "PATCH",
    "payload": {
        "Key01": {
            "a": 100
        },
        "Key02": {}
    }
}

// 第二步
{
    "method": "PATCH",
    "payload": {
        "Key01": {
            "a": 100
        },
        "Key02": {
            "b": 200
        }
    } 
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# 获取模型数据

使用 GET 方法获取影子模型数据

影子模型 data

{
    "Key01": {
        "a": 100
    },
    "Key02": {
        "b": 200
    }
}
1
2
3
4
5
6
7
8

发布主题(shadow/${shadow_id})获取数据

{
    "payload": {},
    "method": "GET"
}
1
2
3
4

在订阅主题(shadow/${shadow_id}/reply)将接收到影子模型 JSON

{
    "data": {
        "Key01": {
            "a": 100
        },
        "Key02": {
            "b": 200
        }
    },
    "createAt": 1660201961567,
    "lastTime": 1660204233317,
    "version": 2
}
1
2
3
4
5
6
7
8
9
10
11
12
13

# API 通信