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

• Требуется Visual Studio

Обзор

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

Создание приложения устройства

Приложения устройств могут считывать и записывать сообщаемые свойства двойника, а также получать уведомления об изменениях желаемых свойств двойника, заданных серверным приложением или IoT Hub.

В этом разделе описывается, как использовать код приложения устройства для:

• Получение двойника устройства и проверка сообщаемых свойств
• Обновление свойств двойника устройства
• Создание обработчика обратного вызова обновления требуемого свойства

Обязательный пакет NuGet для устройства

Клиентские приложения устройств, написанные на C#, требуют пакета NuGet Microsoft.Azure.Devices.Client .

Добавьте эту using инструкцию для использования библиотеки устройств.

using Microsoft.Azure.Devices.Client;

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

Приложение устройства может пройти проверку подлинности в IoT Hub, используя следующие методы:

• Общий ключ доступа
• Сертификат X.509

Проверка подлинности с помощью общего ключа доступа

Класс DeviceClient предоставляет все методы, необходимые для взаимодействия с двойниками устройств с устройства.

Подключитесь к устройству с помощью метода CreateFromConnectionString, используя строку подключения устройства и транспортный протокол связи.

Параметр CreateFromConnectionStringтранспортного протокола TransportType поддерживает следующие транспортные протоколы:

• Mqtt
• Mqtt_WebSocket_Only
• Mqtt_Tcp_Only
• Amqp
• Amqp_WebSocket_Only
• Amqp_Tcp_Only

Протокол Http1 не поддерживается для обновлений двойника устройства.

Этот пример подключается к устройству с использованием транспортного протокола Mqtt.

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

static string DeviceConnectionString = "{IoT hub device connection string}";
static _deviceClient = null;
_deviceClient = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
   TransportType.Mqtt);

Проверка подлинности с помощью сертификата X.509

Чтобы подключить устройство к Центру Интернета вещей с помощью сертификата X.509:

1. Используйте DeviceAuthenticationWithX509Certificate для создания объекта, содержащего сведения об устройстве и сертификате. DeviceAuthenticationWithX509Certificate передается в качестве второго параметра DeviceClient.Create (шаг 2).

2. Используйте DeviceClient.Create для подключения устройства к Центр Интернета вещей с помощью сертификата X.509.

В этом примере сведения об устройстве и сертификате заполняются в объекте authDeviceAuthenticationWithX509Certificate , передаваемом в DeviceClient.Create.

В этом примере показаны значения входных параметров сертификата в качестве локальных переменных для ясности. В рабочей системе храните конфиденциальные входные параметры в переменных среды или другом безопасном расположении хранилища. Например, используйте Environment.GetEnvironmentVariable("HOSTNAME") для чтения переменной среды имени узла.

RootCertPath = "~/certificates/certs/sensor-thl-001-device.cert.pem";
Intermediate1CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate1.cert.pem";
Intermediate2CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate2.cert.pem";
DevicePfxPath = "~/certificates/certs/sensor-thl-001-device.cert.pfx";
DevicePfxPassword = "1234";
DeviceName = "MyDevice";
HostName = "xxxxx.azure-devices.net";

var chainCerts = new X509Certificate2Collection();
chainCerts.Add(new X509Certificate2(RootCertPath));
chainCerts.Add(new X509Certificate2(Intermediate1CertPath));
chainCerts.Add(new X509Certificate2(Intermediate2CertPath));
using var deviceCert = new X509Certificate2(DevicePfxPath, DevicePfxPassword);
using var auth = new DeviceAuthenticationWithX509Certificate(DeviceName, deviceCert, chainCerts);

using var deviceClient = DeviceClient.Create(
    HostName,
    auth,
    TransportType.Amqp);

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

• Проверка подлинности удостоверений с помощью сертификатов X.509
• Руководство. Создание и отправка сертификатов для тестирования

Примеры кода

Рабочие примеры проверки подлинности сертификата X.509 см. здесь:

• Подключение к сертификату X.509
• DeviceClientX509AuthenticationE2ETests
• Пошаговый проект - Подготовка и защита устройств Интернета вещей в большом масштабе с помощью Службы подготовки устройств IoT Hub

Получение двойника устройства и проверка свойств

Вызовите GetTwinAsync, чтобы получить текущие свойства цифрового двойника устройства. Существует множество свойств объекта Twin, которые можно использовать для доступа к определенным областям Twin данных JSON, включая Properties, Status, Tags, и Version.

В этом примере извлекаются свойства двойника устройства и печатаются значения двойников в формате JSON.

Console.WriteLine("Retrieving twin...");
Twin twin = await _deviceClient.GetTwinAsync();
Console.WriteLine("\tInitial twin value received:");
Console.WriteLine($"\t{twin.ToJson()}");

Обновите переданные свойства двойника устройства

Чтобы обновить сообщаемое свойство цифрового двойника, выполните следующие действия.

1. Создание объекта TwinCollection для обновления сообщаемого свойства
2. Обновите одно или несколько сообщаемых свойств в объекте TwinCollection
3. Использование UpdateReportedPropertiesAsync для отправки отчетов об изменениях свойств в службу Центра Интернета вещей

Например:

try
{
Console.WriteLine("Sending sample start time as reported property");
TwinCollection reportedProperties = new TwinCollection();
reportedProperties["DateTimeLastAppLaunch"] = DateTime.UtcNow;
await _deviceClient.UpdateReportedPropertiesAsync(reportedProperties);
}
catch (Exception ex)
{
   Console.WriteLine();
   Console.WriteLine("Error in sample: {0}", ex.Message);
}

Создайте обработчик обратного вызова для обновления необходимого свойства

Создайте обработчик обратного вызова обновления требуемого свойства, который выполняется при изменении требуемого свойства в двойнике устройства путем передачи имени метода обработчика обратного вызова в SetDesiredPropertyUpdateCallbackAsync.

Например, этот вызов настраивает систему для уведомления метода с именемOnDesiredPropertyChangedAsync при изменении требуемого свойства.

await _deviceClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

Свойства двойника передаются методу обратного вызова в виде TwinCollection и могут рассматриваться как KeyValuePair структуры.

Этот пример получает обновления требуемого свойства в виде TwinCollection, а затем проходит по обновлениям коллекции KeyValuePair и печатает их. После прохода по KeyValuePair коллекции код вызывает UpdateReportedPropertiesAsync, чтобы обновить DateTimeLastDesiredPropertyChangeReceived сообщаемое свойство и обеспечить актуальность последнего обновления времени.

private async Task OnDesiredPropertyChangedAsync(TwinCollection desiredProperties, object userContext)
{
   var reportedProperties = new TwinCollection();

   Console.WriteLine("\tDesired properties requested:");
   Console.WriteLine($"\t{desiredProperties.ToJson()}");

   // For the purpose of this sample, we'll blindly accept all twin property write requests.
   foreach (KeyValuePair<string, object> desiredProperty in desiredProperties)
   {
         Console.WriteLine($"Setting {desiredProperty.Key} to {desiredProperty.Value}.");
         reportedProperties[desiredProperty.Key] = desiredProperty.Value;
   }

   Console.WriteLine("\tAlso setting current time as reported property");
   reportedProperties["DateTimeLastDesiredPropertyChangeReceived"] = DateTime.UtcNow;

   await _deviceClient.UpdateReportedPropertiesAsync(reportedProperties);
}

Пример устройства SDK

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

Создание серверного приложения

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

В этом разделе описывается, как создать код внутреннего приложения для:

• Чтение и обновление полей двойника устройства
• Создайте запрос двойника устройства

Класс RegistryManager предоставляет все методы, необходимые для создания серверного приложения для взаимодействия с двойниками устройств из службы.

Добавьте пакет NuGet для службы

Для приложений бекенд-сервиса требуется пакет NuGet Microsoft.Azure.Devices.

Подключение к Центру Интернета вещей

Вы можете подключить серверную службу к Центр Интернета вещей с помощью следующих методов:

• Политика общего доступа
• Microsoft Entra

Подключение с помощью политики общего доступа

Подключите серверное приложение к устройству с помощью CreateFromConnectionString. Приложению требуется разрешение на подключение к службе для изменения желаемых свойств двойника устройства, а разрешение на чтение необходимо для запроса реестра идентификаций. Политика общего доступа по умолчанию отсутствует, содержащая только эти два разрешения, поэтому необходимо создать его, если он еще не существует. Укажите строку подключения политики общего доступа в качестве параметра fromConnectionString. Дополнительные сведения о политиках общего доступа см. в статье "Управление доступом к Центр Интернета вещей с помощью подписанных URL-адресов".

using Microsoft.Azure.Devices;
static RegistryManager registryManager;
static string connectionString = "{Shared access policy connection string}";
registryManager = RegistryManager.CreateFromConnectionString(connectionString);

Подключение с помощью Microsoft Entra

Заднее приложение, использующее Microsoft Entra, должно успешно пройти проверку подлинности и получить учетные данные токена безопасности перед подключением к Центру Интернета вещей. Этот маркер передается методу подключения Концентратора IoT. Общие сведения о настройке и использовании Microsoft Entra для Центр Интернета вещей см. в разделе "Управление доступом к Центр Интернета вещей с помощью идентификатора Microsoft Entra".

Настройка приложения Microsoft Entra

Необходимо настроить приложение Microsoft Entra для использования предпочитаемых учетных данных проверки подлинности. Приложение содержит такие параметры, как секрет клиента, используемый серверным приложением для проверки подлинности. Доступные конфигурации проверки подлинности приложений:

• Секрет клиента
• Сертификат
• Федеративные учетные данные

Приложения Microsoft Entra могут требовать определенные разрешения ролей в зависимости от выполняемых операций. Например, Участник-близнец IoT Hub требуется для предоставления доступа на чтение и запись к двойникам устройств и модулей IoT Hub. Для получения дополнительных сведений см. Управление доступом к Центру IoT с помощью назначения ролей Azure RBAC.

Для получения дополнительной информации о настройке приложения Microsoft Entra, см. краткое руководство: Регистрация приложения на платформе удостоверений Microsoft.

Проверка подлинности с помощью DefaultAzureCredential

Самый простой способ использовать Microsoft Entra для проверки подлинности серверного приложения — это использовать DefaultAzureCredential, но в рабочей среде рекомендуется использовать другой метод, например, определенный метод TokenCredential или упрощенный метод ChainedTokenCredential. Для простоты в этом разделе описывается использование аутентификации с DefaultAzureCredential и секретом клиента. Для получения дополнительных сведений о преимуществах и недостатках использования DefaultAzureCredential, см. руководство по использованию DefaultAzureCredential.

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

Для Microsoft Entra требуются следующие пакеты NuGet и соответствующие using инструкции:

• Azure.Core
• Azure.Identity

using Azure.Core;
using Azure.Identity;

В этом примере секрет клиента для регистрации приложения Microsoft Entra, идентификатор клиента и идентификатор арендатора добавляются в переменные среды. Эти переменные среды используются DefaultAzureCredential для проверки подлинности приложения. Результат успешной проверки подлинности Microsoft Entra — это учетные данные токена безопасности, передаваемые методу подключения Центра Интернета вещей (IoT Hub).

string clientSecretValue = "xxxxxxxxxxxxxxx";
string clientID = "xxxxxxxxxxxxxx";
string tenantID = "xxxxxxxxxxxxx";

Environment.SetEnvironmentVariable("AZURE_CLIENT_SECRET", clientSecretValue);
Environment.SetEnvironmentVariable("AZURE_CLIENT_ID", clientID);
Environment.SetEnvironmentVariable("AZURE_TENANT_ID", tenantID);

TokenCredential tokenCredential = new DefaultAzureCredential();

Результирующий TokenCredential затем можно передать методу подключения к IoT Hub для любого клиента SDK, который принимает учетные данные Microsoft Entra.

• JobClient
• RegistryManager
• DigitalTwinClient
• ServiceClient

В этом примере TokenCredential передается в ServiceClient.Create для создания объекта подключения ServiceClient.

string hostname = "xxxxxxxxxx.azure-devices.net";
using var serviceClient = ServiceClient.Create(hostname, tokenCredential, TransportType.Amqp);

В этом примере TokenCredential передается в RegistryManager.Create, чтобы создать объект RegistryManager.

string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);

Пример кода

Для рабочего примера проверки подлинности службы Microsoft Entra см. пример проверки подлинности на основе ролей.

Чтение и обновление полей двойника устройства

Вы можете получить текущие поля двойника устройства в объект Twin путем вызова GetTwinAsync.

Класс Twin содержит свойства , соответствующие каждому разделу двойника устройства. Twin Используйте свойства класса для просмотра и обновления полей двойника устройства. Свойства объекта Twin можно использовать для обновления нескольких полей близнецов перед передачей их на устройство с помощью UpdateTwinAsync.

После обновления полей двойника вызовите UpdateTwinAsync для записи Twin обновлений поля объекта обратно на устройство. Используйте логику try и catch, связанную с обработчиком ошибок, чтобы перехватывать неправильно отформатированные ошибки исправлений из UpdateTwinAsync.

Чтение и обновление тегов двойника устройства

Используйте свойство тегов двойника устройства для чтения и записи сведений о теге устройства.

Обновление тегов с помощью объекта двойника

В этом примере создается патч для тега location, который назначается объекту Twin через свойство Tags, а затем применяется с помощью UpdateTwinAsync.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

// Create the tag patch
var tagspatch =
   @"{
   tags: {
         location: {
            region: 'US',
            plant: 'Redmond43'
         }
   }
}";

// Assign the patch to the Twin object
twin.Tags["location"] = tagspatch;

// Apply the patch to update the device twin tags section
try
{
   await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);
}
catch (Exception e)
{
   console.WriteLine("Twin update failed.", e.Message);
}

Обновление тегов с помощью строки JSON

Вы можете создать и применить патч обновления сведений о цифровых двойниках устройств в формате JSON. Центр Интернета вещей анализирует и применяет исправление, если оно правильно отформатировано.

В этом примере вызывается GetTwinAsync, чтобы получить текущие поля двойника устройства в объект Twin, создается патч в формате JSON с информацией о регионе и местоположении завода, а затем вызывается UpdateTwinAsync для применения патча и обновления двойника устройства. Сообщение об ошибке отображается, если произошел сбой UpdateTwinAsync.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

// Create the JSON tags patch
var patch =
   @"{
      tags: {
            location: {
               region: 'US',
               plant: 'Redmond43'
            }
      }
   }";
// Apply the patch to update the device twin tags
try
{
   await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);
}
catch (Exception e)
{
   console.WriteLine("Twin update failed.", e.Message);
}

Просмотр и обновление нужных свойств двойника

Используйте свойство twin TwinProperties.Desired для чтения и записи сведений о нужном свойстве устройства. Обновите свойства двойника Desired с помощью пэтча в формате JSON.

В этом примере вызывается GetTwinAsync, чтобы получить текущие поля двойника устройства в объект Twin, обновляет желаемое свойство двойника, а затем вызывает speed, чтобы применить объект Twin для обновления двойника устройства.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

twin.Properties.Desired["speed"] = "type: '5G'";
await registryManager.UpdateTwinAsync(twin.DeviceId, twin, twin.ETag);

Другие методы обновления двойников

Вы также можете применять парные обновления с помощью следующих методов SDK:

• Вызовите ReplaceTwinAsync, чтобы заменить весь цифровой двойник устройства.
• Вызовите UpdateTwins2Async , чтобы обновить список двойников, созданных ранее в системе.

Создать запрос двойника устройства

В этом разделе демонстрируются два двойных запроса устройства. Запросы двойников устройств — это запросы, такие как SQL, которые возвращают результирующий набор двойников устройств.

Чтобы создать запрос двойника устройства, вызовите CreateQuery для отправки SQL-запроса двойников и получения интерфейса IQuery. При необходимости можно вызвать CreateQuery, указав второй параметр для задания максимального количества элементов на странице.

Вызовите метод GetNextAsTwinAsync или GetNextAsJsonAsync столько раз, сколько необходимо для получения всех данных двойника.

• GetNextAsTwinAsync для получения следующего результата страницы в виде объектов Twin .
• GetNextAsJsonAsync для получения следующего результата страницы в виде строк JSON.

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

В этом примере запроса выбираются только двойники устройств, расположенные в заводе Redmond43 .

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)));

Пример службы SDK

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

• Требуется пакет разработки Java SE 8. Убедитесь, что вы выбрали Java 8 в разделе долгосрочной поддержки , чтобы перейти к скачиванию для JDK 8.

Обзор

В этой статье описывается, как использовать пакет SDK Для Интернета вещей Azure для Java для создания кода приложения службы устройств и серверной службы для двойников устройств.

Создание приложения устройства

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

В этом разделе описывается, как создать код приложения устройства для:

• Получение и просмотр двойника устройства
• Обновление свойств двойника устройства
• Подписка на изменения желаемых свойств

Класс DeviceClient предоставляет все методы, необходимые для взаимодействия с двойниками устройств с устройства.

Инструкции импорта устройств

Используйте следующие инструкции импорта устройств для доступа к пакету SDK Интернета вещей Azure для Java.

import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.DeviceTwin.*;

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

Приложение устройства может пройти проверку подлинности с помощью IoT Hub следующими методами:

• Общий ключ доступа
• Сертификат X.509

Проверка подлинности с помощью общего ключа доступа

Чтобы подключить устройство к Центр Интернета вещей, выполните действия.

1. Используйте IotHubClientProtocol для выбора протокола транспорта. Например:

   IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
   

2. Используйте конструктор DeviceClient для добавления основной строки подключения устройства и протокола.

   String connString = "{IoT hub device connection string}";
   DeviceClient client = new DeviceClient(connString, protocol);
   

3. Используйте открыть для подключения устройства к узлу Интернета вещей. Если клиент уже открыт, метод ничего не делает.

   client.open(true);
   

Проверка подлинности с помощью сертификата X.509

Чтобы подключить устройство к IoT Hub с помощью сертификата X.509:

1. Создайте объект SSLContext с помощью buildSSLContext.
2. SSLContext Добавьте сведения в объект ClientOptions.
3. Вызов DeviceClient с помощью ClientOptions сведений для создания подключения "устройство — Центр Интернета вещей".

В этом примере показаны значения входных параметров сертификата в качестве локальных переменных для ясности. В рабочей системе храните конфиденциальные входные параметры в переменных среды или другом безопасном расположении хранилища. Например, используйте Environment.GetEnvironmentVariable("PUBLICKEY") для чтения переменной среды с строкой сертификата открытого ключа.

private static final String publicKeyCertificateString =
        "-----BEGIN CERTIFICATE-----\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "-----END CERTIFICATE-----\n";

//PEM encoded representation of the private key
private static final String privateKeyString =
        "-----BEGIN EC PRIVATE KEY-----\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "-----END EC PRIVATE KEY-----\n";

SSLContext sslContext = SSLContextBuilder.buildSSLContext(publicKeyCertificateString, privateKeyString);
ClientOptions clientOptions = ClientOptions.builder().sslContext(sslContext).build();
DeviceClient client = new DeviceClient(connString, protocol, clientOptions);

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

• Проверка подлинности удостоверений с помощью сертификатов X.509
• Руководство. Создание и отправка сертификатов для тестирования

Примеры кода

Для работающих примеров проверки подлинности сертификата X.509 см. статью:

• Пример отправки и получения x509
• Отправка события x509

Получение и просмотр двойника устройства

После открытия подключения клиента вызовите getTwin, чтобы получить текущие свойства двоичного объекта в объект Twin.

Например:

private static Twin twin;
System.out.println("Getting current twin");
twin = client.getTwin();
System.out.println("Received current twin:");
System.out.println(twin);

Обновление сообщаемых свойств двойника устройства

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

Чтобы обновить сообщаемые свойства, выполните указанные действия.

1. Вызовите getReportedProperties , чтобы получить сообщаемые свойства двойника в объект TwinCollection .

2. Используйте put для обновления сообщаемого свойства в объекте TwinCollection. Вызовите put для каждого обновления свойств.

3. Используйте updateReportedProperties , чтобы применить группу сообщаемых свойств, которые были обновлены с помощью put метода.

Например:

TwinCollection reportedProperties = twin.getReportedProperties();

int newTemperature = new Random().nextInt(80);
reportedProperties.put("HomeTemp(F)", newTemperature);
System.out.println("Updating reported property \"HomeTemp(F)\" to value " + newTemperature);

ReportedPropertiesUpdateResponse response = client.updateReportedProperties(reportedProperties);
System.out.println("Successfully set property \"HomeTemp(F)\" to value " + newTemperature);

Подписка на изменения требуемого свойства

Вызовите subscribeToDesiredProperties , чтобы подписаться на нужные изменения свойств. Этот клиент получает обратный вызов с Twin объектом при каждом обновлении требуемого свойства. Этот обратный вызов содержит полный набор требуемых свойств или только обновленное свойство в зависимости от того, как было изменено требуемое свойство.

В этом примере подписывается на изменения требуемого свойства. Любые изменения требуемого свойства передаются обработчику с именем DesiredPropertiesUpdatedHandler.

client.subscribeToDesiredProperties(new DesiredPropertiesUpdatedHandler(), null);

В этом примере обработчик изменения требуемых DesiredPropertiesUpdatedHandler свойств вызывает функцию getDesiredProperties для получения изменений, а затем выводит на печать обновленные свойства двойника.

  private static class DesiredPropertiesUpdatedHandler implements DesiredPropertiesCallback
  {
      @Override
      public void onDesiredPropertiesUpdated(Twin desiredPropertyUpdateTwin, Object context)
      {
          if (twin == null)
          {
              // No need to care about this update because these properties will be present in the twin retrieved by getTwin.
              System.out.println("Received desired properties update before getting current twin. Ignoring this update.");
              return;
          }

          // desiredPropertyUpdateTwin.getDesiredProperties() contains all the newly updated desired properties as well as the new version of the desired properties
          twin.getDesiredProperties().putAll(desiredPropertyUpdateTwin.getDesiredProperties());
          twin.getDesiredProperties().setVersion(desiredPropertyUpdateTwin.getDesiredProperties().getVersion());
          System.out.println("Received desired property update. Current twin:");
          System.out.println(twin);
      }
  }

Пример устройства SDK

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

Создание серверного приложения

В этом разделе описывается, как создать серверное приложение, которое:

• Обновление тегов двойника устройства
• Запросы устройств с помощью фильтров по тегам и свойствам

Класс ServiceClientDeviceTwin содержит методы, которые службы могут использовать для доступа к двойникам устройств.

Инструкции импорта служб

Используйте следующие инструкции импорта служб для доступа к пакету SDK Интернета вещей Azure для Java.

import com.microsoft.azure.sdk.iot.service.devicetwin.*;
import com.microsoft.azure.sdk.iot.service.exceptions.IotHubException;

Подключение к Центру Интернета вещей

Вы можете подключить серверную службу к Центр Интернета вещей с помощью следующих методов:

• Политика общего доступа
• Microsoft Entra

Подключение с помощью политики общего доступа

Используйте конструктор DeviceTwin для создания подключения к Центру Интернета вещей. Объект DeviceTwin обрабатывает обмен данными с центром Интернета вещей.

Приложению требуется разрешение на подключение службы service connect для изменения желаемых свойств двойника устройства, а также требуется разрешение на чтение registry read для запроса реестра идентификации. Политика общего доступа по умолчанию отсутствует, содержащая только эти два разрешения, поэтому необходимо создать его, если он еще не существует. Укажите строку подключения политики общего доступа в качестве параметра fromConnectionString. Дополнительные сведения о политиках общего доступа см. в статье "Управление доступом к Центр Интернета вещей с помощью подписанных URL-адресов".

Объект DeviceTwinDevice представляет двойник устройства со своими свойствами и тегами.

Например:

public static final String iotHubConnectionString = "{Shared access policy connection string}";
public static final String deviceId = "myDeviceId";
public static final String region = "US";
public static final String plant = "Redmond43";

// Get the DeviceTwin and DeviceTwinDevice objects
DeviceTwin twinClient = new DeviceTwin(iotHubConnectionString);
DeviceTwinDevice device = new DeviceTwinDevice(deviceId);

Подключение с помощью Microsoft Entra

Серверное приложение, использующее Microsoft Entra, должно успешно пройти аутентификацию и получить токен безопасности до подключения к IoT Hub. Этот маркер передается методу подключения к Центру Интернета вещей. Общие сведения о настройке и использовании Microsoft Entra для Центр Интернета вещей см. в разделе "Управление доступом к Центр Интернета вещей с помощью идентификатора Microsoft Entra".

Общие сведения о проверке подлинности Java SDK см. в разделе "Проверка подлинности Azure с использованием Java и Azure Identity".

Для простоты в этом разделе рассматривается описание проверки подлинности с помощью секрета клиента.

Настройка приложения Microsoft Entra

Необходимо настроить приложение Microsoft Entra, настройка которого соответствует вашим предпочитаемым учетным данным для проверки подлинности. Приложение содержит такие параметры, как секрет клиента, используемый серверным приложением для проверки подлинности. Доступные конфигурации проверки подлинности приложений:

• Секрет клиента
• Сертификат
• Учетные данные федеративной идентификации

Приложения Microsoft Entra могут требовать определенные разрешения ролей в зависимости от выполняемых операций. Например, IoT Hub Twin Contributor требуется для предоставления прав на чтение и запись двойникам устройства и модуля в Центре Интернета вещей. Дополнительные сведения см. в статье «Управление доступом к узлу IoT с помощью назначения ролей Azure RBAC».

Дополнительные сведения о настройке приложения Microsoft Entra см. в разделе 'Краткое руководство: Регистрация приложения на платформе идентификации Microsoft'.

Проверка подлинности с помощью DefaultAzureCredential

Самый простой способ использовать Microsoft Entra для аутентификации серверного приложения — это использовать DefaultAzureCredential, но рекомендуется использовать другой метод в рабочей среде, включая конкретный TokenCredential или упрощенный ChainedTokenCredential. Дополнительные сведения о преимуществах и недостатках использования DefaultAzureCredential см. в цепочках учетных данных в клиентской библиотеке удостоверений Azure для Java.

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

Учетные данные приложения Microsoft Entra можно аутентифицировать с помощью DefaultAzureCredentialBuilder. Сохраните параметры подключения, такие как client secret, tenantID, clientID и значения client secret в качестве переменных среды. После того как TokenCredential будет создан, передайте его в ServiceClient или другой экземпляр в качестве параметра 'credential'.

В этом примере DefaultAzureCredentialBuilder пытается выполнить проверку подлинности подключения из списка, описанного в defaultAzureCredential. Результатом успешной проверки подлинности Microsoft Entra являются учетные данные маркера безопасности, которые передаются конструктору, например, ServiceClient.

TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build();

Проверка подлинности с помощью ClientSecretCredentialBuilder

С помощью ClientSecretCredentialBuilder можно создать учетные данные с помощью сведений о секрете клиента. В случае успеха этот метод возвращает TokenCredential, который можно передать в ServiceClient или другому построителю в качестве параметра 'credential'.

В этом примере в переменные среды добавлены секрет клиента, идентификатор клиента и идентификатор арендатора для регистрации приложений Microsoft Entra. Эти переменные среды ClientSecretCredentialBuilder используются для формирования учетных данных.

string clientSecretValue = System.getenv("AZURE_CLIENT_SECRET");
string clientID = System.getenv("AZURE_CLIENT_ID");
string tenantID = System.getenv("AZURE_TENANT_ID");

TokenCredential credential =
     new ClientSecretCredentialBuilder()
          .tenantId(tenantID)
          .clientId(clientID)
          .clientSecret(clientSecretValue)
          .build();

Другие классы проверки подлинности

Пакет SDK для Java также включает следующие классы, которые проходят проверку подлинности серверного приложения с помощью Microsoft Entra:

• AuthorizationCodeCredential
• AzureCliCredential
• AzureDeveloperCliCredential
• AzurePipelinesCredential
• ChainedTokenCredential
• ClientAssertionCredential
• ClientCertificateCredential
• DeviceCodeCredential
• EnvironmentCredential
• InteractiveBrowserCredential
• ManagedIdentityCredential
• OnBehalfOfCredential

Примеры кода

Для примеров работы с проверкой подлинности службы Microsoft Entra см. Пример проверки подлинности на основе ролей.

Обновление полей двойника устройства

Чтобы обновить поля двойника устройства, выполните следующие действия.

1. Используйте getTwin для получения текущих полей двойника устройства

   В этом примере извлекаются и печатаются поля цифрового двойника устройства:

   // Get the device twin from IoT Hub
   System.out.println("Device twin before update:");
   twinClient.getTwin(device);
   System.out.println(device);
   

2. HashSet Использование объекта для add группы пар тегов двойников

3. Добавление группы пар тегов из объекта в tags объект с помощью DeviceTwinDevice

4. Обновление двойника в Центре Интернета вещей с помощью updateTwin

   В этом примере обновляются теги региона и завода для двойника устройства.

   // Update device twin tags if they are different
   // from the existing values
   String currentTags = device.tagsToString();
   if ((!currentTags.contains("region=" + region) && !currentTags.contains("plant=" + plant))) {
   
   // Create the tags and attach them to the DeviceTwinDevice object
   Set<Pair> tags = new HashSet<Pair>();
   tags.add(new Pair("region", region));
   tags.add(new Pair("plant", plant));
   device.setTags(tags);
   
   // Update the device twin in IoT Hub
   System.out.println("Updating device twin");
   twinClient.updateTwin(device);
   }
   
   // Retrieve and display the device twin with the tag values from IoT Hub
   System.out.println("Device twin after update:");
   twinClient.getTwin(device);
   System.out.println(device);
   

Создайте запрос двойника устройства

В этом разделе представлены два примера запросов к двойнику устройства. Запросы двойников устройств — это запросы, такие как SQL, которые возвращают результирующий набор двойников устройств.

Класс Query содержит методы, которые можно использовать для создания SQL-запросов к IoT Hub для работы с цифровыми двойниками, заданиями, заданиями устройства или необработанными данными.

Чтобы создать запрос устройства, выполните приведенные действия.

1. Создание SQL-запроса двойников с помощью createSqlQuery

2. Использование queryTwin для выполнения запроса

3. Используйте hasNextDeviceTwin , чтобы проверить наличие другого двойника устройства в результирующем наборе

4. Для получения следующего двойника устройства из набора результатов используйте getNextDeviceTwin.

В следующих примерах запросов возвращается максимум 100 устройств.

В этом примере запроса выбираются только двойники устройств, расположенные на заводе Redmond43.

// Query the device twins in IoT Hub
System.out.println("Devices in Redmond:");

// Construct the query
SqlQuery sqlQuery = SqlQuery.createSqlQuery("*", SqlQuery.FromType.DEVICES, "tags.plant='Redmond43'", null);

// Run the query, returning a maximum of 100 devices
Query twinQuery = twinClient.queryTwin(sqlQuery.getQuery(), 100);
while (twinClient.hasNextDeviceTwin(twinQuery)) {
  DeviceTwinDevice d = twinClient.getNextDeviceTwin(twinQuery);
  System.out.println(d.getDeviceId());
}

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

System.out.println("Devices in Redmond using a cellular network:");

// Construct the query
sqlQuery = SqlQuery.createSqlQuery("*", SqlQuery.FromType.DEVICES, "tags.plant='Redmond43' AND properties.reported.connectivityType = 'cellular'", null);

// Run the query, returning a maximum of 100 devices
twinQuery = twinClient.queryTwin(sqlQuery.getQuery(), 3);
while (twinClient.hasNextDeviceTwin(twinQuery)) {
  DeviceTwinDevice d = twinClient.getNextDeviceTwin(twinQuery);
  System.out.println(d.getDeviceId());
}

Пример службы SDK

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

• Рекомендуется использовать пакет SDK для Python версии 3.7 или более поздней версии. Обязательно используйте 32-разрядную или 64-разрядную версию установки согласно требованиям программы настройки. При появлении запроса во время установки обязательно добавьте Python в переменную среды соответствующей платформы.

Обзор

В этой статье описывается, как использовать Azure IoT SDK для Python для создания кода приложений устройств и серверных служб для двойников устройств.

Установка пакетов

Для создания приложений устройств необходимо установить библиотеку azure-iot-device .

pip install azure-iot-device

Для создания внутренних приложений службы необходимо установить библиотеку Azure-iot-hub.

pip install azure-iot-hub

Создание приложения устройства

Приложения устройств могут считывать и записывать сообщенные свойства двойника, а также получать уведомления об изменениях желаемых свойств двойника, заданных серверным приложением или Центром Интернета вещей (IoT Hub).

Класс IoTHubDeviceClient содержит методы, которые можно использовать для работы с двойниками устройств.

В этом разделе описывается, как создать код приложения устройства, который:

• Извлекает двойник устройства и изучает сообщаемые свойства
• Обновлённые свойства двойника устройства

Команда импорта устройства

Добавьте этот код для импорта функций IoTHubDeviceClient из SDK azure.iot.device.

from azure.iot.device import IoTHubDeviceClient

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

Приложение устройства может аутентифицироваться в Центре Интернета вещей следующими методами:

• Общий ключ доступа
• Сертификат X.509

Проверка подлинности с помощью общего ключа доступа

Чтобы подключить устройство к Центр Интернета вещей, выполните действия.

1. Вызовите create_from_connection_string, чтобы добавить основную строку подключения устройства.
2. Вызовите connect, чтобы подключить клиент устройства.

Например:

# Add your IoT hub primary connection string
CONNECTION_STRING = "{Device primary connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(CONNECTION_STRING)

# Connect the client
device_client.connect()

Проверка подлинности с помощью сертификата X.509

Чтобы подключить устройство к IoT Hub с помощью сертификата X.509:

1. Добавление параметров сертификата X.509 с помощью create_from_x509_certificate
2. Вызовите connect, чтобы подключить клиента устройства

В этом примере показаны значения входных параметров сертификата в качестве локальных переменных для ясности. В рабочей системе храните конфиденциальные входные параметры в переменных среды или другом безопасном расположении хранилища. Например, используйте os.getenv("HOSTNAME") для чтения переменной среды имени узла.

# The Azure IoT hub name
hostname = "xxxxx.azure-devices.net"

# The device that has been created on the portal using X509 CA signing or self-signing capabilities
device_id = "MyDevice"

# The X.509 certificate file name
cert_file = "~/certificates/certs/sensor-thl-001-device.cert.pfx"
key_file = "~/certificates/certs/sensor-thl-001-device.cert.key"
# The optional certificate pass phrase
pass_phrase = "1234"

x509 = X509(
    cert_file,
    key_file,
    pass_phrase,
)

# The client object is used to interact with your Azure IoT hub.
device_client = IoTHubDeviceClient.create_from_x509_certificate(
    hostname=hostname, device_id=device_id, x509=x509
)

# Connect to IoT Hub
await device_client.connect()

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

• Проверка подлинности удостоверений с помощью сертификатов X.509
• Руководство. Создание и отправка сертификатов для тестирования

Примеры кода

Для ознакомления с рабочими примерами аутентификации с использованием сертификатов X.509 устройств, см. примеры, имена файлов которых заканчиваются на x509, в разделе сценариев Async hub.

Получение двойника устройства и проверка сообщаемых свойств

Вы можете извлекать и анализировать информацию о двойниках устройств, включая метки и свойства. Информация о двойнике устройства, полученная в формате JSON, соответствует данным двойника устройства, которые можно просмотреть в портале Azure.

Вызовите get_twin, чтобы получить двойник устройства из службы Azure IoT Hub. Информация о близнецах помещается в переменную, которую можно распечатать или изучить.

В этом примере извлекается двойник устройства и используется print команда для просмотра двойника устройства в формате JSON.

# get the twin
twin = await device_client.get_twin()
print("Twin document:")
print("{}".format(twin))

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

Вы можете применить исправление для обновления сообщаемого свойства устройства в формате JSON.

Чтобы применить исправление для обновления сообщаемого свойства, выполните указанные действия.

1. Назначьте исправление JSON для сообщаемого свойства переменной.
2. Вызовите patch_twin_reported_properties, чтобы применить исправление JSON к сообщаемым свойствам. Это синхронный вызов, то есть эта функция не возвращается, пока исправление не будет отправлено в службу и подтверждено.

Если patch_twin_reported_properties возвращает ошибку, эта функция генерирует соответствующую ошибку.

# create the reported properties patch
reported_properties = {"temperature": random.randint(320, 800) / 10}
print("Setting reported temperature to {}".format(reported_properties["temperature"]))
# update the reported properties and wait for the result
await device_client.patch_twin_reported_properties(reported_properties)

Вы также можете вызвать эти методы для обновления двойников устройств:

• Вызовите replace_twin для замены тегов устройства-двойника и желаемых свойств.
• Вызовите update_twin для обновления тегов двойника устройства и требуемых свойств.

Обработчик исправлений для входящих требуемых свойств

Вызовите on_twin_desired_properties_patch_received для создания функции обработчика или корутины, вызываемой при получении исправления свойств двойника. Обработчик принимает один аргумент, который является исправлением двойника в виде объекта словаря JSON.

В этом примере настраивается обработчик исправлений для требуемых свойств с именем twin_patch_handler.

Например:

try:
    # Set handlers on the client
    device_client.on_twin_desired_properties_patch_received = twin_patch_handler
except:
    # Clean up in the event of failure
    client.shutdown()

Получает twin_patch_handler и выводит обновления требуемого свойства JSON.

    # Define behavior for receiving twin desired property patches
    def twin_patch_handler(twin_patch):
        print("Twin patch received:")
        print(twin_patch)

Примеры устройств SDK

Пакет SDK Для Интернета вещей Azure для Python включает следующие примеры:

• get_twin — подключитесь к устройству и получите сведения о двойниках.
• update_twin_reported_properties — обновить сообщаемые свойства двойника.
• receive_twin_desired_properties — прием и обновление требуемых свойств.

Создание серверного приложения

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

В этом разделе описывается, как создать серверное приложение для:

• Обновление тегов двойников и требуемых свойств
• Выполняет запросы к устройствам с использованием фильтров по тегам и свойствам

Класс IoTHubRegistryManager предоставляет все методы, необходимые для создания серверного приложения для взаимодействия с двойниками устройств из службы.

Подключение к Центру Интернета вещей

Вы можете подключить серверную службу к Центр Интернета вещей с помощью следующих методов:

• Политика общего доступа
• Microsoft Entra

Подключение с помощью политики общего доступа

Подключитесь к Центру Интернета вещей с помощью from_connection_string. Приложению требуется разрешение на подключение службы для изменения требуемых свойств двойника устройства, и для запроса реестра требуется разрешение на чтение реестра. Политика общего доступа по умолчанию отсутствует, содержащая только эти два разрешения, поэтому необходимо создать его, если он еще не существует. Укажите строку подключения политики общего доступа в качестве параметра fromConnectionString. Дополнительные сведения о политиках общего доступа см. в статье "Управление доступом к Центр Интернета вещей с помощью подписанных URL-адресов".

Например:

import sys
from time import sleep
from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import Twin, TwinProperties, QuerySpecification, QueryResult

# Connect to IoT hub
IOTHUB_CONNECTION_STRING = "{IoT hub service connection string}"
iothub_registry_manager = IoTHubRegistryManager.from_connection_string(IOTHUB_CONNECTION_STRING)

Подключение с помощью Microsoft Entra

Приложение на стороне сервера, использующее Microsoft Entra, должно успешно пройти проверку подлинности и получить учетные данные токена безопасности перед подключением к центру Интернета вещей. Этот токен передаётся методу подключения к IoT-хабу. Общие сведения о настройке и использовании Microsoft Entra для Центр Интернета вещей см. в разделе "Управление доступом к Центр Интернета вещей с помощью идентификатора Microsoft Entra".

Общие сведения о проверке подлинности пакета SDK для Python см. в статье "Проверка подлинности приложений Python в службах Azure с помощью пакета SDK Azure для Python"

Настройка приложения Microsoft Entra

Необходимо настроить приложение Microsoft Entra для ваших предпочтительных учетных данных аутентификации. Приложение содержит такие параметры, как секрет клиента, используемый серверным приложением для проверки подлинности. Доступные конфигурации проверки подлинности приложений:

• Секрет клиента
• Сертификат
• Федеративные учетные данные

Приложения Microsoft Entra могут требовать определенные разрешения ролей в зависимости от выполняемых операций. Например, Сотрудник двойников IoT Hub требуется для предоставления доступа на чтение и запись к двойникам устройств и модулей IoT Hub. Дополнительные сведения см. в статье "Управление доступом к Центру Интернета вещей с использованием назначения ролей Azure RBAC".

Для получения дополнительной информации о настройке приложения Microsoft Entra см. краткое руководство: Регистрация приложения на платформе удостоверений Майкрософт.

Проверка подлинности с помощью DefaultAzureCredential

Самый простой способ аутентифицировать серверное приложение с помощью Microsoft Entra — это DefaultAzureCredential, но в рабочей среде рекомендуется использовать другой метод, включая определенный TokenCredential или упрощенный ChainedTokenCredential. Для простоты в этом разделе описывается аутентификация с использованием DefaultAzureCredential и клиентского секрета. Дополнительные сведения о преимуществах и недостатках использования DefaultAzureCredential см. в разделе "Цепочки учетных данных" в клиентской библиотеке удостоверений Azure для Python.

DefaultAzureCredential поддерживает различные механизмы проверки подлинности и определяет соответствующий тип учетных данных в зависимости от среды, в которой он выполняется. Он пытается использовать несколько типов учетных данных по очереди, пока не найдёт действующие учетные данные.

Для Microsoft Entra требуется этот пакет импорта и соответствующая import инструкция:

pip install azure-identity

from azure.identity import DefaultAzureCredential

В этом примере в переменные среды были добавлены секрет клиента, идентификатор клиента и идентификатор арендатора для регистрации приложений Microsoft Entra. Эти переменные среды используются DefaultAzureCredential для проверки подлинности приложения. Результат успешной проверки подлинности Microsoft Entra — это учетные данные токена безопасности, передаваемые методу подключения в концентратор Интернета вещей.

from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()

Результирующий AccessToken можно передать from_token_credential для подключения к Центру Интернета вещей для любого SDK клиента, который принимает учетные данные Microsoft Entra.

• IoTHubRegistryManager для создания подключения к службе для Центра Интернета вещей с помощью учетных данных маркера Entra.
• IoTHubJobManager
• DigitalTwinClient
• IoTHubHttpRuntimeManager
• IoTHubConfigurationManager

from_token_credential требуется два параметра:

• URL-адрес службы Azure— URL-адрес службы Azure должен находиться в формате {Your Entra domain URL}.azure-devices.net без https:// префикса. Например, MyAzureDomain.azure-devices.net.
• Токен учетных данных Azure

В этом примере учетные данные Azure получаются с помощью DefaultAzureCredential. Затем url-адрес службы Azure и учетные данные предоставляются для IoTHubRegistryManager.from_token_credential создания подключения к Центр Интернета вещей.

import sys
import os

from azure.identity import DefaultAzureCredential
from azure.iot.hub import IoTHubRegistryManager

# Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

# Set environment variables
os.environ['AZURE_CLIENT_SECRET'] = clientSecretValue
os.environ['AZURE_CLIENT_ID'] = clientID
os.environ['AZURE_TENANT_ID'] = tenantID

# Acquire a credential object
credential = DefaultAzureCredential()

# Use Entra to authorize IoT Hub service
print("Connecting to IoTHubRegistryManager...")
iothub_registry_manager = IoTHubRegistryManager.from_token_credential(
url="MyAzureDomain.azure-devices.net",
token_credential=credential)

Примеры кода

Рабочие примеры проверки подлинности службы Microsoft Entra см. в разделе "Библиотека проверки подлинности Майкрософт" (MSAL) для Python.

Обновление тегов двойников и требуемых свойств

Вы можете одновременно обновлять теги двойников устройств и требуемые свойства из серверного приложения с помощью update_twin.

1. Вызов get_twin для получения текущей версии двойника устройства
2. Используйте класс Twin для добавления тегов и свойств в формате JSON.
3. Вызов, update_twin чтобы применить исправление к двойнику устройства. Вы также можете использовать replace_twin для замены нужных свойств и тегов для двойника устройства.

В этом примере обновляется информация о тегах region и plant, а также задается желаемое свойство power_level с помощью 1.

new_tags = {
        'location' : {
            'region' : 'US',
            'plant' : 'Redmond43'
        }
    }

DEVICE_ID = "[Device Id]"
twin = iothub_registry_manager.get_twin(DEVICE_ID)
twin_patch = Twin(tags=new_tags, properties= TwinProperties(desired={'power_level' : 1}))
twin = iothub_registry_manager.update_twin(DEVICE_ID, twin_patch, twin.etag)

Создайте запрос двойника устройства

Сведения о двойниках устройств можно запрашивать с помощью запросов двойников устройств. Запросы двойников устройств — это запросы, такие как SQL, которые возвращают результирующий набор двойников устройств.

Чтобы использовать запрос двойника устройства, выполните следующие действия.

1. Используйте объект QuerySpecification для определения запроса, аналогичного SQL.

2. Используйте query_iot_hub для запроса к IoTHub и получения сведений о двойниках устройств с помощью спецификации запроса в стиле SQL.

В этом примере выполняется два запроса. Первый выбирает только двойники устройств, расположенных на Redmond43 заводе, а второй уточняет запрос, чтобы выбрать устройства, которые также подключены через сотовую сеть. Результаты печатаются после каждого запроса.

query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'")
query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
print("Devices in Redmond43 plant: {}".format(', '.join([twin.device_id for twin in query_result.items])))

print()

query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity = 'cellular'")
query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
print("Devices in Redmond43 plant using cellular network: {}".format(', '.join([twin.device_id for twin in query_result.items])))

print()

Пример службы SDK

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

• Требуется Node.js версии 10.0.x или более поздней

Обзор

В этой статье описывается, как использовать пакет SDK Azure IoT для Node.js для создания кода приложения для службы устройств и кода серверной службы для двойников устройств.

Создание приложения устройства

Приложения устройств могут считывать и записывать сообщаемые свойства двойника устройства и получать уведомления об изменениях желаемых свойств двойника устройства, заданных серверным приложением или IoT Hub.

В этом разделе описывается, как использовать пакет azure-iot-device в пакете SDK Для Интернета вещей Azure для Node.js для создания приложения для устройства:

• Получение двойника устройства и проверка сообщаемых свойств
• Обновление свойств двойника устройства
• Получение уведомления об изменениях требуемого свойства

Установка пакета SDK для устройств

Выполните следующую команду, чтобы установить пакет SDK для устройств Azure-iot-device на компьютере разработки:

npm install azure-iot-device --save

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

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

• Сертификат X.509
• Общий ключ доступа

Проверка подлинности с помощью сертификата X.509

Сертификат X.509 прикреплён к транспорту подключения устройства к Центру Интернета вещей.

Чтобы настроить подключение устройства к IoT-хабу с помощью сертификата X.509:

1. Вызовите fromConnectionString, чтобы добавить строку подключения для устройства или модуля идентификации и тип транспорта в объект Client. Добавьте x509=true в строку подключения, чтобы указать, что сертификат добавляется к DeviceClientOptions. Например:

   • Строка подключения устройства:

     HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true

   • Строка подключения модуля удостоверений:

     HostName=xxxxx.azure-devices.net;DeviceId=Device-1;ModuleId=Module-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true

2. Настройте переменную JSON с сведениями о сертификате и передайте ее в DeviceClientOptions.

3. Вызовите setOptions, чтобы добавить сертификат и ключ X.509 (и при необходимости парольную фразу) в транспорт клиента.

4. Вызовите open, чтобы открыть соединение от устройства к IoT Hub.

В этом примере показаны сведения о конфигурации сертификата в переменной JSON. Конфигурация сертификации clientOptions передается setOptions, и подключение открывается с помощью open.

const Client = require('azure-iot-device').Client;
const Protocol = require('azure-iot-device-mqtt').Mqtt;
// Connection string illustrated for demonstration only. Never hard-code the connection string in production. Instead use an environmental variable or other secure storage.
const connectionString = `HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true`
const client = Client.fromConnectionString(connectionString, Protocol);

var clientOptions = {
   cert: myX509Certificate,
   key: myX509Key,
   passphrase: passphrase,
   http: {
     receivePolicy: {
       interval: 10
     }
   }
 }

 client.setOptions(clientOptions);
 client.open(connectCallback);

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

• Проверка подлинности удостоверений с помощью сертификатов X.509
• Создание и отправка сертификатов для тестирования

Пример кода

Рабочий пример проверки подлинности сертификата X.509 см. в разделе "Простой пример устройства X.509".

Проверка подлинности с помощью общего ключа доступа

Пакет azure-iot-device содержит объекты, которые интерфейсирует с устройствами Интернета вещей. Класс Twin включает объекты, относящиеся к двойнику. В этом разделе описывается Client код класса, используемый для чтения и записи данных двойника устройства.

Выбор транспортного протокола

Объект Client поддерживает следующие протоколы:

• Amqp
• Http— При использовании Http, экземпляр Client нечасто проверяет наличие сообщений из IoT Hub (минимум раз в 25 минут).
• Mqtt
• MqttWs
• AmqpWs

Установите необходимые транспортные протоколы на компьютере разработки.

Например, эта команда устанавливает Mqtt протокол:

npm install azure-iot-device-mqtt --save

Дополнительные сведения о различиях между MQTT, AMQP и HTTPS см. в статьях Руководство по обмену данными между облаком и устройством и Выбор протокола связи.

Создание клиентского модуля

Client Создайте модуль с помощью установленного пакета.

Например:

const Client = require('azure-iot-device').Client;

Создание модуля протокола

Protocol Создайте модуль с помощью установленного транспортного пакета.

В этом примере назначается протокол MQTT:

const Protocol = require('azure-iot-device-mqtt').Mqtt;

Добавьте строку подключения устройства и транспортный протокол.

Вызов изConnectionString для предоставления параметров подключения устройства:

• connStr — строка подключения, которая инкапсулирует разрешения "подключение устройства" для Центра Интернета вещей. Строка подключения содержит имя узла, идентификатор устройства и общий ключ доступа в этом формате: "HostName=<iothub_host_name>; DeviceId=<device_id>; SharedAccessKey=<device_key>".
• transportCtor — транспортный протокол.

В этом примере используется транспортный Mqtt протокол:

const deviceConnectionString = "{IoT hub device connection string}"
const Protocol = require('azure-iot-device-mqtt').Mqtt;
let client = Client.fromConnectionString(deviceConnectionString, Protocol);

Откройте подключение к Центру интернета вещей

Используйте метод open, чтобы открыть подключение между устройством Интернета вещей и IoT Hub. Используйте .catch(err) для перехвата ошибки и выполнения кода обработчика.

Например:

client.open()  //open the connection
.catch((err) => {
  console.error('Could not connect: ' + err.message);
});

Получение двойника устройства и проверка сообщаемых свойств

Вызовите getTwin для получения текущей информации о двойнике устройства в объекте Twin.

Например:

client.getTwin(function(err, twin))
if (err)
    console.error('could not get twin');

Обновление свойств цифрового двойника устройства

Используйте обновление чтобы обновить сообщаемые свойства устройства. Включите исправление в формате JSON в качестве первого параметра и метода обратного вызова состояния выполнения функции в качестве второго параметра метода.

В этом примере исправление двойника устройства в формате JSON хранится в переменной patch. Исправление содержит обновление двойника устройства со значением cellularconnectivity. Обработчик исправлений и ошибок передается методу update . При возникновении ошибки отображается сообщение об ошибке консоли.

var patch = {
    connectivity: {
        type: 'cellular'
    }
}
twin.properties.reported.update(patch, function(err)
  {
    if (err)
      {
        console.error('could not update twin');
      } 
    else
      {
        console.log('twin state reported');
        process.exit();
      }
  });

Получение уведомления об изменениях требуемого свойства

Создайте слушатель событий обновления нужного свойства, который выполняется при его изменении на устройстве, передав имя метода обработчика обратного вызова в twin.on.

Прослушиватель событий требуемого свойства может принимать одну из следующих форм:

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

Получение всех исправлений с помощью одного обработчика событий

Вы можете создать прослушиватель для отслеживания изменений любого нужного свойства.

В этом примере код выводит все свойства, полученные от службы.

twin.on('properties.desired', function (delta) {
    console.log('new desired properties received:');
    console.log(JSON.stringify(delta));
});

Получите событие, если в группе свойств что-либо изменится.

Вы можете создать прослушиватель для получения события, если что-либо изменится в группе свойств.

Например:

1. minTemperature и maxTemperature свойства находятся в группе свойств под названием properties.desired.climate changes.

2. Приложение серверной службы применяет это исправление для обновления minTemperature и maxTemperature требуемых свойств:

   const twinPatch1 = {
   properties: {
      desired: {
       climate: { minTemperature: 68, maxTemperature: 76, },
       },
     },
    };
   

3. Этот код настраивает прослушиватель событий изменения требуемых свойств, вызывающий срабатывание при любых изменениях в группе свойств properties.desired.climate. Если в этой группе изменяется требуемое свойство, в консоли отображаются сообщения об изменении минимальной и максимальной температуры:

   twin.on('properties.desired.climate', function (delta) {
       if (delta.minTemperature || delta.maxTemperature) {
           console.log('updating desired temp:');
           console.log('min temp = ' + twin.properties.desired.climate.minTemperature);
           console.log('max temp = ' + twin.properties.desired.climate.maxTemperature);
       }
   });
   

Получение события для изменения единственного свойства

Вы можете настроить прослушиватель для изменения одного свойства. В этом примере код этого события выполняется только в том случае, если fanOn булево значение является частью исправления. Код выводит новое требуемое fanOn состояние всякий раз, когда служба обновляет ее.

1. Серверное приложение применяет это требуемое исправление свойства:

    const twinPatch2 = {
     properties: {
       desired: {
         climate: {
           hvac: {
             systemControl: { fanOn: true, },
           },
         },
       },
     },
   };
   

2. Прослушиватель активируется только при изменении свойства fanOn.

    twin.on('properties.desired.climate.hvac.systemControl', function (fanOn) {
        console.log('setting fan state to ' + fanOn);
     });
   

Примеры пакета SDK для устройств

Пакет SDK Для Интернета вещей Azure для Node.js содержит два примера двойников устройств:

• Простой пример двойника устройства

• Простой пример двойника устройства с SAS

Создание серверного приложения

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

В этом разделе описывается, как создать серверное приложение, которое:

• Извлекает и обновляет цифровой двойник устройства
• Создаёт запрос двойника устройства

Установка пакета SDK службы

Выполните следующую команду, чтобы установить azure-iothub на компьютере разработки:

npm install azure-iothub --save

Класс Registry предоставляет все методы, необходимые для взаимодействия с двойниками устройств из серверного приложения.

Подключение к Центру Интернета вещей

Вы можете подключить серверную службу к Центр Интернета вещей с помощью следующих методов:

• Политика общего доступа
• Microsoft Entra

Подключение с помощью политики общего доступа

Используйте fromConnectionString для подключения к Центру Интернета вещей. Вашему приложению требуется разрешение на соединение с службой для изменения требуемых свойств двойника устройства и разрешение на чтение реестра для запроса реестра идентификаций. Политика общего доступа по умолчанию отсутствует, содержащая только эти два разрешения, поэтому необходимо создать его, если он еще не существует. Укажите эту строку подключения политики общего доступа в качестве параметра fromConnectionString. Дополнительные сведения о политиках общего доступа см. в статье "Управление доступом к Центр Интернета вещей с помощью подписанных URL-адресов".

'use strict';
var iothub = require('azure-iothub');
var connectionString = '{Shared access policy connection string}';
var registry = iothub.Registry.fromConnectionString(connectionString);

Подключение с помощью Microsoft Entra

Серверное приложение, использующее Microsoft Entra, должно успешно аутентифицироваться и получить учетные данные токена безопасности перед подключением к IoT Hub. Этот токен передается методу подключения к IoT Хабу. Общие сведения о настройке и использовании Microsoft Entra для Центр Интернета вещей см. в разделе "Управление доступом к Центр Интернета вещей с помощью идентификатора Microsoft Entra".

Общие сведения о проверке подлинности пакета SDK для Node.js см. в следующих статье:

• Начало работы с проверкой подлинности пользователей в Azure
• Библиотека управления идентификацией Azure для JavaScript

Настройка приложения Microsoft Entra

Необходимо настроить приложение Microsoft Entra, настроенное для предпочитаемых учетных данных проверки подлинности. Приложение содержит такие параметры, как секрет клиента, используемый серверным приложением для проверки подлинности. Доступные конфигурации проверки подлинности приложений:

• Секрет клиента
• Сертификат
• Учетные данные федеративного удостоверения

Приложения Microsoft Entra могут требовать определенные разрешения ролей в зависимости от выполняемых операций. Например, Сотрудник двойников IoT Hub требуется для предоставления доступа на чтение и запись к двойникам устройства и модуля в IoT Hub. Дополнительные сведения см. в статье «Управление доступом к Центру Интернета вещей с помощью назначения ролей Azure RBAC».

Для получения дополнительной информации о настройке приложения Microsoft Entra см. Краткое руководство: Регистрация приложения с помощью платформы удостоверений Microsoft.

Проверка подлинности с помощью DefaultAzureCredential

Самый простой способ использовать Microsoft Entra для проверки подлинности серверного приложения — использовать DefaultAzureCredential, но в рабочей среде рекомендуется использовать другой метод, включая конкретные TokenCredential или оптимизированные ChainedTokenCredential. Для простоты в этом разделе описывается аутентификация с использованием DefaultAzureCredential и клиентского секрета. Дополнительные сведения о преимуществах и недостатках использования DefaultAzureCredential см. в разделе "Цепочки учетных данных" в клиентской библиотеке удостоверений Azure для JavaScript

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

Для Microsoft Entra требуется этот пакет:

npm install --save @azure/identity

В этом примере в переменные среды были добавлены секрет клиента регистрации приложения Microsoft Entra, идентификатор клиента и идентификатор арендатора. Эти переменные среды используются DefaultAzureCredential для проверки подлинности приложения. Результатом успешной проверки подлинности Microsoft Entra является учетный токен безопасности, который передается в метод подключения к Узлу Интернета вещей.

import { DefaultAzureCredential } from "@azure/identity";

// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();

Затем полученный токен учетных данных можно передать fromTokenCredential для подключения к центру Интернета вещей для любого клиента SDK, который принимает учетные данные Microsoft Entra.

• Реестр
• Клиент
• JobClient

fromTokenCredential требуется два параметра:

• URL-адрес службы Azure— URL-адрес службы Azure должен находиться в формате {Your Entra domain URL}.azure-devices.net без https:// префикса. Например, MyAzureDomain.azure-devices.net.
• Токен учетных данных Azure

В этом примере учетные данные Azure получаются с помощью DefaultAzureCredential. Для создания подключения к Центру Интернета вещей предоставляются URL-адрес домена Azure и учетные данные в Registry.fromTokenCredential.

const { DefaultAzureCredential } = require("@azure/identity");

let Registry = require('azure-iothub').Registry;

// Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

// Set environment variables
process.env['AZURE_CLIENT_SECRET'] = clientSecretValue;
process.env['AZURE_CLIENT_ID'] = clientID;
process.env['AZURE_TENANT_ID'] = tenantID;

// Acquire a credential object
const credential = new DefaultAzureCredential()

// Create an instance of the IoTHub registry
hostName = 'MyAzureDomain.azure-devices.net';
let registry = Registry.fromTokenCredential(hostName,credential);

Примеры кода

Для примеров аутентификации службы Microsoft Entra см. примеры использования удостоверений Azure.

Получение и обновление двойника устройства

Вы можете создать исправление, содержащее теги и необходимые обновления свойств для двойника устройства.

Чтобы обновить цифровой двойник устройства, выполните следующие действия.

1. Вызовите getTwin , чтобы получить объект двойника устройства.

• Отформатируйте патч, включающий обновление двойника устройства. Исправление отформатировано в формате JSON, как описано в классе Twin. Исправление серверной службы может содержать теги и необходимые обновления свойств. Для получения дополнительной информации о формате исправлений см. Формат тегов и свойств.

1. Вызовите функцию обновить для обновления двойника устройства посредством исправления.

В этом примере извлекается двойник устройства для myDeviceId, затем применяется исправление к двойникам, содержащим обновление тега location для region: 'US', plant: 'Redmond43'.

     registry.getTwin('myDeviceId', function(err, twin){
         if (err) {
             console.error(err.constructor.name + ': ' + err.message);
         } else {
             var patch = {
                 tags: {
                     location: {
                         region: 'US',
                         plant: 'Redmond43'
                   }
                 }
             };

             twin.update(patch, function(err) {
               if (err) {
                 console.error('Could not update twin: ' + err.constructor.name + ': ' + err.message);
               } else {
                 console.log(twin.deviceId + ' twin updated successfully');
                 queryTwins();
               }
             });
         }
     });

Создание запроса двойника устройства

Вы можете создавать запросы на устройства, подобные SQL, для сбора сведений из двойников устройств.

Используйте createQuery для создания запроса, который можно выполнить в экземпляре IoT хаба, чтобы найти сведения об устройствах или заданиях.

createQuery включает два параметра:

• sqlQuery — запрос, написанный как строка SQL.
• pageSize — требуемое количество результатов на страницу (необязательно. по умолчанию: 1000, максимум: 10000).

Если указан параметр pageSize, объект запроса содержит булевое свойство, которое можно проверить, и использовать метод nextAsTwin, чтобы получить следующую страницу результатов столько раз, сколько необходимо для получения всех результатов. Метод next доступен для результатов, которые не являются двойниками устройств, например, результаты агрегирования запросов.

В этом примере запроса выбираются только двойники устройств, расположенные на заводе Redmond43.

var queryTwins = function() {
var query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
query.nextAsTwin(function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        console.log("Devices in Redmond43: " + results.map(function(twin) {return twin.deviceId}).join(','));
    }
});

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

query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
query.nextAsTwin(function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        console.log("Devices in Redmond43 using cellular network: " + results.map(function(twin) {return twin.deviceId}).join(','));
    }
});
};

Пример пакета SDK службы

Пакет SDK для Интернета вещей Azure для Node.js предоставляет пример рабочего приложения службы, обрабатывающего задания двойника устройства. Дополнительные сведения см. в разделе "Серверная служба двойника устройства" — этот проект используется для отправки обновлений исправлений двойника устройства для конкретного устройства.