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

Начало работы с удостоверениями модулей Центр Интернета вещей и двойниками удостоверений модуля

  • Статья

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

Примечание.

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

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

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

Примечание.

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

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

  • Центр Интернета вещей.

  • Устройство Центра Интернета вещей

  • Удостоверение модуля устройства Центра Интернета вещей

  • Если приложение использует протокол MQTT, убедитесь, что порт 8883 открыт в брандмауэре. Протокол MQTT взаимодействует через порт 8883. В некоторых корпоративных и академических сетях этот порт может быть заблокирован. Дополнительные сведения и способы устранения этой проблемы см. в разделе о подключении к Центру Интернета вещей по протоколу MQTT.

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

Обзор

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

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

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

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

Внимание

В этой статье содержатся шаги по подключению устройства с помощью подписанного URL-адреса, также называемого проверкой подлинности симметричного ключа. Этот метод проверки подлинности удобнее для тестирования и оценки, но проверка подлинности устройства с помощью сертификатов X.509 является более безопасным подходом. Дополнительные сведения см. в разделе "Рекомендации > по обеспечению безопасности подключений".

Обязательный пакет 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);

Примечание.

C#/.NET не поддерживает подключение приложения устройства к двойнику удостоверения модуля Центр Интернета вещей с помощью сертификата.

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

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

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

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

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

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

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

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

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

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

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

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

Внимание

В этой статье содержатся шаги по подключению к службе с помощью подписанного URL-адреса. Этот метод проверки подлинности удобнее для тестирования и оценки, но проверка подлинности в службе с помощью идентификатора Microsoft Entra или управляемых удостоверений является более безопасным подходом. Дополнительные сведения см. в статье "Рекомендации > по безопасности cloud security".

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

Подключите серверное приложение к Центру Интернета вещей с помощью 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, должно успешно пройти проверку подлинности и получить учетные данные маркера безопасности перед подключением к Центр Интернета вещей. Этот маркер передается методу подключения Центр Интернета вещей. Общие сведения о настройке и использовании Microsoft Entra для Центр Интернета вещей см. в разделе "Управление доступом к Центр Интернета вещей с помощью идентификатора Microsoft Entra".

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

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

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

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

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

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

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

Обзор

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

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

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

pip install azure-iot-device

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

pip install azure-iot-hub

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

pip install msrest

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

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

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

Внимание

В этой статье содержатся шаги по подключению устройства с помощью подписанного URL-адреса, также называемого проверкой подлинности симметричного ключа. Этот метод проверки подлинности удобнее для тестирования и оценки, но проверка подлинности устройства с помощью сертификатов X.509 является более безопасным подходом. Дополнительные сведения см. в разделе "Рекомендации > по обеспечению безопасности подключений".

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

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

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

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

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

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

  1. Вызов create_from_connection_string для добавления удостоверения модуля строка подключения
  2. Вызов подключения для подключения клиента устройства к Центру Интернета вещей Azure
# 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()

Примечание.

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

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

Вызовите 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 для 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

Внимание

В этой статье содержатся шаги по подключению к службе с помощью подписанного URL-адреса. Этот метод проверки подлинности удобнее для тестирования и оценки, но проверка подлинности в службе с помощью идентификатора Microsoft Entra или управляемых удостоверений является более безопасным подходом. Дополнительные сведения см. в статье "Рекомендации > по безопасности cloud security".

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

Подключитесь к Центру Интернета вещей с помощью 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, должно успешно пройти проверку подлинности и получить учетные данные маркера безопасности перед подключением к Центр Интернета вещей. Этот маркер передается методу подключения Центр Интернета вещей. Общие сведения о настройке и использовании Microsoft Entra для Центр Интернета вещей см. в разделе "Управление доступом к Центр Интернета вещей с помощью идентификатора Microsoft Entra".

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

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

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

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

Приложения Microsoft Entra могут требовать определенные разрешения ролей в зависимости от выполняемых операций. Например, Центр Интернета вещей участник двойников требуется для включения доступа на чтение и запись к двойникам устройства и модуля Центр Интернета вещей. Дополнительные сведения см. в статье "Управление доступом к Центр Интернета вещей с помощью назначения ролей 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:

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 или более поздней

Обзор

В этой статье описывается, как использовать пакет SDK Для Интернета вещей Azure для 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

Внимание

В этой статье содержатся шаги по подключению устройства с помощью подписанного URL-адреса, также называемого проверкой подлинности симметричного ключа. Этот метод проверки подлинности удобнее для тестирования и оценки, но проверка подлинности устройства с помощью сертификатов X.509 является более безопасным подходом. Дополнительные сведения см. в разделе "Рекомендации > по обеспечению безопасности подключений".

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

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

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

  • Amqp
  • Http— При использовании HttpClient экземпляр проверяет наличие сообщений из Центр Интернета вещей редко (как минимум каждые 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 — модуль удостоверений Центра Интернета вещей строка подключения.
  • transportCtor — транспортный протокол.

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

const deviceConnectionString = "{IoT hub identity module connection string}"
const Protocol = require('azure-iot-device-mqtt').Amqp;
let client = Client.fromConnectionString(deviceConnectionString, Protocol);
Открытие подключения к Центр Интернета вещей

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

Например:

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

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

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

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

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

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

Вызовите 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 . Исправление содержит значение cellularобновления двойника connectivity удостоверения модуля. Обработчик исправлений и ошибок передается методу 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. maxTemperature Свойства minTemperature находятся под группированием свойств с именем 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 предоставляет рабочие примеры приложений устройств, обрабатывающих задачи двойника удостоверений модуля. Дополнительные сведения см. в разделе:

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

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

Установка пакета ПАКЕТА SDK службы

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

npm install azure-iothub --save

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

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

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

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

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

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

Внимание

В этой статье содержатся шаги по подключению к службе с помощью подписанного URL-адреса. Этот метод проверки подлинности удобнее для тестирования и оценки, но проверка подлинности в службе с помощью идентификатора Microsoft Entra или управляемых удостоверений является более безопасным подходом. Дополнительные сведения см. в статье "Рекомендации > по безопасности cloud security".

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

Используйте 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, должно успешно пройти проверку подлинности и получить учетные данные маркера безопасности перед подключением к Центр Интернета вещей. Этот маркер передается методу подключения Центр Интернета вещей. Общие сведения о настройке и использовании Microsoft Entra для Центр Интернета вещей см. в разделе "Управление доступом к Центр Интернета вещей с помощью идентификатора Microsoft Entra".

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

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

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

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

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

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

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

Затем полученный маркер учетных данных можно передать изTokenCredential для подключения к Центр Интернета вещей для любого клиента ПАКЕТА SDK, который принимает учетные данные Microsoft Entra:

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

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

В этом примере учетные данные Azure получаются с помощью DefaultAzureCredential. Затем для создания подключения к Центр Интернета вещей предоставляется Registry.fromTokenCredential 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. Вызов обновления для обновления двойника удостоверения модуля с помощью исправления.

В этом примере двойник удостоверения модуля извлекается и myDeviceIdmyModuleId. Затем исправление применяется к двойникам, содержащим 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 предоставляет рабочие примеры приложений служб, обрабатывающих задачи двойника удостоверения модуля. Дополнительные сведения см. в разделе: