你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
IoT 中心数据平面 MQTT 5 API 参考（预览版）
本文档定义了 IoT 中心数据平面 API 版本 2.0（api-version：2020-10-01-preview）中可用的操作。
注意
IoT 中心对 MQTT 的功能支持有限。 如果你的解决方案需要 MQTT v3.1.1 或 v5 支持，我们建议查看 Azure 事件网格中的 MQTT 支持。 有关详细信息，请参阅比较 IoT 中心和事件网格中的 MQTT 支持。
操作
Get Twin
获取孪生体状态
请求
主题名称：
属性：无
有效负载：空
成功响应
属性：无
有效负载：孪生体
替代响应
| 状态 | 名称 | 说明 |
|---|---|---|
| 0100 | 错误的请求 | 操作消息格式不正确，无法处理。 |
| 0101 | 未授权 | 客户端无权执行此操作。 |
| 0102 | 不允许 | 操作不允许。 |
| 0501 | 已中止 | 每个 SKU 的请求速率太高 |
| 0502 | 超出配额 | 超过每个当前 SKU 的每日配额 |
| 0601 | 服务器错误 | 内部服务器错误 |
| 0602 | 超时 | 操作超时，无法完成。 |
| 0603 | 服务器忙 | 服务器忙 |
伪代码示例
-> PUBLISH
QoS: 0
Topic: $iothub/twin/get
<- PUBLISH
QoS: 0
Topic: $iothub/responses
报告的补丁孪生体
报告的补丁孪生体的状态
请求
主题名称：
属性：
| 名称 | Type | 需要 | 说明 |
|---|---|---|---|
| if-version | u64 | 否 |
有效负载：TwinState
成功响应
属性：
| 名称 | Type | 需要 | 说明 |
|---|---|---|---|
| 版本 | u64 | 是 | 应用补丁后报告的状态的版本 |
有效负载：空
替代响应
| 状态 | 名称 | 说明 |
|---|---|---|
| 0104 | 不满足前提条件 | 不满足前提条件，导致请求被取消 |
| 0100 | 错误的请求 | 操作消息格式不正确，无法处理。 |
| 0101 | 未授权 | 客户端无权执行此操作。 |
| 0102 | 不允许 | 操作不允许。 |
| 0501 | 已中止 | 每个 SKU 的请求速率太高 |
| 0502 | 超出配额 | 超过每个当前 SKU 的每日配额 |
| 0601 | 服务器错误 | 内部服务器错误 |
| 0602 | 超时 | 操作超时，无法完成。 |
| 0603 | 服务器忙 | 服务器忙 |
伪代码示例
-> PUBLISH
QoS: 0
Topic: $iothub/twin/patch/reported
[if-version: <u64>]
<- PUBLISH
QoS: 0
Topic: $iothub/responses
接收命令
接收并处理命令
消息
主题名称：
属性：
| 名称 | Type | 需要 | 说明 |
|---|---|---|---|
| sequence-no | u64 | 是 | 消息的序列号 |
| enqueued-time | time | 是 | 消息进入系统时的时间戳 |
| delivery-count | u32 | 是 | 尝试消息传递的次数 |
| creation-time | time | 否 | 创建消息时的时间戳（由发送方提供） |
| message-id | string | 否 | 消息标识（由发送方提供） |
| user-id | string | 否 | 用户标识（由发送方提供） |
| correlation-id | string | 否 | 关联标识（由发送方提供） |
| 内容类型 | string | 否 | 确定有效负载的内容类型 |
| content-encoding | string | 否 | 确定有效负载的内容编码 |
有效负载：任意字节序列
成功确认
指示客户端已接受命令进行处理
属性：无
有效负载：空
替代确认
| 原因代码 | 状态 | 名称 | 说明 |
|---|---|---|---|
| 131 | 0603 | 放弃 | 指示此时不会处理命令，应在将来重新传递它。 |
| 131 | 0100 | 拒绝 | 指示客户端拒绝了该命令，且不应再次尝试它。 |
伪代码示例
-> SUBSCRIBE
- Topic: $iothub/commands
QoS: 1
<- PUBLISH
QoS: 1
Topic: $iothub/commands
sequence-no: <u64>enqueued-time: <time>delivery-count: <u32>[creation-time: <time>][message-id: <string>][user-id: <string>][correlation-id: <string>][Content Type: <string>][content-encoding: <string>]
Payload: ...
-> PUBACK
接收直接方法
接收并处理直接方法调用
请求
主题名称：
属性：无
有效负载：任意字节序列
成功响应
属性：
| 名称 | Type | 需要 | 说明 |
|---|---|---|---|
| response-code | u32 | 是 |
有效负载：任意字节序列
替代响应
| 状态 | 名称 | 说明 |
|---|---|---|
| 06A0 | 不可用 | 指示无法通过此连接访问客户端。 |
伪代码示例
-> SUBSCRIBE
- Topic: methods/{name}
QoS: 0
<- SUBACK
<- PUBLISH
QoS: 0
Topic: $iothub/methods/{name}
-> PUBLISH
QoS: 0
Topic: $iothub/responses
接收孪生体所需状态更改
接收对孪生体所需状态的更新
消息
主题名称：
属性：
| 名称 | Type | 需要 | 说明 |
|---|---|---|---|
| 版本 | u64 | 是 | 与此更新匹配的所需状态的版本 |
有效负载：TwinState
伪代码示例
-> SUBSCRIBE
- Topic: $iothub/twin/patch/desired
QoS: 0
<- PUBLISH
QoS: 0
Topic: $iothub/twin/patch/desired
version: <u64>
Payload: ...
发送遥测数据
通过路由配置将消息发布到遥测通道 - 事件中心（默认）或其他终结点。
消息
主题名称：
属性：
| 名称 | Type | 需要 | 说明 |
|---|---|---|---|
| 内容类型 | string | 否 | 在发布后的消息中转换为 content-type 系统属性 |
| content-encoding | string | 否 | 在发布后的消息中转换为 content-encoding 系统属性 |
| message-id | string | 否 | 在发布后的消息中转换为 message-id 系统属性 |
| user-id | string | 否 | 在发布后的消息中转换为 user-id 系统属性 |
| correlation-id | string | 否 | 在发布后的消息中转换为 correlation-id 系统属性 |
| creation-time | time | 否 | 在发布后的消息中转换为 iothub-creation-time-utc 属性 |
提示
creation-time 的格式必须为 UTC（不含时区信息）。 例如，2021-04-21T11:30:16Z 有效，2021-04-21T11:30:16-07:00 无效。
有效负载：任意字节序列
成功确认
已成功将消息发布到遥测数据通道
属性：无
有效负载：空
替代确认
| 原因代码 | 状态 | 名称 | 说明 |
|---|---|---|---|
| 131 | 0100 | 错误的请求 | 操作消息格式不正确，无法处理。 |
| 135 | 0101 | 未授权 | 客户端无权执行此操作。 |
| 131 | 0102 | 不允许 | 操作不允许。 |
| 131 | 0601 | 服务器错误 | 内部服务器错误 |
| 151 | 0501 | 已中止 | 每个 SKU 的请求速率太高 |
| 151 | 0502 | 超出配额 | 超过每个当前 SKU 的每日配额 |
| 131 | 0602 | 超时 | 操作超时，无法完成。 |
| 131 | 0603 | 服务器忙 | 服务器忙 |
伪代码示例
-> PUBLISH
QoS: 1
Topic: $iothub/telemetry
[Content Type: <string>]
[content-encoding: <string>]
[message-id: <string>]
[user-id: <string>]
[correlation-id: <string>]
[creation-time: <time>]
<- PUBACK
响应
错误的请求
操作消息格式不正确，无法处理。
原因代码：
状态：
属性：
| 名称 | Type | 需要 | 说明 |
|---|---|---|---|
| reason | string | 否 | 包含有关消息中具体哪些内容无效的信息 |
有效负载：空
Conflict
操作与另一个正在进行的操作冲突。
原因代码：
状态：
属性：
| 名称 | Type | 需要 | 说明 |
|---|---|---|---|
| trace-id | string | 否 | 用于和错误的其他诊断关联的跟踪 ID |
| reason | string | 否 | 包含有关消息中具体哪些内容无效的信息 |
有效负载：空
不允许
操作不允许。
原因代码：
状态：
属性：
| 名称 | Type | 需要 | 说明 |
|---|---|---|---|
| reason | string | 否 | 包含有关消息中具体哪些内容无效的信息 |
有效负载：空
未授权
客户端无权执行此操作。
原因代码：
状态：
属性：
| 名称 | Type | 需要 | 说明 |
|---|---|---|---|
| trace-id | string | 否 | 用于和错误的其他诊断关联的跟踪 ID |
有效负载：空
未找到
请求的资源不存在
原因代码：
状态：
属性：
| 名称 | Type | 需要 | 说明 |
|---|---|---|---|
| reason | string | 否 | 包含有关消息中具体哪些内容无效的信息 |
有效负载：空
未修改
根据提供的前提条件，资源未修改。
原因代码：
状态：
属性：无
有效负载：空
不满足前提条件
前提条件不满足，导致请求被取消
原因代码：
状态：
属性：无
有效负载：空
超出配额
超过每个当前 SKU 的每日配额
原因代码：
状态：
属性：无
有效负载：空
资源已耗尽
资源没有容量来完成操作
原因代码：
状态：
属性：
| 名称 | Type | 需要 | 说明 |
|---|---|---|---|
| reason | string | 否 | 包含有关消息中具体哪些内容无效的信息 |
有效负载：空
服务器忙
服务器忙
原因代码：
状态：
属性：
| 名称 | Type | 需要 | 说明 |
|---|---|---|---|
| trace-id | string | 否 | 用于和错误的其他诊断关联的跟踪 ID |
有效负载：空
服务器错误
内部服务器错误
原因代码：
状态：
属性：
| 名称 | Type | 需要 | 说明 |
|---|---|---|---|
| trace-id | string | 否 | 用于和错误的其他诊断关联的跟踪 ID |
有效负载：空
目标失败
目标已响应，但响应无效或格式不正确
原因代码：
状态：
属性：
| 名称 | Type | 需要 | 说明 |
|---|---|---|---|
| reason | string | 否 | 包含有关消息中具体哪些内容无效的信息 |
有效负载：空
目标超时
等待目标完成请求时超时
原因代码：
状态：
属性：
| 名称 | Type | 需要 | 说明 |
|---|---|---|---|
| trace-id | string | 否 | 用于和错误的其他诊断关联的跟踪 ID |
| reason | string | 否 | 包含有关消息中具体哪些内容无效的信息 |
有效负载：空
目标不可用
无法访问目标来完成请求
原因代码：
状态：
属性：无
有效负载：空
已中止
每个 SKU 的请求速率太高
原因代码：
状态：
属性：无
有效负载：空
超时
操作超时，无法完成。
原因代码：
状态：
属性：
| 名称 | Type | 需要 | 说明 |
|---|---|---|---|
| trace-id | string | 否 | 用于和错误的其他诊断关联的跟踪 ID |
有效负载：空