导入更新到 IoT 中心设备更新功能

2022-06-27

若要将 IoT 中心的设备更新部署到设备，首先必须将该更新导入设备更新服务。本文概述了一些在导入更新时要了解的重要概念。

导入清单

导入清单是一个 JSON 文件，用于定义有关要导入的更新的重要信息。您提交导入清单和相关更新文件（如固件更新包）作为导入过程的一部分。导入清单中定义的元数据用于引入更新。某些元数据也在部署时使用 - 例如，验证是否已正确安装更新。

例如：

{
  "updateId": {
    "provider": "Contoso",
    "name": "Toaster",
    "version": "1.0"
  },
  "isDeployable": false,
  "compatibility": [
    {
      "deviceManufacturer": "Contoso",
      "deviceModel": "Toaster"
    }
  ],
  "instructions": {
    "steps": [
      {
        "handler": "microsoft/swupdate:1",
        "files": [
          "firmware.swu"
        ],
        "handlerProperties": {
          "installedCriteria": "1.0"
        }
      }
    ]
  },
  "files": [
    {
      "filename": "firmware.swu",
      "sizeInBytes": 7558,
      "hashes": {
        "sha256": "/CD7Sn6fiknWa3NgcFjGlJ+ccA81s1QAXX4oo5GHiFA="
      }
    }
  ],
  "createdDateTime": "2022-01-19T06:23:52.6996916Z",
  "manifestVersion": "4.0"
}

导入清单包含若干项与 IoT 中枢设备更新相关的重要概念。本节概述了这些项目。有关完整导入架构的信息，请参阅导入清单 JSON 架构。

更新标识

更新标识或 updateId 是 IoT 中心设备更新中更新的唯一标识符。它由三个部分组成：

提供者：正在创建或直接负责更新的实体。它通常是公司名称。
名称：更新类的标识符。它通常是设备类型或模型名称。
版本：将此更新与具有相同提供程序和名称的其他人区分开来的版本号。

例如：

{
  "updateId": {
    "provider": "Contoso",
    "name": "Toaster",
    "version": "1.0"
  }
}

注释

UpdateId 仅由设备更新服务使用，可能与设备上的实际软件组件的标识不同。

兼容性

兼容性 定义了可安装更新的设备的条件。它包含设备属性，这些属性是一组从设备报告的任意键值对。只有具有匹配属性的设备才有资格进行部署。更新可以通过具有多个设备属性集来与多个设备类兼容。

下面是一个更新示例，该更新只能部署到将 Contoso 和 烤面包机 报告为其设备制造商和型号的设备。

{
  "compatibility": [
    {
      "deviceManufacturer": "Contoso",
      "deviceModel": "Toaster"
    }
  ]
}

说明书

“说明”部分包含设备代理安装更新所需的信息或步骤。最简单的更新包含单个内联步骤。此步骤通过设备代理注册的 处理程序 执行所包含的有效负载文件。

{
  "instructions": {
    "steps": [
      {
        "handler": "microsoft/swupdate:1",
        "files": [
          "contoso.toaster.1.0.swu"
        ]
      }
    ]
  }
}

小提示

handler 等效于 updateType 导入清单版本 3.0 或更旧版本。

更新可能包含多个步骤：

{
  "instructions": {
    "steps": [
      {
        "description": "pre-install script",
        "handler": "microsoft/script:1",
        "handlerProperties": {
          "arguments": "--pre-install"
        },
        "files": [
          "configure.sh"
        ]
      },
      {
        "description": "firmware package",
        "handler": "microsoft/swupdate:1",
        "files": [
          "contoso.toaster.1.0.swu"
        ]
      }
    ]
  }
}

更新可能包含参考步骤，指示设备代理使用自己的导入清单安装另一个更新，从而建立父更新和子更新关系。例如，烤面包机的一个软件更新可能包含两个子更新。

{
  "instructions": {
    "steps": [
      {
        "type": "reference",
        "updateId": {
          "provider": "Contoso",
          "name": "Toaster.HeatingElement",
          "version": "1.0"
        }
      },
      {
        "type": "reference",
        "updateId": {
          "provider": "Contoso",
          "name": "Toaster.Sensors",
          "version": "1.0"
        }
      }
    ]
  }
}

注释

更新可能包含内联和引用步骤的任意组合。

文件

“文件”部分包含更新有效负载文件的元数据，例如其名称、大小和哈希。 IoT 中心的设备更新在导入过程中使用此元数据进行完整性验证。然后将相同的信息转发到设备代理，以在安装之前重复完整性验证。

注释

仅包含引用步骤的更新在父更新中没有任何更新有效负载文件。

创建导入清单

可以使用任何文本编辑器创建导入清单 JSON 文件。还有一些示例脚本用于以编程方式在 GitHub 上的 Azure/iot-hub-device-update 中创建导入清单。

重要

通过 Azure 门户导入时，导入清单 JSON 文件名必须以结尾 .importmanifest.json 。

小提示

使用 Visual Studio Code 在创建导入清单时启用自动完成和 JSON 架构验证。

导入更新的限制

对于每个 Device Update for IoT Hub 实例，强制实施特定限制。如果尚未查看，请参阅 Device Update 限制。

后续步骤

若要了解有关导入过程的详细信息，请参阅准备要导入的更新。
查看导入清单架构。

通过