设备孪生入门 (.NET/.NET)

设备孪生是存储设备状态信息(元数据、配置和条件)的 JSON 文档。 IoT 中心为连接到它的每台设备保留一个设备孪生。

Note

本文中所述的功能仅可在 IoT 中心的标准层中使用。 有关基本和标准 IoT 中心层的详细信息,请参阅如何选择合适的 IoT 中心层

使用设备孪生可以:

  • 存储来自解决方案后端的设备元数据。
  • 通过设备应用报告当前状态信息,例如可用功能和条件(例如,使用的连接方法)。
  • 同步设备应用和后端应用之间的长时间运行的工作流的状态(例如固件和配置更新)。
  • 查询设备的元数据、配置或状态。

设备孪生旨在执行同步以及查询设备的配置和条件。 了解设备孪生中提供了有关何时使用设备孪生的详细信息。

设备孪生存储在 IoT 中心内,其中包含:

  • 标记,仅可由解决方案后端访问的设备元数据;
  • 所需属性,可以由解决方案后端修改以及由设备应用观察的 JSON 对象;以及
  • 报告属性,可由设备应用修改以及由解决方案后端读取的 JSON 对象。 标记和属性不能包含数组,但可以嵌套对象。

此外,解决方案后端可以根据上述所有数据查询设备孪生。 有关设备孪生的详细信息,请参阅了解设备孪生,有关查询的参考,请参阅 IoT 中心查询语言

本教程演示如何:

  • 创建将标记添加到设备孪生的后端应用,以及将其连接通道作为设备孪生上的报告属性进行报告的模拟设备应用。
  • 使用标记上的筛选器和之前创建的属性通过后端应用查询设备。

在本教程结束时,将会创建这些 .NET 控制台应用:

  • CreateDeviceIdentity,一个 .NET 应用,用于创建设备标识和关联的安全密钥以连接模拟设备应用。
  • AddTagsAndQuery,一个 .NET 后端应用,用于添加标记并查询设备孪生。
  • ReportConnectivity,一个 .NET 设备应用,它模拟使用早前创建的设备标识连接到 IoT 中心的设备,并报告其连接条件。

Note

Azure IoT SDK 一文介绍了可用于构建设备和后端应用的 Azure IoT SDK。

若要完成本教程,需要满足以下条件:

  • Visual Studio 2017。
  • 有效的 Azure 帐户。 如果没有帐户,可以创建一个试用帐户,只需几分钟即可完成。

创建 IoT 中心

此部分介绍如何使用 Azure 门户创建 IoT 中心。

  1. 登录到 Azure 门户

  2. 选择+“创建资源”,然后选择“物联网”。

  3. 在右侧列表中单击“Iot 中心”。 随即显示 IoT 中心创建过程的第一个屏幕。

    显示了在 Azure 门户中创建中心的屏幕截图

    填充字段。

    订阅:请选择要用于 IoT 中心的订阅。

    资源组:可创建新的资源组或使用现有资源组。 若要新建一个,请单击“新建”,并填写要使用的名称。 若要使用现有资源组,请单击“使用现有资源组”并从下拉列表中选择该组。 有关详细信息,请参阅使用资源组管理 Azure 资源

    区域:这是要在其中设置中心的区域。 从下拉列表中选择最靠近自己的位置。

    IoT 中心名称:输入 IoT 中心的名称。 此名称必须全局唯一。 如果输入的名称可用,会显示一个绿色复选标记。

    Important

    IoT 中心将公开为 DNS 终结点,因此,命名时请务必避免包含任何敏感信息。

  4. 单击“下一步: 大小和规模”,以便继续创建 IoT 中心。

    屏幕截图显示使用 Azure 门户为新的 IoT 中心设置大小和缩放级别

    在此屏幕上,可以采用默认值,只需在底部单击“查看+创建”即可。

    定价和缩放层级:可以根据需要的功能数以及每天通过解决方案发送的消息数从多个层中进行选择。 免费层适用于测试和评估。 它允许 500 台设备连接到 IoT 中心,并且每天最多传输 8,000 条信息。 每个 Azure 订阅可以在免费层中创建一个 IoT 中心。

    IoT 中心单位:每日每单位允许的消息数取决于中心的定价层。 例如,如果希望 IoT 中心支持 700,000 条消息输入,则选择两个 S1 层单位。

    有关其他层选项的详细信息,请参阅选择合适的 IoT 中心层

    高级/设备到云的分区:此属性将设备到云消息与这些消息的同步读取器数目相关联。 大多数 IoT 中心只需要 4 个分区。

  5. 单击“查看+创建”可查看选择。 会显示类似于以下的屏幕。

    屏幕截图显示用于创建新 IoT 中心的信息

  6. 单击“创建”以创建新的 IoT 中心。 创建中心需要几分钟时间。

检索 IoT 中心的连接字符串

创建中心以后,请检索中心的连接字符串。 该字符串用于将设备和应用程序连接到中心。

  1. 单击中心,查看“IoT 中心”窗格,其中包含“设置”等内容。 单击“共享访问策略”。

  2. 在“共享访问策略”中,选择 iothubowner 策略。

  3. 在“共享访问密钥”下,复制“连接字符串 -- 主密钥”供以后使用。

    显示如何检索连接字符串

    有关详细信息,请参阅“IoT 中心开发人员指南”中的访问控制

在 IoT 中心内注册新设备

本部分在 IoT 中心的标识注册表中创建设备标识。 设备无法连接到 IoT 中心,除非它在标识注册表中具有条目。 有关详细信息,请参阅 IoT 中心开发人员指南的“标识注册表”部分

  1. 在 IoT 中心导航菜单中,打开“IoT 设备”,然后单击“添加”,在 IoT 中心注册新设备。

    在门户中创建设备标识

  2. 提供新设备的名称(例如 myDeviceId),然后单击“保存”。 此操作会为 IoT 中心创建新设备标识。

    添加新设备

    Important

    收集的日志中可能会显示设备 ID 用于客户支持和故障排除,因此,在为日志命名时,请务必避免包含任何敏感信息。

  3. 创建设备后,在“IoT 设备”窗格的列表中打开该设备。 复制“连接字符串 ---主密钥”供以后使用。

    设备连接字符串

Note

IoT 中心标识注册表仅存储用于实现 IoT 中心安全访问的设备标识。 它存储设备 ID 和密钥作为安全凭据,以及启用/禁用标志让你禁用对单个设备的访问。 如果应用程序需要存储其他特定于设备的元数据,则应使用特定于应用程序的存储。 有关详细信息,请参阅 IoT 中心开发人员指南

创建服务应用

本部分创建一个 .NET 控制台应用(使用 C#),该应用将位置元数据添加到与 myDeviceId 关联的设备孪生。 然后,该应用选择设备来查询存储在 IoT 中心的设备孪生,然后查询报告手机网络连接的设备孪生。

  1. 在 Visual Studio 中,使用“控制台应用程序”项目模板将 Visual C# Windows 经典桌面项目添加到当前解决方案。 将项目命名为 AddTagsAndQuery

    新的 Visual C# Windows 经典桌面项目

  2. 在“解决方案资源管理器”中,右键单击“AddTagsAndQuery”项目,并单击“管理 NuGet 包...”。

  3. 在“NuGet 包管理器”窗口中,选择“浏览”,并搜索“Microsoft.Azure.Devices”。 选择“安装”以安装“Microsoft.Azure.Devices”包,并接受使用条款。 该过程将下载、安装 Azure IoT 服务 SDK NuGet 包及其依赖项并添加对其的引用。

    “NuGet 包管理器”窗口

  4. Program.cs 文件顶部添加以下 using 语句:

    using Microsoft.Azure.Devices;
    
  5. 将以下字段添加到 Program 类。 将占位符值替换为在上一部分为中心创建的 IoT 中心连接字符串。

    static RegistryManager registryManager;
    static string connectionString = "{iot hub connection string}";
    
  6. 将以下方法添加到 Program 类:

    public static async Task AddTagsAndQuery()
    {
        var twin = await registryManager.GetTwinAsync("myDeviceId");
        var patch =
            @"{
                tags: {
                    location: {
                        region: 'US',
                        plant: 'Redmond43'
                    }
                }
            }";
        await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);
    
        var query = registryManager.CreateQuery(
          "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
        var twinsInRedmond43 = await query.GetNextAsTwinAsync();
        Console.WriteLine("Devices in Redmond43: {0}", 
          string.Join(", ", twinsInRedmond43.Select(t => t.DeviceId)));
    
        query = registryManager.CreateQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
        var twinsInRedmond43UsingCellular = await query.GetNextAsTwinAsync();
        Console.WriteLine("Devices in Redmond43 using cellular network: {0}", 
          string.Join(", ", twinsInRedmond43UsingCellular.Select(t => t.DeviceId)));
    }
    

    RegistryManager 类公开从该服务与设备孪生交互所需的所有方法。 上面的代码首先初始化 registryManager 对象,并检索 myDeviceId 的设备孪生,最后使用所需位置信息更新其标记。

    在更新后,它执行两个查询:第一个仅选择位于 Redmond43 工厂的设备的设备孪生,第二个将查询细化为仅选择还要通过移动电话网络连接的设备。

    请注意上面的代码,当它创建 query 对象时,会指定返回的最大文档数。 query 对象包含 HasMoreResults 布尔值属性,可以使用它多次调用 GetNextAsTwinAsync 方法来检索所有结果。 名为 GetNextAsJson 的方法可用于非设备孪生的结果(例如聚合查询的结果)。

  7. 最后,在 Main 方法中添加以下行:

    registryManager = RegistryManager.CreateFromConnectionString(connectionString);
    AddTagsAndQuery().Wait();
    Console.WriteLine("Press Enter to exit.");
    Console.ReadLine();
    
  8. 在“解决方案资源管理器”中,打开“设置启动项目...”,并确保 AddTagsAndQuery 项目的“操作”为“启动”。 生成解决方案。

  9. 右键单击 AddTagsAndQuery 项目并选择“调试”,并选择“启动新实例”来运行此应用程序。 在查询位于 Redmond43 的所有设备的查询结果中,应该会看到一个设备,而在将结果限制为使用蜂窝网络的设备的查询结果中没有任何设备。

    在窗口中查询结果

在下一部分中,创建的设备应用会报告连接信息,并更改上一部分中查询的结果。

创建设备应用

在此部分,需创建一个 .NET 控制台应用作为“myDeviceId”连接到中心,然后更新其报告属性,使其包含它使用手机网络进行连接的信息。

  1. 在 Visual Studio 中,使用“ 控制台应用程序 ”项目模板将 Visual C# Windows 经典桌面项目添加到当前解决方案。 将项目命名为“ReportConnectivity”。

    新建 Visual C# Windows 经典设备应用

  2. 在解决方案资源管理器中,右键单击“ReportConnectivity”项目,然后单击“管理 NuGet 包...”。

  3. 在“NuGet 包管理器”窗口中,选择“浏览”,然后搜索“Microsoft.Azure.Devices.Client”。 选择“安装”,安装“microsoft.azure.devices.client”包,并接受使用条款。 该过程将下载、安装 Azure IoT 设备 SDK NuGet 包及其依赖项并添加对其的引用。

    “NuGet 包管理器”窗口客户端应用

  4. Program.cs 文件顶部添加以下 using 语句:

    using Microsoft.Azure.Devices.Client;
    using Microsoft.Azure.Devices.Shared;
    using Newtonsoft.Json;
    
  5. 将以下字段添加到 Program 类。 将占位符值替换为在上一部分中记下的设备连接字符串。

    static string DeviceConnectionString = "HostName=<yourIotHubName>.azure-devices.cn;
      DeviceId=<yourIotDeviceName>;SharedAccessKey=<yourIotDeviceAccessKey>";
    static DeviceClient Client = null;
    
  6. 将以下方法添加到 Program 类:

    public static async void InitClient()
    {
        try
        {
            Console.WriteLine("Connecting to hub");
            Client = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
              TransportType.Mqtt);
            Console.WriteLine("Retrieving twin");
            await Client.GetTwinAsync();
        }
        catch (Exception ex)
        {
            Console.WriteLine();
            Console.WriteLine("Error in sample: {0}", ex.Message);
        }
    }
    

    Client 对象公开从该设备与设备孪生交互所需的所有方法。 上述代码会初始化“客户端”对象,然后检索 myDeviceId设备孪生。

  7. 将以下方法添加到 Program 类:

    public static async void ReportConnectivity()
    {
        try
        {
            Console.WriteLine("Sending connectivity data as reported property");
    
            TwinCollection reportedProperties, connectivity;
            reportedProperties = new TwinCollection();
            connectivity = new TwinCollection();
            connectivity["type"] = "cellular";
            reportedProperties["connectivity"] = connectivity;
            await Client.UpdateReportedPropertiesAsync(reportedProperties);
        }
        catch (Exception ex)
        {
            Console.WriteLine();
            Console.WriteLine("Error in sample: {0}", ex.Message);
        }
    }
    

    上述代码会使用连接信息更新 myDeviceId 的报告属性。

  8. 最后,在 Main 方法中添加以下行:

    try
    {
        InitClient();
        ReportConnectivity();
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error in sample: {0}", ex.Message);
    }
    Console.WriteLine("Press Enter to exit.");
    Console.ReadLine();
    
  9. 在“解决方案资源管理器”中,打开“设置启动项目...”,并确保“ReportConnectivity”项目的“操作”为“启动”。 生成解决方案。

  10. 右键单击“ReportConnectivity”项目并选择“调试”,然后选择“启动新实例”来运行此应用程序。 应该可以看到应用获取孪生信息,然后发送连接信息作为报告属性。

    运行设备应用来报告连接信息

  11. 现在设备报告了其连接信息,该信息应出现在两个查询中。 运行 .NET AddTagsAndQuery 应用即可再次运行查询。 这一次 myDeviceId 应显示在两个查询结果中。

    成功报告设备连接信息

后续步骤

本教程中,在 Azure 门户中配置了新的 IoT 中心,并在 IoT 中心的标识注册表中创建了设备标识。 已从后端应用以标记形式添加了设备元数据,并编写了模拟的设备应用,用于报告设备孪生中的设备连接信息。 还学习了如何使用类似 SQL 的 IoT 中心查询语言来查询此信息。

充分利用以下资源: