使用英语阅读

通过


使用 Azure IoT 和 OSConfig 进行自定义配置和报告

重要

版本 1.0.3 (2022 年 6 月 28 日发布) 包括对可能影响现有用户的成员名称的重大更改。 有关详细信息,请参阅: 成员名称从 PascalCase 转换为 1.0.3 版中的 camelCase

本文旨在支持使用 Azure IoT 预配或管理设备 的人员。 如果这听起来不像你,请考虑查看 OSConfig 的受众文档

CommandRunner -->RunCommand 功能允许你权衡一些简单性,以获得灵活性。 如果需要,可以下拉抽象级别来执行自定义报告和配置。

自定义报告和配置的常见示例

  • 验证设备与密钥终结点的连接
  • 验证特定守护程序是否正在运行
  • 调试或排查设备问题,例如收集日志文件并将其上传到云存储
  • 将所有设备配置为在记录数据、生成时间戳等时使用所需的时区。
  • 报告 (或配置自己的唯一设备组件) ,否则 OSConfig 永远不会知道
  • 可能性是无休止的,几乎任何可以在 shell 中为一台设备执行的任务- 可以使用 Azure IoT 和 OSConfig CommandRunner 为设备群执行

提示

本文重点介绍具有最少解释的实际示例。 有关 CommandRunner 的技术背景,请参阅: 如何与 OSConfig 和 Azure IoT 的 CommandRunner 功能进行交互

用例示例

这些示例可用作适应独特环境的起点。

每个示例包括用于在 Azure 门户 中工作的步骤和屏幕截图,以及使用 Azure CLI 在 bash 中工作的步骤和屏幕截图。

每个示例还包括一个设备 (的变体,例如故障排除方案) ,或许多设备 (,例如配置预配或报告方案) 。

预期内容

在单个设备说明中,你将直接在设备的 OSConfig 孪生中读取和写入报告和所需属性。 在大规模指令中,你将使用IoT 中心配置 (也称为“自动设备管理”或“ADM”) 将所需属性推送到多个孪生体,并使用IoT 中心 (查询单独使用,或作为指标附加到“配置”) 来观察从设备返回的结果。

以下示例的先决条件

例如,如果使用本文进行参考 (,则在此处复制属性名称) ,则无需先决条件。

如果要尝试实时系统上的示例 (建议) ,则:

  1. 需要使用具有IoT 中心的 Azure 帐户

    本文假设你熟悉IoT 中心和相关工具。 例如,它假设你愿意创建 IoT 中心和附加设备。 如果更倾向于从头开始安装和使用 OSConfig 的更规范性的分步介绍,请参阅: 快速入门:改用 Azure CLI 管理单个虚拟 IoT 设备

  2. 至少需要安装并连接到 Azure IoT 的 OSConfig 代理的 Linux 设备。

    有关详细信息,请参阅: 如何以及如何安装适用于 Linux 的 OSConfig 代理

  3. 你将使用 Azure 门户或 Azure CLI 通过IoT 中心与设备交互

    有关进一步步骤,请选择首选体验:

  1. 确保已登录到 Azure 门户,可以访问IoT 中心的“概述”页屏幕截图,其中显示了 Azure 门户中的IoT 中心和设备

提示

应了解 CommandRunner 行为的两个事项才能使用以下示例成功:

  • 如示例中所示,每个新请求必须包含 (的新值 commandId 可以是任何字符串,例如“MyCmd01”、“MyCmd02”) 。
  • 该过程是异步的,因此结果无法即时提供。 最简单的过程是在启动 CommandRunner 请求后等待大约一分钟。 在该分钟后,无需执行任何额外的步骤,结果将可用 properties.reported.CommandRunner.commandStatus。 有关刷新行为、异步状态更新等的详细信息,请参阅: 如何与 OSConfig 和 Azure IoT 的 CommandRunner 功能进行交互

示例 1。 检查设备与特定终结点的连接

在此示例中,我们要求设备 () ping www.github.com 3 次。 我们观察 ping 的退出代码 (成功或失败) ,我们可以观察 ping 命令的文本输出。

  1. 在IoT 中心的门户页中,导航到要管理的设备的 OSConfig 模块孪生。 然后将以下内容添加到 properties.desired 节 (后跟一个逗号,以将其与) 中的 properties.desired 下一项分开。

      "CommandRunner": {
                 "__t": "c",
                 "commandArguments": {
                     "commandId": "pingcmd",
                     "arguments": "ping -c 3 www.github.com",
                     "timeout": 120,
                     "singleLineTextResult": false,
                     "action": 3
                 }
             }
    

    屏幕截图显示了使用 Azure 门户单个设备的 OSConfig 模块执行 ping 命令所需的孪生内容

  2. 可以通过检查 OSConfig 模块孪生本身对 ping 命令的响应来验证设备连接。 向下滚动模块孪生,查找 CommandRunner的报告属性。 检查 resultCode:0,指示命令已成功,并显示 ping 命令输出的 textResult

    显示 Azure 门户中单个设备的 OSConfig 模块为 ping 命令报告的孪生内容的屏幕截图

示例 2。 获取 /etc/ssh/sshd_config 的内容

在此示例中,我们使用 CommandRunner 从每个设备捕获文件的内容。 在此示例中,我们不会将文件显式上传到任何云存储服务,而只是捕获其内容在孪生体中。

重要

孪生属性更新限制为 4KB。 此处所示的方法捕获从 cat) 内联到孪生体的文件内容 (。 对于非常小的文件,此方法的优点是不需要任何外部存储服务或凭据。 对于较大的文件,此方法不适用。 而是在脚本/命令中包含逻辑,以便将文件上传到所选的本地或云存储。 例如,可以连接到 cifs 共享并在那里复制文件,或将文件内容推送到 Azure 存储。

  1. 在IoT 中心的门户页中,导航到要管理的设备的 OSConfig 孪生。 然后将以下内容添加到 properties.desired 节 (后跟逗号,将其与) 中的 properties.desired 下一项分开。 可以在下面的 参数 字段中替换所选的文件名。

      "CommandRunner": {
                 "__t": "c",
                 "commandArguments": {
                     "commandId": "sshdconfig",
                     "arguments": "cat /etc/ssh/sshd_config",
                     "timeout": 30,
                     "singleLineTextResult": false,
                     "action": 3
                 }
             }
    

    显示如何设置 OSConfig 模块孪生的所需属性以使用 Azure 门户的 OSConfig 模块从单个设备读取文件内容的屏幕截图

  2. 可以从模块孪生本身查看文件内容。 向下滚动模块孪生,在 CommandRunner的报告属性下查找 commandStatus,此处将在 textResult 中看到这一点。 检查 resultCode:0 ,指示命令已成功, textResult 将显示所需的文件内容。

    "CommandRunner": {
                 "__t": "c",
                 "commandStatus": {
                     "commandId": "sshdconfig",
                     "resultCode": 0,
                     "textResult": "<sshd_config_file_contents>",
                     "currentState": 2
                 }
              }   
    

    显示 OSConfig 模块孪生的屏幕截图,其中显示了来自 Azure 门户的单个设备请求的文件内容

示例 3。 部署简单的内联脚本,将时区设置为 UTC 并报告时区

此示例演示了一个简单的用例,其中脚本和结果都可以作为孪生体的一部分内联处理。 以下示例将时区设置为 UTC,然后在设置时区后查询时区。

  1. 在IoT 中心的门户页中,导航到要管理的设备的 OSConfig 孪生体,并将以下内容properties.desired添加到该部分,然后用逗号将其与下properties.desired一项分开。 下面的 action=3 指定 RunCommand 操作。

    "CommandRunner": {
       "__t": "c",
       "commandArguments": {
          "commandId": "settimezonecmd",
          "arguments": "timedatectl set-timezone Etc/UTC | timedatectl | grep Time",
          "timeout": 30,
          "singleLineTextResult": false,
          "action": 3
       }
    }
    

    显示如何使用 Azure 门户的 OSConfig 模块在设备上设置所需属性以更新时区的屏幕截图

  2. 执行该命令后,向下滚动模块孪生以在 CommandRunner的报告属性下查找 commandStatus,此处将看到 textResult 显示设备上设置的当前时区。

    "CommandRunner": {
       "__t": "c",
       "commandStatus": {
          "commandId": "settimezonecmd",
          "resultCode": 0,
          "textResult": " Time zone: Etc/UTC (UTC, +0000)",
          "currentState": 2
       }
    }   
    

    显示从 Azure 门户在单个设备上设置时区命令的响应的屏幕截图

示例 4. 从联机存储库部署自定义报告脚本

此示例演示如何调用位于孪生体外部的脚本。 例如,可以将脚本放在 GitHub 中。 (脚本对于孪生体) 或首选项来说,这种模式可能出于必要而产生。 孪生体中的命令是一个简单的包装器。 它下载主脚本并运行它。

重要

为了支持本文档,我们发布了一个 示例脚本。 此示例脚本作为 GitHub 或其他位置你自己的脚本的备用脚本提供。 它从设备收集几个数据点,包括时间戳、守护程序状态和可用磁盘空间。 在设备上运行脚本之前,应先检查 Internet 中的脚本,包括此脚本。

  1. 在IoT 中心的门户页中,导航到要管理的设备的 OSConfig 孪生体,然后将以下内容properties.desired添加到该部分,然后用逗号将其与下一项properties.desired分开。

    "CommandRunner": {
        "__t": "c",
       "commandArguments": {
          "commandId": "runcustomscript",
          "arguments": "curl -s -L https://learn.microsoft.com/azure/osconfig/samples/report-multiple-datapoints-from-device.sh | tr -d \r| bash",
          "timeout": 60,
          "singleLineTextResult": false,
          "action": 3
       }
    }
    

    显示如何使用 Azure 门户更新孪生内容以在单个设备上运行自定义脚本的屏幕截图

  2. 向下滚动模块孪生,在孪生体的报告属性部分中查找 CommandRunner -->commandStatus。 检查 resultCode:0, 指示命令已成功,并显示执行脚本的输出 的 textResult 。 下面是从设备的 OSConfig 孪生获取的示例输出:

    "CommandRunner": {
       "__t": "c",
       "commandStatus": {
          "commandId": "runcustomscript",
          "resultCode": 0,
          "textResult": "+TIMESTAMP: 'Fri Jul  8 19:01:15 UTC 2022'  +DAEMON_STATUS: 'Active: active (running) since Mon 2022-06-27 19:02:46 UTC; 1 weeks 3 days ago'  +FREE_SPACE: '/dev/sda1       30309264 8811724  21481156  30% /'"
          "currentState": 2
       },
    }   
    

    显示如何使用 Azure 门户在单个设备上运行自定义脚本后检查孪生内容的屏幕截图

后续步骤

有关 OSConfig 方案和功能的概述,请参阅:

有关特定实际示例,请参阅: