Erste Schritte mit Gerätezwillingen (.NET)

Artikel
03/18/2023

Gerätezwillinge sind JSON-Dokumente, in denen Gerätestatusinformationen gespeichert werden, einschließlich Metadaten, Konfigurationen und Bedingungen. Von IoT Hub wird für jedes Gerät, das eine Verbindung herstellt, dauerhaft ein Gerätezwilling gespeichert.

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.

Verwenden Sie Gerätezwillinge für Folgendes:

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

Gerätezwillinge sind für die Synchronisierung und zum Abfragen von Gerätekonfigurationen und -bedingungen ausgelegt. Weitere Informationen zu Gerätezwillingen, einschließlich der Verwendung von Gerätezwillingen, finden Sie unter Verstehen und Verwenden von Gerätezwillingen in IoT Hub.

IoT-Hubs speichern Gerätezwillinge, die die folgenden Elemente enthalten:

Tags. Gerätemetadaten, auf die nur vom Lösungs-Back-End zugegriffen werden kann.
Gewünschte Eigenschaften JSON-Objekte, die vom Lösungs-Back-End geändert und von der Geräte-App überwacht werden können.
Gemeldete Eigenschaften JSON-Objekte, die von der Geräte-App geändert und vom Lösungs-Back-End gelesen werden können.

Tags und Eigenschaften können keine Arrays, aber geschachtelte Objekte enthalten.

Die folgende Abbildung zeigt die Organisation des Gerätezwillings:

Screenshot eines Konzeptdiagramms für Gerätezwillinge.

Außerdem können mit dem Lösungs-Back-End Gerätezwillinge basierend auf allen obigen Daten abgefragt werden. Weitere Informationen zu Gerätezwillingen finden Sie unter Grundlegendes zu Gerätezwillingen. Weitere Informationen zu Abfragen finden Sie unter IoT Hub-Abfragesprache.

In diesem Artikel lernen Sie Folgendes:

Verwenden Sie eine simulierte Geräte-App, um ihren Konnektivitätskanal als gemeldete Eigenschaft auf dem Gerätezwilling zu melden.
Fragen Sie Geräte von Ihrer Back-End-App ab, indem Sie Filter für die zuvor erstellten Tags und Eigenschaften verwenden.

In diesem Artikel erstellen Sie zwei .NET-Konsolen-Apps:

AddTagsAndQuery: eine Back-End-App, die Tags hinzufügt und Gerätezwillinge abfragt.
ReportConnectivity: eine simulierte Geräte-App, die eine Verbindung mit Ihrem IoT-Hub herstellt und seine Konnektivitätsbedingung meldet.

Hinweis

Weitere Informationen zu den SDK-Tools zum Erstellen von Geräten und Back-End-Apps finden Sie unter Azure IoT SDKs.

Voraussetzungen

Visual Studio.
Einen IoT Hub. Erstellen Sie einen mit der CLI oder dem Azure-Portal.
Ein registriertes Gerät. Registrieren Sie eins im Azure-Portal.
Stellen Sie sicher, dass der Port 8883 in Ihrer Firewall geöffnet ist. Das Beispielgerät in diesem Artikel verwendet das MQTT-Protokoll, das über Port 8883 kommuniziert. 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).

Abrufen der IoT-Hub-Verbindungszeichenfolge

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:

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.
Wählen Sie im linken Bereich Ihres Hubs SAS-Richtlinien aus.
Wählen Sie im Menü oberhalb der Richtlinienliste die Option Richtlinie für den gemeinsamen Zugriff hinzufügen aus.
Geben Sie unter 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.
Wählen Sie Ihre neue Richtlinie aus der Liste der Richtlinien aus.
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 Access Control und Berechtigungen.

Erstellen einer Geräte-App, die gemeldete Eigenschaften aktualisiert

In diesem Abschnitt erstellen Sie eine .NET-Konsolen-App, die sich als Ihre myDeviceId mit Ihrem Hub verbindet und dann dessen gemeldete Eigenschaften aktualisiert, um zu bestätigen, dass sie über ein Mobilfunknetz verbunden ist.

Öffnen Sie Visual Studio, und wählen Sie Neues Projekt erstellen aus.
Wählen Sie Konsolen-App (.NET Framework) und dann Weiter aus.
Geben Sie dem Projekt unter Neues Projekt konfigurieren den Namen ReportConnectivity, und wählen Sie Weiter aus.
Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt ReportConnectivity, und wählen Sie dann NuGet-Pakete verwalten aus.
Behalten Sie das Standard-.NET Framework bei, und wählen Sie Erstellen aus, um das Projekt zu erstellen.
Wählen Sie Durchsuchen aus, suchen Sie nach dem Paket Microsoft.Azure.Devices.Client, und wählen Sie es aus. Wählen Sie Installieren aus.

In diesem Schritt wird das NuGet-Paket Azure IoT-Geräte-SDK heruntergeladen und installiert sowie ein Verweis auf das Paket und seine Abhängigkeiten hinzugefügt.

Fügen Sie am Anfang der Datei Program.cs die folgenden using-Anweisungen hinzu:

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

Fügen Sie der Program -Klasse die folgenden Felder hinzu. Ersetzen Sie {device connection string} durch die Geräteverbindungszeichenfolge, die Ihnen beim Registrieren eines Geräts im IoT-Hub angezeigt wurde:
```
static string DeviceConnectionString = "HostName=<yourIotHubName>.azure-devices.net;DeviceId=<yourIotDeviceName>;SharedAccessKey=<yourIotDeviceAccessKey>";
static DeviceClient Client = null;
```

Fügen Sie der Program -Klasse die folgende Methode hinzu:

public static async void InitClient()
{
    try
    {
        Console.WriteLine("Connecting to hub");
        Client = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
          TransportType.Mqtt);
        Console.WriteLine("Retrieving twin");
        await Client.GetTwinAsync();
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error in sample: {0}", ex.Message);
    }
}

Das Client-Objekt macht alle Methoden verfügbar, die für die Interaktion mit Gerätezwillingen des Geräts erforderlich sind. Der oben gezeigte Code initialisiert das Client-Objekt und ruft dann den Gerätezwilling für myDeviceId ab.

Fügen Sie der Program -Klasse die folgende Methode hinzu:

public static async void ReportConnectivity()
{
    try
    {
        Console.WriteLine("Sending connectivity data as reported property");

        TwinCollection reportedProperties, connectivity;
        reportedProperties = new TwinCollection();
        connectivity = new TwinCollection();
        connectivity["type"] = "cellular";
        reportedProperties["connectivity"] = connectivity;
        await Client.UpdateReportedPropertiesAsync(reportedProperties);
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error in sample: {0}", ex.Message);
    }
}

Der Code oben aktualisiert die für myDeviceId gemeldete Eigenschaft mit den Konnektivitätsinformationen.

Fügen Sie abschließend der Main -Methode die folgenden Zeilen hinzu:

try
{
    InitClient();
    ReportConnectivity();
}
catch (Exception ex)
{
    Console.WriteLine();
    Console.WriteLine("Error in sample: {0}", ex.Message);
}
Console.WriteLine("Press Enter to exit.");
Console.ReadLine();

Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf Ihre Projektmappe, und wählen Sie Startprojekte festlegen aus.
Wählen Sie unter Allgemeine Eigenschaften>Startprojekt die Option Mehrere Startprojekte aus. Wählen Sie für ReportConnectivity die Option Starten als Aktion aus. Klicken Sie zum Speichern der Änderungen auf OK .
Sie führen diese App aus, indem Sie mit der rechten Maustaste auf das Projekt ReportConnectivity klicken und Debuggen und dann Neue Instanz starten auswählen. Sie sollten sehen, wie die Zwillingsinformationen für die App abgerufen und die Konnektivität anschließend als gemeldete Eigenschaft gesendet wird.

Nachdem das Gerät die Verbindungsinformationen gemeldet hat, sollten sie in beiden Abfragen angezeigt werden.
Klicken Sie mit der rechten Maustaste auf das Projekt AddTagsAndQuery, und wählen Sie Debuggen>Neue Instanz starten aus, um die Abfragen erneut auszuführen. Nun sollte myDeviceId in beiden Abfrageergebnissen angezeigt werden.

Erstellen einer Dienst-App, die gewünschte Eigenschaften aktualisiert und Zwillinge abfragt

In diesem Abschnitt erstellen Sie eine .NET-Konsolen-App in C#, mit der dem Gerätezwilling, der myDeviceId zugeordnet ist, Standortmetadaten hinzugefügt werden. Die App fragt IoT Hub nach Geräten ab, die sich in den USA befinden, und fragt dann Geräte ab, die eine Mobilfunknetzverbindung melden.

Wählen Sie in Visual Studio Datei > Neu > Projekt aus. Wählen Sie in Neues Projekt erstellen die Option Konsolen-App (.NET Framework) und dann Weiter aus.
Geben Sie dem Projekt in Neues Projekt konfigurieren den Namen AddTagsAndQuery, und wählen Sie Weiter aus.
Akzeptieren Sie die Standardversion des .NET Framework, und wählen Sie Erstellen aus, um das Projekt zu erstellen.
Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt AddTagsAndQuery, und wählen Sie dann NuGet-Pakete verwalten aus.
Wählen Sie Durchsuchen aus, suchen Sie nach dem Paket Microsoft.Azure.Devices, und wählen Sie es aus. Wählen Sie Installieren aus.

In diesem Schritt wird das NuGet-Paket Azure IoT-Dienst-SDK heruntergeladen und installiert und ein Verweis auf das Paket und seine Abhängigkeiten hinzugefügt.
Fügen Sie am Anfang der Datei Program.cs die folgenden using-Anweisungen hinzu:
```
using Microsoft.Azure.Devices;
```
Fügen Sie der Program -Klasse die folgenden Felder hinzu. Ersetzen Sie {iot hub connection string} durch die IoT-Hub-Verbindungszeichenfolge, die Sie unter Abrufen der IoT-Hub-Verbindungszeichenfolge kopiert haben.
```
static RegistryManager registryManager;
static string connectionString = "{iot hub connection string}";
```
Fügen Sie der Program -Klasse die folgende Methode hinzu:
```
public static async Task AddTagsAndQuery()
{
    var twin = await registryManager.GetTwinAsync("myDeviceId");
    var patch =
        @"{
            tags: {
                location: {
                    region: 'US',
                    plant: 'Redmond43'
                }
            }
        }";
    await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);

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

    query = registryManager.CreateQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
    var twinsInRedmond43UsingCellular = await query.GetNextAsTwinAsync();
    Console.WriteLine("Devices in Redmond43 using cellular network: {0}", 
      string.Join(", ", twinsInRedmond43UsingCellular.Select(t => t.DeviceId)));
}
```
Die Registry-Klasse macht alle Methoden verfügbar, die für die Interaktion mit Gerätezwillingen des Diensts erforderlich sind. Mit dem vorherigen Code werden zunächst das registryManager-Objekt initialisiert, dann der Gerätezwilling für myDeviceId abgerufen und schließlich die zugehörigen Tags mit den gewünschten Standortinformationen aktualisiert.

Nach der Aktualisierung werden zwei Abfragen ausgeführt: 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.

Mit diesem Code wird beim Erstellen des query-Objekts eine maximale Anzahl von zurückgegebenen Dokumenten angegeben. Das query-Objekt enthält die boolesche Eigenschaft HasMoreResults, mit der Sie die GetNextAsTwinAsync-Methoden mehrmals aufrufen können, um alle Ergebnisse abzurufen. Die GetNextAsJson-Methode ist für Ergebnisse verfügbar, die keine Gerätezwillinge sind, z.B. Ergebnisse von Aggregationsabfragen.

Fügen Sie abschließend der Main -Methode die folgenden Zeilen hinzu:

registryManager = RegistryManager.CreateFromConnectionString(connectionString);
AddTagsAndQuery().Wait();
Console.WriteLine("Press Enter to exit.");
Console.ReadLine();

Führen Sie diese Anwendung aus, indem Sie mit der rechten Maustaste auf das Projekt AddTagsAndQuery klicken und Debuggen und anschließend Neue Instanz starten auswählen. In den Ergebnissen für die Abfrage, mit der alle Geräte in der Anlage Redmond43 abgefragt werden, sollte ein Gerät angezeigt werden und keines für die Abfrage, mit der die Ergebnisse auf die über ein Mobilfunknetz verbundenen Geräte beschränkt werden.

In diesem Artikel führen Sie folgende Schritte aus:

Gerätemetadaten als Tags aus einer Back-End-App hinzugefügt
Gemeldete Gerätekonnektivitätsinformationen im Gerätezwilling
Sie haben zudem erfahren, wie die Gerätezwillingsinformationen mithilfe der SQL-ähnlichen IoT Hub-Abfragesprache abgefragt werden können

Nächste Schritte

Eine entsprechende Anleitung

Zum Senden von Telemetriedaten von Geräten finden Sie im Schnellstart: Senden von Telemetriedaten von einem IoT Plug & Play-Gerät an Azure IoT Hub.
Konfigurieren Sie Geräte mit den gewünschten Eigenschaften des Gerätezwillings, siehe Tutorial: Konfigurieren Sie Ihre Geräte über einen Back-End-Diens.
Steuern von Geräten interaktiv, z. B. das Aktivieren eines Lüfters von einer benutzergesteuerten App, finden Sie unter Schnellstart: Steuern eines Geräts, das mit einem IoT-Hub verbunden ist.