你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Azure Device Update for IoT Hub 中的 IoT 即插即用

项目
03/08/2025

IoT 中心的设备更新使用 IoT 即插即用以发现和管理支持无线更新的设备。本文介绍了 Device Update 服务如何使用 IoT 即插即用接口向设备发送属性和消息以及从设备接收属性和消息。

有关详细信息，请参阅 IoT 即插即用设备开发人员指南和如何生成 Device Update 代理。

Device Update 模型

智能设备使用 IoT 即插即用模型 ID 将其功能播发到 Azure IoT 应用程序。 Device Update 要求 IoT 即插即用智能设备在设备连接过程中公布模型 ID。有关详细信息，请参阅模型 ID 公告。

Device Update 有几个定义的 IoT 即插即用模型支持 Device Update 功能。 Device Update 模型 **dtmi:azure:iot:deviceUpdateContractModel;3** 支持核心 Device Update 功能，并使用 Device Update 核心接口将更新操作和元数据发送到设备，并从设备接收更新状态。

另一种支持的模型是 **dtmi:azure:iot:deviceUpdateModel;3**，它扩展 **deviceUpdateContractModel;3**，并使用 IoT 即插即用接口发送设备属性信息并启用诊断功能。有关这些版本和其他版本，请参阅 Azure IoT 即插即用 Device Update 模型。

Device Update 代理使用 **dtmi:azure:iot:deviceUpdateModel;3**，它支持 Device Update 1.1.0 版本中的所有最新功能。此模型支持导入清单版本 5.0。较旧的清单适用于最新代理，但新功能需要最新的清单版本。

代理元数据

Device Update 代理使用以下代理元数据字段将信息发送到 Device Update 服务。

名称	架构	方向	说明
deviceProperties	映射	设备到云	一组属性，其中包含制造商、型号和其他设备信息。有关详细信息，请参阅设备属性。
compatPropertyNames	字符串（以英文逗号分隔）	设备到云	最多 5 个属性，用于检查设备兼容性以定位更新部署。示例："compatPropertyNames": "manufacturer,model"
lastInstallResult	映射	设备到云	代理报告的结果，包含结果代码、扩展的结果代码以及主更新和其他步骤更新的结果详细信息。
resultCode	integer	设备到云	此代码包含上次更新操作结果的信息。可能填充成功，也可能填充失败。示例：700
extendedResultCode	integer	设备到云	包含有关结果的更多信息的代码。可能填充成功，也可能填充失败。示例：0x80004005
resultDetails	字符串	设备到云	用户提供的自由格式的字符串，用于提供更多结果详细信息。返回到未解析的孪生体。
stepResults	map	设备到云	代理报告的结果，包含结果代码、扩展的结果代码以及步骤更新的结果详细信息。示例："step_1": { "resultCode": 0,"extendedResultCode": 0, "resultDetails": ""}
state	integer	设备到云	此整数用于指示 Device Update 代理的当前状态。有关详细信息，请参阅状态。
workflow	complex	设备到云	一组值，指示代理当前正在处理的部署、当前安装的部署的 ID 以及从服务发送到代理的任何重试请求的确认。 `workflow` ID 在取消部署后报告 `"nodeployment"` 值。示例："workflow": {"action": 3,"ID": "11b6a7c3-6956-4b33-b5a9-87fdd79d2f01","retryTimestamp": "2022-01-26T11:33:29.9680598Z"}
installedUpdateId	string	设备到云	当前安装的 Device Update 部署的 ID。此值捕获更新 ID JSON，对于从未通过 Device Update 进行更新的设备，此值为 `null`。示例："installedUpdateID": "{\"provider\":\"contoso\",\"name\":\"image-update\",\"version\":\"1.0.0\"}"

IoT 中心设备孪生示例：

"deviceUpdate": {
                "__t": "c",
                "agent": {
                    "deviceProperties": {
                        "manufacturer": "contoso",
                        "model": "virtual-vacuum-v1",
                        "contractModelId": "dtmi:azure:iot:deviceUpdateContractModel;3",
                        "aduVer": "DU;agent/1.1.0",
                        },
                    "compatPropertyNames": "manufacturer,model",
                    "lastInstallResult": {
                        "resultCode": 700,
                        "extendedResultCode": 0,
                        "resultDetails": "",
                        "stepResults": {
                            "step_0": {
                                "resultCode": 700,
                                "extendedResultCode": 0,
                                "resultDetails": ""
                            }
                        }
                    },
                    "state": 0,
                    "workflow": {
                        "action": 3,
                        "id": "11b6a7c3-6956-4b33-b5a9-87fdd79d2f01",
                        "retryTimestamp": "2022-01-26T11:33:29.9680598Z"
                    },
                    "installedUpdateId": "{\"provider\":\"Contoso\",\"name\":\"Virtual-Vacuum\",\"version\":\"5.0\"}"
                },

注意

设备或模块必须添加 {"__t": "c"} 标记以指示元素引用组件。有关详细信息，请参阅 IoT 即插即用约定。

设备属性

deviceProperties 字段包含设备的制造商和型号信息。

名称	架构	方向	描述
制造商	string	设备到云	设备的制造商，通过 `deviceProperties` 报告。 `DeviceUpdateCore` 接口首先尝试从配置文件读取 `aduc_manufacturer` 值。如果未在配置文件中填充该值，则接口默认报告 `ADUC_DEVICEPROPERTIES_MANUFACTURER` 的编译时定义。仅在启动时报告此属性。默认值：“Contoso”
model	string	设备到云	设备的型号，通过 `deviceProperties` 报告。 `DeviceUpdateCore` 接口首先尝试从配置文件读取 `aduc_model` 值。如果未在配置文件中填充该值，则接口默认报告 `ADUC_DEVICEPROPERTIES_MODEL` 的编译时定义。仅在启动时报告此属性。默认值：“Video”
contractModelId	string	设备到云	服务用于标识 Device Update 代理用于管理代理和与代理进行通信的基本模型版本的属性。值：对于使用 Device Update 代理版本 1.1.0 的设备为 `dtmi:azure:iot:deviceUpdateContractModel;3`。注意：使用 `dtmi:azure:iot:deviceUpdateModel;2` 的代理必须将 `contractModelId` 报告为 `dtmi:azure:iot:deviceUpdateContractModel;3`，因为 `deviceUpdateModel;3` 是从 `deviceUpdateContractModel;3` 扩展的。
aduVer	string	设备到云	设备上运行的设备更新代理的版本。仅在编译时将 `ENABLE_ADU_TELEMETRY_REPORTING` 设置为 `1` (true) 时，才会从生成中读取此值。可以通过将值设置为 `0` (false) 来选择退出版本报告。有关详细信息，请参阅如何生成 Device Update 代理。
doVer	string	设备到云	设备上运行的传递优化代理的版本。仅在编译时将 `ENABLE_ADU_TELEMETRY_REPORTING` 设置为 `1` (true) 时，才会从生成中读取该值。可以通过将值设置为 `0` (false) 来选择退出版本报告。有关详细信息，请参阅如何自定义传递优化代理属性。
自定义兼容性属性	用户定义	设备到云	面向更新部署时用于兼容性检查的其他用户定义的设备属性。

State

state 字段是 Device Update 代理响应从 Device Update 服务发送到 Device Update 代理的操作而报告的状态。若要详细了解在 Device Update 服务和 Device Update 代理之间流动的请求，请参阅代理工作流。

名称	值	说明
闲置	0	设备已准备就绪，可以接收来自设备更新服务的操作。成功更新后，状态将返回到 `Idle` 状态。
DeploymentInprogress	6	正在进行部署。
已失败	255	更新时出错。
DownloadSucceeded	2	下载成功。只有代理版本为 0.7.0 或更早版本的设备才会报告此状态。
InstallSucceeded	4	安装成功。只有代理版本为 0.7.0 或更早版本的设备才会报告此状态。

操作

action 字段表示 Device Update 代理应按照 Device Update 服务指示执行的操作。 Device Update 代理会报告其收到的操作的处理状态。若要详细了解在 Device Update 服务和 Device Update 代理之间流动的请求，请参阅代理工作流。

名称	值	说明
applyDeployment	3	应用已部署的更新。
cancel	255	停止处理当前操作，并返回到 `Idle`，或告知状态为 `Failed` 的代理返回到 `Idle`。
下载	0	下载已发布的内容或更新以及任何其他所需内容。此操作仅发送到代理版本为 0.7.0 或更早版本的设备。
install	1	安装内容或更新，通常调用内容或更新的安装程序。 Device Update 仅向代理版本为 0.7.0 或更早版本的设备发送此操作。
apply	2	如有必要，请重新启动来完成更新。 Device Update 仅向代理版本为 0.7.0 或更早版本的设备发送此操作。

服务元数据

服务元数据包含 Device Update 服务用于将操作和数据传达给 Device Update 代理的字段。

名称	架构	方向	说明
action	integer	云到设备	此整数与代理应执行的操作相对应。有关详细信息，请参阅操作。
updateManifest	string	云到设备	描述更新的内容。根据导入清单生成。
updateManifestSignature	JSON 对象	云到设备	JSON Web 签名 (JWS)，具有用于源验证的 JSON Web 密钥。
fileUrls	映射	云到设备	`FileID` 到 `DownloadUrl` 的映射。告知代理要下载的文件以及用于验证文件是否正确下载的哈希。

设备信息接口

设备信息接口是 IoT 即插即用体系结构中使用的概念。该接口包含设备到云属性，其提供有关设备硬件和操作系统的信息。 Device Update 使用 DeviceInformation.manufacturer 和 DeviceInformation.model 属性进行遥测和诊断。有关设备信息接口的示例，请参阅 https://devicemodels.azure.com/dtmi/azure/devicemanagement/deviceinformation-1.json。

实现此接口时，模型中的预期组件名称为 deviceInformation。有关详细信息，请参阅 IoT 即插即用建模指南。

名称	类型	架构	方向	说明	示例
制造商	属性	string	设备到云	设备制造商的公司名称。制造商可以与原始设备制造商 (OEM) 的名称相同。	Contoso
模型	属性	string	设备到云	设备型号名称或 ID。	IoT Edge 设备
swVersion	属性	string	设备到云	设备上的软件版本。 swVersion 可能是固件版本。	4.15.0-122
osName	属性	string	设备到云	设备上的操作系统名称。	Ubuntu Server 18.04
processorArchitecture	属性	string	设备到云	设备上处理器的体系结构。	ARM64
processorManufacturer	属性	string	设备到云	设备上处理器制造商的名称。	Microsoft
totalStorage	属性	string	设备到云	设备上的可用存储总量（以千字节为单位）。	2048
totalMemory	属性	string	设备到云	设备上的可用内存总量（以千字节为单位）。	256

通过

Azure Device Update for IoT Hub 中的 IoT 即插即用

Device Update 模型

代理元数据

设备属性

State

操作

服务元数据

设备信息接口

反馈

其他资源

通过

Azure Device Update for IoT Hub 中的 IoT 即插即用

Device Update 模型

代理元数据

设备属性

State

操作

服务元数据

设备信息接口

相关内容

反馈

其他资源