Wprowadzenie do zarządzania bliźniaczymi reprezentacjami urządzeń

Artykuł
10/16/2024

Użyj zestawu SDK urządzenia usługi Azure IoT Hub i zestawu SDK usługi, aby opracowywać aplikacje obsługujące typowe zadania bliźniaczych reprezentacji urządzeń. Bliźniacze reprezentacje urządzeń to dokumenty JSON, które przechowują informacje o stanie urządzenia, w tym metadane, konfiguracje i warunki. Usługa IoT Hub utrzymuje bliźniacze reprezentację urządzenia dla każdego urządzenia, które łączy się z nim.

Bliźniacze reprezentacje urządzeń umożliwiają:

Przechowywanie metadanych urządzenia z zaplecza rozwiązania
Zgłoś bieżące informacje o stanie, takie jak dostępne możliwości i warunki, na przykład użyta metoda łączności z poziomu aplikacji urządzenia
Synchronizowanie stanu długotrwałych przepływów pracy, takich jak aktualizacje oprogramowania układowego i konfiguracji, między aplikacją urządzenia a aplikacją zaplecza
Wykonywanie zapytań dotyczących metadanych, konfiguracji lub stanu urządzenia

Aby uzyskać więcej informacji o bliźniaczych reprezentacjach urządzeń, w tym o tym, kiedy używać bliźniaczych reprezentacji urządzeń, zobacz Omówienie bliźniaczych reprezentacji urządzeń i korzystanie z nich w usłudze IoT Hub.

Uwaga

Funkcje opisane w tym artykule są dostępne tylko w warstwie Standardowa usługi IoT Hub. Aby uzyskać więcej informacji na temat warstw podstawowej i standardowej/bezpłatnej usługi IoT Hub, zobacz Wybieranie odpowiedniej warstwy usługi IoT Hub dla rozwiązania.

W tym artykule przedstawiono sposób tworzenia dwóch typów aplikacji:

Aplikacje urządzeń mogą obsługiwać żądania aktualizacji żądanych właściwości i reagować na zmiany w zgłoszonych właściwościach.
Aplikacje usługi mogą aktualizować tagi bliźniaczych reprezentacji urządzeń, ustawiać nowe żądane właściwości i wykonywać zapytania dotyczące urządzeń na podstawie wartości bliźniaczych reprezentacji urządzeń.

Uwaga

Ten artykuł ma na celu uzupełnienie przykładów zestawów SDK usługi Azure IoT, do których odwołuje się ten artykuł. Za pomocą narzędzi zestawu SDK można tworzyć zarówno aplikacje urządzeń, jak i zaplecza.

Wymagania wstępne

Centrum IoT. Niektóre wywołania zestawu SDK wymagają parametry połączenia podstawowej usługi IoT Hub, dlatego zanotuj parametry połączenia.
Zarejestrowane urządzenie. Niektóre wywołania zestawu SDK wymagają parametry połączenia podstawowego urządzenia, dlatego zanotuj parametry połączenia.
Parametry połączenia usługi IoT Hub

W tym artykule utworzysz usługę zaplecza, która dodaje żądane właściwości do bliźniaczej reprezentacji urządzenia, a następnie wysyła zapytanie do rejestru tożsamości w celu znalezienia wszystkich urządzeń z zgłoszonymi właściwościami, które zostały odpowiednio zaktualizowane. Usługa wymaga uprawnienia połączenia usługi, aby zmodyfikować żądane właściwości bliźniaczej reprezentacji urządzenia i potrzebuje uprawnień do odczytu rejestru w celu wykonywania zapytań dotyczących rejestru tożsamości. Nie ma domyślnych zasad dostępu współdzielonego, które zawierają tylko te dwa uprawnienia, więc musisz je utworzyć.

Aby utworzyć zasady dostępu współdzielonego, które udzielają uprawnień do nawiązywania połączenia z usługą i odczytu rejestru i uzyskiwania parametry połączenia dla tych zasad, wykonaj następujące kroki:
1. W witrynie Azure Portal wybierz pozycję Grupy zasobów. Wybierz grupę zasobów, w której znajduje się centrum, a następnie wybierz centrum z listy zasobów.
2. W okienku po lewej stronie centrum wybierz pozycję Zasady dostępu współdzielonego.
3. W górnym menu powyżej listy zasad wybierz pozycję Dodaj zasady dostępu współdzielonego.
4. W okienku Dodawanie zasad dostępu współdzielonego po prawej stronie wprowadź opisową nazwę zasad, taką jak "serviceAndRegistryRead". W obszarze Uprawnienia wybierz pozycję Odczyt rejestru i Połączenie z usługą, a następnie wybierz pozycję Dodaj.
5. Wybierz nowe zasady z listy zasad.
6. Wybierz ikonę kopiowania dla parametry połączenia podstawowej i zapisz wartość.
Aby uzyskać więcej informacji na temat zasad dostępu współdzielonego i uprawnień usługi IoT Hub, zobacz Kontrola dostępu do usługi IoT Hub przy użyciu sygnatur dostępu współdzielonego.
Jeśli aplikacja używa protokołu MQTT, upewnij się, że port 8883 jest otwarty w zaporze. Protokół MQTT komunikuje się za pośrednictwem portu 8883. Ten port może zostać zablokowany w niektórych środowiskach sieci firmowych i edukacyjnych. Aby uzyskać więcej informacji i sposobów obejścia tego problemu, zobacz Nawiązywanie połączenia z usługą IoT Hub (MQTT).
Wymagania dotyczące zestawu SDK języka:
- .NET SDK — wymaga programu Visual Studio.
- Zalecany jest zestaw Python SDK - w wersji 3.7 lub nowszej. Upewnij się, że używasz 32-bitowej lub 64-bitowej instalacji zgodnie z wymaganiami konfiguracji. Po wyświetleniu monitu podczas instalacji upewnij się, że język Python został dodany do zmiennej środowiskowej specyficznej dla platformy.
- Java — wymaga zestawu Java SE Development Kit 8. Upewnij się, że wybrano środowisko Java 8 w obszarze Obsługa długoterminowa , aby przejść do pobierania zestawu JDK 8.
- Node.js — wymaga Node.js w wersji 10.0.x lub nowszej.

Omówienie

W tym artykule opisano sposób użycia zestawu SDK usługi Azure IoT dla platformy .NET do tworzenia kodu aplikacji usługi urządzenia i zaplecza dla bliźniaczych reprezentacji urządzeń.

Tworzenie aplikacji urządzenia

Aplikacje urządzeń mogą odczytywać i zapisywać zgłaszane właściwości bliźniaczej reprezentacji bliźniaczej oraz otrzymywać powiadomienia o zmianach właściwości żądanej reprezentacji bliźniaczej, które są ustawiane przez aplikację zaplecza lub usługę IoT Hub.

W tej sekcji opisano sposób używania kodu aplikacji urządzenia do wykonywania następujących czynności:

Pobieranie bliźniaczej reprezentacji urządzenia i badanie zgłoszonych właściwości
Aktualizowanie zgłoszonych właściwości bliźniaczej reprezentacji urządzenia
Tworzenie procedury obsługi wywołania zwrotnego żądanej aktualizacji właściwości

Dodawanie pakietu NuGet urządzenia

Aplikacje klienckie urządzeń napisane w języku C# wymagają pakietu NuGet Microsoft.Azure.Devices.Client .

Nawiązywanie połączenia z urządzeniem

Klasa DeviceClient uwidacznia wszystkie metody wymagane do interakcji z bliźniaczymi reprezentacjami urządzeń z urządzenia.

Nawiąż połączenie z urządzeniem przy użyciu metody CreateFromConnectionString wraz z parametry połączenia urządzenia i protokołem transportu połączenia.

Parametr CreateFromConnectionString protokołu transportowego TransportType obsługuje następujące protokoły transportu:

Mqtt
Mqtt_WebSocket_Only
Mqtt_Tcp_Only
Amqp
Amqp_WebSocket_Only
Amqp_Tcp_Only

Protokół Http1 nie jest obsługiwany w przypadku aktualizacji bliźniaczej reprezentacji urządzenia.

Ten przykład łączy się z urządzeniem przy użyciu protokołu transportowego 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);

Pobieranie bliźniaczej reprezentacji urządzenia i badanie właściwości

Wywołaj metodę GetTwinAsync , aby pobrać bieżące właściwości bliźniaczej reprezentacji urządzenia. Istnieje wiele właściwości obiektu bliźniaczej reprezentacji, których można użyć do uzyskiwania dostępu do określonych obszarów Twin danych JSON, w tym Properties, Status, Tagsi Version.

Ten przykład pobiera właściwości bliźniaczej reprezentacji urządzenia i drukuje wartości bliźniaczych reprezentacji w formacie JSON.

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

Aktualizowanie zgłoszonych właściwości bliźniaczej reprezentacji urządzenia

Aby zaktualizować zgłoszoną właściwość bliźniaczej reprezentacji:

Tworzenie obiektu TwinCollection dla zgłaszanej aktualizacji właściwości
Aktualizowanie co najmniej jednej zgłoszonej właściwości w TwinCollection obiekcie
Użyj metody UpdateReportedPropertiesAsync , aby wypchnąć zmiany zgłaszanej właściwości do usługi IoT Hub

Na przykład:

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

Tworzenie procedury obsługi wywołania zwrotnego żądanej aktualizacji właściwości

Utwórz żądaną procedurę obsługi wywołania zwrotnego aktualizacji właściwości, która jest wykonywana po zmianie żądanej właściwości w bliźniaczej reprezentacji urządzenia, przekazując nazwę metody obsługi wywołania zwrotnego na SetDesiredPropertyUpdateCallbackAsync.

Na przykład to wywołanie konfiguruje system w celu powiadomienia metody o nazwieOnDesiredPropertyChangedAsync za każdym razem, gdy żądana właściwość zostanie zmieniona.

await _deviceClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

Właściwości bliźniaczej reprezentacji są przekazywane do metody wywołania zwrotnego jako twinCollection i można je zbadać jako KeyValuePair struktury.

Ten przykład odbiera żądane aktualizacje właściwości jako TwinCollectionelement , a następnie przechodzi w pętli i drukuje KeyValuePair aktualizacje kolekcji. Po pętli w KeyValuePair kolekcji kod wywołuje UpdateReportedPropertiesAsync polecenie w celu zaktualizowania zgłaszanej DateTimeLastDesiredPropertyChangeReceived właściwości, aby zachować aktualność czasu ostatniej aktualizacji.

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

Przykład urządzenia z zestawem SDK

Zestaw SDK usługi Azure IoT dla platformy .NET udostępnia działającą przykładową aplikację urządzenia, która obsługuje zadania bliźniaczej reprezentacji urządzenia. Aby uzyskać więcej informacji, zobacz TwinSample.

Tworzenie aplikacji zaplecza

Aplikacja zaplecza:

Nawiązuje połączenie z urządzeniem za pośrednictwem usługi IoT Hub
Może odczytywać zgłaszane i żądane właściwości urządzenia, zapisywać żądane właściwości i uruchamiać zapytania dotyczące urządzeń

Klasa RegistryManager uwidacznia wszystkie metody wymagane do utworzenia aplikacji zaplecza w celu interakcji z bliźniaczymi reprezentacjami urządzeń z usługi.

W tej sekcji opisano sposób tworzenia kodu aplikacji zaplecza w celu:

Odczytywanie i aktualizowanie pól bliźniaczych reprezentacji urządzenia
Tworzenie zapytania bliźniaczej reprezentacji urządzenia

Dodawanie pakietu NuGet usługi

Aplikacje usługi zaplecza wymagają pakietu NuGet Microsoft.Azure.Devices .

Nawiązywanie połączenia z centrum IoT

Połącz aplikację zaplecza z urządzeniem przy użyciu polecenia CreateFromConnectionString. Jako parametr podaj usługę IoT Hub parametry połączenia utworzoną w sekcji wymagań wstępnych.

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

Odczytywanie i aktualizowanie pól bliźniaczych reprezentacji urządzenia

Bieżące pola bliźniaczej reprezentacji urządzenia można pobrać do obiektu bliźniaczej reprezentacji , wywołując polecenie GetTwinAsync.

Klasa Twin zawiera właściwości odpowiadające każdej sekcji bliźniaczej reprezentacji urządzenia. Twin Użyj właściwości klasy, aby wyświetlić i zaktualizować pola bliźniaczej reprezentacji urządzenia. Właściwości obiektu umożliwiają Twin aktualizowanie wielu pól bliźniaczych reprezentacji przed zapisaniem aktualizacji na urządzeniu przy użyciu polecenia UpdateTwinAsync.

Po wprowadzeniu aktualizacji pól bliźniaczej reprezentacji wywołaj metodę UpdateTwinAsync , aby zapisać Twin aktualizacje pól obiektów z powrotem na urządzeniu. Użyj funkcji try i catch logiki powiązanej z procedurą obsługi błędów, aby przechwycić błędy niepoprawnie sformatowanych poprawek z programu UpdateTwinAsync.

Odczytywanie i aktualizowanie tagów bliźniaczych reprezentacji urządzenia

Użyj właściwości Tag bliźniaczej reprezentacji urządzenia, aby odczytywać i zapisywać informacje o tagach urządzenia.

Aktualizowanie tagów przy użyciu obiektu bliźniaczej reprezentacji

W tym przykładzie jest tworzona poprawka tagu location , przypisuje ją do Twin obiektu przy użyciu właściwości , a następnie stosuje poprawkę przy użyciu Tags polecenia 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);
}

Aktualizowanie tagów przy użyciu ciągu JSON

Możesz utworzyć i zastosować poprawkę aktualizacji informacji bliźniaczej reprezentacji urządzenia w formacie JSON. Usługa IoT Hub analizuje i stosuje poprawkę, jeśli jest poprawnie sformatowana.

W tym przykładzie wywołano metodę GetTwinAsync pobierania bieżących pól bliźniaczej reprezentacji urządzenia do Twin obiektu, tworzy poprawkę w tag formacie JSON z informacjami o regionie i lokalizacji zakładu, a następnie wywołuje UpdateTwinAsync metodę stosowania poprawki w celu zaktualizowania bliźniaczej reprezentacji urządzenia. Jeśli błąd nie powiedzie się, zostanie wyświetlony UpdateTwinAsync komunikat o błędzie.

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

Wyświetlanie i aktualizowanie żądanych właściwości bliźniaczej reprezentacji

Użyj właściwości TwinProperties.Desired bliźniaczej reprezentacji urządzenia, aby odczytywać i zapisywać informacje o żądanej właściwości urządzenia. Zaktualizuj właściwości bliźniaczej reprezentacji Desired przy użyciu poprawki w formacie JSON.

W tym przykładzie wywoływane jest GetTwinAsync pobieranie bieżących pól bliźniaczej reprezentacji urządzenia do Twin obiektu, aktualizowanie żądanej właściwości bliźniaczej reprezentacji bliźniaczej speed , a następnie wywoływanie UpdateTwinAsync w celu zastosowania Twin obiektu w celu zaktualizowania bliźniaczej reprezentacji urządzenia.

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

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

Inne metody aktualizacji bliźniaczej reprezentacji bliźniaczej

Aktualizacje bliźniaczej reprezentacji można również stosować przy użyciu następujących metod zestawu SDK:

Wywołaj metodę ReplaceTwinAsync , aby zastąpić całą reprezentację urządzenia.
Wywołaj metodę UpdateTwins2Async , aby zaktualizować listę bliźniaczych reprezentacji utworzonych wcześniej w systemie.

Tworzenie zapytania bliźniaczej reprezentacji urządzenia

W tej sekcji przedstawiono dwa zapytania bliźniaczej reprezentacji urządzenia. Zapytania bliźniaczych reprezentacji urządzeń to zapytania podobne do języka SQL, które zwracają zestaw wyników bliźniaczych reprezentacji urządzeń.

Aby utworzyć zapytanie bliźniaczej reprezentacji urządzenia, wywołaj metodę CreateQuery , aby przesłać zapytanie SQL bliźniaczych reprezentacji bliźniaczych i uzyskać interfejs IQuery . Opcjonalnie można wywołać CreateQuery przy użyciu drugiego parametru, aby określić maksymalną liczbę elementów na stronę.

Następne wywołanie GetNextAsTwinAsync lub GetNextAsJsonAsync metoda tyle razy, ile potrzeba, aby pobrać wszystkie wyniki reprezentacji bliźniaczej.

GetNextAsTwinAsync , aby pobrać następny stronicowany wynik jako obiekty bliźniaczej reprezentacji .
GetNextAsJsonAsync , aby pobrać następny stronicowany wynik jako ciągi JSON.

Interfejs IQuery zawiera właściwość logiczną HasMoreResults , której można użyć, aby sprawdzić, czy istnieje więcej wyników bliźniaczych reprezentacji do pobrania.

To przykładowe zapytanie wybiera tylko bliźniacze reprezentacje urządzeń znajdujące się w zakładzie 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)));

To przykładowe zapytanie uściśli pierwsze zapytanie, aby wybrać tylko urządzenia, które są również połączone za pośrednictwem sieci komórkowej.

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

Przykład usługi SDK

Zestaw SDK usługi Azure IoT dla platformy .NET udostępnia działający przykład aplikacji usługi obsługującej zadania bliźniaczej reprezentacji urządzenia. Aby uzyskać więcej informacji, zobacz Przykład menedżera rejestru.

Omówienie

W tym artykule opisano sposób używania zestawu SDK usługi Azure IoT dla języka Java do tworzenia kodu aplikacji usługi urządzenia i zaplecza dla bliźniaczych reprezentacji urządzeń.

Tworzenie aplikacji urządzenia

W tej sekcji opisano sposób tworzenia kodu aplikacji urządzenia w celu:

Pobieranie i wyświetlanie bliźniaczej reprezentacji urządzenia
Aktualizowanie zgłoszonych właściwości bliźniaczej reprezentacji urządzenia
Subskrybowanie żądanych zmian właściwości

Klasa DeviceClient uwidacznia wszystkie metody wymagane do interakcji z bliźniaczymi reprezentacjami urządzeń z urządzenia.

Instrukcje importowania urządzenia

Użyj poniższych instrukcji importowania urządzeń, aby uzyskać dostęp do zestawu AZURE IoT SDK dla języka Java.

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

Nawiązywanie połączenia z urządzeniem

Aby nawiązać połączenie z urządzeniem:

Użyj protokołu IotHubClientProtocol , aby wybrać protokół transportu. Na przykład:
```
IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
```

Użyj konstruktoraDeviceClient, aby dodać podstawowe parametry połączenia i protokół urządzenia.

String connString = "{IoT hub device connection string}";
DeviceClient client = new DeviceClient(connString, protocol);

Użyj opcji otwórz , aby połączyć urządzenie z centrum IoT Hub. Jeśli klient jest już otwarty, metoda nic nie robi.
```
client.open(true);
```

Pobieranie i wyświetlanie bliźniaczej reprezentacji urządzenia

Po otwarciu połączenia klienta wywołaj metodę getTwin , aby pobrać bieżące właściwości bliźniaczej reprezentacji do Twin obiektu.

Na przykład:

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

Aktualizowanie zgłoszonych właściwości bliźniaczej reprezentacji urządzenia

Po pobraniu bieżącej reprezentacji bliźniaczej możesz rozpocząć wprowadzanie aktualizacji zgłoszonych właściwości. Można również aktualizować zgłaszane właściwości bez pobierania bieżącej reprezentacji bliźniaczej, o ile masz poprawną zgłoszoną wersję właściwości. Jeśli wysyłasz zgłoszone właściwości i otrzymujesz błąd "Niepowodzenie warunku wstępnego", zgłoszona wersja właściwości jest nieaktualna. W takim przypadku pobierz najnowszą wersję, wywołując getTwin ponownie.

Aby zaktualizować zgłoszone właściwości:

Wywołaj metodę getReportedProperties, aby pobrać zgłoszone właściwości bliźniaczej reprezentacji do obiektu TwinCollection .
Użyj polecenia put , aby zaktualizować zgłoszoną właściwość w TwinCollection obiekcie. Wywołaj put każdą zgłoszoną aktualizację właściwości.
Użyj właściwości updateReportedProperties , aby zastosować grupę zgłoszonych właściwości, które zostały zaktualizowane przy użyciu put metody .

Na przykład:

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

Wywołaj metodę subscribeToDesiredProperties , aby zasubskrybować żądane zmiany właściwości. Ten klient otrzymuje wywołanie zwrotne z obiektem Twin za każdym razem, gdy żądana właściwość jest aktualizowana. Wywołanie zwrotne zawiera pełny zestaw żądanych właściwości lub tylko zaktualizowaną żądaną właściwość w zależności od sposobu zmiany żądanej właściwości.

W tym przykładzie subskrybowane są zmiany żądanej właściwości. Wszelkie żądane zmiany właściwości są przekazywane do programu obsługi o nazwie DesiredPropertiesUpdatedHandler.

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

W tym przykładzie DesiredPropertiesUpdatedHandler żądana właściwość zmienia wywołania obsługi wywołania zwrotnego wywołuje metodę getDesiredProperties w celu pobrania zmian właściwości, a następnie wyświetla zaktualizowane właściwości bliźniaczej reprezentacji.

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

Przykład urządzenia z zestawem SDK

Zestaw SDK usługi Azure IoT dla języka Java zawiera działający przykład testowania pojęć dotyczących aplikacji urządzenia opisanych w tym artykule. Aby uzyskać więcej informacji, zobacz Przykład bliźniaczej reprezentacji urządzenia.

Tworzenie aplikacji zaplecza

W tej sekcji opisano sposób tworzenia aplikacji zaplecza, która:

Aktualizuje tagi bliźniaczej reprezentacji urządzenia
Wysyła zapytania do urządzeń przy użyciu filtrów w tagach i właściwościach

Klasa ServiceClient DeviceTwin zawiera metody, których usługi mogą używać do uzyskiwania dostępu do bliźniaczych reprezentacji urządzeń.

Instrukcje importowania usługi

Użyj poniższych instrukcji importowania usługi, aby uzyskać dostęp do zestawu AZURE IoT SDK dla języka Java.

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

Nawiązywanie połączenia z klientem usługi IoT Hub

Aby nawiązać połączenie z usługą IoT Hub, aby wyświetlić i zaktualizować informacje o bliźniaczej reprezentacji urządzenia:

Utwórz obiekt DeviceTwinClientOptions. Ustaw wszelkie opcje wymagane dla aplikacji. Te opcje są przekazywane do DeviceTwin obiektu.
Użyj konstruktora DeviceTwin , aby utworzyć połączenie z centrum IoT Hub. Obiekt DeviceTwin obsługuje komunikację z centrum IoT Hub. Jako parametry podaj usługę IoT Hub parametry połączenia utworzoną w sekcji Wymagania wstępne i DeviceTwinClientOptions obiekt .
Obiekt DeviceTwinDevice reprezentuje bliźniacze reprezentację urządzenia z jego właściwościami i tagami.

Na przykład:

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

Aktualizowanie pól bliźniaczych reprezentacji urządzenia

Aby zaktualizować pola bliźniaczej reprezentacji urządzenia:

Użyj polecenia getTwin , aby pobrać bieżące pola bliźniaczej reprezentacji urządzenia

W tym przykładzie są pobierane i drukowane pola bliźniaczej reprezentacji urządzenia:
```
// Get the device twin from IoT Hub
System.out.println("Device twin before update:");
twinClient.getTwin(device);
System.out.println(device);
```
HashSet Używanie obiektu do add grupy par tagów bliźniaczych
Dodawanie grupy par tagów z tags obiektu do DeviceTwinDevice obiektu za pomocą elementu setTags

Aktualizowanie bliźniaczej reprezentacji bliźniaczej w centrum IoT za pomocą narzędzia updateTwin

W tym przykładzie zaktualizowano tagi bliźniaczej reprezentacji urządzenia w regionie i zakładzie dla bliźniaczej reprezentacji urządzenia:

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

Tworzenie zapytania bliźniaczej reprezentacji urządzenia

Klasa Query zawiera metody, których można użyć do tworzenia zapytań w stylu SQL w usłudze IoT Hub dla bliźniaczych reprezentacji, zadań, zadań urządzeń lub danych pierwotnych.

Aby utworzyć zapytanie dotyczące urządzenia:

Tworzenie zapytania SQL bliźniaczych reprezentacji bliźniaczych za pomocą polecenia createSqlQuery
Wykonywanie zapytania przy użyciu metody queryTwin
Użyj polecenia hasNextDeviceTwin , aby sprawdzić, czy w zestawie wyników znajduje się inna reprezentacja urządzenia
Użyj polecenia getNextDeviceTwin , aby pobrać następną reprezentację urządzenia z zestawu wyników

Poniższe przykładowe zapytania zwracają maksymalnie 100 urządzeń.

To przykładowe zapytanie wybiera tylko bliźniacze reprezentacje urządzeń znajdujące się w zakładzie 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());
}

To przykładowe zapytanie uściśli pierwsze zapytanie, aby wybrać tylko urządzenia, które są również połączone za pośrednictwem sieci komórkowej.

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

Przykład usługi SDK

Zestaw SDK usługi Azure IoT dla języka Java udostępnia działający przykład aplikacji usługi obsługującej zadania bliźniaczej reprezentacji urządzenia. Aby uzyskać więcej informacji, zobacz Przykład bliźniaczej reprezentacji urządzenia.

Omówienie

W tym artykule opisano sposób używania zestawu SDK usługi Azure IoT dla języka Python do tworzenia kodu aplikacji usługi urządzenia i zaplecza dla bliźniaczych reprezentacji urządzeń.

Tworzenie aplikacji urządzenia

Klasa IoTHubDeviceClient zawiera metody, których można użyć do pracy z bliźniaczymi reprezentacjami urządzeń.

W tej sekcji opisano sposób tworzenia kodu aplikacji urządzenia, który:

Pobiera bliźniacze reprezentacje urządzenia i sprawdza zgłaszane właściwości
Stosowanie poprawek zgłoszonych właściwości bliźniaczej reprezentacji urządzenia

Nawiązywanie połączenia z urządzeniem

W tej sekcji pokazano, jak połączyć aplikację z urządzeniem przy użyciu klucza podstawowego urządzenia zawierającego klucz dostępu współdzielonego.

Aby połączyć aplikację z urządzeniem:

Wywołaj create_from_connection_string, aby dodać parametry połączenia urządzenia
Wywołanie połączenia w celu połączenia klienta urządzenia z centrum Azure IoT Hub

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

Pobieranie bliźniaczej reprezentacji urządzenia i badanie zgłoszonych właściwości

Możesz pobrać i zbadać informacje o bliźniaczej reprezentacji urządzenia, w tym tagi i właściwości. Pobrane informacje o bliźniaczej reprezentacji urządzenia są zgodne z danymi w formacie JSON bliźniaczej reprezentacji urządzenia, które można wyświetlić dla urządzenia w witrynie Azure Portal.

Wywołaj get_twin , aby pobrać bliźniacze reprezentacje urządzenia z usługi Azure IoT Hub. Informacje o bliźniaczej reprezentacji są umieszczane w zmiennej, którą można wydrukować lub zbadać.

W tym przykładzie pobrano bliźniacza reprezentację urządzenia i użyto print polecenia w celu wyświetlenia bliźniaczej reprezentacji urządzenia w formacie JSON.

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

Stosowanie poprawek zgłoszonych właściwości bliźniaczej reprezentacji urządzenia

Możesz zastosować poprawkę w celu zaktualizowania właściwości zgłoszonych przez urządzenie w formacie JSON.

Aby zastosować poprawkę w celu zaktualizowania zgłoszonych właściwości:

Przypisz poprawkę JSON zgłaszanej właściwości do zmiennej.
Wywołaj patch_twin_reported_properties , aby zastosować poprawkę JSON do zgłoszonych właściwości. Jest to wywołanie synchroniczne, co oznacza, że ta funkcja nie zwraca się do momentu wysłania poprawki do usługi i potwierdzenia.

Jeśli patch_twin_reported_properties zwraca błąd, ta funkcja zgłasza odpowiedni błąd.

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

Można również wywołać te metody w celu zaktualizowania bliźniaczych reprezentacji urządzeń:

Wywołaj replace_twin , aby zastąpić tagi bliźniaczej reprezentacji urządzenia i żądane właściwości.
Wywołaj update_twin, aby zaktualizować tagi bliźniaczej reprezentacji urządzenia i żądane właściwości.

Przychodzący żądany program obsługi poprawek właściwości

Wywołaj on_twin_desired_properties_patch_received , aby utworzyć funkcję obsługi lub coroutine wywoływaną po odebraniu poprawki żądanej właściwości bliźniaczej reprezentacji. Procedura obsługi przyjmuje jeden argument, który jest poprawką bliźniaczej reprezentacji w postaci obiektu słownika JSON.

W tym przykładzie skonfigurowano żądaną procedurę obsługi poprawek właściwości o nazwie twin_patch_handler.

Na przykład:

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

Odbiera twin_patch_handler i drukuje aktualizacje żądanej właściwości w formacie JSON.

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

Przykłady urządzeń z zestawem SDK

Zestaw AZURE IoT SDK dla języka Python zawiera następujące przykłady:

get_twin — połącz się z urządzeniem i pobierz informacje o bliźniaczej reprezentacji.
update_twin_reported_properties — aktualizowanie zgłoszonych właściwości bliźniaczej reprezentacji bliźniaczej.
receive_twin_desired_properties — odbieranie i aktualizowanie żądanych właściwości.

Tworzenie aplikacji zaplecza

Aplikacja zaplecza łączy się z urządzeniem za pośrednictwem usługi IoT Hub i może odczytywać zgłaszane i żądane właściwości urządzenia, zapisywać żądane właściwości urządzenia i uruchamiać zapytania dotyczące urządzeń.

W tej sekcji opisano sposób tworzenia aplikacji zaplecza w celu:

Aktualizowanie tagów bliźniaczych reprezentacji i żądanych właściwości
Wysyła zapytania do urządzeń przy użyciu filtrów w tagach i właściwościach

Klasa IoTHubRegistryManager uwidacznia wszystkie metody wymagane do utworzenia aplikacji zaplecza w celu interakcji z bliźniaczymi reprezentacjami urządzeń z usługi.

Nawiązywanie połączenia z centrum IoT

Nawiąż połączenie z centrum IoT Przy użyciu from_connection_string. Jako parametr podaj usługę IoT Hub parametry połączenia utworzoną w sekcji wymagań wstępnych.

Na przykład:

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)

Aktualizowanie tagów bliźniaczych reprezentacji i żądanych właściwości

Tagi bliźniaczej reprezentacji urządzenia i żądane właściwości można zaktualizować z poziomu aplikacji zaplecza w tym samym czasie przy użyciu update_twin.

Wywołaj get_twin , aby pobrać bieżącą wersję bliźniaczej reprezentacji urządzenia
Użyj klasy bliźniaczej, aby dodać tagi i właściwości w formacie JSON.
Wywołaj metodę update_twin , aby zastosować poprawkę do bliźniaczej reprezentacji urządzenia. Można również użyć replace_twin , aby zastąpić żądane właściwości i tagi bliźniaczej reprezentacji urządzenia.

Ten przykład aktualizuje region informacje o tagach i plant ustawia żądaną power_level właściwość na 1wartość .

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)

Tworzenie zapytania bliźniaczej reprezentacji urządzenia

Zapytania dotyczące bliźniaczej reprezentacji urządzenia można wykonywać przy użyciu zapytań bliźniaczych reprezentacji urządzenia. Zapytania bliźniaczych reprezentacji urządzeń to zapytania podobne do języka SQL, które zwracają zestaw wyników bliźniaczych reprezentacji urządzeń.

Aby użyć zapytania bliźniaczej reprezentacji urządzenia:

Użyj obiektu QuerySpecification, aby zdefiniować żądanie zapytania przypominające sql.
Użyj query_iot_hub , aby wysłać zapytanie do usługi IoTHub i pobrać informacje o bliźniaczej reprezentacji urządzenia przy użyciu specyfikacji zapytania przypominającej język SQL.

W tym przykładzie są uruchamiane dwa zapytania. Pierwszy wybiera tylko bliźniacze reprezentacje urządzeń znajdujących się w Redmond43 zakładzie, a drugi uściśli zapytanie, aby wybrać tylko urządzenia połączone za pośrednictwem sieci komórkowej. Wyniki są drukowane po każdym zapytaniu.

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

Przykład usługi SDK

Zestaw SDK usługi Azure IoT dla języka Python udostępnia działający przykład aplikacji usługi, która obsługuje zadania bliźniaczej reprezentacji urządzenia. Aby uzyskać więcej informacji, zobacz Przykład zapytania Menedżera rejestru.

Omówienie

W tym artykule opisano sposób używania zestawu SDK usługi Azure IoT dla Node.js do tworzenia kodu aplikacji usługi urządzenia i zaplecza dla bliźniaczych reprezentacji urządzeń.

Tworzenie aplikacji urządzenia

W tej sekcji opisano sposób użycia pakietu azure-iot-device w zestawie SDK usługi Azure IoT dla Node.js w celu utworzenia aplikacji urządzenia w celu:

Pobieranie bliźniaczej reprezentacji urządzenia i badanie zgłoszonych właściwości
Aktualizowanie zgłoszonych właściwości bliźniaczej reprezentacji urządzenia
Otrzymywanie powiadomienia o zmianach żądanych właściwości

Instalowanie pakietów zestawu SDK

Uruchom to polecenie, aby zainstalować zestaw SDK urządzenia azure-iot-device na maszynie dewelopera:

npm install azure-iot-device --save

Pakiet azure-iot-device zawiera obiekty interfejsu z urządzeniami IoT. Klasa Bliźniacze obejmuje obiekty specyficzne dla bliźniaczej reprezentacji. W tej sekcji opisano Client kod klasy używany do odczytywania i zapisywania danych bliźniaczej reprezentacji urządzenia.

Wybieranie protokołu transportowego

Obiekt Client obsługuje następujące protokoły:

Amqp
Http — W przypadku korzystania z Httpusługi Client wystąpienie sprawdza komunikaty z usługi IoT Hub rzadko (co najmniej co 25 minut).
Mqtt
MqttWs
AmqpWs

Zainstaluj wymagane protokoły transportu na maszynie dewelopera.

Na przykład to polecenie instaluje Mqtt protokół:

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

Aby uzyskać więcej informacji na temat różnic między obsługą protokołów MQTT, AMQP i HTTPS, zobacz Wskazówki dotyczące komunikacji między chmurą a urządzeniem i Wybieranie protokołu komunikacyjnego.

Tworzenie modułu klienta

Client Utwórz moduł przy użyciu zainstalowanego pakietu.

Na przykład:

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

Tworzenie modułu protokołu

Protocol Utwórz moduł przy użyciu zainstalowanego pakietu transportowego.

W tym przykładzie przypisano protokół MQTT:

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

Dodawanie protokołu parametry połączenia urządzenia i transportu

Wywołaj metodę fromConnectionString, aby podać parametry połączenia urządzenia:

connStr — parametry połączenia, która hermetyzuje uprawnienia "device connect" dla centrum IoT. Parametry połączenia zawiera nazwę hosta, identyfikator urządzenia i klucz dostępu współużytkowanego w tym formacie: "HostName=<iothub_host_name>; DeviceId=<device_id>; SharedAccessKey=<device_key>".
transportCtor — protokół transportowy.

W tym przykładzie użyto Mqtt protokołu transportu:

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

Otwieranie połączenia z usługą IoT Hub

Użyj metody open, aby otworzyć połączenie między urządzeniem IoT i usługą IoT Hub. Użyj .catch(err) polecenia , aby przechwycić błąd i wykonać kod procedury obsługi.

Na przykład:

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

Pobieranie bliźniaczej reprezentacji urządzenia i badanie zgłoszonych właściwości

Wywołaj metodę getTwin , aby pobrać bieżące informacje o bliźniaczej reprezentacji urządzenia do obiektu bliźniaczej reprezentacji .

Na przykład:

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

Aktualizowanie zgłoszonych właściwości bliźniaczej reprezentacji urządzenia

Użyj aktualizacji , aby zaktualizować zgłaszane właściwości urządzenia. Dołącz poprawkę w formacie JSON jako pierwszy parametr i metodę wywołania zwrotnego stanu wykonywania funkcji jako drugi parametr metody .

W tym przykładzie poprawka bliźniaczej reprezentacji urządzenia w formacie JSON jest przechowywana w zmiennej patch . Poprawka zawiera wartość aktualizacji bliźniaczej reprezentacji connectivity urządzenia .cellular Procedura obsługi poprawek i błędów jest przekazywana update do metody . Jeśli wystąpi błąd, zostanie wyświetlony komunikat o błędzie konsoli.

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

Otrzymywanie powiadomienia o zmianach żądanych właściwości

Utwórz żądany odbiornik zdarzeń aktualizacji właściwości, który jest wykonywany po zmianie żądanej właściwości na urządzeniu, przekazując nazwę metody obsługi wywołania zwrotnego do twin.on.

Odbiornik zdarzeń żądanej właściwości może mieć jedną z następujących form:

Odbieranie wszystkich poprawek za pomocą pojedynczej procedury obsługi zdarzeń
Odbieranie zdarzenia, jeśli cokolwiek się zmienia w ramach grupowania właściwości
Odbieranie zdarzenia dla zmiany pojedynczej właściwości

Odbieranie wszystkich poprawek za pomocą pojedynczej procedury obsługi zdarzeń

Możesz utworzyć odbiornik, aby otrzymać dowolną zmianę żądanej właściwości.

Ten przykładowy kod generuje wszystkie właściwości odebrane z usługi.

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

Odbieranie zdarzenia, jeśli cokolwiek się zmienia w ramach grupowania właściwości

Możesz utworzyć odbiornik, aby odebrać zdarzenie, jeśli coś w ramach zmiany grupowania właściwości.

Na przykład:

Właściwości minTemperature i maxTemperature znajdują się w grupie właściwości o nazwie properties.desired.climate changes.

Aplikacja usługi zaplecza stosuje tę poprawkę do aktualizacji minTemperature i maxTemperature żądanych właściwości:

const twinPatch1 = {
properties: {
   desired: {
    climate: { minTemperature: 68, maxTemperature: 76, },
    },
  },
 };

Ten kod konfiguruje żądany odbiornik zdarzeń zmiany właściwości, który wyzwala wszelkie zmiany w properties.desired.climate obrębie grupowania właściwości. Jeśli w tej grupie zostanie zmieniona żądana właściwość, minimalna i maksymalna liczba komunikatów o zmianie temperatury wyświetlanych w konsoli:

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

Odbieranie zdarzenia dla zmiany pojedynczej właściwości

Odbiornik można skonfigurować pod kątem zmiany pojedynczej właściwości. W tym przykładzie kod tego zdarzenia jest wykonywany tylko wtedy, gdy fanOn wartość logiczna jest częścią poprawki. Kod generuje nowy żądany fanOn stan za każdym razem, gdy usługa go zaktualizuje.

Aplikacja zaplecza stosuje tę żądaną poprawkę właściwości:

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

Odbiornik jest wyzwalany tylko wtedy, gdy fanOn właściwość ulegnie zmianie:

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

Przykłady zestawu SDK urządzeń

Zestaw SDK usługi Azure IoT dla Node.js zawiera dwa przykłady bliźniaczej reprezentacji urządzenia:

Tworzenie aplikacji zaplecza

W tej sekcji opisano sposób tworzenia aplikacji zaplecza, która:

Pobiera i aktualizuje bliźniacze reprezentacje urządzenia
Tworzy zapytanie bliźniaczej reprezentacji urządzenia

Instalowanie pakietów zestawu SDK usługi

Uruchom to polecenie, aby zainstalować usługę azure-iothub na maszynie deweloperskiej:

npm install azure-iothub --save

Klasa Registry uwidacznia wszystkie metody wymagane do interakcji z bliźniaczymi reprezentacjami urządzeń z aplikacji zaplecza.

Nawiązywanie połączenia z centrum IoT

Użyj polecenia fromConnectionString , aby nawiązać połączenie z centrum IoT. Jako parametr podaj usługę IoT Hub parametry połączenia utworzoną w sekcji wymagań wstępnych.

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

Pobieranie i aktualizowanie bliźniaczej reprezentacji urządzenia

Możesz utworzyć poprawkę zawierającą tagi i żądane aktualizacje właściwości dla bliźniaczej reprezentacji urządzenia.

Aby zaktualizować bliźniacze reprezentacje urządzenia:

Wywołaj metodę getTwin , aby pobrać obiekt bliźniaczej reprezentacji urządzenia.

Sformatuj poprawkę zawierającą aktualizację bliźniaczej reprezentacji urządzenia. Poprawka jest formatowana w formacie JSON zgodnie z opisem w klasie Twin. Poprawka usługi zaplecza może zawierać aktualizacje tagów i żądanych właściwości. Aby uzyskać więcej informacji o formacie poprawki, zobacz Tagi i format właściwości.

Wywołaj aktualizację w celu zaktualizowania bliźniaczej reprezentacji urządzenia za pomocą poprawki.

W tym przykładzie bliźniacze reprezentacje urządzenia są pobierane dla myDeviceIdelementu , a następnie poprawka jest stosowana do bliźniaczych reprezentacji zawierających location aktualizację tagu 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();
               }
             });
         }
     });

Tworzenie zapytania bliźniaczej reprezentacji urządzenia

Zapytania dotyczące urządzeń przypominających język SQL można tworzyć w celu zbierania informacji z bliźniaczych reprezentacji urządzeń.

Użyj polecenia createQuery , aby utworzyć zapytanie, które można uruchomić w wystąpieniu usługi IoT Hub, aby znaleźć informacje o urządzeniach lub zadaniach.

createQuery zawiera dwa parametry:

sqlQuery — zapytanie napisane jako ciąg SQL.
pageSize — żądana liczba wyników na stronę (opcjonalnie. wartość domyślna: 1000, maksymalna: 10000).

Jeśli parametr pageSize jest określony, obiekt zapytania zawiera właściwość logiczną, którą można sprawdzić i użyć nextAsTwin metody , aby uzyskać następną hasMoreResults stronę wyników reprezentacji bliźniaczej tyle razy, ile potrzeba, aby pobrać wszystkie wyniki. Metoda o nazwie next jest dostępna dla wyników, które nie są bliźniaczymi reprezentacjami urządzeń, na przykład wynikami zapytań agregacji.

To przykładowe zapytanie wybiera tylko bliźniacze reprezentacje urządzeń znajdujące się w Redmond43 zakładzie.

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(','));
    }
});

To przykładowe zapytanie uściśli pierwsze zapytanie, aby wybrać tylko urządzenia, które są również połączone za pośrednictwem sieci komórkowej.

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(','));
    }
});
};

Przykład zestawu SDK usługi

Zestaw SDK usługi Azure IoT dla Node.js udostępnia działający przykład aplikacji usługi obsługującej zadania bliźniaczej reprezentacji urządzenia. Aby uzyskać więcej informacji, zobacz Usługa zaplecza bliźniaczej reprezentacji urządzenia — ten projekt służy do wysyłania aktualizacji poprawek bliźniaczej reprezentacji urządzenia dla określonego urządzenia.

Udostępnij za pośrednictwem

Wprowadzenie do zarządzania bliźniaczymi reprezentacjami urządzeń

Wymagania wstępne

Omówienie

Tworzenie aplikacji urządzenia

Dodawanie pakietu NuGet urządzenia

Nawiązywanie połączenia z urządzeniem

Pobieranie bliźniaczej reprezentacji urządzenia i badanie właściwości

Aktualizowanie zgłoszonych właściwości bliźniaczej reprezentacji urządzenia

Tworzenie procedury obsługi wywołania zwrotnego żądanej aktualizacji właściwości

Przykład urządzenia z zestawem SDK

Tworzenie aplikacji zaplecza

Dodawanie pakietu NuGet usługi

Nawiązywanie połączenia z centrum IoT

Odczytywanie i aktualizowanie pól bliźniaczych reprezentacji urządzenia

Odczytywanie i aktualizowanie tagów bliźniaczych reprezentacji urządzenia

Aktualizowanie tagów przy użyciu obiektu bliźniaczej reprezentacji

Aktualizowanie tagów przy użyciu ciągu JSON

Wyświetlanie i aktualizowanie żądanych właściwości bliźniaczej reprezentacji

Inne metody aktualizacji bliźniaczej reprezentacji bliźniaczej

Tworzenie zapytania bliźniaczej reprezentacji urządzenia

Przykład usługi SDK

Omówienie

Tworzenie aplikacji urządzenia

Instrukcje importowania urządzenia

Nawiązywanie połączenia z urządzeniem

Pobieranie i wyświetlanie bliźniaczej reprezentacji urządzenia

Aktualizowanie zgłoszonych właściwości bliźniaczej reprezentacji urządzenia

Subskrybowanie żądanych zmian właściwości

Przykład urządzenia z zestawem SDK

Tworzenie aplikacji zaplecza

Instrukcje importowania usługi

Nawiązywanie połączenia z klientem usługi IoT Hub

Aktualizowanie pól bliźniaczych reprezentacji urządzenia

Tworzenie zapytania bliźniaczej reprezentacji urządzenia

Przykład usługi SDK

Omówienie

Tworzenie aplikacji urządzenia

Nawiązywanie połączenia z urządzeniem

Pobieranie bliźniaczej reprezentacji urządzenia i badanie zgłoszonych właściwości

Stosowanie poprawek zgłoszonych właściwości bliźniaczej reprezentacji urządzenia

Przychodzący żądany program obsługi poprawek właściwości

Przykłady urządzeń z zestawem SDK

Tworzenie aplikacji zaplecza

Nawiązywanie połączenia z centrum IoT

Aktualizowanie tagów bliźniaczych reprezentacji i żądanych właściwości

Tworzenie zapytania bliźniaczej reprezentacji urządzenia

Przykład usługi SDK

Omówienie

Tworzenie aplikacji urządzenia

Instalowanie pakietów zestawu SDK

Wybieranie protokołu transportowego

Tworzenie modułu klienta

Tworzenie modułu protokołu

Dodawanie protokołu parametry połączenia urządzenia i transportu

Otwieranie połączenia z usługą IoT Hub

Pobieranie bliźniaczej reprezentacji urządzenia i badanie zgłoszonych właściwości

Aktualizowanie zgłoszonych właściwości bliźniaczej reprezentacji urządzenia

Otrzymywanie powiadomienia o zmianach żądanych właściwości

Odbieranie wszystkich poprawek za pomocą pojedynczej procedury obsługi zdarzeń

Odbieranie zdarzenia, jeśli cokolwiek się zmienia w ramach grupowania właściwości

Odbieranie zdarzenia dla zmiany pojedynczej właściwości

Przykłady zestawu SDK urządzeń

Tworzenie aplikacji zaplecza

Instalowanie pakietów zestawu SDK usługi

Nawiązywanie połączenia z centrum IoT

Pobieranie i aktualizowanie bliźniaczej reprezentacji urządzenia

Tworzenie zapytania bliźniaczej reprezentacji urządzenia

Przykład zestawu SDK usługi

Opinia

Dodatkowe zasoby