你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
借助 Azure Device Update for IoT Hub 中的多步骤有序执行,可以在部署无线更新时运行安装前和安装后任务。 此功能是 Device Update 更新清单架构版本 4 的一部分。 有关详细信息,请参阅 Device Update 更新清单。
多步骤有序执行可以有两种类型的步骤:内联步骤和引用步骤。 内联步骤是代码执行说明,是默认类型。 引用步骤是包含另一个更新的标识符的步骤。
父更新和子更新
当更新清单相互引用时,顶级清单称为父更新,引用步骤中指定的清单称为子更新。 子更新不能包含任何引用步骤,只能包含内联步骤。 Device Update 在导入时验证此限制,如果未满足,则更新失败。
父更新中的内联步骤
Device Update 代理将父更新中指定的内联步骤应用于主机设备。 传递给步骤处理程序(也称为更新内容处理程序)的 ADUC_WorkflowData
对象不包含任何 Selected Components
数据。 这种类型的步骤的处理程序不得是 Component-Aware
处理程序。
Device Update 代理的步骤内容处理程序为每个步骤应用 IsInstalled
验证逻辑。 步骤处理程序通过检查 IsInstalled()
是否返回结果代码 900
或 true 来检查是否已安装更新,并使用此结果确定是否执行该步骤。 为了避免重新安装设备上已有的更新,如果已安装更新,Device Update 代理将跳过后续步骤。
若要报告更新结果,请将步骤处理程序执行的结果写入所需结果文件中的 ADUC_Result
结构中,如 --result-file
选项中指定的那样。 根据执行结果,返回 0
表示成功,返回 -1
或 0xFF
表示严重错误。
有关详细信息,请参阅步骤处理程序和如何实现自定义组件感知内容处理程序。
父更新中的引用步骤
Device Update 代理将父更新中指定的引用步骤应用于主机设备上的组件或连接到主机设备的组件。 处理引用步骤时,步骤处理程序会下载步骤中指定的分离更新清单文件,并验证文件完整性。
然后,步骤处理程序分析子更新清单并创建 ADUC_Workflow
对象(也称为子工作流数据),方法是将子更新清单中的数据和父更新清单中的文件 URL 信息合并起来。 此子工作流数据还具有设置为 1
的 level
属性。
示例
以下示例更新清单具有一个内联步骤:
{
"updateId": {...},
"isDeployable": true,
"compatibility": [
{
"manufacturer": "du-device",
"model": "e2e-test"
}
],
"instructions": {
"steps": [
{
"description": "Example APT update that installs libcurl4-doc on a host device.",
"handler": "microsoft/apt:1",
"files": [
"apt-manifest-1.0.json"
],
"handlerProperties": {
"installedCriteria": "apt-update-test-1.0"
}
}
]
},
"manifestVersion": "4.0",
"importedDateTime": "2021-11-16T14:54:55.8858676Z",
"createdDateTime": "2021-11-16T14:50:47.3511877Z"
}
以下示例更新清单具有两个内联步骤:
{
"updateId": {...},
"isDeployable": true,
"compatibility": [
{
"manufacturer": "du-device",
"model": "e2e-test"
}
],
"instructions": {
"steps": [
{
"description": "Install libcurl4-doc on host device",
"handler": "microsoft/apt:1",
"files": [
"apt-manifest-1.0.json"
],
"handlerProperties": {
"installedCriteria": "apt-update-test-2.2"
}
},
{
"description": "Install tree on host device",
"handler": "microsoft/apt:1",
"files": [
"apt-manifest-tree-1.0.json"
],
"handlerProperties": {
"installedCriteria": "apt-update-test-tree-2.2"
}
}
]
},
"manifestVersion": "4.0",
"importedDateTime": "2021-11-16T20:21:33.6514738Z",
"createdDateTime": "2021-11-16T20:19:29.4019035Z"
}
以下父更新清单有一个引用步骤,该步骤引用子更新:
{
"updateId": {...},
"isDeployable": true,
"compatibility": [
{
"manufacturer": "du-device",
"model": "e2e-test"
}
],
"instructions": {
"steps": [
{
"type": "reference",
"description": "Cameras Firmware Update",
"updateId": {
"provider": "contoso",
"name": "virtual-camera",
"version": "1.2"
}
}
]
},
"manifestVersion": "4.0",
"importedDateTime": "2021-11-17T07:26:14.7484389Z",
"createdDateTime": "2021-11-17T07:22:10.6014567Z"
}
子更新包含内联步骤。
{
"updateId": {
"provider": "contoso",
"name": "virtual-camera",
"version": "1.2"
},
"isDeployable": false,
"compatibility": [
{
"group": "cameras"
}
],
"instructions": {
"steps": [
{
"description": "Cameras Update - preinstall step",
"handler": "microsoft/script:1",
"files": [
"contoso-camera-installscript.sh"
],
"handlerProperties": {
"scriptFileName": "contoso-camera-installscript.sh",
"arguments": "--pre-install-sim-success --component-name --component-name-val --component-group --component-group-val --component-prop path --component-prop-val path",
"installedCriteria": "contoso-virtual-camera-1.2-step-0"
}
},
{
"description": "Cameras Update - firmware installation (failure - missing file)",
"handler": "microsoft/script:1",
"files": [
"contoso-camera-installscript.sh",
"camera-firmware-1.1.json"
],
"handlerProperties": {
"scriptFileName": "missing-contoso-camera-installscript.sh",
"arguments": "--firmware-file camera-firmware-1.1.json --component-name --component-name-val --component-group --component-group-val --component-prop path --component-prop-val path",
"installedCriteria": "contoso-virtual-camera-1.2-step-1"
}
},
{
"description": "Cameras Update - postinstall step",
"handler": "microsoft/script:1",
"files": [
"contoso-camera-installscript.sh"
],
"handlerProperties": {
"scriptFileName": "contoso-camera-installscript.sh",
"arguments": "--post-install-sim-success --component-name --component-name-val --component-group --component-group-val --component-prop path --component-prop-val path",
"installedCriteria": "contoso-virtual-camera-1.2-step-2"
}
}
]
},
"referencedBy": [
{
"provider": "DU-Client-Eng",
"name": "MSOE-Update-Demo",
"version": "3.1"
}
],
"manifestVersion": "4.0",
"importedDateTime": "2021-11-17T07:26:14.7376536Z",
"createdDateTime": "2021-11-17T07:22:09.2232968Z",
"etag": "\"ad7a553d-24a8-492b-9885-9af424d44d58\""
}
注意
如果使用 installedCriteria
来确定是否应执行步骤,则应在更新清单中为每个步骤提供不同的 installedCriteria
值。
分离的更新清单
为了避免由于 Azure IoT 中心孪生数据大小限制而导致部署失败,Device Update 会将大型更新清单作为 JSON 数据文件传递给设备,称为“分离的更新清单”。 当将大型内容更新导入到 Device Update 中时,生成的更新清单包含另一个名为 Detached Update Manifest
的有效负载文件,该文件包含完整更新清单数据。
设备或模块孪生中的 UpdateManifest
属性包含分离的更新清单文件信息。 处理 PnP PropertyChanged
事件时,Device Update 代理会自动下载分离的更新清单文件,并创建包含完整更新清单数据的 ADUC_WorkflowData
对象。