自动 IoT 设备和模块管理

先决条件

• 有效的 Azure 订阅。 如果没有 Azure 订阅，可在开始前创建一个试用帐户。

• Azure 订阅中的 IoT 中心。 如果还没有中心，则可以按照创建 IoT 中心中的步骤进行操作。

实现孪生体

自动设备配置需要通过使用“设备孪生”来在云与设备之间同步状态。 有关详细信息，请参阅了解并在 IoT 中心内使用设备孪生。

自动模块配置需要使用模块孪生在云和模块之间同步状态。 有关详细信息，请参阅 了解和使用 IoT 中心中的模块孪生。

使用标记定位孪生体

在创建配置之前，必须指定要影响的设备或模块。 Azure IoT 中心通过设备孪生中的标记来标识设备，并通过模块孪生中的标记来标识模块。 每个设备或模块可以具有多个标记，并且你可以通过任何对解决方案有意义的方式定义它们。 例如，如果管理不同位置的设备，请将以下标记添加到设备孪生体：

"tags": {
    "location": {
        "state": "Washington",
        "city": "Tacoma"
    }
},

创建配置

在标准层 IoT 中心上，最多可以创建 100 个自动配置；在免费层 IoT 中心上，可以创建 10 个。 若要了解详细信息，请参阅 配额和节流。

1. 在 Azure 门户中，转到 IoT 中心。

2. 在左侧导航窗格中选择 “配置 + 部署 ”。

3. 从下拉列表中选择“添加”并选择“设备孪生配置”或“模块孪生配置”。

   

创建配置有五个步骤。 以下各节将依次讲解每一部分。

名称和标签

1. 输入配置的唯一名称。 该名称最多可包含 128 个字符，并且可能包含小写字母和以下特殊字符： -+%_*!' 不允许包含空格。
2. 添加标签以组织和描述配置。 标签是键值对，例如 HostPlatform, Linux 或 Version, 3.0.1。
3. 选择“下一步”继续操作。

双重设置

通过为每个设置提供两个输入来设置目标设备孪生或模块孪生所需属性中的内容。 首先，指定孪生路径，该路径指向要更新的孪生体所需属性中的 JSON 节。 接下来，输入要在该位置插入的 JSON 内容。

例如，可以将该孪生路径设置为 properties.desired.chiller-water，然后提供以下 JSON 内容：

{
  "temperature": 66,
  "pressure": 28
}

还可以通过指定整个孪生路径并提供没有方括号的值来设置单个设置。 例如，使用双路径properties.desired.chiller-water.temperature，将内容设置为66。 然后为压力属性创建新的孪生体设置。

如果两个或多个配置面向同一孪生路径，则最高优先级配置中的内容适用（优先级是在步骤 4 中定义的）。

如果要删除现有属性，请将属性值指定为 null.

可以通过选择“ 添加设备孪生设置 ”或 “添加模块孪生设置”来添加其他设置。

目标设备或模块

使用数字孪生中的 tags 属性来定位应该接收此配置的特定设备或模块。 还可以以孪生报告属性为目标。

自动设备配置只能面向设备孪生标记，而自动模块配置只能面向模块孪生标记。

由于多个配置可能面向同一设备或模块，每个配置都需要一个优先级编号。 如果存在冲突，则优先级最高的配置将获胜。

1. 输入配置 优先级的正整数。 最高数值被视为最高优先级。 如果两个配置具有相同的优先级编号，则最近创建的配置将获胜。

2. 输入 目标条件 以确定哪些设备或模块以此配置为目标。 条件基于孪生标记或孪生报告属性，应与表达式格式匹配。

   • 对于自动设备配置，只需指定目标标记或报告属性。 例如，tags.environment='test' 或 properties.reported.chillerProperties.model='4000x'。 可以指定 * 以所有设备为目标。

   • 对于自动模块配置，请使用查询指定注册到 IoT 中心的模块中的标记或报告属性。 例如，from devices.modules where tags.environment='test' 或 from devices.modules where properties.reported.chillerProperties.model='4000x'。 通配符不能用于面向所有模块。

Metrics

指标提供设备或模块在应用配置内容后可以报告的各种状态的摘要计数。 例如，您可以为挂起的设置更改、产生错误和成功的设置更改创建各自的指标。

每个配置最多可以有五个自定义指标。

1. 输入 指标名称的名称。

2. 输入 指标条件的查询。 查询基于设备孪生的报告属性。 该指标表示查询返回的行数。

   例如：

   SELECT deviceId FROM devices 
     WHERE properties.reported.chillerWaterSettings.status='pending'
   

   您可以添加一个说明配置已应用的条款，例如：

   /* Include the double brackets. */
   SELECT deviceId FROM devices 
     WHERE configurations.[[yourconfigname]].status='Applied'
   

   如果要生成指标来报告配置模块，请选择moduleId从devices.modules中。 例如：

   SELECT deviceId, moduleId FROM devices.modules
     WHERE properties.reported.lastDesiredStatus.code = 200
   

查看配置

查看配置信息，然后选择“ 提交”。

监视某个配置

若要查看配置的详细信息并监视运行它的设备，请使用以下步骤：

1. 在 Azure 门户中，转到 IoT 中心。

2. 在设备管理中选择 “配置 ”。

3. 检查配置列表。 对于每个配置，可以查看以下详细信息：

   • ID - 配置的名称。

   • 目标条件 - 用于定义目标设备或模块的查询。

   • 优先级 - 分配给配置的优先级编号。

   • 创建时间 - 创建配置的时间戳。 当两个配置具有相同优先级时，此时间戳用于中断关系。

   • 系统指标 - 由 IoT 中心计算的指标，开发人员无法自定义。 Targeted 指定与目标条件匹配的设备孪生数。 应用指定已由配置修改的设备孪生数，这可能包括部分修改，如果单独的更高优先级配置也进行了更改。

   • 自定义指标 - 由开发人员指定的用于查询孪生报告属性的指标。 每个配置最多可以定义五个自定义指标。

4. 选择要监视的配置。

5. 检查配置详细信息。 可以使用选项卡查看有关接收配置的设备的特定详细信息。

   • 目标设备 或 目标模块 - 与目标条件匹配的设备或模块。

   • 指标 - 系统指标和自定义指标的列表。 可以通过在下拉列表中选择指标，然后选择 “查看设备 ”或 “查看模块”来查看针对每个指标计算的设备或模块的列表。

   • 标签 - 用于描述配置的键值对。 标签对功能没有影响。

   • 设备孪生设置 或 模块孪生设置 - 由配置设置的孪生设置（如果有）。

修改配置

修改配置时，更改会立即复制到所有目标设备或模块。

如果更新目标条件，将发生以下更新：

• 如果孪生体不符合旧的目标条件，但满足新的目标条件，并且此配置是该孪生体的最高优先级，则应用此配置。

• 如果当前运行此配置的孪生不再满足目标条件，则会删除配置中的设置，并将由下一个最高优先级配置修改孪生体。

• 如果当前运行此配置的孪生不再满足目标条件，并且不满足任何其他配置的目标条件，则会删除配置中的设置，并且不会对孪生体进行任何其他更改。

若要修改配置，请使用以下步骤：

1. 在 Azure 门户中，转到 IoT 中心。
2. 在设备管理中选择 “配置 + 部署 ”。
3. 选择要修改的配置。
4. 可以更新以下字段：优先级、指标、目标条件和标签。
5. 选择“保存”。
6. 按照 监视配置 中的步骤查看更改的推出情况。

删除配置

删除配置时，任何设备孪生都采用其下一个最高优先级配置。 如果设备孪生不符合任何其他配置的目标条件，则不会应用其他设置。

1. 在 Azure 门户中，转到 IoT 中心。
2. 在设备管理中选择 “配置 + 部署 ”。
3. 使用复选框选择要删除的配置。
4. 选择 删除。
5. 提示将要求你确认。

先决条件

• 有效的 Azure 订阅。 如果没有 Azure 订阅，可在开始前创建一个试用帐户。

• Azure 订阅中的 IoT 中心。 如果还没有中心，则可以按照创建 IoT 中心中的步骤进行操作。

• 你的环境中的 Azure CLI。 Azure CLI 版本必须至少为 2.0.70 或更高版本。 请使用 az –-version 验证版本。 此版本支持 az extension 命令并引入 Knack 命令框架。

• 适用于 Azure CLI 的 IoT 扩展。

实现孪生体

自动设备配置需要通过使用“设备孪生”来在云与设备之间同步状态。 有关详细信息，请参阅了解并在 IoT 中心内使用设备孪生。

自动模块配置需要使用模块孪生在云和模块之间同步状态。 有关详细信息，请参阅 了解和使用 IoT 中心中的模块孪生。

使用标记定位孪生体

在创建配置之前，必须指定要影响的设备或模块。 Azure IoT 中心通过在设备孪生中使用标记来标识设备，并通过在模块孪生中使用标记来标识模块。 每个设备或模块可以具有多个标记，你可以通过任何对解决方案有意义的方式定义它们。 例如，如果管理不同位置的设备，请将以下标记添加到设备孪生体：

"tags": {
	"location": {
		"state": "Washington",
		"city": "Tacoma"
    }
},

定义目标内容和指标

目标内容和指标查询被指定为 JSON 文档，描述了设备孪生或模块孪生的期望属性以进行设置，以及报告属性以进行度量。 若要使用 Azure CLI 创建自动配置，请将目标内容和指标保存为 .txt 文件。 在运行命令将配置应用到设备时，您将在后面的部分使用文件路径。

下面是自动设备配置的基本目标内容示例：

{
  "content": {
    "deviceContent": {
      "properties.desired.chillerWaterSettings": {
        "temperature": 38,
        "pressure": 78
      }
    }
  }
}

自动模块配置的行为类似，但目标是 moduleContent 而不是 deviceContent。

{
  "content": {
    "moduleContent": {
      "properties.desired.chillerWaterSettings": {
        "temperature": 38,
        "pressure": 78
      }
    }
  }
}

下面是指标查询的示例：

{
  "queries": {
    "Compliant": "select deviceId from devices where configurations.[[chillerdevicesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='current'",
    "Error": "select deviceId from devices where configurations.[[chillerdevicesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='error'",
    "Pending": "select deviceId from devices where configurations.[[chillerdevicesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='pending'"
  }
}

模块的指标查询也类似于设备的查询，但从 moduleId 中选择 devices.modules。 例如：

{
  "queries": {
    "Compliant": "select deviceId, moduleId from devices.module where configurations.[[chillermodulesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='current'"
  }
}

创建配置

在标准层 IoT 中心上，最多可以创建 100 个自动配置；在免费层 IoT 中心上，可以创建 10 个。 若要了解详细信息，请参阅 配额和节流。

通过创建由目标内容和指标组成的配置来配置目标设备。 使用以下命令创建配置：

   az iot hub configuration create --config-id [configuration id] \
     --labels [labels] --content [file path] --hub-name [hub name] \
     --target-condition [target query] --priority [int] \
     --metrics [metric queries]

• -- config-id - 在 IoT 中心中创建的配置的名称。 为配置提供长达 128 个字符的唯一名称。 允许小写字母和以下特殊字符： -+%_*!' 不允许包含空格。

• -- 标签 - 添加标签以帮助跟踪配置。 标签是描述部署的名称、值对。 例如，HostPlatform, Linux 或 Version, 3.0.1

• -- content - 要设置为孪生所需属性的目标内容的内联 JSON 或文件路径。

• -- hub-name - 在其中创建配置的 IoT 中心的名称。 集线器必须位于当前订阅中。 使用命令 az account set -s [subscription name] 切换到所需的订阅

• -- target-condition - 输入目标条件以确定将针对此配置的设备或模块。 对于自动设备配置，条件基于设备孪生标记或设备孪生所需的属性，应与表达式格式匹配。 例如，tags.environment='test' 或 properties.desired.devicemodel='4000x'。 对于自动模块配置，条件基于模块数字孪生标记或模块数字孪生期望属性。 例如，from devices.modules where tags.environment='test' 或 from devices.modules where properties.reported.chillerProperties.model='4000x'。

• -- priority - 正整数。 如果两个或多个配置针对同一设备或模块，则应用优先级值最高的配置。

• -- metrics - 指标查询的文件路径。 指标提供设备或模块在应用配置内容后可以报告的各种状态的摘要计数。 例如，您可以为挂起的设置更改、产生错误和成功的设置更改创建各自的指标。

监视某个配置

使用以下命令显示配置的内容：

az iot hub configuration show --config-id [configuration id] \
  --hub-name [hub name]

• -- config-id - IoT 中心中存在的配置的名称。

• -- hub-name - 配置所在的 IoT 中心的名称。 集线器必须位于当前订阅中。 使用命令 az account set -s [subscription name]切换到所需的订阅。

检查命令窗口中的配置。  指标属性列出了每个中心评估的每个指标的计数：

• targetedCount - 一个系统指标，指定与目标条件匹配的 IoT 中心的设备孪生或模块孪生的数量。

• appliedCount - 系统指标指定已应用目标内容的设备或模块数。

• 自定义指标 - 你定义的任何指标都是用户指标。

可以使用以下命令显示每个指标的设备 ID、模块 ID 或对象列表：

az iot hub configuration show-metric --config-id [configuration id] \
   --metric-id [metric id] --hub-name [hub name] --metric-type [type] 

• -- config-id - IoT 中心中存在的部署的名称。

• -- metric-id - 例如appliedCount，这是用于查看设备 ID 或模块 ID 列表的指标名称。

• -- hub-name - 部署所在的 IoT 中心的名称。 集线器必须位于当前订阅中。 使用命令 az account set -s [subscription name]切换到所需的订阅。

• -- metric-type - 可以是 system 或 user 的指标类型。 系统指标是 targetedCount 和 appliedCount。 所有其他指标都是用户指标。

修改配置

修改配置时，更改会立即复制到所有目标设备。

如果更新目标条件，将发生以下更新：

• 如果孪生体不符合旧的目标条件，但满足新的目标条件，并且此配置是该孪生体的最高优先级，则应用此配置。

• 如果当前运行此配置的孪生不再满足目标条件，则会删除配置中的设置，并将由下一个最高优先级配置修改孪生体。

• 如果当前运行此配置的孪生不再满足目标条件，并且不满足任何其他配置的目标条件，则会删除配置中的设置，并且不会对孪生体进行任何其他更改。

使用以下命令更新配置：

az iot hub configuration update --config-id [configuration id] \
   --hub-name [hub name] --set [property1.property2='value']

• -- config-id - IoT 中心中存在的配置的名称。

• -- hub-name - 配置所在的 IoT 中心的名称。 集线器必须位于当前订阅中。 使用命令 az account set -s [subscription name]切换到所需的订阅。

• -- set - 更新配置中的属性。 可以更新以下属性：

  • targetCondition - 例如 targetCondition=tags.location.state='Oregon'

  • labels

  • priority

删除配置

删除配置时，任何设备孪生或模块孪生都采用其下一个最高优先级配置。 如果孪生体不符合任何其他配置的目标条件，则不会应用其他设置。

使用以下命令删除配置：

az iot hub configuration delete --config-id [configuration id] \
   --hub-name [hub name] 

• -- config-id - IoT 中心中存在的配置的名称。

• -- hub-name - 配置所在的 IoT 中心的名称。 集线器必须位于当前订阅中。 使用命令 az account set -s [subscription name]切换到所需的订阅。