通过

使用 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 方案和功能的概述，请参阅：

有关特定实际示例，请参阅：