Начало работы с двойниками устройств (.NET)

Статья
03/17/2023

Двойники устройств — это документы JSON, хранящие сведения о состоянии устройства, в том числе метаданные, конфигурации и условия. Центр Интернета вещей сохраняет двойник устройства для каждого устройства, подключаемого к нему.

Примечание.

Функции, описанные в этой статье, доступны только на стандартном уровне Центра Интернета вещей. Дополнительные сведения о базовых и бесплатных уровнях Центр Интернета вещей см. в разделе "Выбор подходящего уровня Центр Интернета вещей" для решения.

Двойники устройства используются для выполнения следующих действий:

хранение метаданных устройства из серверной части вашего решения;
сообщение сведений о текущем состоянии приложения устройства, таких как доступные возможности и условия, например используемый метод подключения;
синхронизация состояния длительных рабочих процессов между приложением устройства и серверной частью, например при обновлении встроенного ПО и конфигурации;
выполнение запроса метаданных, конфигурации или состояния устройства.

Двойники устройств используются для синхронизации и выполнения запроса конфигураций или условий устройства. Дополнительные сведения об двойниках устройств, включая использование двойников устройств, см. в разделе "Общие сведения о двойниках устройств".

Центры Интернета вещей хранят двойники устройств, которые содержат следующие элементы:

Теги. Метаданные устройства, доступные только в серверной части решения.
Требуемые свойства. Объекты JSON, задаваемые только в серверной части решения и наблюдаемые в приложении устройства.
Сообщаемые свойства. Объекты JSON, задаваемые только в приложении устройства и считываемые в серверной части решения.

Теги и свойства не могут содержать массивы, но могут содержать вложенные объекты.

Следующая иллюстрация показывает организацию двойника устройства:

Снимок экрана: схема концепции двойника устройства.

Кроме того, из серверной части решения можно запросить двойники устройств на основе всех вышеизложенных данных. Дополнительные сведения о двойниках устройств см. в статье Основные сведения о двойниках устройств. Дополнительные сведения запросах см. в статье Язык запросов Центра Интернета вещей.

Из этой статьи вы узнаете, как выполнять следующие задачи:

С помощью приложения имитированного устройства вы можете передавать данные о своем канале подключения как передаваемое свойство двойника устройства.
запрос устройств из серверного приложения с использованием фильтров в созданных ранее тегах и свойствах.

При работе с этой статьей вы создадите два консольных приложения для .NET:

AddTagsAndQuery. Внутреннее приложение, которое добавляет теги и выполняет запросы к двойникам устройств.
ReportConnectivity. Приложение для имитированного устройства, которое подключается к Центру Интернета вещей и предоставляет сведения о состоянии подключения.

Примечание.

Дополнительные сведения о средствах SDK, доступных для создания приложения устройства и внутреннего приложения, см. в статье Пакеты SDK для Интернета вещей Azure.

Необходимые компоненты

Visual Studio.
Центр Интернета вещей. Создайте его с помощью CLI или портала Azure.
Зарегистрированное устройство. Зарегистрируйте его на портале Azure.
Убедитесь, что в брандмауэре открыт порт 8883. Пример устройства в этой статье использует протокол MQTT, который передает данные через порт 8883. В некоторых корпоративных и академических сетях этот порт может быть заблокирован. Дополнительные сведения и способы устранения этой проблемы см. в разделе о подключении к Центру Интернета вещей по протоколу MQTT.

Получение строки подключения центра Интернета вещей

В этой статье вы создадите серверную службу, которая добавляет требуемые свойства в двойник устройства, а затем запрашивает реестр удостоверений, чтобы найти все устройства с передаваемыми свойствами, которые были обновлены соответствующим образом. Службе требуется разрешение service connect для изменения требуемых свойств двойника устройства и разрешение registry read для запроса реестра удостоверений. Политика общего доступа по умолчанию, которая содержит только эти два разрешения, не существует, поэтому необходимо создать ее.

Чтобы создать политику общего доступа, которая предоставляет разрешения service connect и registry read, и получить строку подключения для этой политики, выполните следующие действия.

На портале Azure выберите Группы ресурсов. Выберите группу ресурсов, в которой находится центр, а затем выберите центр из списка ресурсов.
В левой части центра выберите Политики общего доступа.
В верхнем меню над списком политик выберите Добавить политику общего доступа.
В области Добавить политику общего доступа справа введите описательное имя политики, например serviceAndRegistryRead. В разделе Разрешения выберите Чтение реестра и Подключение службы, а затем нажмите кнопку Добавить.
Выберите новую политику из списка политик.
Выберите значок копирования рядом с пунктом Первичная строка подключения и сохраните значение.

Дополнительные сведения о политиках и разрешениях общего доступа Центра Интернета вещей см. в разделе Управления доступом и разрешения.

Создание приложения устройства, которое обновляет сообщаемые свойства

При работе с этим разделом вы создадите консольное приложение .NET, которое подключается к центру как myDeviceId и обновляет передаваемые свойства для подтверждения подключения по сотовой сети.

Откройте Visual Studio и выберите элемент Создать проект.
Выберите элемент Консольное приложение (.NET Framework) и нажмите кнопкуДалее.
В окне Настроить новый проект присвойте проекту имя ReportConnectivity и нажмите кнопку Далее.
В обозревателе решений щелкните правой кнопкой мыши проект ReportConnectivity, а затем Управление пакетами NuGet
Оставьте .NET Framework по умолчанию и выберите Создать для создания проекта.
Выберите Обзор, найдите и выберите Microsoft.Azure.Devices.Client. Выберите Установить.

В результате выполняется скачивание и установка пакета NuGet SDK для устройств Azure IoT и его зависимостей, а также добавляется соответствующая ссылка.

Добавьте следующие инструкции using в начало файла Program.cs :

using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;
using Newtonsoft.Json;

Добавьте следующие поля в класс Program . Замените {device connection string} строкой подключения устройства, которую вы видели при регистрации устройства в Центре Интернета вещей:
```
static string DeviceConnectionString = "HostName=<yourIotHubName>.azure-devices.net;DeviceId=<yourIotDeviceName>;SharedAccessKey=<yourIotDeviceAccessKey>";
static DeviceClient Client = null;
```
Добавьте следующий метод в класс 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 позволяет получить все методы, необходимые для взаимодействия с двойниками устройства с устройства. Приведенный выше код инициализирует объект Client, а затем получает двойник устройства для myDeviceId.

Добавьте следующий метод в класс 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 с помощью сведений о подключении.

Наконец, добавьте следующие строки в метод 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();

В обозревателе решений щелкните решение правой кнопкой мыши и выберите Назначить запускаемые проекты.
Выберите Общие свойства>Запускаемый проект, затем пункт Несколько запускаемых проектов. Для проекта ReportConnectivity выберите Запустить в качестве значения параметра Действие. Нажмите кнопку ОК , чтобы сохранить изменения.
Запустите это приложение, щелкнув правой кнопкой мыши проект ReportConnectivity и выбрав Отладка, а затем — Запустить новый экземпляр. Приложение получит сведения о двойнике, а затем отправит данные подключения как передаваемое свойство.

После того как устройство сообщило сведения о подключении, оно должно появиться в обоих запросах.
Щелкните правой кнопкой мыши проект AddTagsAndQuery и выберите Отладка>Запустить новый экземпляр, чтобы снова запустить запросы. На этот раз myDeviceId должен появиться в результатах обоих запросов.

Создание приложения-службы, которое обновляет требуемые свойства и двойники запросов

В этом разделе рассказывается о том, как создать консольное приложение .NET с помощью C#, которое добавляет метаданные расположения в двойник устройства, связанный с myDeviceId. Приложение запрашивает центр Интернета вещей для устройств, расположенных в США, а затем запрашивает устройства, которые сообщают о подключении к сотовой сети.

В Visual Studio выберите Файл > Новый > проект. В окне Создание проекта выберите Консольное приложение (.NET Framework) и нажмите кнопку Далее.
В разделе Настроить новый проект присвойте проекту имя AddTagsAndQuery и нажмите Далее.
Примите версию платформа .NET Framework по умолчанию и выберите Создать для создания проекта.
В обозревателе решений щелкните правой кнопкой мыши проект AddTagsAndQuery, а затем Управление пакетами Nuget.
Выберите Обзор, найдите и выберите Microsoft.Azure.Devices. Выберите Установить.

В результате выполняется скачивание и установка пакета NuGet SDK для служб Azure IoT и его зависимостей, а также добавляется соответствующая ссылка.
Добавьте следующие инструкции using в начало файла Program.cs :
```
using Microsoft.Azure.Devices;
```
Добавьте следующие поля в класс Program . Замените {iot hub connection string} строкой подключения Центра Интернета вещей, скопированной в разделе Получение строки подключения центра Интернета вещей.
```
static RegistryManager registryManager;
static string connectionString = "{iot hub connection string}";
```
Добавьте следующий метод в класс 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 доступен для результатов, которые не являются двойниками устройств, например результатов статистических запросов.

Наконец, добавьте следующие строки в метод Main :

registryManager = RegistryManager.CreateFromConnectionString(connectionString);
AddTagsAndQuery().Wait();
Console.WriteLine("Press Enter to exit.");
Console.ReadLine();

Запустите это приложение, щелкнув правой кнопкой мыши проект AddTagsAndQuery и выбрав Отладка, а затем — Запустить новый экземпляр. В результатах запроса на все устройства, расположенные на фабрике Redmond43, отобразится одно устройство, а для запроса на ограничение результатов устройствами, использующими сеть мобильной связи, не отобразится ни одного устройства.

Работая с этой статьей, вы выполните следующие задачи:

Добавлены метаданные устройства в виде тегов из внутреннего приложения
передача сведений о возможности подключения устройства в двойнике устройства;
Запрошена информация о двойнике устройства с помощью подобного SQL языка запросов Центра Интернета вещей

Следующие шаги

Ознакомьтесь со следующими материалами.

Сведения об отправке данных телеметрии с устройств см. в статье Краткое руководство. Отправка данных телеметрии с устройства IoT Plug and Play в Центр Интернета вещей Azure.
Сведения о настройке устройств с использованием нужных свойств двойника устройства см. в статье Руководство по настройке устройств из внутренней службы.
Интерактивное управление устройствами, например включение вентилятора из контролируемого пользователем приложения. См. Краткое руководство. Управление подключенным к Центру Интернета вещей устройством.

Поделиться через