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

Статья
01/06/2025

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

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

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

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

Примечание.

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

Обзор

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

Объявление клиентского объекта устройства
Подключение к Центру Интернета вещей
Получение сообщений из очереди сообщений Центр Интернета вещей
Обработка сообщения и отправка подтверждения обратно в Центр Интернета вещей
Настройка политики повторных попыток получения сообщения

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

Объявление объекта клиента службы
Подключение к Центру Интернета вещей
Создание и отправка сообщения
Получение подтверждений доставки
Настройка политики повторных попыток отправки сообщения

Общие сведения о очереди сообщений

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

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

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

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

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

Отклонить сообщение, которое приводит к тому, что Центр Интернета вещей задать для него состояние "Мертвый". Устройства, подключающиеся через протокол транспорта телеметрии очереди сообщений (MQTT), не могут отклонять сообщения из облака на устройство.
Откложите сообщение, которое приводит к тому, что Центр Интернета вещей вернуть сообщение в очередь, при этом состояние сообщения задано как Enqueued. Устройства, подключающиеся через протокол MQTT, не могут отказаться от сообщений из облака на устройство.

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

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

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

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

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

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

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

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

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

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

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

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

Внимание

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

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

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

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

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

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

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

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

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

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

В этом примере сведения об устройстве и сертификате заполняются в объекте auth DeviceAuthenticationWithX509Certificate , передаваемом в 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 см. в статье:

Обратный вызов

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

С помощью обратного вызова приложение устройства настраивает метод обработчика сообщений с помощью 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) — получение сообщения из очереди устройства с помощью определенного времени ожидания.
ReceiveAsync (CancellationToken) — получение сообщения из очереди устройства с помощью маркера отмены. При использовании маркера отмены период времени ожидания по умолчанию не используется.

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

Метод CompleteAsync

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

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

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

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

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

Цикл опроса

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

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

При получении сообщения объект Task возвращается ReceiveAsync в 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

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

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

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

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

Добавление пакета NuGet службы

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

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

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

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

Внимание

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

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

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

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

В этом примере создается ServiceClient объект с помощью Центр Интернета вещей строка подключения и транспорта по умолчаниюAmqp.

static string connectionString = "{your IoT hub connection string}";
serviceClient = ServiceClient.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 см . в примере проверки подлинности на основе ролей.

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

Используйте 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();

Отправка сообщений с помощью параметра Ack

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

none (по умолчанию): сообщение обратной связи не создается.
Positive: получает сообщение обратной связи, если сообщение было завершено.
Negative: получает сообщение обратной связи, если сообщение истекло (или максимальное число доставки было достигнуто) без завершения устройством.
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);

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

CancellationTokenОпределение . Затем в цикле вызовите ReceiveAsync повторно, проверяя наличие сообщений обратной связи о доставке. Каждый вызов ожидает ReceiveAsync периода ожидания времени ожидания, определенного ServiceClient для объекта.

ReceiveAsync Если истекает время ожидания без получения сообщения, ReceiveAsync возвращается null и цикл продолжается.
Если сообщение обратной связи получено, объект Task возвращается ReceiveAsync в CompleteAsync вместе с маркером отмены. Вызов CompleteAsync для удаления указанного отправленного сообщения из очереди сообщений на Task основе параметра.
При необходимости код получения может вызвать AbandonAsync , чтобы отправить сообщение обратно в очередь.

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

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

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

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

Например:

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

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

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

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

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

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

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

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

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

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

Примеры кода

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

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

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

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

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

В этом примере callback метод с именем MessageCallback без параметра контекста передается setMessageCallbackв .

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 сообщение. Центр Интернета вещей повторно пересылает его и отправляет его снова позже.
- IotHubMessageResult.REJECT сообщение. Центр Интернета вещей не пересылает сообщение и окончательно удаляет сообщение из очереди сообщений.
Клиенты, использующие MQTT или не могутABANDON, или MQTT_WS REJECT сообщения.

Примечание.

Если в качестве транспорта вместо MQTT или AMQP используется HTTPS, экземпляр DeviceClient редко проверяет наличие сообщений от Центра Интернета вещей (не чаще, чем каждые 25 минут). Дополнительные сведения о различиях между MQTT, AMQP и HTTPS см. в статьях Руководство по обмену данными между облаком и устройством и Выбор протокола связи.

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

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

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

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

Обратный ConnectionStatusChangeContext вызов запускается и передается объект.

Вызов 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();

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

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

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

client.open(true);

Пример сообщения получения пакета SDK

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

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

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

Добавление инструкции зависимостей

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

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

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

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

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

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

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

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

Внимание

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

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

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

IotHubServiceClientProtocolпринимает только перечислениеAMQPS.AMQPS_WS

IotHubServiceClientProtocol protocol = IotHubServiceClientProtocol.AMQPS;

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

Создайте объект ServiceClient, предоставляя строка подключения и протокол Центра Iot.

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

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

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

serviceClient.open();

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примеры кода

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

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

Вы можете использовать ОтзывReceiver для отправки сообщений в Центр Интернета вещей обратной связи. A FeedbackReceiver — специализированный приемник, Receive метод которого возвращает FeedbackBatch вместо него Message.

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

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

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

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

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

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

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

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

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

Внимание

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

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

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

Например:

# 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

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

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

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

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

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

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

Создайте функцию обработчика сообщений для обработки входящих сообщений на устройство. Это будет назначено on_message_received (следующим шагом) в качестве обработчика обратного вызова.

В этом примере 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 присоединен к объекту IoTHubDeviceClient client . Объект 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

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

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

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

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

pip install azure-iot-hub

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

Добавьте следующий оператор import . IoTHubRegistryManager включает API для операций диспетчера реестра Центр Интернета вещей.

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

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

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

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

Azure.Core
Azure.Identity

using Azure.Core;
using Azure.Identity;

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

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

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

npm install azure-iot-device --save

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

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

Внимание

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

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

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

Вызовите 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
Настройте переменную JSON с сведениями о сертификате и передайте ее в DeviceClientOptions.
Вызов setOptions для добавления сертификата и ключа X.509 (при необходимости парольной фразы) в транспорт клиента.
Вызовите, чтобы открыть подключение с устройства, чтобы Центр Интернета вещей.

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

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

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

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

Amqp
Http— При использовании HttpClient экземпляр проверяет наличие сообщений из Центр Интернета вещей редко (как минимум каждые 25 минут).
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).
Отмена — чтобы отказаться от сообщения, Центр Интернета вещей немедленно пытается повторно отправить его. Центр Интернета вещей сохраняет сообщение в очереди устройств для будущего потребления. Метод принимает форму client.abandon(message, callback function).

MQTT

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

Попытки redelivery

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

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 уведомление Центр Интернета вещей о том, что он обработал сообщение и что его можно безопасно удалить из очереди устройства. Вызов complete не требуется, если вы используете транспорт MQTT и может быть опущен. Для транспорта AMQP или HTTPS требуется вызовcomplete .

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

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

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

В этом примере отображается сообщение об ошибке отключения в консоли.

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

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

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

Обработчик соединений
Обработчик ошибок
Обработчик отключения
Обработчик сообщений

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

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

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

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

Например:

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

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

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

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

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

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

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

Пакет Azure-iothub содержит объекты, которые интерфейсирует с Центр Интернета вещей. В этой статье описывается 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 для подключения к Центру Интернета вещей.

В этом примере serviceClient объект создается с типом Amqp транспорта.

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

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

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

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

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

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

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

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

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

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

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

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

Для 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.

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

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

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

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

Добавьте текст сообщения при создании экземпляра объекта сообщения. В этом примере 'Cloud to device message.' добавляется сообщение.

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

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

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

none (по умолчанию): сообщение обратной связи не создается.
sent: получает сообщение обратной связи, если сообщение было завершено.
: получает сообщение обратной связи, если сообщение истекло (или максимальное число доставки было достигнуто) без завершения устройством.
full: отзывы о отправленных и не отправленных результатах.

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

message.ack = 'full';

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

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

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

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

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

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 в консоль. В этом примере функция предоставляется в качестве параметра send функции, printResultFor описанной в следующем разделе.

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 — идентификатор устройства целевого устройства.
сообщение — текст сообщения для отправки на устройство.
Готово . Необязательная функция для вызова при завершении операции. Готово вызывается с двумя аргументами:
- Объект ошибки (может иметь значение 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 на устройство через Центр Интернета вещей.

Политика повторного подключения подключения подключения

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

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

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

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

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

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

Обзор

Общие сведения о очереди сообщений

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

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

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

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

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

Примеры кода

Обратный вызов

Опросы

Метод CompleteAsync

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

Цикл опроса

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

Пример сообщения получения пакета SDK

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

Добавление пакета NuGet службы

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

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

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

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

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

Пример кода

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

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

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

Отправка сообщений с помощью параметра Ack

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

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

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

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

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

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

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

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

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

Примеры кода

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

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

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

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

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

Пример сообщения получения пакета SDK

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

Добавление инструкции зависимостей

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

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

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

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

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

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

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

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

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

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

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

Примеры кода

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

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

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

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

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

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

Оператор импорта устройства

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

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

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

Примеры кода

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

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

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

Пример сообщения получения пакета SDK

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

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

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

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

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

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