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

Мақала
11/06/2024

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

Двойники устройств можно использовать для:

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

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

Примечание.

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

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

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

Примечание.

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

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

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

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

Чтобы создать политику общего доступа, которая предоставляет разрешения service connect и registry read, и получить строку подключения для этой политики, выполните следующие действия.
1. На портале Azure выберите "Группы ресурсов". Выберите группу ресурсов, в которой находится центр, а затем выберите центр из списка ресурсов.
2. В левой части центра выберите Политики общего доступа.
3. В верхнем меню над списком политик выберите Добавить политику общего доступа.
4. В области "Добавление политики общего доступа" справа введите описательное имя политики, например serviceAndRegistryRead. В разделе Разрешения выберите Чтение реестра и Подключение службы, а затем нажмите кнопку Добавить.
5. Выберите новую политику из списка политик.
6. Выберите значок копирования рядом с пунктом Первичная строка подключения и сохраните значение.
Дополнительные сведения о политиках и разрешениях общего доступа Центр Интернета вещей см. в статье "Управление доступом к Центр Интернета вещей с помощью подписанных URL-адресов".
Если приложение использует протокол MQTT, убедитесь, что порт 8883 открыт в брандмауэре. Протокол MQTT взаимодействует через порт 8883. В некоторых корпоративных и академических сетях этот порт может быть заблокирован. Дополнительные сведения и способы устранения этой проблемы см. в разделе о подключении к Центру Интернета вещей по протоколу MQTT.
Требования к языковому пакету SDK:
- Пакет SDK для .NET . Требуется Visual Studio.
- Рекомендуется использовать пакет SDK - Для Python версии 3.7 или более поздней версии. Обязательно используйте 32-разрядную или 64-разрядную версию установки согласно требованиям программы настройки. При появлении запроса во время установки обязательно добавьте Python в переменную среды соответствующей платформы.
- Java — требуется пакет разработки Java SE 8. Убедитесь, что вы выбрали Java 8 в разделе долгосрочной поддержки , чтобы перейти к скачиванию для JDK 8.
- Node.js — требуется Node.js версии 10.0.x или более поздней.

Обзор

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

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

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

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

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

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

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

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

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

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

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

Mqtt
Mqtt_WebSocket_Only
Mqtt_Tcp_Only
Amqp
Amqp_WebSocket_Only
Amqp_Tcp_Only

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

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

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

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

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

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

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

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

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

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

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

Например:

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

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

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

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

await _deviceClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

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

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

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

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

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

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

   await _deviceClient.UpdateReportedPropertiesAsync(reportedProperties);
}

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

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

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

Серверное приложение:

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

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

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

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

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

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

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

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

using Microsoft.Azure.Devices;
static RegistryManager registryManager;
static string connectionString = "{IoT hub service connection string}";
registryManager = RegistryManager.CreateFromConnectionString(connectionString);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

var query = registryManager.CreateQuery(
"SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
var twinsInRedmond43 = await query.GetNextAsTwinAsync();
Console.WriteLine("Devices in Redmond43: {0}", 
string.Join(", ", twinsInRedmond43.Select(t => t.DeviceId)));

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

query = registryManager.CreateQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
var twinsInRedmond43UsingCellular = await query.GetNextAsTwinAsync();
Console.WriteLine("Devices in Redmond43 using cellular network: {0}", 
string.Join(", ", twinsInRedmond43UsingCellular.Select(t => t.DeviceId)));

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

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

Обзор

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

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

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

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

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

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

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

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

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

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

Используйте IotHubClientProtocol для выбора протокола транспорта. Например:
```
IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
```
DeviceClient Используйте конструктор для добавления основного строка подключения устройства и протокола.
```
String connString = "{IoT hub device connection string}";
DeviceClient client = new DeviceClient(connString, protocol);
```
Используйте открытую для подключения устройства к Центру Интернета вещей. Если клиент уже открыт, метод ничего не делает.
```
client.open(true);
```

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

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

Например:

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

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

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

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

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

Например:

TwinCollection reportedProperties = twin.getReportedProperties();

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Создайте объект DeviceTwinClientOptions. Задайте все параметры, необходимые для приложения. Эти параметры передаются объекту DeviceTwin .
Используйте конструктор DeviceTwin для создания подключения к Центру Интернета вещей. Объект DeviceTwin обрабатывает обмен данными с центром Интернета вещей. В качестве параметров укажите службу Центр Интернета вещей строка подключения, созданную в разделе предварительных требований и объектеDeviceTwinClientOptions.
Объект DeviceTwinDevice представляет двойник устройства со своими свойствами и тегами.

Например:

public static final String iotHubConnectionString = "{IoT hub service connection string}";
public static final String deviceId = "myDeviceId";
public static final String region = "US";
public static final String plant = "Redmond43";

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

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

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

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

В этом примере извлекаются и печатаются поля двойника устройства:
```
// Get the device twin from IoT Hub
System.out.println("Device twin before update:");
twinClient.getTwin(device);
System.out.println(device);
```
HashSet Использование объекта для add группы пар тегов двойников
Добавление группы пар тегов из tags объекта в DeviceTwinDevice объект с помощью setTags

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

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

// Update device twin tags if they are different
// from the existing values
String currentTags = device.tagsToString();
if ((!currentTags.contains("region=" + region) && !currentTags.contains("plant=" + plant))) {

// Create the tags and attach them to the DeviceTwinDevice object
Set<Pair> tags = new HashSet<Pair>();
tags.add(new Pair("region", region));
tags.add(new Pair("plant", plant));
device.setTags(tags);

// Update the device twin in IoT Hub
System.out.println("Updating device twin");
twinClient.updateTwin(device);
}

// Retrieve and display the device twin with the tag values from IoT Hub
System.out.println("Device twin after update:");
twinClient.getTwin(device);
System.out.println(device);

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

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

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

Создание SQL-запроса двойников с помощью createSqlQuery
Использование queryTwin для выполнения запроса
Используйте hasNextDeviceTwin , чтобы проверить наличие другого двойника устройства в результирующем наборе
Получение следующего двойника устройства из результированного набора с помощью getNextDeviceTwin

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

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

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

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

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

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

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

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

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

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

Обзор

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

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

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

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

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

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

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

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

Вызов create_from_connection_string для добавления строка подключения устройства
Вызов подключения для подключения клиента устройства к Центру Интернета вещей Azure

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Например:

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

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

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

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

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

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

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

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

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

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

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

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

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

Например:

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

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

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

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

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

В этом примере обновляются region и plant содержатся сведения о тегах и задаются 1требуемые power_level свойства.

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

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

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

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

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

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

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

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

print()

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

print()

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

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

Обзор

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

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

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

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

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

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

npm install azure-iot-device --save

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

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

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

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

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

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

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

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

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

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

Например:

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

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

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

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

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

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

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

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

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

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

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

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

Например:

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

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

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

Например:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Например:

maxTemperature Свойства minTemperature находятся под группированием свойств с именем properties.desired.climate changes.
Приложение серверной службы применяет это исправление для обновления minTemperature и maxTemperature требуемых свойств:
```
const twinPatch1 = {
properties: {
   desired: {
    climate: { minTemperature: 68, maxTemperature: 76, },
    },
  },
 };
```
Этот код настраивает требуемые свойства, изменяющий прослушиватель событий, который активирует любые изменения в properties.desired.climate группе свойств. Если в этой группе изменяется требуемое свойство, сообщения об изменении температуры min и max, отображаемые в консоли:
```
twin.on('properties.desired.climate', function (delta) {
    if (delta.minTemperature || delta.maxTemperature) {
        console.log('updating desired temp:');
        console.log('min temp = ' + twin.properties.desired.climate.minTemperature);
        console.log('max temp = ' + twin.properties.desired.climate.maxTemperature);
    }
});
```

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

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

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

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

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

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

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

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

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

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

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

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

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

npm install azure-iothub --save

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

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

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

'use strict';
var iothub = require('azure-iothub');
var connectionString = '{Iot Hub service connection string}';
var registry = iothub.Registry.fromConnectionString(connectionString);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Бөлісу құралы:

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

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

Обзор

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Обзор

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

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

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

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

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

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

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

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

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

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

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

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

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

Обзор

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

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

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

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

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

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

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

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

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

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

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

Обзор

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Кері байланыс

Қосымша ресурстар