Начало работы с идентификаторами модулей IoT Hub и их двойниками идентификаторов.

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

Обзор

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

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

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

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

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

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

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

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

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

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

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

При вызове CreateFromConnectionString без параметра транспорта используется транспорт AMQP по умолчанию.

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

static string ModuleConnectionString = "{Device module identity connection string}";
private static ModuleClient _moduleClient = null;

_moduleClient = ModuleClient.CreateFromConnectionString(ModuleConnectionString, null);

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

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

Пример демонстрирует извлечение и отображение свойств двойника идентификации модуля в формате JSON.

Console.WriteLine("Retrieving twin...");
Twin twin = await _moduleClient.GetTwinAsync();
Console.WriteLine("\tModule identity twin value received:");
Console.WriteLine(JsonConvert.SerializeObject(twin.Properties));

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

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

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 _moduleClient.UpdateReportedPropertiesAsync(reportedProperties);
}
catch (Exception ex)
{
   Console.WriteLine();
   Console.WriteLine("Error in sample: {0}", ex.Message);
}

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

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

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

await _moduleClient.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 _moduleClient.UpdateReportedPropertiesAsync(reportedProperties);
}

Пример модуля SDK

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

• TwinSample
• Тесты устройства клиента

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

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

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

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

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

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

using Microsoft.Azure.Devices;
using Microsoft.Azure.Devices.Shared;

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

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

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

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

Подключите серверное приложение к Центру Интернета вещей с помощью CreateFromConnectionString.

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

Например:

static RegistryManager registryManager;
static string connectionString = "{IoT hub 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. Дополнительные сведения см. в статье "Управление доступом к Центру Интернета Вещей с помощью назначения ролей 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 — это учетные данные маркера безопасности, передаваемые методу подключения Центр Интернета вещей.

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 можно передать в подключение к методу Центр Интернета вещей для любого клиента ПАКЕТА 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 см. Пример аутентификации на основе ролей.

Чтение и обновление идентификационных полей модуля

Вызовите GetModuleAsync , чтобы получить поля двойников удостоверений модуля в объект module .

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

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

Этот пример извлекает модуль в объект Module, обновляет свойство moduleLastActivityTime, а затем обновляет модуль в IoT Hub с помощью UpdateModuleAsync.

// Retrieve the module
var module = await registryManager.GetModuleAsync("myDeviceId","myModuleId");

// Update the module object
module.LastActivityTime = DateTime.Now;

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

Другой API модуля

• GetModulesOnDeviceAsync — извлекает идентификаторы модуля на устройстве
• RemoveModuleAsync — удаляет ранее зарегистрированный модуль с устройства

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

Пакет SDK для интернета вещей Azure для .NET предоставляет рабочий пример приложения-службы для обработки задач идентификационного двойника модуля. Дополнительные сведения см. в разделе "Тесты диспетчера реестра E2E".

• Рекомендуется использовать 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

Библиотека msrest используется для перехвата исключений HTTPOperationError.

pip install msrest

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

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

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

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

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

# import the device client library
import asyncio
from azure.iot.device.aio import IoTHubDeviceClient

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

Класс IoTHubModuleClient содержит методы для работы с твинами идентичности модуля.

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

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

# import the device client library
import asyncio
from azure.iot.device.aio import IoTHubDeviceClient

# substitute the device connection string in conn_str
# and add it to the IoTHubDeviceClient object
conn_str = "{Device module identity connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(conn_str)

# connect the application to the device
await device_client.connect()

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

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

В этом примере извлекается двойник устройства и используется 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 к сообщаемой свойствам.

Например:

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

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

Вызовите 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 IoT для Python предоставляет пример работающего приложения устройства, обрабатывающего задачи модульного идентификационного двойника.

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

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

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

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

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

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

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

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

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

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

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

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

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

Например:

# Connect to IoT hub
IOTHUB_CONNECTION_STRING = "{IoT hub shared access policy 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 см. Краткое руководство: регистрация приложения на платформе удостоверений Microsoft.

Проверка подлинности с помощью 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_module_twin.

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

1. Вызовите get_module_twin, чтобы получить текущую версию двойника идентификатора модуля.
2. Используйте класс Twin для добавления требуемых свойств в формате JSON.
3. Вызов, update_module_twin чтобы применить исправление к двойнику устройства. Вы также можете использовать replace_module_twin для замены необходимых свойств и меток для модуля-двойника.

В этом примере обновляется требуемое telemetryInterval свойство 122.

try:
    module_twin = iothub_registry_manager.get_module_twin(DEVICE_ID, MODULE_ID)
    print ( "" )
    print ( "Module identity twin properties before update:" )
    print ( "{0}".format(module_twin.properties) )

    # Update twin
    twin_patch = Twin()
    twin_patch.properties = TwinProperties(desired={"telemetryInterval": 122})
    updated_module_twin = iothub_registry_manager.update_module_twin(
        DEVICE_ID, MODULE_ID, twin_patch, module_twin.etag
    )
    print ( "" )
    print ( "Module identity twin properties after update     :" )
    print ( "{0}".format(updated_module_twin.properties) )

except Exception as ex:
    print ( "Unexpected error {0}".format(ex) )
except KeyboardInterrupt:
    print ( "IoTHubRegistryManager sample stopped" )

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

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

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

Обзор

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

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

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

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

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

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

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

npm install azure-iot-device --save

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

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

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

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

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

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

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

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

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

npm install azure-iot-device-amqp --save

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

Создание клиентского объекта

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

Например:

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

Создание объекта протокола

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

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

const Protocol = require('azure-iot-device-amqp').Amqp;

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

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

• connStr — строка подключения модуля идентификации центра IoT.
• transportCtor — транспортный протокол.

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

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

Откройте подключение к IoT Hub

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

Например:

client.open(function(err) {
  if (err) {
    console.error('error connecting to hub: ' + err);
    process.exit(1);
  }
})

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

Сертификат X.509 прикреплён к транспортному подключению устройства к IoT-хабу.

Чтобы настроить подключение устройства к 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, чтобы открыть подключение устройства к концентратору Интернета вещей.

В этом примере показаны сведения о конфигурации сертификата в переменной 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".

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

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

Затем код устройства может получить доступ к свойствам "двойника" идентификатора модуля.

Например:

// Retrieve the current module identity twin
client.getTwin(function(err, twin))
if (err)
    console.error('could not get twin');

// Display the current properties
console.log('twin contents:');
console.log(twin.properties);

Обновление сообщенных свойств идентификационного двойника модуля

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

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

// Create a patch to send to IoT Hub
var patch = {
  updateTime: new Date().toString(),
  firmwareVersion:'1.2.1',
  weather:{
    temperature: 72,
    humidity: 17
  }
};

// Apply the patch
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);
     });
   

Полный пример

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

var Client = require('azure-iot-device').Client;
var Protocol = require('azure-iot-device-amqp').Amqp;
// Copy/paste your module connection string here.
var connectionString = 'HostName=xxx.azure-devices.net;DeviceId=myFirstDevice2;ModuleId=myFirstModule2;SharedAccessKey=xxxxxxxxxxxxxxxxxx';
// Create a client using the Amqp protocol.
var client = Client.fromConnectionString(connectionString, Protocol);
client.on('error', function (err) {
  console.error(err.message);
});
// connect to the hub
client.open(function(err) {
  if (err) {
    console.error('error connecting to hub: ' + err);
    process.exit(1);
  }
  console.log('client opened');
// Create device Twin
  client.getTwin(function(err, twin) {
    if (err) {
      console.error('error getting twin: ' + err);
      process.exit(1);
    }
    // Output the current properties
    console.log('twin contents:');
    console.log(twin.properties);
    // Add a handler for desired property changes
    twin.on('properties.desired', function(delta) {
        console.log('new desired properties received:');
        console.log(JSON.stringify(delta));
    });
    // create a patch to send to the hub
    var patch = {
      updateTime: new Date().toString(),
      firmwareVersion:'1.2.1',
      weather:{
        temperature: 75,
        humidity: 20
      }
    };
    // send the patch
    twin.properties.reported.update(patch, function(err) {
      if (err) throw err;
      console.log('twin state reported');
    });

  });
});

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

Пакет SDK для интернета вещей Azure для Node.js предоставляет рабочие примеры приложений устройств, обрабатывающих задачи двойника идентификации модуля. Дополнительные сведения см. в разделе:

• Двойник идентификации модуля
• Вспомогательный помощник по тестированию модуля
• Тесты Twin e2e

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

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

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

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

npm install azure-iothub --save

Создание объекта Registry

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

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

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

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

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

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

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

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

let connectionString = '{IoT hub shared access policy connection string}';
let registry = Registry.fromConnectionString(serviceConnectionString);

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

Серверное приложение, использующее Microsoft Entra, должно успешно аутентифицироваться и получить токен безопасности перед подключением к IoT Hub. Этот токен передается методу подключения к IoT Hub. Общие сведения о настройке и использовании 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. Затем для создания подключения к IoT Hub предоставляются доменный URL-адрес Azure и учетные данные.

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. Вызовите getModuleTwin, чтобы получить объект Twin устройства.

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

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

В этом примере двойник удостоверения модуля извлекается для myDeviceId и myModuleId. Затем исправление применяется к двойникам, содержащим climate сведения.

// Insert your device ID and moduleId here.
var deviceId = 'myFirstDevice2';
var moduleId = 'myFirstModule2';

// Retrieve the current module identity twin
registry.getModuleTwin(deviceId, moduleId, function (err, twin) {
  console.log('getModuleTwin returned ' + (err ? err : 'success'));
  if (err) {
    console.log(err);
  } else {
    console.log('success');
    console.log('Current twin:' + JSON.stringify(twin))

    // Format a desired property patch
    const twinPatch1 = {
      properties: {
        desired: {
          climate: { minTemperature: 69, maxTemperature: 77, },
        },
      },
    };

    // Send the desired property patch to IoT Hub
    twin.update(twinPatch1, function(err) {
    if (err) throw err;
    console.log('twin state reported');
    });
  }
});

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

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

• Двойник идентификации модуля
• Вспомогательный помощник по тестированию модуля
• Тесты Twin e2e