Erste Schritte mit Gerätezwillingen

Verwenden Sie das Geräte-SDK und Dienst-SDK von Azure IoT Hub, um Anwendungen zu entwickeln, die allgemeine Tasks von Gerätezwillingen verarbeiten. Gerätezwillinge sind JSON-Dokumente, in denen Gerätestatusinformationen gespeichert werden, z. B. Metadaten, Konfigurationen und Bedingungen. Von IoT Hub wird für jedes Gerät, das eine Verbindung herstellt, dauerhaft ein Gerätezwilling gespeichert.

Sie können Gerätezwillinge für folgende Zwecke verwenden:

• Speichern von Gerätemetadaten von Ihrem Lösungs-Back-End
• Melden von aktuellen Zustandsinformationen wie verfügbare Funktionen und Bedingungen, wie die verwendete Verbindungsmethode, von Ihrer Geräte-App
• Synchronisieren des Zustands von Workflows mit langer Ausführungsdauer, wie Firmware- und Konfigurationsupdates, zwischen einer Geräte-App und einer Back-End-App
• Abfragen von Metadaten, der Konfiguration oder des Status des Geräts

Weitere Informationen zu Gerätezwillingen, einschließlich der Verwendung von Gerätezwillingen, finden Sie unter Verstehen und Verwenden von Gerätezwillingen in IoT Hub.

Hinweis

Die in diesem Artikel beschriebenen Features stehen nur im Standard-Tarif von IoT Hub zur Verfügung. Weitere Informationen zu den IoT Hub-Tarifen „Basic“ und „Standard/Free“ finden Sie unter Wählen des richtigen IoT Hub-Tarifs für Ihre Lösung.

In diesem Artikel erfahren Sie, wie Sie zwei Arten von Anwendungen entwickeln:

• Geräte-Apps können Anfragen zum Aktualisieren der gewünschten Eigenschaften verarbeiten und mit Änderungen auf gemeldete Eigenschaften reagieren.
• Dienst-Apps können Tags von Gerätezwillingen aktualisieren, neue gewünschte Eigenschaften festlegen und Geräte basierend auf Werten von Gerätezwillingen abfragen.

Hinweis

Dieser Artikel soll die Beispiele der Azure IoT-SDKs ergänzen, auf die in diesem Artikel verwiesen wird. Sie können SDK Tools verwenden, um Geräte- und Back-End-Anwendungen zu erstellen.

Voraussetzungen

• Einen IoT-Hub. Für einige SDK-Aufrufe ist die primäre IoT Hub-Verbindungszeichenfolge erforderlich. Notieren Sie sich daher die Verbindungszeichenfolge.

• Ein registriertes Gerät. Für einige SDK-Aufrufe ist die primäre Geräteverbindungszeichenfolge erforderlich. Notieren Sie sich daher die Verbindungszeichenfolge.

• Verbindungszeichenfolge des IoT Hub-Diensts

  In diesem Artikel erstellen Sie einen Back-End-Dienst, der einem Gerätezwilling die gewünschten Eigenschaften hinzufügt und anschließend die Identitätsregistrierung abfragt, um alle Geräte mit gemeldeten Eigenschaften zu ermitteln, die entsprechend aktualisiert wurden. Ihr Dienst benötigt die Berechtigung Dienstverbindung, um die gewünschten Eigenschaften eines Gerätezwillings ändern zu können, sowie die Berechtigung Lesevorgänge in Registrierung, um die Identitätsregistrierung abfragen zu können. Da keine SAS-Standardrichtlinie mit nur diesen beiden Berechtigungen zur Verfügung steht, müssen Sie eine erstellen.

  Gehen Sie wie folgt vor, um eine SAS-Richtlinie zu erstellen, die die Berechtigungen Dienstverbindung und Lesevorgänge in Registrierung gewährt, und eine Verbindungszeichenfolge für diese Richtlinie abzurufen:

  1. Wählen Sie im Azure-Portal die Option „Ressourcengruppen“ aus. Wählen Sie die Ressourcengruppe aus, in der sich der Hub befindet, und wählen Sie dann in der Liste der Ressourcen Ihren Hub aus.

  2. Wählen Sie im linken Bereich Ihres Hubs SAS-Richtlinien aus.

  3. Wählen Sie im Menü oberhalb der Richtlinienliste die Option Richtlinie für den gemeinsamen Zugriff hinzufügen aus.

  4. Geben Sie rechts im Bereich Richtlinie für den gemeinsamen Zugriff hinzufügen einen aussagekräftigen Namen für Ihre Richtlinie ein, wie z. B. "serviceAndRegistryRead". Wählen Sie unter Berechtigungen die Berechtigungen Registry Read und Service Connect aus und klicken Sie anschließend auf Hinzufügen.

  5. Wählen Sie Ihre neue Richtlinie aus der Liste der Richtlinien aus.

  6. Wählen Sie das Kopiersymbol für Primäre Verbindungszeichenfolge aus, und speichern Sie den Wert.

  Weitere Informationen zu SAS-Richtlinien und Berechtigungen für IoT-Hubs finden Sie unter Steuer des Zugriffs auf IoT Hub mithilfe von Shared Access Signatures.

• Wenn Ihre Anwendung das MQTT-Protokoll verwendet, stellen Sie sicher, dass der Port 8883 in Ihrer Firewall geöffnet ist. Das MQTT-Protokoll kommuniziert über den Port 8883. In einigen Netzwerkumgebungen von Unternehmen oder Bildungseinrichtungen ist dieser Port unter Umständen blockiert. Weitere Informationen und Problemumgehungen finden Sie unter Herstellen einer Verbindung mit IoT Hub (MQTT).

• Anforderungen an Language SDK:

  • .NET SDK: erfordert Visual Studio.
  • Python SDK - Die Python-Version 3.7 oder höher wird empfohlen. Stellen Sie je nach Einrichtung sicher, dass die 32-Bit- bzw. die 64-Bit-Installation verwendet wird. Fügen Sie Python Ihrer plattformspezifischen Umgebungsvariablen hinzu, wenn Sie während der Installation dazu aufgefordert werden.
  • Java: erfordert das Java SE Development Kit 8. Wählen Sie unter Langfristiger Support unbedingt Java 8 aus, um zu den Downloads für JDK 8 zu gelangen.
  • Node.js: erfordert die Node.js-Version 10.0.x oder höher.

Übersicht

Dieser Artikel beschreibt, wie Sie Azure IoT-SDK für .NET verwenden, um Geräte- und Back-End-Dienstanwendungscode für Gerätezwillinge zu erstellen.

Erstellen einer Geräteanwendung

Geräteanwendungen können von Zwillingen gemeldete Eigenschaften lesen und schreiben und über die gewünschten Änderungen der Zwillingseigenschaften benachrichtigt werden, die von einer Back-End-Anwendung oder IoT Hub festgelegt werden.

In diesem Abschnitt wird beschrieben, wie Sie Geräteanwendungscode verwenden, um:

• Einen Gerätezwilling abzurufen und die gemeldeten Eigenschaften zu untersuchen
• Gemeldete Eigenschaften von Gerätezwillingen zu aktualisieren
• Einen Rückrufhandler zum Aktualisieren gewünschter Eigenschaften zu erstellen

Hinzufügen des NuGet-Gerätepakets

Geräteclientanwendungen, die in C# geschrieben wurden, erfordern das NuGet-Paket Microsoft.Azure.Devices.Client.

Mit einem Gerät verbinden

Die Klasse DeviceClient macht alle Methoden verfügbar, die für die Interaktion mit Gerätezwillingen des Geräts erforderlich sind.

Stellen Sie eine Verbindung zu dem Gerät mithilfe der Methode CreateFromConnectionString sowie der Geräteverbindungszeichenfolge und dem Verbindungstransportprotokoll her.

Der Transportprotokollparameter CreateFromConnectionString TransportType unterstützt die folgenden Transportprotokolle:

• Mqtt
• Mqtt_WebSocket_Only
• Mqtt_Tcp_Only
• Amqp
• Amqp_WebSocket_Only
• Amqp_Tcp_Only

Das Http1-Protokoll wird für Aktualisierungen von Gerätezwillingen nicht unterstützt.

In diesem Beispiel wird mithilfe des Mqtt-Transportprotokolls eine Verbindung mit einem Gerät hergestellt.

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

Abrufen eines Gerätezwillings und Untersuchung der gemeldeten Eigenschaften

Rufen Sie GetTwinAsync auf, um die aktuellen Eigenschaften des Gerätezwillings abzurufen. Ein Twin-Objekt hat vieleEigenschaften, mit denen Sie auf bestimmte Bereiche der Twin JSON-Daten zugreifen können, einschließlich Properties, Status, Tags und Version.

In diesem Beispiel werden Eigenschaften von Gerätezwillingen abgerufen und die Zwillingswerte im JSON-Format gedruckt.

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

Aktualisieren gemeldeter Eigenschaften von Gerätezwillingen

So aktualisieren Sie eine gemeldete Eigenschaften eines Gerätezwillings:

1. Erstellen Sie ein TwinCollection-Objekt für die Aktualisierung der gemeldeten Eigenschaft
2. Aktualisieren Sie eine oder mehrere gemeldete Eigenschaften innerhalb des TwinCollection-Objekts
3. Verwenden Sie UpdateReportedPropertiesAsync, um Änderungen an der gemeldeten Eigenschaft an den IoT Hub-Dienst zu übertragen

Zum Beispiel:

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

Erstellen eines Rückrufhandlers zum Aktualisieren gewünschter Eigenschaften

Erstellen Sie einen Rückrufhandler zur Aktualisierung gewünschter Eigenschaften, der ausgeführt wird, wenn eine gewünschte Eigenschaft im Gerätezwilling geändert wird, indem der Name der Rückrufhandlermethode an SetDesiredPropertyUpdateCallbackAsync übergeben wird.

Mit diesem Aufruf wird das System beispielsweise so eingerichtet, dass eine Methode mit dem NamenOnDesiredPropertyChangedAsync benachrichtigt wird, wenn eine gewünschte Eigenschaft geändert wird.

await _deviceClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

Die Eigenschaften des Zwillings werden als TwinCollection an die Rückrufmethode übergeben und können als KeyValuePair-Strukturen untersucht werden.

In diesem Beispiel wird die Aktualisierung der gewünschten Eigenschaften als TwinCollection empfangen. Anschließend werden die Aktualisierungen durchlaufen und die KeyValuePair-Auflistung gedruckt. Nach dem Durchlaufen der KeyValuePair-Auflistung ruft der Code UpdateReportedPropertiesAsync auf, um die DateTimeLastDesiredPropertyChangeReceived gemeldete Eigenschaft zu aktualisieren, um den letzten Aktualisierungszeitpunkt auf dem neuesten Stand zu halten.

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

Beispiel für ein SDK-Gerät

Das Azure IoT SDK für .NET bietet ein praktisches Beispiel für eine Geräte-App, die Tasks von Gerätezwillingen verarbeitet. Weitere Informationen finden Sie unter TwinSample.

Erstellen einer Back-End-Anwendung

Eine Back-End-Anwendung:

• Stellt über IoT Hub eine Verbindung mit einem Gerät her
• Kann von Geräten gemeldete und gewünschte Eigenschaften lesen, die gewünschten Eigenschaften des Geräts schreiben und Geräteabfragen ausführen

Die Klasse RegistryManager macht alle Methoden verfügbar, die für die Erstellung einer Back-End-Anwendung zur Interaktion mit Gerätezwillingen des Diensts erforderlich sind.

In diesem Abschnitt wird beschrieben, wie Sie Back-End-Anwendungscode erstellen, um:

• Felder für Gerätezwillinge zu lesen und zu aktualisieren
• Zwillingsabfragen zu erstellen

Hinzufügen des NuGet-Dienstpakets

Back-End-Dienstanwendungen erfordern das NuGet-Paket Microsoft.Azure.Devices.

Herstellen einer Verbindung mit dem IoT-Hub

Verbinden Sie eine Back-End-Anwendung mit einem Gerät mithilfe von CreateFromConnectionString. Geben Sie als Parameter die IoT Hub-Dienstverbindungszeichenfolge an, die Sie im Abschnitt „Voraussetzungen“ erstellt haben.

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

Lesen und Aktualisieren von Feldern für Gerätezwillinge

Sie können die aktuellen Felder für Gerätezwillinge in einem Twin-Objekt abrufen, indem Sie GetTwinAsync aufrufen.

Die Twin-Klasse enthält Eigenschaften, die jedem Abschnitt eines Gerätezwillings entsprechen. Verwenden Sie die Twin-Klasseneigenschaften zum Anzeigen und Aktualisieren von Feldern für Gerätezwillinge. Sie können die Twin-Objekteigenschaften verwenden, um mehrere Zwillingsfelder zu aktualisieren, bevor Sie die Aktualisierungen mithilfe von UpdateTwinAsync auf das Gerät schreiben.

Rufen Sie nach der Aktualisierung der Zwillingsfelder UpdateTwinAsync auf, um die Aktualisierungen des Twin-Objektfelds zurück auf ein Gerät zu schreiben. Verwenden Sie die try- und catch-Logik, die mit einem Fehlerhandler gekoppelt ist, um falsch formatierte Patchfehler aus UpdateTwinAsync abzufangen.

Lesen und Aktualisieren von Tags für Gerätezwillinge

Verwenden Sie die Eigenschaft Tags von Gerätezwillingen, um Informationen über Geräte-Tags zu lesen und zu schreiben.

Aktualisieren von Tags mithilfe eines Zwillingsobjekts

In diesem Beispiel wird ein location-Tagpatch erstellt und dem Twin-Objekt mithilfe der Tags-Eigenschaft zugewiesen. Anschließend wird der Patch mit UpdateTwinAsync angewendet.

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

Aktualisieren von Tags mithilfe einer JSON-Zeichenfolge

Sie können einen JSON-formatierten Patch zur Aktualisierung von Informationen eines Gerätezwillings erstellen und anwenden. IoT Hub analysiert und wendet den Patch an, wenn er ordnungsgemäß formatiert ist.

In diesem Beispiel wird GetTwinAsync aufgerufen, um die aktuellen Felder des Gerätezwillings in einem Twin-Objekt abzurufen und ein JSON-formatiertes tag-Patch mit Informationen zur Region und dem Werksstandort zu erstellen. Es ruft dann UpdateTwinAsync auf, um den Patch anzuwenden und schließlich den Gerätezwilling zu aktualisieren. Falls UpdateTwinAsync fehlschlägt, wird eine Fehlermeldung angezeigt.

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

Ansehen und Aktualisieren der gewünschten Eigenschaften von Gerätezwillingen

Verwenden Sie die Eigenschaft TwinProperties.Desired des Gerätezwillings, um die gewünschten Eigenschafteninformationen des Geräts zu lesen und zu schreiben. Aktualisieren Sie die Desired-Eigenschaften des Zwillings mithilfe eines JSON-formatierten Patches.

In diesem Beispiel wird GetTwinAsync aufgerufen, um die aktuellen Felder des Gerätezwillings in einem Twin-Objekt abzurufen und die gewünschte speed-Eigenschaft des Zwillings zu aktualisieren. Es ruft dann UpdateTwinAsync auf, um das Twin-Objekt anzuwenden und schließlich den Gerätezwilling zu aktualisieren.

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

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

Andere Methoden zur Aktualisierung von Zwillingen

Sie können Zwillinge auch mit den folgenden SDK-Methoden aktualisieren:

• Rufen Sie ReplaceTwinAsync auf, um den gesamten Gerätezwilling zu ersetzen.
• Rufen Sie UpdateTwins2Async auf, um eine Liste der Zwillinge zu aktualisieren, die zuvor im System erstellt wurden.

Erstellen einer Zwillingsabfrage

In diesem Abschnitt werden zwei Zwillingsabfragen veranschaulicht. Zwillingsabfragen sind SQL-ähnliche Abfragen, die ein Resultset von Gerätezwillingen zurückgeben.

Rufen Sie zum Erstellen einer Zwillingsabfrage CreateQuery auf, um eine SQL-Abfrage zu senden und eine IQuery-Schnittstelle abzurufen. Sie können optional CreateQuery mit einem zweiten Parameter aufrufen, um eine maximale Anzahl von Elementen pro Seite anzugeben.

Rufen Sie als Nächstes die Methode GetNextAsTwinAsync oder GetNextAsJsonAsync so oft auf, wie erforderlich, um alle Zwillingsergebnisse abzurufen.

• GetNextAsTwinAsync, um das nächste Ergebnis als Twin -Objekte abzurufen.
• GetNextAsJsonAsync, um das nächste Ergebnis als JSON-Zeichenfolgen abzurufen.

Die IQuery-Schnittstelle enthält die boolesche Eigenschaft HasMoreResults, mit der Sie überprüfen können, ob mehr Zwillingsergebnisse abgerufen werden können.

In diesem Beispiel wählt die Abfrage nur die Gerätezwillinge von Geräten aus, die sich im Werk Redmond43 befinden.

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

In diesem Beispiel wird die erste Abfrage so optimiert, dass nur die Geräte ausgewählt werden, die auch über ein Mobilfunknetz verbunden sind.

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

Beispiel des SDK-Diensts

Das Azure IoT SDK für .NET bietet ein praktisches Beispiel für eine Dienst-App, die Aufgaben von Gerätezwillingen verarbeitet. Weitere Informationen finden Sie unter Registry Manager Beispiel.

Übersicht

Dieser Artikel beschreibt, wie Sie Azure IoT-SDK für Java verwenden, um Geräte- und Back-End-Dienstanwendungscode für Gerätezwillinge zu erstellen.

Erstellen einer Geräteanwendung

Geräteanwendungen können von Zwillingen gemeldete Eigenschaften lesen und schreiben und über die gewünschten Änderungen der Zwillingseigenschaften benachrichtigt werden, die von einer Back-End-Anwendung oder IoT Hub festgelegt werden.

In diesem Abschnitt wird beschrieben, wie Sie Geräteanwendungscode erstellen, um:

• Einen Gerätezwilling abzurufen und anzusehen
• Gemeldete Eigenschaften von Gerätezwillingen zu aktualisieren
• Aktualisierungen der gewünschten Eigenschaften zu abonnieren

Die Klasse DeviceClient macht alle Methoden verfügbar, die für die Interaktion mit Gerätezwillingen des Geräts erforderlich sind.

Geräte-Importanweisungen

Verwenden Sie die folgenden Geräte-Importanweisungen, um auf das Azure IoT SDK für Java zuzugreifen.

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

Stellen Sie eine Verbindung mit dem Gerät her.

So stellen Sie eine Verbindung zu einem Gerät her:

1. Verwenden Sie IotHubClientProtocol, um ein Transportprotokoll auszuwählen. Zum Beispiel:

   IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
   

2. Verwenden Sie den DeviceClient-Konstruktor, um die primäre Verbindungszeichenfolge und das Protokoll des Geräts hinzuzufügen.

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

3. Stellen Sie für das Gerät mithilfe von open eine Verbindung mit dem IoT-Hub her. Wenn der Client bereits geöffnet ist, tut die Methode nichts.

   client.open(true);
   

Abrufen und Ansehen eines Gerätezwillings

Rufen Sie nach dem Öffnen der Clientverbindung getTwin auf, um die aktuellen Eigenschaften des Zwillings in einem Twin-Objekt abzurufen.

Zum Beispiel:

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

Aktualisieren der gemeldeten Eigenschaften des Gerätezwillings

Nach dem Abrufen des aktuellen Zwillings können Sie mit der Aktualisierung gemeldeter Eigenschaften beginnen. Sie können gemeldete Eigenschaften auch aktualisieren, ohne den aktuellen Zwilling zu erhalten, solange Sie über die richtige Version der gemeldeten Eigenschaft verfügen. Wenn Sie gemeldete Eigenschaften senden und den Fehler „Fehler bei Vorbedingung" erhalten, ist die Version der gemeldeten Eigenschaft veraltet. Rufen Sie in diesem Fall die neueste Version ab, indem Sie getTwin erneut aufrufen.

So aktualisieren Sie gemeldete Eigenschaften:

1. Rufen Sie getReportedProperties auf, um die gemeldeten Eigenschaften des Zwillings in einem TwinCollection-Objekt abzurufen.

2. Verwenden Sie put, um eine gemeldete Eigenschaft innerhalb des TwinCollection-Objekts zu aktualisieren. Rufen Sie put jede Aktualisierung einer gemeldeten Eigenschaft auf.

3. Verwenden Sie updateReportedProperties, um die Gruppe der gemeldeten Eigenschaften anzuwenden, die mithilfe der put-Methode aktualisiert wurden.

Zum Beispiel:

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

Aktualisierungen der gewünschten Eigenschaften abonnieren

Rufen Sie subscribeToDesiredProperties auf, um die Änderungen gewünschter Eigenschaften zu abonnieren. Dieser Client empfängt jedes Mal einen Rückruf mit einem Twin-Objekt, wenn eine gewünschte Eigenschaft aktualisiert wird. Dieser Rückruf enthält entweder den vollständigen gewünschten Eigenschaftensatz oder nur die aktualisierte gewünschte Eigenschaft, je nachdem, wie die gewünschte Eigenschaft geändert wurde.

In diesem Beispiel werden die Änderungen der gewünschten Eigenschaft abonniert. Alle Änderungen der gewünschten Eigenschaft werden an einen Handler mit dem Namen DesiredPropertiesUpdatedHandler übergeben.

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

In diesem Beispiel ruft der DesiredPropertiesUpdatedHandler Rückrufhandler für Änderungen gewünschter Eigenschaften getDesiredProperties zum Abrufen der Eigenschaftsänderungen auf und druckt dann die aktualisierten Eigenschaften der Zwillinge.

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

Beispiel für ein SDK-Gerät

Das Azure IoT SDK für Java enthält ein praktisches Beispiel zum Testen der in diesem Artikel beschriebenen Konzepte für Geräte-Apps. Weitere Informationen finden Sie unter Beispiel für Gerätezwilling.

Erstellen einer Back-End-Anwendung

In diesem Abschnitt wird beschrieben, wie Sie eine Back-End-Anwendung erstellen, die:

• Tags von Gerätezwillingen aktualisiert
• Geräte abfragt, indem Sie Filter für die Tags und Eigenschaften verwendet

Die Klasse ServiceClient DeviceTwin enthält Methoden, mit denen Dienste auf Gerätezwillinge zugreifen können.

Dienst-Importanweisungen

Verwenden Sie die folgenden Dienst-Importanweisungen, um auf das Azure IoT SDK für Java zuzugreifen.

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

Herstellen einer Verbindung mit dem Dienstclient für den IoT-Hub

So stellen Sie eine Verbindung mit IoT Hub her, um Informationen zu Gerätezwillingen anzuzeigen und zu aktualisieren:

1. Erstellen Sie ein DeviceTwinClientOptions-Objekt. Legen Sie alle Optionen fest, die für Ihre Anwendung erforderlich sind. Diese Optionen werden an das DeviceTwin-Objekt übergeben.
2. Verwenden Sie einen DeviceTwin-Konstruktor, um die Verbindung mit IoT Hub zu erstellen. Das DeviceTwin-Objekt führt die Kommunikation mit Ihrem IoT Hub durch. Geben Sie als Parameter die IoT Hub-Dienstverbindungszeichenfolge an, die Sie im Abschnitt „Voraussetzungen“ erstellt haben, und führen Sie das DeviceTwinClientOptions-Objekt aus.
3. Das DeviceTwinDevice-Objekt stellt den Gerätezwilling mit seinen Eigenschaften und Tags dar.

Zum Beispiel:

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

Aktualisieren der Felder von Gerätezwillingen

So aktualisieren Sie die Felder von Gerätezwillingen:

1. Verwenden Sie getTwin zum Abrufen der aktuellen Felder von Gerätezwillingen

   In diesem Beispiel werden die Felder von Gerätezwillingen abgerufen und gedruckt:

   // Get the device twin from IoT Hub
   System.out.println("Device twin before update:");
   twinClient.getTwin(device);
   System.out.println(device);
   

2. Verwenden Sie ein HashSet-Objekt für add eine Gruppe von Tagpaaren eines Zwillings

3. Verwenden Sie setTags, um eine Gruppe von Tagpaaren aus einem tags-Objekt zu einem DeviceTwinDevice-Objekt hinzuzufügen

4. Verwenden Sie updateTwin, um den Zwilling im IoT Hub zu aktualisieren

   In diesem Beispiel werden die Zwillings-Tags für die Region und das Werk für einen Gerätezwilling aktualisiert:

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

Erstellen einer Zwillingsabfrage

In diesem Abschnitt werden zwei Zwillingsabfragen veranschaulicht. Zwillingsabfragen sind SQL-ähnliche Abfragen, die ein Resultset von Gerätezwillingen zurückgeben.

Die Query-Klasse enthält Methoden, die zum Erstellen von SQL-Abfragen an IoT Hub für Zwillinge, Aufträge, Geräteaufträge oder Rohdaten verwendet werden können.

So erstellen Sie eine Geräteabfrage:

1. Verwenden Sie createSqlQuery zum Erstellen der SQL-Abfrage für den Zwilling

2. Verwenden Sie queryTwin, um die Abfrage auszuführen

3. Verwenden Sie hasNextDeviceTwin, um zu überprüfen, ob ein anderer Gerätezwilling im Resultset vorhanden ist

4. Verwenden Sie getNextDeviceTwin, um den nächsten Gerätezwilling aus dem Resultset abzurufen

Im folgenden Beispiel werden maximal 100 Geräte in den Abfragen zurückgegeben.

In diesem Beispiel wählt die Abfrage nur die Gerätezwillinge von Geräten aus, die sich im Werk Redmond43 befinden.

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

In diesem Beispiel wird die erste Abfrage so optimiert, dass nur die Geräte ausgewählt werden, die auch über ein Mobilfunknetz verbunden sind.

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

Beispiel des SDK-Diensts

Das Azure IoT SDK für Java bietet ein praktisches Beispiel für eine Dienst-App, die Aufgaben von Gerätezwillingen verarbeitet. Weitere Informationen finden Sie unter Beispiel für Gerätezwilling.

Übersicht

Dieser Artikel beschreibt, wie Sie Azure IoT-SDK für Python verwenden, um Geräte- und Back-End-Dienstanwendungscode für Gerätezwillinge zu erstellen.

Erstellen einer Geräteanwendung

Geräteanwendungen können von Zwillingen gemeldete Eigenschaften lesen und schreiben und über die gewünschten Änderungen der Zwillingseigenschaften benachrichtigt werden, die von einer Back-End-Anwendung oder IoT Hub festgelegt werden.

Die IoTHubDeviceClient-Klasse enthält Methoden, die für Gerätezwillinge verwendet werden können.

In diesem Abschnitt wird beschrieben, wie Sie Geräteanwendungscode erstellen, der:

• Einen Gerätezwilling abruft und die gemeldeten Eigenschaften untersucht
• Die gemeldeten Eigenschaften von Gerätezwillingen patcht

Mit einem Gerät verbinden

In diesem Abschnitt wird gezeigt, wie Sie eine Anwendung mit einem Gerät mithilfe eines Geräte-Primärschlüssels verbinden, der einen gemeinsamen Zugriffsschlüssel enthält.

So stellen Sie eine Verbindung zwischen einer Anwendung und einem Gerät her:

1. Rufen Sie create_from_connection_string auf, um die Verbindungszeichenfolge des Geräts hinzuzufügen
2. Rufen Sie connect auf, um den Geräteclient mit Azure IoT Hub zu verbinden

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

Abrufen eines Gerätezwillings und Untersuchen der gemeldeten Eigenschaften

Sie können Informationen zu Gerätezwillingen einschließlich Tags und Eigenschaften abrufen und untersuchen. Die abgerufenen Informationen zum Gerätezwilling entsprechen den JSON-formatierten Gerätedaten, die Sie für ein Gerät im Azure-Portal anzeigen können.

Rufen Sie get_twin auf, um den Gerätezwilling vom Azure IoT Hub-Dienst abzurufen. Die Zwillingsinformationen werden in eine Variable eingefügt, die gedruckt oder untersucht werden kann.

In diesem Beispiel wird der Gerätezwilling abgerufen und der Befehl print verwendet, um den Gerätezwilling im JSON-Format anzuzeigen.

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

Patchen der gemeldeten Eigenschaften von Gerätezwillingen

Sie können einen Patch anwenden, um die gemeldeten Eigenschaften des Geräts im JSON-Format zu aktualisieren.

So wenden Sie ein Patch zum Aktualisieren gemeldeter Eigenschaften an:

1. Weisen Sie ein JSON-Patch einer gemeldeten Eigenschaft einer Variablen zu.
2. Rufen Sie patch_twin_reported_properties auf, um den JSON-Patch auf die gemeldeten Eigenschaften anzuwenden. Dies ist ein synchroner Aufruf, was bedeutet, dass diese Funktion erst zurückgegeben wird, wenn der Patch an den Dienst gesendet und bestätigt wird.

Wenn patch_twin_reported_properties einen Fehler zurückgibt, löst diese Funktion den entsprechenden Fehler aus.

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

Sie können auch diese Methoden aufrufen, um Gerätezwillinge zu aktualisieren:

• Rufen Sie replace_twin auf, um Tags von Gerätezwillingen und die gewünschten Eigenschaften zu ersetzen.
• Rufen Sie update_twin auf, um Tags von Gerätezwillingen und die gewünschten Eigenschaften zu aktualisieren.

Patchhandler für eingehende gewünschte Eigenschaften

Rufen Sie on_twin_desired_properties_patch_received auf, um eine Handlerfunktion oder Coroutine zu erstellen, die aufgerufen werden, wenn ein Patch für die gewünschten Eigenschaften eines Zwillings empfangen wird. Der Handler verwendet ein Argument, bei dem es sich um den Zwillingspatch in Form eines JSON-Wörterbuchobjekts handelt.

In diesem Beispiel wird ein Patchhandler für die gewünschten Eigenschaften mit dem Namen twin_patch_handler eingerichtet.

Zum Beispiel:

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

Der twin_patch_handler empfängt und druckt die JSON-Aktualisierungen der gewünschten Eigenschaften.

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

Beispiele für SDK-Geräte

Das Azure IoT SDK für Python enthält die folgenden Beispiele:

• get_twin: Stellen Sie eine Verbindung mit einem Gerät her und rufen Sie die Informationen zum Zwilling ab.
• update_twin_reported_properties: Aktualisieren Sie die gemeldeten Eigenschaften des Zwillings.
• receive_twin_desired_properties: Empfangen und aktualisieren Sie die gewünschten Eigenschaften.

Erstellen einer Back-End-Anwendung

Eine Back-End-Anwendung stellt über IoT Hub eine Verbindung mit einem Gerät her und kann gemeldete und gewünschte Eigenschaften des Geräts lesen, die gewünschten Eigenschaften des Geräts schreiben und Geräteabfragen ausführen.

In diesem Abschnitt wird beschrieben, wie Sie eine Back-End-Anwendung erstellen, um:

• Die gewünschten Eigenschaften von Gerätezwillingen zu aktualisieren und anzusehen
• Geräte abzufragen, indem Sie Filter für die Tags und Eigenschaften verwenden

Die Klasse IoTHubRegistryManager macht alle Methoden verfügbar, die für die Erstellung einer Back-End-Anwendung zur Interaktion mit Gerätezwillingen des Diensts erforderlich sind.

Herstellen einer Verbindung mit dem IoT-Hub

Stellen Sie mithilfe von from_connection_string eine Verbindung mit dem IoT-Hub her. Geben Sie als Parameter die IoT Hub-Dienstverbindungszeichenfolge an, die Sie im Abschnitt „Voraussetzungen“ erstellt haben.

Zum Beispiel:

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)

Die gewünschten Eigenschaften von Gerätezwillingen zu aktualisieren und anzusehen

Sie können sowohl Tags von Gerätezwillingen als auch gewünschte Eigenschaften aus einer Back-End-Anwendung gleichzeitig mithilfe von update_twin aktualisieren.

1. Rufen Sie get_twin auf, um die aktuelle Version des Gerätezwillings abzurufen
2. Verwenden Sie die Twin-Klasse, um Tags und Eigenschaften im JSON-Format hinzuzufügen.
3. Rufen Sie update_twin auf, um den Patch auf den Gerätezwilling anzuwenden. Sie können auch replace_twin verwenden, um die gewünschten Eigenschaften und Tags für einen Gerätezwilling zu ersetzen.

In diesem Beispiel werden Informationen zu den Tags region und plant aktualisiert und eine power_level gewünschte Eigenschaft auf 1 festgelegt.

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)

Erstellen einer Zwillingsabfrage

Sie können Informationen zu Gerätezwillingen mithilfe von Zwillingsabfragen abfragen. Zwillingsabfragen sind SQL-ähnliche Abfragen, die ein Resultset von Gerätezwillingen zurückgeben.

So verwenden Sie eine Zwillingsabfrage:

1. Verwenden Sie ein QuerySpecification-Objekt, um eine SQL-ähnliche Abfrageanforderung zu definieren.

2. Verwenden Sie query_iot_hub, um einen IoT-Hub abzufragen und Informationen zu Gerätezwillingen mithilfe der SQL-ähnlichen Abfragespezifikation abzurufen.

Dieses Beispiel führt zwei Abfragen aus. Mit der ersten werden nur die Gerätezwillinge von Geräten in der Anlage Redmond43 ausgewählt. Mit der zweiten wird die Abfrage so angepasst, dass nur die Geräte ausgewählt werden, die über ein Mobilfunknetz verbunden sind. Die Ergebnisse werden nach jeder Abfrage gedruckt.

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

Beispiel des SDK-Diensts

Das Azure IoT SDK für Python bietet ein praktisches Beispiel für eine Dienst-App, die Aufgaben von Gerätezwillingen verarbeitet. Weitere Informationen finden Sie unter Registry Manager Abfragebeispiel.

Übersicht

Dieser Artikel beschreibt, wie Sie Azure IoT-SDK für Node.js verwenden, um Geräte- und Back-End-Dienstanwendungscode für Gerätezwillinge zu erstellen.

Erstellen einer Geräteanwendung

Geräteanwendungen können von Zwillingen gemeldete Eigenschaften lesen und schreiben und über die gewünschten Änderungen der Zwillingseigenschaften benachrichtigt werden, die von einer Back-End-Anwendung oder IoT Hub festgelegt werden.

In diesem Abschnitt wird beschrieben, wie Sie das Paket azure-iot-device im Azure IoT SDK für Node.js verwenden, um eine Geräteanwendung zu erstellen, um:

• Einen Gerätezwilling abzurufen und die gemeldeten Eigenschaften zu untersuchen
• Gemeldete Eigenschaften von Gerätezwillingen zu aktualisieren
• Benachrichtigung über die Änderungen gewünschter Eigenschaften zu erhalten

Installieren der SDK-Pakete

Führen Sie diesen Befehl aus, um das Geräte-SDK azure-iot-device auf Ihrem Computer zu installieren:

npm install azure-iot-device --save

Das Paket azure-iot-device enthält Objekte, die über eine Schnittstelle mit IoT-Geräten verfügen. Die Twin-Klasse enthält für Zwillinge spezifische Objekte. In diesem Abschnitt wird der Client-Klassencode beschrieben, der zum Lesen und Schreiben von Daten zu Gerätezwillingen verwendet wird.

Auswählen eines Transportprotokolls

Das Client-Objekt unterstützt die folgenden Protokolle:

• Amqp
• Http: Bei Verwendung von Http führt die Client-Instanz selten eine Überprüfung auf Nachrichten von IoT Hub durch (mindestens alle 25 Minuten).
• Mqtt
• MqttWs
• AmqpWs

Installieren Sie die erforderlichen Transportprotokolle auf Ihrem Computer.

Mit diesem Befehl wird beispielsweise das Mqtt-Protokoll installiert:

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

Weitere Informationen zu den Unterschieden zwischen der Unterstützung für MQTT, AMQP und HTTPS finden Sie unter Leitfaden zur C2D-Kommunikation und Auswählen eines Kommunikationsprotokolls.

Erstellen eines Clientmoduls

Erstellen Sie mithilfe des installierten Pakets ein Client-Modul.

Zum Beispiel:

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

Erstellen Sie ein Protokollmodul

Erstellen Sie ein Protocol-Modul mithilfe eines installierten Transportpakets.

In diesem Beispiel wird das MQTT-Protokoll zugewiesen:

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

Fügen Sie die Verbindungszeichenfolge des Geräts und das Transportprotokoll hinzu

Rufen Sie fromConnectionString auf, um Verbindungsparameter für das Gerät zu liefern:

• connStr: Eine Verbindungszeichenfolge, die „device connect“-Berechtigungen für einen IoT-Hub kapselt. Die Verbindungszeichenfolge enthält den Hostnamen, die Geräte-ID und den Schlüssel für den gemeinsamen Zugriff im folgenden Format: "HostName=<iothub_host_name>;DeviceId=<device_id>;SharedAccessKey=<device_key>".
• transportCtor: Das Transportprotokoll

In diesem Beispiel wird das Mqtt-Transportprotokoll verwendet:

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

Öffnen der Verbindung mit IoT Hub

Verwenden Sie die open-Methode, um eine Verbindung zwischen einem IoT-Gerät und IoT Hub zu öffnen. Verwenden Sie .catch(err), um einen Fehler abzufangen und den Handlercode auszuführen.

Zum Beispiel:

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

Abrufen eines Gerätezwillings und Untersuchen der gemeldeten Eigenschaften

Rufen Sie getTwin auf, um aktuelle Informationen zu Gerätezwillingen in einem Twin-Objekt abzurufen.

Zum Beispiel:

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

Aktualisieren gemeldeter Eigenschaften von Gerätezwillingen

Verwenden Sie update, um die gemeldeten Eigenschaften des Gerätezwillings zu aktualisieren. Fügen Sie einen JSON-formatierten Patch als ersten Parameter und eine Rückrufmethode für den Status der Funktionsausführung als zweiten Parameter zur Methode hinzu.

In diesem Beispiel wird ein JSON-formatierter Patch für den Gerätezwilling in der Variable patch gespeichert. Der Patch enthält einen connectivity Updatewert von cellular für den Gerätezwilling. Der Patch- und Fehlerhandler werden an die update-Methode übergeben. Wenn ein Fehler auftritt, wird eine Fehlermeldung in der Konsole angezeigt.

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

Benachrichtigung über die Änderungen gewünschter Eigenschaften zu erhalten

Erstellen Sie einen Ereignislistener zur Aktualisierung gewünschter Eigenschaften, der ausgeführt wird, wenn eine gewünschte Eigenschaft im Geräte geändert wird, indem der Name der Rückrufhandlermethode an twin.on übergeben wird.

Der gewünschte Ereignislistener für die Eigenschaft kann eine der folgenden Formen annehmen:

• Empfangen aller Patches mit einem einzelnen Ereignishandler
• Empfangen eines Ereignisses, wenn sich etwas bei einer Eigenschaftengruppierung ändert
• Empfangen eines Ereignisses für eine einzelne Änderung einer Eigenschaft

Empfangen aller Patches mit einem einzelnen Ereignishandler

Sie können einen Listener erstellen, um jede Änderung einer gewünschten Eigenschaft zu erhalten.

In diesem Beispielcode werden alle Eigenschaften ausgegeben, die vom Dienst empfangen werden.

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

Empfangen eines Ereignisses, wenn sich etwas bei einer Eigenschaftengruppierung ändert

Sie können einen Listener erstellen, um ein Ereignis zu empfangen, wenn sich etwas bei einer Eigenschaftsgruppierung ändert.

Zum Beispiel:

1. Die Eigenschaften minTemperature und maxTemperature befinden sich unter einer Eigenschaftsgruppierung mit dem Namen properties.desired.climate changes.

2. Eine Back-End-Dienstanwendung wendet diesen Patch an, um die gewünschten Eigenschaften minTemperature und maxTemperature zu aktualisieren:

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

3. Dieser Code richtet einen Ereignislistener für Änderungen der gewünschten Eigenschaften ein, der für Änderungen innerhalb der properties.desired.climate-Eigenschaftengruppierung ausgelöst wird. Wenn innerhalb dieser Gruppe eine Änderung der gewünschten Eigenschaft vorliegt, werden Meldungen zur minimalen und maximalen Temperaturänderung in der Konsole angezeigt:

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

Empfangen eines Ereignisses für eine einzelne Änderung einer Eigenschaft

Sie können einen Listener für eine einzelne Änderung einer Eigenschaft einrichten. In diesem Beispiel wird der Code für dieses Ereignis nur ausgeführt, wenn der boolesche Wert fanOn Teil des Patches ist. Der Code gibt den neuen gewünschten Zustand fanOn aus, wenn der Dienst ihn aktualisiert.

1. Eine Back-End-Anwendung wendet den Patch für die gewünschten Eigenschaften an:

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

2. Der Listener wird nur ausgelöst, wenn sich die fanOn-Eigenschaft ändert:

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

Beispiele für Geräte-SDK

Das Azure IoT SDK für Node.js enthält zwei Beispiele für Gerätezwillinge:

• Einfacher beispielhafter Gerätezwilling

• Einfacher beispielhafter Gerätezwilling mit SAS

Erstellen einer Back-End-Anwendung

Eine Back-End-Anwendung stellt über IoT Hub eine Verbindung mit einem Gerät her und kann gemeldete und gewünschte Eigenschaften des Geräts lesen, die gewünschten Eigenschaften des Geräts schreiben und Geräteabfragen ausführen.

In diesem Abschnitt wird beschrieben, wie Sie eine Back-End-Anwendung erstellen, die:

• Einen Gerätezwilling abruft und aktualisiert
• Eine Zwillingsabfrage erstellt

Dienst-SDK-Pakete installiert

Führen Sie diesen Befehl aus, um azure-iothub auf Ihrem Computer zu installieren:

npm install azure-iothub --save

Die Registry-Klasse macht alle Methoden verfügbar, die für die Interaktion mit Gerätezwillingen einer Back-End-Anwendung erforderlich sind.

Herstellen einer Verbindung mit dem IoT-Hub

Verwenden Sie fromConnectionString, um eine Verbindung mit dem IoT-Hub herzustellen. Geben Sie als Parameter die IoT Hub-Dienstverbindungszeichenfolge an, die Sie im Abschnitt „Voraussetzungen“ erstellt haben.

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

Abrufen und Aktualisieren eines Gerätezwillings

Sie können einen Patch erstellen, der die Aktualisierungen für Tags und gemeldete Eigenschaften eines Gerätezwillings enthält.

So aktualisieren Sie einen Gerätezwilling:

1. Rufen Sie getTwin auf, um das Zwillingsobjekt abzurufen.

• Formatieren Sie einen Patch, der die Aktualisierung des Gerätezwillings enthält. Der Patch ist in JSON formatiert, wie in der Twin-Klassebeschrieben. Ein Patch eines Back-End-Diensts kann Aktualisierungen für Tags und gewünschte Eigenschaften enthalten. Weitere Informationen zum Patchformat finden Sie unter Format von Tags und Eigenschaften.

1. Rufen Sie update auf, um den Gerätezwilling mit dem Patch zu aktualisieren.

In diesem Beispiel wird der Gerätezwilling für myDeviceId abgerufen. Anschließend wird ein Patch auf die Zwillinge angewendet, der location Tagaktualisierungen von region: 'US', plant: 'Redmond43' enthält.

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

Erstellen einer Zwillingsabfrage

Sie können SQL-ähnliche Geräteabfragen erstellen, um Informationen zu Gerätezwillingen zu sammeln.

Verwenden Sie createQuery, um eine Abfrage zu erstellen, die auf einer IoT-Hubinstanz ausgeführt werden kann, um Informationen zu Geräten oder Aufträgen zu ermitteln.

createQuery enthält zwei Parameter:

• sqlQuery: Die Abfrage, die als SQL-Zeichenfolge geschrieben wurde.
• pageSize: Die gewünschte Anzahl von Ergebnissen pro Seite (optional, Standard: 1000, max.: 10000).

Wenn der Parameter pageSize angegeben ist, enthält das Abfrageobjekt eine hasMoreResults boolesche Eigenschaft, die Sie überprüfen können. Sie können die nextAsTwin-Methode verwenden, um die nächste Seite mit den Ergebnissen so oft wie nötig abzurufen, um alle Ergebnisse abzurufen. Die Methode next ist für Ergebnisse verfügbar, die keine Gerätezwillinge sind, z. B. die Ergebnisse von Aggregationsabfragen.

In diesem Beispiel wählt die Abfrage nur die Gerätezwillinge von Geräten aus, die sich im Werk Redmond43 befinden.

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

In diesem Beispiel wird die erste Abfrage so optimiert, dass nur die Geräte ausgewählt werden, die auch über ein Mobilfunknetz verbunden sind.

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

Beispiel für Dienst-SDK

Das Azure IoT SDK für Node.js bietet ein praktisches Beispiel für eine Dienst-App, die Aufgaben von Gerätezwillingen verarbeitet. Weitere Informationen finden Sie unter Back-End-Dienst für Gerätezwilling. Dieses Projekt wird verwendet, um Patchupdates für Gerätezwillinge für ein bestimmtes Gerät zu senden.