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

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

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

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

• Обратный вызов: приложение устройства настраивает асинхронный метод обработчика сообщений, который вызывается немедленно при поступлении сообщения.
• Polling: The device application checks for new IoT Hub messages using a code loop (for example, a while or for loop). Цикл выполняется постоянно, проверяя наличие сообщений.

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

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

Add these using statements to use the device library.

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

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

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

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

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

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

Supply the IoT Hub primary connection string and Device ID to DeviceClient using the CreateFromConnectionString method. Помимо необходимой первичной строки подключения IoT Hub, метод CreateFromConnectionString можно перегрузить, чтобы включить следующие необязательные параметры:

• transportType — транспортный протокол: варианты HTTP версии 1, AMQP или MQTT. Значение по умолчанию — AMQP. Чтобы просмотреть все доступные значения, см. TransportType Enum.
• transportSettings — это интерфейс, используемый для определения различных настроек, специфичных для транспорта, применяемых к DeviceClient и ModuleClient. For more information, see ITransportSettings Interface.
• ClientOptions — Параметры, разрешающие настройку экземпляра клиента устройства или модуля во время инициализации.

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

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

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

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

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

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

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

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

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

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

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

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

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

Примеры кода

For working samples of device X.509 certificate authentication, see:

• Подключение к сертификату X.509
• DeviceClientX509AuthenticationE2ETests
• Guided project - Provision IoT devices securely and at scale with IoT Hub Device Provisioning Service

Callback

Чтобы получать сообщения из облака на устройство в приложении устройства, оно должно подключиться к Центру Интернета вещей и настроить прослушиватель обратного вызова для обработки входящих сообщений. Входящие сообщения на устройство поступают из очереди сообщений в IoT Hub.

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

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

• Mqtt
• Mqtt_WebSocket_Only
• Mqtt_Tcp_Only
• Amqp
• Amqp_WebSocket_Only
• Amqp_Tcp_only

Опция Http1 протокола не поддерживает обратные вызовы, так как методы SDK все равно должны будут опрашивать полученные сообщения, что нарушает принцип обратного вызова.

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

// Subscribe to receive C2D messages through a callback (which isn't supported over HTTP).
await deviceClient.SetReceiveMessageHandlerAsync(OnC2dMessageReceivedAsync, deviceClient);
Console.WriteLine($"\n{DateTime.Now}> Subscribed to receive C2D messages over callback.");

Опросы

Опрос использует ReceiveAsync для проверки сообщений.

Вызов ReceiveAsync может принимать следующие формы:

• ReceiveAsync() — дождитесь истечения времени ожидания по умолчанию для сообщения, прежде чем продолжить.
• ReceiveAsync (Timespan) - Receive a message from the device queue using a specific timeout.
• ReceiveAsync (CancellationToken) - Receive a message from the device queue using a cancellation token. При использовании маркера отмены период времени ожидания по умолчанию не используется.

При использовании типа транспорта HTTP 1 вместо MQTT или AMQP ReceiveAsync метод возвращается немедленно. Поддерживаемый шаблон для облачных сообщений к устройствам по протоколу HTTP 1 подходит для устройств, которые подключаются периодически и редко проверяют сообщения (как минимум каждые 25 минут). Отправка большего количества запросов HTTP 1 приводит к тому, что IoT Hub ограничивает их частоту. Дополнительные сведения о различиях между поддержкой MQTT, AMQP и HTTP 1 см. в разделах Руководство по обмену данными между облаком и устройством и Выбор протокола связи.

Метод CompleteAsync

После получения сообщения приложение устройства вызывает метод CompleteAsync, чтобы уведомить Центр Интернета вещей, что сообщение успешно обработано и что сообщение можно безопасно удалить из очереди устройств Центр Интернета вещей. Устройство должно вызывать этот метод, когда его обработка успешно завершается независимо от используемого транспортного протокола.

Отклонение сообщения, отказ или истечение времени ожидания

С протоколами AMQP и HTTP версии 1, но не протоколом MQTT, устройство также может:

• Отмена сообщения путем вызова AbandonAsync. Это приводит к тому, что Центр Интернета вещей сохраняет сообщение в очереди устройств для дальнейшего использования.
• Отклонить сообщение путем вызова RejectAsync. Это окончательно удаляет сообщение из очереди сообщений устройства.

Если по какой-либо причине устройство не сможет завершить обработку сообщения, отказаться от него или отклонить его, Центр Интернета вещей после фиксированного периода ожидания снова поместит сообщение в очередь для доставки. Поэтому логика обработки сообщений в приложении устройства должна быть идемпотентной. Это обеспечит одинаковый результат при многократном получении одного и того же сообщения.

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

Цикл опроса

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

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

When a message is received, a Task object is returned by ReceiveAsync that should be passed to CompleteAsync. Вызов метода CompleteAsync уведомляет Центр Интернета вещей удалить указанное сообщение из очереди сообщений на основании параметра Task.

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

static bool stopPolling = false;

while (!stopPolling)
{
   // Check for a message. Wait for the default DeviceClient timeout period.
   using Message receivedMessage = await _deviceClient.ReceiveAsync();

   // Continue if no message was received
   if (receivedMessage == null)
   {
      continue;
   }
   else  // A message was received
   {
      // Print the message received
      Console.WriteLine($"{DateTime.Now}> Polling using ReceiveAsync() - received message with Id={receivedMessage.MessageId}");
      PrintMessage(receivedMessage);

      // Notify IoT Hub that the message was received. IoT Hub will delete the message from the message queue.
      await _deviceClient.CompleteAsync(receivedMessage);
      Console.WriteLine($"{DateTime.Now}> Completed C2D message with Id={receivedMessage.MessageId}.");
   }

   // Check to see if polling loop should end
   stopPolling = ShouldPollingstop ();
}

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

Политику повтора сообщения клиента устройства можно определить с помощью DeviceClient.SetRetryPolicy.

Время ожидания повтора сообщения хранится в свойстве DeviceClient.OperationTimeoutInMilliseconds .

SDK receive message sample

Пакет SDK для .NET/C# содержит пример получения сообщений, включающий методы получения сообщений, описанные в этом разделе.

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

В этом разделе описывается важный код для отправки сообщения из серверного приложения решения на устройство Интернета вещей с помощью класса ServiceClient в пакете SDK Для Интернета вещей Azure для .NET. Как упоминалось ранее, серверное приложение решения подключается к Центр Интернета вещей и сообщения отправляются в Центр Интернета вещей закодированные с помощью целевого устройства. Центр Интернета вещей хранит входящие сообщения в очередь сообщений и сообщения доставляются из очереди сообщений Центр Интернета вещей на целевое устройство.

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

Add service NuGet Package

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

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

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

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

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

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

• transportType - Amqp или Amqp_WebSocket_Only.
• transportSettings — параметры прокси-сервера AMQP и HTTP для клиента службы.
• ServiceClientOptions — Параметры, разрешающие настройку экземпляра клиента службы во время инициализации. Дополнительные сведения см. в разделе ServiceClientOptions.

This example creates the ServiceClient object using the IoT Hub connection string and default Amqp transport.

static string connectionString = "{your IoT hub connection string}";
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);

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

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

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

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

• Секрет клиента
• Сертификат
• Federated identity credential

Приложения Microsoft Entra могут требовать определенные разрешения ролей в зависимости от выполняемых операций. For example, IoT Hub Twin Contributor is required to enable read and write access to a IoT Hub device and module twins. Дополнительные сведения см. в управлении доступом к Центру Интернета вещей с помощью назначения ролей Azure RBAC.

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

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

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

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

Microsoft Entra requires these NuGet packages and corresponding using statements:

• Azure.Core
• Azure.Identity

using Azure.Core;
using Azure.Identity;

В этом примере секрет клиента, идентификатор клиента и идентификатор арендатора из регистрации приложений Microsoft Entra добавляются в переменные среды. Эти переменные среды используются DefaultAzureCredential для проверки подлинности приложения. The result of a successful Microsoft Entra authentication is a security token credential that is passed to an IoT Hub connection method.

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

The resulting TokenCredential can then be passed to a connect to IoT Hub method for any SDK client that accepts Microsoft Entra credentials:

• 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 см. образец проверки подлинности на основе ролей.

Отправка асинхронного сообщения об использовании облака на устройство

Используйте sendAsync для отправки асинхронного сообщения из приложения через облако (Центр Интернета вещей) на устройство. Вызов выполняется с помощью протокола AMQP.

sendAsync использует следующие параметры:

• deviceID — строковый идентификатор целевого устройства.
• message — сообщение с облака на устройство. Сообщение имеет тип Message и может быть отформатировано соответствующим образом.
• timeout— необязательное значение времени ожидания. Значение по умолчанию составляет одну минуту, если не указано.

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

string targetDevice = "Device-1";
static readonly TimeSpan operationTimeout = TimeSpan.FromSeconds(10);
var commandMessage = new
Message(Encoding.ASCII.GetBytes("Cloud to device message."));
await serviceClient.SendAsync(targetDevice, commandMessage, operationTimeout);

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

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

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

• feedbackReceiver Создание объекта
• Отправка сообщений с помощью Ack параметра
• Ожидание получения отзывов

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

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

var feedbackReceiver = serviceClient.GetFeedbackReceiver();

Send messages using the Ack parameter

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

• none (по умолчанию): сообщение обратной связи не создается.

• Positive: получает сообщение обратной связи, если сообщение было завершено.

• Negative: receive a feedback message if the message expired (or maximum delivery count was reached) without being completed by the device.

• Full: обратная связь для обоих Positive и Negative результатов.

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

var commandMessage = new
Message(Encoding.ASCII.GetBytes("Cloud to device message."));
commandMessage.Ack = DeliveryAcknowledgement.Full;
await serviceClient.SendAsync(targetDevice, commandMessage);

Ожидание получения отзывов

Define a CancellationToken. Then in a loop, call ReceiveAsync repeatedly, checking for delivery feedback messages. Каждый вызов к ReceiveAsync ожидает завершения периода ожидания, установленного для объекта ServiceClient.

• ReceiveAsync Если истекает время ожидания без получения сообщения, ReceiveAsync возвращается null и цикл продолжается.
• If a feedback message is received, a Task object is returned by ReceiveAsync that should be passed to CompleteAsync along with the cancellation token. Вызов CompleteAsync удаляет указанное отправленное сообщение из очереди сообщений, основанный на параметре Task.
• If needed, the receive code can call AbandonAsync to put a send message back in the queue.

var feedbackReceiver = serviceClient.GetFeedbackReceiver();

// Define the cancellation token.
CancellationTokenSource source = new CancellationTokenSource();
CancellationToken token = source.Token;
// Call ReceiveAsync, passing the token. Wait for the timeout period.
var feedbackBatch = await feedbackReceiver.ReceiveAsync(token);
if (feedbackBatch == null) continue;

В этом примере показан метод, включающий эти шаги.

private async static void ReceiveFeedbackAsync()
{
      var feedbackReceiver = serviceClient.GetFeedbackReceiver();

      Console.WriteLine("\nReceiving c2d feedback from service");
      while (true)
      {
         // Check for messages, wait for the timeout period.
         var feedbackBatch = await feedbackReceiver.ReceiveAsync();
         // Continue the loop if null is received after a timeout.
         if (feedbackBatch == null) continue;

         Console.ForegroundColor = ConsoleColor.Yellow;
         Console.WriteLine("Received feedback: {0}",
            string.Join(", ", feedbackBatch.Records.Select(f => f.StatusCode)));
         Console.ResetColor();

         await feedbackReceiver.CompleteAsync(feedbackBatch);
      }
   }

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

Повторное подключение клиента службы

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

Например:

• Если это сетевое исключение, можно повторить операцию.
• Если это исключение безопасности (несанкционированное исключение), проверьте свои учетные данные и убедитесь, что они актуальны.
• If it is a throttling/quota exceeded exception, monitor and/or modify the frequency of sending requests, or update your hub instance scale unit. See IoT Hub quotas and throttling for details.

Политика повторных попыток отправки сообщения

ServiceClient Политика повторных попыток сообщения может быть определена с помощью ServiceClient.SetRetryPolicy.

Пример отправки сообщения с помощью SDK

Пакет SDK для .NET/C# содержит пример клиента службы, который включает методы отправки сообщений, описанные в этом разделе.

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

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

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

Импорт библиотек пакета SDK Java для Интернета вещей Azure

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

import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.exceptions.IotHubClientException;
import com.microsoft.azure.sdk.iot.device.transport.IotHubConnectionStatus;

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

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

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

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

Для создания экземпляра объекта DeviceClient требуются следующие параметры:

• connString — строка подключения устройства Интернета вещей. Строка подключения — это набор пар ключей и значений, разделенных точкой с запятой ';', где ключи и значения разделены знаком '='. Он должен содержать значения для этих ключей: HostName, DeviceId, and SharedAccessKey
• Транспортный протокол . Подключение DeviceClient может использовать один из следующих транспортных протоколов IoTHubClientProtocol . AMQP является наиболее универсальным, позволяет часто проверять сообщения и позволяет отклонять и отменять сообщения. MQTT не поддерживает отклонение сообщений или отказ от методов:
  • AMQPS
  • AMQPS_WS
  • HTTPS
  • MQTT
  • MQTT_WS

Например:

static string connectionString = "{IOT hub device connection string}";
static protocol = IotHubClientProtocol.AMQPS;
DeviceClient client = new DeviceClient(connectionString, protocol);

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

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

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

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

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

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

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

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

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

Примеры кода

For working samples of device X.509 certificate authentication, see:

• Send-receive x509 sample
• Отправка события x509

Установка метода обратного вызова сообщения

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

setMessageCallback включает следующие параметры:

• callback — имя метода обратного вызова. Может иметь значение null.
• context— необязательный контекст типаobject. Используйте null , если не указано.

В этом примере метод под названием callback, не имеющий параметра контекста, передается в MessageCallback.

client.setMessageCallback(new MessageCallback(), null);

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

Обработчик обратного вызова получает и обрабатывает входящее сообщение, переданное из очереди сообщений Центр Интернета вещей.

В этом примере обработчик сообщений обрабатывает входящее сообщение, а затем возвращает IotHubMessageResult.COMPLETE. Возвращаемое IotHubMessageResult.COMPLETE значение уведомляет Центр Интернета вещей, что сообщение успешно обработано и что сообщение можно безопасно удалить из очереди устройства. Устройство должно вернуться IotHubMessageResult.COMPLETE после успешной обработки, уведомляя Центр Интернета вещей, что сообщение должно быть удалено из очереди сообщений независимо от используемого протокола.

  protected static class MessageCallback implements com.microsoft.azure.sdk.iot.device.MessageCallback
  {
      public IotHubMessageResult onCloudToDeviceMessageReceived(Message msg, Object context)
      {
          System.out.println(
                  "Received message with content: " + new String(msg.getBytes(), Message.DEFAULT_IOTHUB_MESSAGE_CHARSET));
          // Notify IoT Hub that the message
          return IotHubMessageResult.COMPLETE;
      }
  }

Параметры прекращения и отклонения сообщений

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

• С помощью AMQP и HTTPS, но не MQTT, приложение может:
  • IotHubMessageResult.ABANDON the message. IoT hub requeues it and sends it again later.
  • IotHubMessageResult.REJECT the message. Центр Интернета вещей не пересылает сообщение и окончательно удаляет сообщение из очереди сообщений.
• Clients using MQTT or MQTT_WS cannot ABANDON or REJECT messages.

Если по какой-либо причине устройство не сможет завершить обработку сообщения, отказаться от него или отклонить его, Центр Интернета вещей после фиксированного периода ожидания снова поместит сообщение в очередь для доставки. Поэтому логика обработки сообщений в приложении устройства должна быть идемпотентной. Это обеспечит одинаковый результат при многократном получении одного и того же сообщения.

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

Создание метода обратного вызова состояния сообщения

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

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

client.registerConnectionStatusChangeCallback(new IotHubConnectionStatusChangeCallbackLogger(), new Object());

The callback is fired and passed a ConnectionStatusChangeContext object.

Вызов connectionStatusChangeContext.getNewStatus() для получения текущего состояния подключения.

IotHubConnectionStatus status = connectionStatusChangeContext.getNewStatus();

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

• IotHubConnectionStatus.DISCONNECTED
• IotHubConnectionStatus.DISCONNECTED_RETRYING
• IotHubConnectionStatus.CONNECTED

Позвоните по номеру connectionStatusChangeContext.getNewStatusReason(), чтобы узнать причину изменения состояния подключения.

IotHubConnectionStatusChangeReason statusChangeReason = connectionStatusChangeContext.getNewStatusReason();

Позвоните connectionStatusChangeContext.getCause(), чтобы узнать причину изменения статуса подключения. Если нет сведений, getCause() может вернуть null.

Throwable throwable = connectionStatusChangeContext.getCause();
if (throwable != null)
    throwable.printStackTrace();

See the HandleMessages sample listed in the SDK receive message sample section of this article for a complete sample showing how to extract the status change callback method connection status change status, reason why the device status changed, and context.

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

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

client.open(true);

SDK receive message sample

HandleMessages: пример приложения устройства, включенного в Microsoft Azure IoT SDK для Java, которое подключается к IoT-хабу и получает облачные сообщения для устройства.

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

В этом разделе описывается, как отправить сообщение об облаке на устройство с помощью класса ServiceClient из пакета SDK Интернета вещей Azure для Java. Серверное приложение решения подключается к центру Интернета вещей и сообщения отправляются в него, закодированные для конечного устройства. Центр Интернета вещей хранит входящие сообщения в очередь сообщений и сообщения доставляются из очереди сообщений Центр Интернета вещей на целевое устройство.

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

Add the dependency statement

Добавьте зависимость для использования пакета iothub-java-service-client в приложении для взаимодействия со службой Центра Интернета вещей:

<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-service-client</artifactId>
  <version>1.7.23</version>
</dependency>

Добавьте инструкции импорта

Добавьте эти инструкции импорта для использования Azure IoT Java SDK и обработчика исключений.

import com.microsoft.azure.sdk.iot.service.*;
import java.io.IOException;
import java.net.URISyntaxException;

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

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

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

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

Определение протокола подключения

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

IotHubServiceClientProtocol only accepts the AMQPS or AMQPS_WS enum.

IotHubServiceClientProtocol protocol = IotHubServiceClientProtocol.AMQPS;

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

Create the ServiceClient object, supplying the IoT Hub connection string and protocol.

String connectionString = "{yourhubconnectionstring}";
ServiceClient serviceClient (connectionString, protocol);

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

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

serviceClient.open();

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

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

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

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

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

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

• Секрет клиента
• Сертификат
• Federated identity credential

Приложения Microsoft Entra могут требовать определенные разрешения ролей в зависимости от выполняемых операций. For example, IoT Hub Twin Contributor is required to enable read and write access to a IoT Hub device and module twins. Дополнительные сведения см. в управлении доступом к Центру Интернета вещей с помощью назначения ролей Azure RBAC.

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

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

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

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

Вы можете аутентифицировать учетные данные приложения Microsoft Entra, используя DefaultAzureCredentialBuilder. Save connection parameters such as client secret tenantID, clientID, and client secret values as environmental variables. Once the TokenCredential is created, pass it to ServiceClient or other builder as the 'credential' parameter.

В этом примере DefaultAzureCredentialBuilder пытается выполнить проверку подлинности подключения из списка, описанного в defaultAzureCredential. The result of a successful Microsoft Entra authentication is a security token credential that is passed to a constructor such as ServiceClient.

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

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

С помощью ClientSecretCredentialBuilder можно создать учетные данные с помощью сведений о секрете клиента. If successful, this method returns a TokenCredential that can be passed to ServiceClient or other builder as the 'credential' parameter.

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

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

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

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

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

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

Примеры кода

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

Open a feedback receiver for message delivery feedback

You can use a FeedbackReceiver to get sent message delivery to IoT Hub feedback. FeedbackReceiver — это специализированный приемник, метод Receive которого возвращает FeedbackBatch вместо Message.

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

FeedbackReceiver feedbackReceiver = serviceClient
  .getFeedbackReceiver();
if (feedbackReceiver != null) feedbackReceiver.open();

Добавление свойств сообщения

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

Map<String, String> propertiesToSend = new HashMap<String, String>();
propertiesToSend.put(messagePropertyKey,messagePropertyKey);
messageToSend.setProperties(propertiesToSend);

Создание и отправка асинхронного сообщения

Объект Message сохраняет сообщение для отправки. In this example, a "Cloud to device message" is delivered.

Use setDeliveryAcknowledgement to request delivered/not delivered to IoT Hub message queue acknowledgment. In this example, the acknowledgment requested is Full, either delivered or not delivered.

Используйте SendAsync для отправки асинхронного сообщения от клиента на устройство. Кроме того, можно использовать Send метод (не асинхронный), но эта функция синхронизируется внутри системы, чтобы одновременно разрешалось только одна операция отправки. Сообщение доставляется из приложения в Центр Интернета вещей. Центр Интернета вещей помещает сообщение в очередь сообщений, готовую к доставке на целевое устройство.

Message messageToSend = new Message("Cloud to device message.");
messageToSend.setDeliveryAcknowledgementFinal(DeliveryAcknowledgement.Full);
serviceClient.sendAsync(deviceId, messageToSend);

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

После отправки сообщения из приложения приложение может вызвать receive со значением времени ожидания или без него. Если значение времени ожидания не задано, используется время ожидания по умолчанию. Это возвращает объект FeedbackBatch, содержащий свойства обратной связи о доставке сообщений, которые можно проверить.

This example creates the FeedbackBatch receiver and calls getEnqueuedTimeUtc, printing the message enqueued time.

FeedbackBatch feedbackBatch = feedbackReceiver.receive(10000);
if (feedbackBatch != null) {
  System.out.println("Message feedback received, feedback time: "
    + feedbackBatch.getEnqueuedTimeUtc().toString());
}

Примеры сообщений, отправляемых с помощью SDK

Существует два примера отправки сообщений:

• Пример клиента службы— пример отправки сообщения, #1.
• Пример клиента службы— пример отправки сообщения, #2.

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

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

Класс IoTHubDeviceClient включает методы для создания синхронного подключения с устройства на Центр Интернета вещей Azure и получения сообщений из Центр Интернета вещей.

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

pip install azure-iot-device

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

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

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

from azure.iot.device import IoTHubDeviceClient

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

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

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

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

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

1. Call create_from_connection_string to add the device primary connection string.
2. Используйте connect для подключения клиента устройства.

Например:

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

# Connect the client
device_client.connect()

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

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

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

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

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

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

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

x509 = X509(
    cert_file,
    key_file,
    pass_phrase,
)

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

# Connect to IoT Hub
await device_client.connect()

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

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

Примеры кода

For working samples of device X.509 certificate authentication, see the examples whose file names end in x509 at Async hub scenarios.

Handle reconnection

IoTHubDeviceClient по умолчанию попытается восстановить удаленное подключение. Поведение повторного подключения регулируется IoTHubDeviceClientconnection_retry и connection_retry_interval параметрами.

Создание обработчика сообщений

Создайте функцию обработчика сообщений для обработки входящих сообщений на устройство. This will be assigned by on_message_received (next step) as the callback message handler.

В этом примере message_handler вызывается при получении сообщения. Свойства сообщения (.items) выводятся на консоль с помощью цикла.

def message_handler(message):
    global RECEIVED_MESSAGES
    RECEIVED_MESSAGES += 1
    print("")
    print("Message received:")

    # print data from both system and application (custom) properties
    for property in vars(message).items():
        print ("    {}".format(property))

    print("Total calls received: {}".format(RECEIVED_MESSAGES))

Назначение обработчика сообщений

Используйте метод on_message_received для назначения метода обработчика сообщений.

В этом примере метод обработчика сообщений с именем message_handler присоединен к объекту IoTHubDeviceClientclient . Объект client ожидает получения сообщения из облака на устройство от узла Интернета вещей. Этот код ожидает сообщения в течение 300 секунд (5 минут) или завершает работу, если нажата клавиша клавиатуры.

try:
    # Attach the handler to the client
    client.on_message_received = message_handler

    while True:
        time.sleep(300)
except KeyboardInterrupt:
    print("IoT Hub C2D Messaging device sample stopped")
finally:
    # Graceful exit
    print("Shutting down IoT Hub Client")
    client.shutdown()

SDK receive message sample

Получение сообщения— получение сообщений из облака на устройство (C2D), отправляемых с Центр Интернета вещей Azure на устройство.

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

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

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

pip install azure-iot-hub

Импорт объекта IoTHubRegistryManager

Add the following import statement. IoTHubRegistryManager включает в себя API для операций диспетчера реестра Центра IoT.

from azure.iot.hub import IoTHubRegistryManager

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

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

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

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

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

Например:

IoTHubConnectionString = "{IoT hub service connection string}"
registry_manager = IoTHubRegistryManager.from_connection_string(IoTHubConnectionString)

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

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

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

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

• Секрет клиента
• Сертификат
• Federated identity credential

Приложения Microsoft Entra могут требовать определенные разрешения ролей в зависимости от выполняемых операций. For example, IoT Hub Twin Contributor is required to enable read and write access to a IoT Hub device and module twins. Дополнительные сведения см. в управлении доступом к Центру Интернета вещей с помощью назначения ролей Azure RBAC.

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

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

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

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

Microsoft Entra requires these NuGet packages and corresponding using statements:

• Azure.Core
• Azure.Identity

using Azure.Core;
using Azure.Identity;

В этом примере секрет клиента, идентификатор клиента и идентификатор арендатора из регистрации приложений Microsoft Entra добавляются в переменные среды. Эти переменные среды используются DefaultAzureCredential для проверки подлинности приложения. The result of a successful Microsoft Entra authentication is a security token credential that is passed to an IoT Hub connection method.

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

The resulting TokenCredential can then be passed to a connect to IoT Hub method for any SDK client that accepts Microsoft Entra credentials:

• 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 см. образец проверки подлинности на основе ролей.

Создание и отправка сообщения

Используйте send_c2d_message для отправки сообщения через облако (Центр Интернета вещей) на устройство.

send_c2d_message использует следующие параметры:

• deviceID — строковый идентификатор целевого устройства.
• message — сообщение с облака на устройство. Сообщение имеет тип str (строку).
• properties — необязательная коллекция свойств типаdict. Свойства могут содержать свойства приложения и системные свойства. Значение по умолчанию — {}.

В этом примере отправляется тестовое сообщение на целевое устройство.

# define the device ID
deviceID = "Device-1"

# define the message
message = "{\"c2d test message\"}"

# include optional properties
props={}
props.update(messageId = "message1")
props.update(prop1 = "test property-1")
props.update(prop1 = "test property-2")
prop_text = "Test message"
props.update(testProperty = prop_text)

# send the message through the cloud (IoT Hub) to the device
registry_manager.send_c2d_message(deviceID, message, properties=props)

Пример отправки сообщения с помощью SDK

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

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

В этом разделе описывается, как получать сообщения из облака на устройство с помощью пакета azure-iot-device в пакете AZURE IoT SDK для Node.js.

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

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

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

npm install azure-iot-device --save

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

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

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

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

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

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

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

   • A device connection string:

     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. Call setOptions to add an X.509 certificate and key (and optionally, passphrase) to the client transport.

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".

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

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

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

• Amqp
• Http - When using Http, the Client instance checks for messages from IoT Hub infrequently (a minimum of every 25 minutes).
• Mqtt
• MqttWs
• AmqpWs

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

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

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

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

В этом примере протокол AMQP назначается переменной Protocol . Эта переменная протокола передается методу Client.fromConnectionString в разделе «Добавление строки подключения» этой статьи.

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

Возможности завершения, отклонения и прекращения сообщений.

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

AMQP и HTTP

Транспорты AMQP и HTTP могут завершить, отклонить или отказаться от сообщения:

• Завершено . Чтобы завершить сообщение, служба, отправляющая сообщение об облаке на устройство, уведомляется о получении сообщения. Центр Интернета вещей удаляет сообщение из очереди сообщений. Метод принимает форму client.complete(message, callback function).
• Отклонить сообщение. Чтобы отклонить сообщение, служба, отправляющая сообщение об облаке на устройство, уведомляется о том, что сообщение не обрабатывается устройством. Центр Интернета вещей окончательно удаляет сообщение из очереди устройства. Метод принимает форму client.reject(message, callback function).
• Отказ — при отказе от сообщения IoT Hub немедленно пытается отправить его повторно. Центр Интернета вещей сохраняет сообщение в очереди устройств для будущего потребления. Метод принимает форму client.abandon(message, callback function).

MQTT

MQTT не поддерживает функции завершения, отклонения или отказа обработки сообщений. Вместо этого MQTT принимает сообщение по умолчанию, и сообщение удаляется из очереди сообщений Центр Интернета вещей.

Попытки повторной доставки

Если по какой-либо причине устройство не сможет завершить обработку сообщения, отказаться от него или отклонить его, Центр Интернета вещей после фиксированного периода ожидания снова поместит сообщение в очередь для доставки. Поэтому логика обработки сообщений в приложении устройства должна быть идемпотентной. Это обеспечит одинаковый результат при многократном получении одного и того же сообщения.

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

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 device connection string}"
const Protocol = require('azure-iot-device-mqtt').Amqp;
let client = Client.fromConnectionString(deviceConnectionString, Protocol);

Создание обработчика входящих сообщений

Обработчик сообщений вызывается для каждого входящего сообщения.

После успешного получения сообщения при использовании транспорта AMQP или HTTP вызовите client.complete метод, чтобы сообщить Центр Интернета вещей, что сообщение можно удалить из очереди сообщений.

Например, этот обработчик сообщений выводит идентификатор сообщения и текст сообщения в консоль, а затем вызывает client.complete, чтобы уведомить Центр Интернета вещей о том, что он обработал сообщение и что его можно безопасно удалить из очереди устройства. The call to complete isn't required if you're using MQTT transport and can be omitted. A call tocomplete is required for AMQP or HTTPS transport.

function messageHandler(msg) {
  console.log('Id: ' + msg.messageId + ' Body: ' + msg.data);
  client.complete(msg, printResultFor('completed'));
}

Создание обработчика отключения подключения

Обработчик отключения вызывается при отключении подключения. Обработчик отключения полезен для реализации кода повторного подключения.

This example catches and displays the disconnect error message to the console.

function disconnectHandler() {
  clearInterval(sendInterval);
  sendInterval = null;
  client.open().catch((err) => {
    console.error(err.message);
  });
}

Добавление прослушивателей событий

Эти прослушиватели событий можно указать с помощью метода .on .

• Обработчик соединений
• Обработчик ошибок
• Disconnect handler
• Обработчик сообщений

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

client.on('connect', connectHandler);
client.on('error', errorHandler);
client.on('disconnect', disconnectHandler);
client.on('message', messageHandler);

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

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

Например:

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

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

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

simple_sample_device — приложение устройства, которое подключается к центру Интернета вещей и получает сообщения из облака на устройство.

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

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

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

Install service SDK package

Пакет azure-iothub содержит объекты, которые взаимодействуют с IoT Hub. В этой статье описывается Client код класса, который отправляет сообщение из приложения на устройство через Центр Интернета вещей.

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

npm install azure-iothub --save

Загрузка модулей клиента и сообщений

Объявите Client объект с помощью Client класса из azure-iothub пакета.

Объявите Message объект с помощью Message класса из azure-iot-common пакета.

'use strict';
var Client = require('azure-iothub').Client;
var Message = require('azure-iot-common').Message;

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

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

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

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

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

In this example, the serviceClient object is created with the Amqp transport type.

var connectionString = '{IoT hub device connection string}';
var serviceClient = Client.fromConnectionString(connectionString,`Amqp`);

Открытие подключения клиента

Вызовите метод Clientopen, чтобы открыть соединение между приложением и IoT Hub.

open можно вызывать с или без указания функции обратного вызова, вызываемой при open завершении операции.

В этом примере метод open включает необязательную функцию обратного вызова для открытия подключения err. При возникновении открытой ошибки возвращается объект ошибки. If the open connection is successful, a null callback value is returned.

serviceClient.open(function (err)
if (err)
  console.error('Could not connect: ' + err.message);

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

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

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

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

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

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

• Секрет клиента
• Сертификат
• Federated identity credential

Приложения Microsoft Entra могут требовать определенные разрешения ролей в зависимости от выполняемых операций. For example, IoT Hub Twin Contributor is required to enable read and write access to a IoT Hub device and module twins. Дополнительные сведения см. в управлении доступом к Центру Интернета вещей с помощью назначения ролей Azure RBAC.

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

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

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

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

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

npm install --save @azure/identity

В этом примере в переменные среды были добавлены клиентский секрет для регистрации приложения Microsoft Entra, идентификатор клиента и идентификатор клиента. Эти переменные среды используются DefaultAzureCredential для проверки подлинности приложения. The result of a successful Microsoft Entra authentication is a security token credential that is passed to an IoT Hub connection method.

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

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

The resulting credential token can then be passed to fromTokenCredential to connect to IoT Hub for any SDK client that accepts Microsoft Entra credentials:

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

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

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

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

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.

Создание сообщения

Объект сообщения включает асинхронное сообщение из облака на устройство. Функциональность передачи сообщений работает одинаково через AMQP, MQTT и HTTP.

Объект сообщения поддерживает несколько свойств, включая эти свойства. См. свойства сообщения для полного списка.

• ack — Отзывы о доставке. Описано в следующем разделе.
• properties — карта, содержащая строковые ключи и значения для хранения настраиваемых свойств сообщения.
• messageId — используется для корреляции двустороннего взаимодействия.

Add the message body when the message object is instantiated. В этом примере добавляется сообщение 'Cloud to device message.'.

var message = new Message('Cloud to device message.');
message.ack = 'full';
message.messageId = "My Message ID";

Подтверждение доставки

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

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

• none (по умолчанию): сообщение обратной связи не создается.

• sent: получает сообщение обратной связи, если сообщение было завершено.

• : receive a feedback message if the message expired (or maximum delivery count was reached) without being completed by the device.

• full: отзывы о отправленных и не отправленных результатах.

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

message.ack = 'full';

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

Функция обратного вызова получателя сообщений связана с Client с помощью getFeedbackReceiver.

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

• Объект ошибки (может иметь значение NULL)
• Объект AmqpReceiver — выдает события при получении клиентом новых сообщений обратной связи.

This example function receives and prints a delivery feedback message to the console.

function receiveFeedback(err, receiver){
  receiver.on('message', function (msg) {
    console.log('Feedback message:')
    console.log(msg.getData().toString('utf-8'));
  });
}

Этот код связывает receiveFeedback функцию обратной связи с объектом сервиса Client с помощью getFeedbackReceiver.

serviceClient.getFeedbackReceiver(receiveFeedback);

Определение обработчика результатов завершения сообщения

Функция обратного вызова, сигнализирующая об окончании отправки сообщения, вызывается после отправки каждого сообщения.

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

function printResultFor(op) {
  return function printResult(err, res) {
    if (err) console.log(op + ' error: ' + err.toString());
    if (res) console.log(op + ' status: ' + res.constructor.name);
  };
}

Отправка сообщений

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

send поддерживает следующие параметры:

• deviceID — идентификатор устройства целевого устройства.
• сообщение — текст сообщения для отправки на устройство.
• Готово . Необязательная функция для вызова при завершении операции. Функция Done вызывается с двумя аргументами:
  • Объект ошибки (может иметь значение NULL).
  • Объект ответа, специфичный для транспорта, полезный для журналирования или отладки.

Этот код вызывает send отправку сообщения из облака на устройство через Центр Интернета вещей. Функция обратного вызова printResultFor , определенная в предыдущем разделе, получает сведения о подтверждении доставки.

var targetDevice = '{device ID}';
serviceClient.send(targetDevice, message, printResultFor('send'));

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

serviceClient.open(function (err) {
  if (err) {
    console.error('Could not connect: ' + err.message);
  } else {
    console.log('Service client connected');
    serviceClient.getFeedbackReceiver(receiveFeedback);
    var message = new Message('Cloud to device message.');
    message.ack = 'full';
    message.messageId = "My Message ID";
    console.log('Sending message: ' + message.getData());
    serviceClient.send(targetDevice, message, printResultFor('send'));
  }
});

Пример отправки сообщения с помощью SDK

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

send_c2d_message.js — отправка сообщений C2D на устройство через Центр Интернета вещей.