Erste Schritte mit Azure IoT Hub-Gerätezwillingen - Azure IoT Hub

Ü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

Wichtig

Dieser Artikel enthält Schritte zum Verbinden eines Geräts mithilfe einer Shared Access Signature, was auch als symmetrische Schlüsselauthentifizierung bezeichnet wird. Diese Authentifizierungsmethode eignet sich für Tests und Auswertungen, aber die Authentifizierung eines Geräts mit X.509-Zertifikaten ist ein sichererer Ansatz. Weitere Informationen finden Sie unter Bewährte Methoden für die Sicherheit von IoT-Lösungen > Verbindungssicherheit.

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:

Erstellen Sie ein TwinCollection-Objekt für die Aktualisierung der gemeldeten Eigenschaft
Aktualisieren Sie eine oder mehrere gemeldete Eigenschaften innerhalb des TwinCollection-Objekts
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 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 Back-End-Anwendungscode erstellen, um:

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

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.

Hinzufügen des NuGet-Dienstpakets

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

Herstellen einer Verbindung mit dem IoT-Hub

Sie können einen Back-End-Dienst mit IoT Hub mithilfe der folgenden Methoden verbinden:

SAS-Richtlinie
Microsoft Entra

Wichtig

Dieser Artikel enthält Schritte zum Herstellen einer Verbindung mit einem Dienst mithilfe einer Shared Access Signature. Diese Authentifizierungsmethode eignet sich für Tests und Auswertungen, aber die Authentifizierung bei einem Dienst mit Microsoft Entra ID oder verwalteten Identitäten ist ein sichererer Ansatz. Weitere Informationen finden Sie unter Bewährte Methoden für die Sicherheit von IoT-Lösungen > Cloudsicherheit.

Herstellen einer Verbindung mithilfe einer SAS-Richtlinie

Verbinden Sie eine Back-End-Anwendung mit einem Gerät mithilfe von CreateFromConnectionString. Ihre Anwendung benötigt die Dienstverbindung Berechtigung zum Ändern der gewünschten Eigenschaften eines Geräte-Zwillings und benötigt Registrierung lese- Berechtigung zum Abfragen der Identitätsregistrierung. Da keine SAS-Standardrichtlinie mit nur diesen beiden Berechtigungen zur Verfügung steht, müssen Sie eine erstellen, wenn nicht bereits eine vorhanden ist. Geben Sie diese SAS-Richtlinie Verbindungszeichenfolge als Parameter an fromConnectionString. Weitere Informationen zu SAS-Richtlinien finden Sie unter Steuer des Zugriffs auf IoT Hub mithilfe von Shared Access Signatures.

using Microsoft.Azure.Devices;
static RegistryManager registryManager;
static string connectionString = "{Shared access policy connection string}";
registryManager = RegistryManager.CreateFromConnectionString(connectionString);

Verbinden mit Microsoft Entra

Eine Back-End-App, die Microsoft Entra verwendet, muss erfolgreich authentifiziert werden und Anmeldeinformationen für Sicherheitstoken erhalten, bevor Sie eine Verbindung mit IoT Hub herstellen. Dieses Token wird an eine IoT Hub-Verbindungsmethode übergeben. Allgemeine Informationen zum Einrichten und Verwenden von Microsoft Entra für IoT Hub finden Sie unter Steuern des Zugriffs auf IoT Hub mithilfe von Microsoft Entra ID.

Konfigurieren der Microsoft Entra-App

Sie müssen eine Microsoft Entra-App einrichten, die für Ihre bevorzugten Authentifizierungsanmeldeinformationen konfiguriert ist. Die App enthält Parameter wie den geheimen Clientschlüssel, der von der Back-End-Anwendung zur Authentifizierung verwendet wird. Die verfügbaren Konfigurationen für die App-Authentifizierung sind:

Geheimer Clientschlüssel
Zertifikat
Anmeldeinformationen für Verbundidentität

Microsoft Entra-Apps erfordern je nach ausgeführten Vorgängen möglicherweise bestimmte Rollenberechtigungen. Beispielsweise ist IoT Hub Twin Contributor erforderlich, um Lese- und Schreibzugriff auf ein IoT Hub-Gerät und Modulzwilling zu ermöglichen. Weitere Informationen finden Sie unter Verwalten des Zugriffs auf IoT Hub mithilfe der Azure RBAC-Rollenzuweisung.

Weitere Informationen zum Einrichten einer Microsoft Entra-App finden Sie in der Schnellstartanleitung: Registrieren einer Anwendung bei der Microsoft Identitäts-Plattform.

Authentifizieren mithilfe von DefaultAzureCredential

Die einfachste Möglichkeit, Microsoft Entra zum Authentifizieren einer Back-End-Anwendung zu verwenden, besteht darin, DefaultAzureCredential zu verwenden. Es wird jedoch empfohlen, eine andere Methode in einer Produktionsumgebung zu verwenden, einschließlich einer bestimmten TokenCredential oder analysierten ChainedTokenCredential. Der Einfachheit halber beschreibt dieser Abschnitt die Authentifizierung mit DefaultAzureCredential und den geheimen Clientschlüssel. Weitere Informationen zu den Vor- und Nachteilen der Verwendung von DefaultAzureCredential finden Sie unter Verwendungsleitfaden für DefaultAzureCredential.

DefaultAzureCredential unterstützt verschiedene Authentifizierungsmechanismen und bestimmt den entsprechenden Anmeldeinformationstyp basierend auf der Umgebung, in der er ausgeführt wird. Es versucht, mehrere Anmeldeinformationstypen in einer Reihenfolge zu verwenden, bis sie eine funktionierende Anmeldeinformation findet.

Microsoft Entra erfordert diese NuGet-Pakete und entsprechende using Anweisungen:

Azure.Core
Azure.Identity

using Azure.Core;
using Azure.Identity;

In diesem Beispiel werden Clientschlüssel, Client-ID und Mandanten-ID der Microsoft Entra-App zu Umgebungsvariablen hinzugefügt. Diese Umgebungsvariablen werden von DefaultAzureCredential verwendet, um die Anwendung zu authentifizieren. Das Ergebnis einer erfolgreichen Microsoft Entra-Authentifizierung ist eine Sicherheitstoken-Anmeldeinformation, die an eine IoT Hub-Verbindungsmethode übergeben wird.

string clientSecretValue = "xxxxxxxxxxxxxxx";
string clientID = "xxxxxxxxxxxxxx";
string tenantID = "xxxxxxxxxxxxx";

Environment.SetEnvironmentVariable("AZURE_CLIENT_SECRET", clientSecretValue);
Environment.SetEnvironmentVariable("AZURE_CLIENT_ID", clientID);
Environment.SetEnvironmentVariable("AZURE_TENANT_ID", tenantID);

TokenCredential tokenCredential = new DefaultAzureCredential();

Das resultierende TokenCredential kann dann an eine Verbindung mit der IoT Hub-Methode für jeden SDK-Client übergeben werden, der Microsoft Entra-Anmeldeinformationen akzeptiert:

In diesem Beispiel wird TokenCredential an ServiceClient.Create übergeben, um ein ServiceClient-Verbindungsobjekt zu erstellen.

string hostname = "xxxxxxxxxx.azure-devices.net";
using var serviceClient = ServiceClient.Create(hostname, tokenCredential, TransportType.Amqp);

In diesem Beispiel wird TokenCredential an RegistryManager.Create übergeben, um ein RegistryManager-Objekt zu erstellen.

string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);

Codebeispiel

Ein funktionierendes Beispiel für die Microsoft Entra-Dienstauthentifizierung finden Sie im Beispiel für die rollenbasierte Authentifizierung.

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.

Wichtig

Dieser Artikel enthält Schritte zum Verbinden eines Geräts mithilfe einer Shared Access Signature, was auch als symmetrische Schlüsselauthentifizierung bezeichnet wird. Diese Authentifizierungsmethode eignet sich für Tests und Auswertungen, aber die Authentifizierung eines Geräts mit X.509-Zertifikaten ist ein sichererer Ansatz. Weitere Informationen finden Sie unter Bewährte Methoden für die Sicherheit von IoT-Lösungen > Verbindungssicherheit.

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:

Verwenden Sie IotHubClientProtocol, um ein Transportprotokoll auszuwählen. Zum Beispiel:
```
IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
```
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);
```
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:

Rufen Sie getReportedProperties auf, um die gemeldeten Eigenschaften des Zwillings in einem TwinCollection-Objekt abzurufen.
Verwenden Sie put, um eine gemeldete Eigenschaft innerhalb des TwinCollection-Objekts zu aktualisieren. Rufen Sie put jede Aktualisierung einer gemeldeten Eigenschaft auf.
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);

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 der Verbindung mit dem IoT Hub

Sie können einen Back-End-Dienst mit IoT Hub mithilfe der folgenden Methoden verbinden:

SAS-Richtlinie
Microsoft Entra

Wichtig

Dieser Artikel enthält Schritte zum Herstellen einer Verbindung mit einem Dienst mithilfe einer Shared Access Signature. Diese Authentifizierungsmethode eignet sich für Tests und Auswertungen, aber die Authentifizierung bei einem Dienst mit Microsoft Entra ID oder verwalteten Identitäten ist ein sichererer Ansatz. Weitere Informationen finden Sie unter Bewährte Methoden für die Sicherheit von IoT-Lösungen > Cloudsicherheit.

Herstellen einer Verbindung mithilfe einer SAS-Richtlinie

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.

Ihre Anwendung benötigt die Dienstverbindung Berechtigung zum Ändern der gewünschten Eigenschaften eines Geräte-Zwillings und benötigt Registrierung lese- Berechtigung zum Abfragen der Identitätsregistrierung. Da keine SAS-Standardrichtlinie mit nur diesen beiden Berechtigungen zur Verfügung steht, müssen Sie eine erstellen, wenn nicht bereits eine vorhanden ist. Geben Sie diese SAS-Richtlinie Verbindungszeichenfolge als Parameter an fromConnectionString. Weitere Informationen zu SAS-Richtlinien finden Sie unter Steuer des Zugriffs auf IoT Hub mithilfe von Shared Access Signatures.

Das DeviceTwinDevice-Objekt stellt den Gerätezwilling mit seinen Eigenschaften und Tags dar.

Zum Beispiel:

public static final String iotHubConnectionString = "{Shared access policy 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
DeviceTwin twinClient = new DeviceTwin(iotHubConnectionString);
DeviceTwinDevice device = new DeviceTwinDevice(deviceId);

Verbinden mit Microsoft Entra

Eine Back-End-App, die Microsoft Entra verwendet, muss erfolgreich authentifiziert werden und Anmeldeinformationen für Sicherheitstoken erhalten, bevor Sie eine Verbindung mit IoT Hub herstellen. Dieses Token wird an eine IoT Hub-Verbindungsmethode übergeben. Allgemeine Informationen zum Einrichten und Verwenden von Microsoft Entra für IoT Hub finden Sie unter Steuern des Zugriffs auf IoT Hub mithilfe von Microsoft Entra ID.

Eine Übersicht über die Java SDK-Authentifizierung finden Sie unter Azure-Authentifizierung mit Java und Azure Identität.

Der Einfachheit halber konzentriert sich dieser Abschnitt auf die Beschreibung der Authentifizierung mithilfe des geheimen Clientschlüssels.

Konfigurieren der Microsoft Entra-App

Sie müssen eine Microsoft Entra-App einrichten, die für Ihre bevorzugten Authentifizierungsanmeldeinformationen konfiguriert ist. Die App enthält Parameter wie den geheimen Clientschlüssel, der von der Back-End-Anwendung zur Authentifizierung verwendet wird. Die verfügbaren Konfigurationen für die App-Authentifizierung sind:

Geheimer Clientschlüssel
Zertifikat
Anmeldeinformationen für Verbundidentität

Microsoft Entra-Apps erfordern je nach ausgeführten Vorgängen möglicherweise bestimmte Rollenberechtigungen. Beispielsweise ist IoT Hub Twin Contributor erforderlich, um Lese- und Schreibzugriff auf ein IoT Hub-Gerät und Modulzwilling zu ermöglichen. Weitere Informationen finden Sie unter Verwalten des Zugriffs auf IoT Hub mithilfe der Azure RBAC-Rollenzuweisung.

Weitere Informationen zum Einrichten einer Microsoft Entra-App finden Sie in der Schnellstartanleitung: Registrieren einer Anwendung bei der Microsoft Identitäts-Plattform.

Authentifizieren mithilfe von DefaultAzureCredential

Die einfachste Möglichkeit, Microsoft Entra zum Authentifizieren einer Back-End-Anwendung zu verwenden, besteht darin, DefaultAzureCredential zu verwenden. Es wird jedoch empfohlen, eine andere Methode in einer Produktionsumgebung zu verwenden, einschließlich einer bestimmten TokenCredential oder analysierten ChainedTokenCredential. Weitere Informationen zu den Vor- und Nachteilen der Verwendung DefaultAzureCredentialfinden Sie unter Anmeldeinformationsketten in der Azure Identity-Clientbibliothek für Java.

DefaultAzureCredential unterstützt verschiedene Authentifizierungsmechanismen und bestimmt den entsprechenden Anmeldeinformationstyp basierend auf der Umgebung, in der er ausgeführt wird. Er versucht, mehrere Anmeldeinformationstypen in einer Reihenfolge zu verwenden, bis er eine funktionierende Anmeldeinformation findet.

Sie können Microsoft Entra-App-Anmeldeinformationen mithilfe von DefaultAzureCredentialBuilderauthentifizieren. Speichern Sie Verbindungsparameter wie geheime Clientschlüssel-Mandanten-ID, Client-ID und geheime Clientschlüsselwerte als Umgebungsvariablen. Nachdem die TokenCredential Datei erstellt wurde, übergeben Sie sie an ServiceClient oder einen anderen Generator als Parameter Anmeldeinformationen.

In diesem Beispiel versucht DefaultAzureCredentialBuilder eine Verbindung aus der in DefaultAzureCredential beschriebenen Liste zu authentifizieren. Das Ergebnis einer erfolgreichen Microsoft Entra-Authentifizierung ist eine Sicherheitstokenanmeldeinformation, die an einen Konstruktor wie ServiceClientübergeben wird.

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

Authentifizieren mit ClientSecretCredentialBuilder

Sie können ClientSecretCredentialBuilder verwenden, um eine Anmeldeinformation mithilfe von geheimen Clientinformationen zu erstellen. Bei erfolgreicher Ausführung gibt die Methode eine TokenCredential zurück, die als Parameter "Anmeldeinformationen" an ServiceClient oder einen anderen Generator übergeben werden kann.

In diesem Beispiel wurden Clientschlüssel, Client-ID und Mandanten-ID-Werte der Microsoft Entra-App zu Umgebungsvariablen hinzugefügt. Diese Umgebungsvariablen werden von ClientSecretCredentialBuilderverwendet, um die Anmeldeinformationen zu erstellen.

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

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

Andere Authentifizierungsklassen

Das Java SDK enthält auch diese Klassen, die eine Back-End-App mit Microsoft Entra authentifizieren:

Codebeispiele

Arbeitsbeispiele für die Microsoft Entra-Dienstauthentifizierung finden Sie im Beispielfür die rollenbasierte Authentifizierung.

Aktualisieren der Felder von Gerätezwillingen

So aktualisieren Sie die Felder von Gerätezwillingen:

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);
```
Verwenden Sie ein HashSet-Objekt für add eine Gruppe von Tagpaaren eines Zwillings
Verwenden Sie setTags, um eine Gruppe von Tagpaaren aus einem tags-Objekt zu einem DeviceTwinDevice-Objekt hinzuzufügen

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:

Verwenden Sie createSqlQuery zum Erstellen der SQL-Abfrage für den Zwilling
Verwenden Sie queryTwin, um die Abfrage auszuführen
Verwenden Sie hasNextDeviceTwin, um zu überprüfen, ob ein anderer Gerätezwilling im Resultset vorhanden ist
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

Wichtig

Dieser Artikel enthält Schritte zum Verbinden eines Geräts mithilfe einer Shared Access Signature, was auch als symmetrische Schlüsselauthentifizierung bezeichnet wird. Diese Authentifizierungsmethode eignet sich für Tests und Auswertungen, aber die Authentifizierung eines Geräts mit X.509-Zertifikaten ist ein sichererer Ansatz. Weitere Informationen finden Sie unter Bewährte Methoden für die Sicherheit von IoT-Lösungen > Verbindungssicherheit.

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:

Rufen Sie create_from_connection_string auf, um die Verbindungszeichenfolge des Geräts hinzuzufügen
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:

Weisen Sie ein JSON-Patch einer gemeldeten Eigenschaft einer Variablen zu.
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

Sie können einen Back-End-Dienst mit IoT Hub mithilfe der folgenden Methoden verbinden:

SAS-Richtlinie
Microsoft Entra

Wichtig

Dieser Artikel enthält Schritte zum Herstellen einer Verbindung mit einem Dienst mithilfe einer Shared Access Signature. Diese Authentifizierungsmethode eignet sich für Tests und Auswertungen, aber die Authentifizierung bei einem Dienst mit Microsoft Entra ID oder verwalteten Identitäten ist ein sichererer Ansatz. Weitere Informationen finden Sie unter Bewährte Methoden für die Sicherheit von IoT-Lösungen > Cloudsicherheit.

Herstellen einer Verbindung mithilfe einer SAS-Richtlinie

Stellen Sie mithilfe von from_connection_string eine Verbindung mit dem IoT-Hub her. Ihre Anwendung benötigt die Dienstverbindung Berechtigung zum Ändern der gewünschten Eigenschaften eines Geräte-Zwillings und benötigt Registrierung lese- Berechtigung zum Abfragen der Identitätsregistrierung. Da keine SAS-Standardrichtlinie mit nur diesen beiden Berechtigungen zur Verfügung steht, müssen Sie eine erstellen, wenn nicht bereits eine vorhanden ist. Geben Sie diese SAS-Richtlinie Verbindungszeichenfolge als Parameter an fromConnectionString. Weitere Informationen zu SAS-Richtlinien finden Sie unter Steuer des Zugriffs auf IoT Hub mithilfe von Shared Access Signatures.

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)

Verbinden mit Microsoft Entra

Eine Back-End-App, die Microsoft Entra verwendet, muss erfolgreich authentifiziert werden und Anmeldeinformationen für Sicherheitstoken erhalten, bevor Sie eine Verbindung mit IoT Hub herstellen. Dieses Token wird an eine IoT Hub-Verbindungsmethode übergeben. Allgemeine Informationen zum Einrichten und Verwenden von Microsoft Entra für IoT Hub finden Sie unter Steuern des Zugriffs auf IoT Hub mithilfe von Microsoft Entra ID.

Eine Übersicht über die Python SDK-Authentifizierung finden Sie unter Authentifizieren von Python-Apps für Azure-Dienste mithilfe des Azure SDK für Python

Konfigurieren der Microsoft Entra-App

Sie müssen eine Microsoft Entra-App einrichten, die für Ihre bevorzugten Authentifizierungsanmeldeinformationen konfiguriert ist. Die App enthält Parameter wie den geheimen Clientschlüssel, der von der Back-End-Anwendung zur Authentifizierung verwendet wird. Die verfügbaren Konfigurationen für die App-Authentifizierung sind:

Geheimer Clientschlüssel
Zertifikat
Anmeldeinformationen für Verbundidentität

Microsoft Entra-Apps erfordern je nach ausgeführten Vorgängen möglicherweise bestimmte Rollenberechtigungen. Beispielsweise ist IoT Hub Twin Contributor erforderlich, um Lese- und Schreibzugriff auf ein IoT Hub-Gerät und Modulzwilling zu ermöglichen. Weitere Informationen finden Sie unter Verwalten des Zugriffs auf IoT Hub mithilfe der Azure RBAC-Rollenzuweisung.

Weitere Informationen zum Einrichten einer Microsoft Entra-App finden Sie in der Schnellstartanleitung: Registrieren einer Anwendung bei der Microsoft Identitäts-Plattform.

Authentifizieren mithilfe von DefaultAzureCredential

Die einfachste Möglichkeit, Microsoft Entra zum Authentifizieren einer Back-End-Anwendung zu verwenden, besteht darin, DefaultAzureCredential zu verwenden. Es wird jedoch empfohlen, eine andere Methode in einer Produktionsumgebung zu verwenden, einschließlich einer bestimmten TokenCredential oder analysierten ChainedTokenCredential. Der Einfachheit halber beschreibt dieser Abschnitt die Authentifizierung mit DefaultAzureCredential und den geheimen Clientschlüssel. Weitere Informationen zu den Vor- und Nachteilen der Verwendung von DefaultAzureCredential finden Sie unter Anmeldeinformationsketten in der Azure Identity-Clientbibliothek für Python.

DefaultAzureCredential unterstützt verschiedene Authentifizierungsmechanismen und bestimmt den entsprechenden Anmeldeinformationstyp basierend auf der Umgebung, in der er ausgeführt wird. Er versucht, mehrere Anmeldeinformationstypen in einer Reihenfolge zu verwenden, bis er eine funktionierende Anmeldeinformation findet.

Microsoft Entra erfordert dieses Importpaket und die entsprechende import-Anweisung:

pip install azure-identity

from azure.identity import DefaultAzureCredential

In diesem Beispiel wurden Clientschlüssel, Client-ID und Mandanten-ID der Microsoft Entra-App zu Umgebungsvariablen hinzugefügt. Diese Umgebungsvariablen werden von DefaultAzureCredential verwendet, um die Anwendung zu authentifizieren. Das Ergebnis einer erfolgreichen Microsoft Entra-Authentifizierung ist eine Sicherheitstoken-Anmeldeinformation, die an eine IoT Hub-Verbindungsmethode übergeben wird.

from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()

Das resultierende AccessToken kann dann an from_token_credential zur Verbindung mit IoT Hub für jeden SDK-Client übergeben werden, der Microsoft Entra-Anmeldeinformationen akzeptiert:

IoTHubRegistryManager zum Erstellen einer Dienstverbindung mit IoT Hub mithilfe einer Entra-Token-Anmeldeinformationen.
IoTHubJobManager
DigitalTwinClient
IoTHubHttpRuntimeManager
IoTHubConfigurationManager

from_token_credential erfordert zwei Parameter:

Die Azure-Dienst-URL – Die Azure-Dienst-URL sollte im Format {Your Entra domain URL}.azure-devices.net ohne ein https://-Präfix vorliegen. Beispiel: MyAzureDomain.azure-devices.net.
Das Azure-Anmeldeinformationstoken

In diesem Beispiel werden die Azure-Anmeldeinformationen mithilfe von DefaultAzureCredential erlangt. Die Azure-Dienst-URL und die Anmeldeinformationen werden dann an IoTHubRegistryManager.from_token_credential bereitgestellt, um die Verbindung mit IoT Hub zu erstellen.

import sys
import os

from azure.identity import DefaultAzureCredential
from azure.iot.hub import IoTHubRegistryManager

# Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

# Set environment variables
os.environ['AZURE_CLIENT_SECRET'] = clientSecretValue
os.environ['AZURE_CLIENT_ID'] = clientID
os.environ['AZURE_TENANT_ID'] = tenantID

# Acquire a credential object
credential = DefaultAzureCredential()

# Use Entra to authorize IoT Hub service
print("Connecting to IoTHubRegistryManager...")
iothub_registry_manager = IoTHubRegistryManager.from_token_credential(
url="MyAzureDomain.azure-devices.net",
token_credential=credential)

Codebeispiele

Arbeitsbeispiele für die Microsoft Entra-Dienstauthentifizierung finden Sie unter Microsoft Authentication Library (MSAL) für Python.

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.

Rufen Sie get_twin auf, um die aktuelle Version des Gerätezwillings abzurufen
Verwenden Sie die Twin-Klasse, um Tags und Eigenschaften im JSON-Format hinzuzufügen.
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:

Verwenden Sie ein QuerySpecification-Objekt, um eine SQL-ähnliche Abfrageanforderung zu definieren.
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

Wichtig

Dieser Artikel enthält Schritte zum Verbinden eines Geräts mithilfe einer Shared Access Signature, was auch als symmetrische Schlüsselauthentifizierung bezeichnet wird. Diese Authentifizierungsmethode eignet sich für Tests und Auswertungen, aber die Authentifizierung eines Geräts mit X.509-Zertifikaten ist ein sichererer Ansatz. Weitere Informationen finden Sie unter Bewährte Methoden für die Sicherheit von IoT-Lösungen > Verbindungssicherheit.

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:

Die Eigenschaften minTemperature und maxTemperature befinden sich unter einer Eigenschaftsgruppierung mit dem Namen properties.desired.climate changes.
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, },
    },
  },
 };
```
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.

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

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

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:

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

Sie können einen Back-End-Dienst mit IoT Hub mithilfe der folgenden Methoden verbinden:

SAS-Richtlinie
Microsoft Entra

Wichtig

Dieser Artikel enthält Schritte zum Herstellen einer Verbindung mit einem Dienst mithilfe einer Shared Access Signature. Diese Authentifizierungsmethode eignet sich für Tests und Auswertungen, aber die Authentifizierung bei einem Dienst mit Microsoft Entra ID oder verwalteten Identitäten ist ein sichererer Ansatz. Weitere Informationen finden Sie unter Bewährte Methoden für die Sicherheit von IoT-Lösungen > Cloudsicherheit.

Herstellen einer Verbindung mithilfe einer SAS-Richtlinie

Verwenden Sie fromConnectionString, um eine Verbindung mit dem IoT-Hub herzustellen. Ihre Anwendung benötigt die Dienstverbindung Berechtigung zum Ändern der gewünschten Eigenschaften eines Geräte-Zwillings und benötigt Registrierung lese- Berechtigung zum Abfragen der Identitätsregistrierung. Da keine SAS-Standardrichtlinie mit nur diesen beiden Berechtigungen zur Verfügung steht, müssen Sie eine erstellen, wenn nicht bereits eine vorhanden ist. Geben Sie diese SAS-Richtlinie Verbindungszeichenfolge als Parameter an fromConnectionString. Weitere Informationen zu SAS-Richtlinien finden Sie unter Steuer des Zugriffs auf IoT Hub mithilfe von Shared Access Signatures.

'use strict';
var iothub = require('azure-iothub');
var connectionString = '{Shared access policy connection string}';
var registry = iothub.Registry.fromConnectionString(connectionString);

Verbinden mit Microsoft Entra

Eine Back-End-App, die Microsoft Entra verwendet, muss erfolgreich authentifiziert werden und Anmeldeinformationen für Sicherheitstoken erhalten, bevor Sie eine Verbindung mit IoT Hub herstellen. Dieses Token wird an eine IoT Hub-Verbindungsmethode übergeben. Allgemeine Informationen zum Einrichten und Verwenden von Microsoft Entra für IoT Hub finden Sie unter Steuern des Zugriffs auf IoT Hub mithilfe von Microsoft Entra ID.

Eine Übersicht über Node.js SDK-Authentifizierung finden Sie unter:

Konfigurieren der Microsoft Entra-App

Sie müssen eine Microsoft Entra-App einrichten, die für Ihre bevorzugten Authentifizierungsanmeldeinformationen konfiguriert ist. Die App enthält Parameter wie den geheimen Clientschlüssel, der von der Back-End-Anwendung zur Authentifizierung verwendet wird. Die verfügbaren Konfigurationen für die App-Authentifizierung sind:

Geheimer Clientschlüssel
Zertifikat
Anmeldeinformationen für Verbundidentität

Microsoft Entra-Apps erfordern je nach ausgeführten Vorgängen möglicherweise bestimmte Rollenberechtigungen. Beispielsweise ist IoT Hub Twin Contributor erforderlich, um Lese- und Schreibzugriff auf ein IoT Hub-Gerät und Modulzwilling zu ermöglichen. Weitere Informationen finden Sie unter Verwalten des Zugriffs auf IoT Hub mithilfe der Azure RBAC-Rollenzuweisung.

Weitere Informationen zum Einrichten einer Microsoft Entra-App finden Sie in der Schnellstartanleitung: Registrieren einer Anwendung bei der Microsoft Identitäts-Plattform.

Authentifizieren mithilfe von DefaultAzureCredential

Die einfachste Möglichkeit, Microsoft Entra zum Authentifizieren einer Back-End-Anwendung zu verwenden, besteht darin, DefaultAzureCredential zu verwenden. Es wird jedoch empfohlen, eine andere Methode in einer Produktionsumgebung zu verwenden, einschließlich einer bestimmten TokenCredential oder analysierten ChainedTokenCredential. Der Einfachheit halber beschreibt dieser Abschnitt die Authentifizierung mit DefaultAzureCredential und den geheimen Clientschlüssel. Weitere Informationen zu den Vor- und Nachteilen der Verwendung von DefaultAzureCredential finden Sie unter Anmeldeinformationsketten in der Azure Identity-Clientbibliothek für JavaScript

DefaultAzureCredential unterstützt verschiedene Authentifizierungsmechanismen und bestimmt den entsprechenden Anmeldeinformationstyp basierend auf der Umgebung, in der er ausgeführt wird. Er versucht, mehrere Anmeldeinformationstypen in einer Reihenfolge zu verwenden, bis er eine funktionierende Anmeldeinformation findet.

Microsoft Entra erfordert dieses Paket:

npm install --save @azure/identity

In diesem Beispiel wurden Clientschlüssel, Client-ID und Mandanten-ID der Microsoft Entra-App zu Umgebungsvariablen hinzugefügt. Diese Umgebungsvariablen werden von DefaultAzureCredential verwendet, um die Anwendung zu authentifizieren. Das Ergebnis einer erfolgreichen Microsoft Entra-Authentifizierung ist eine Sicherheitstoken-Anmeldeinformation, die an eine IoT Hub-Verbindungsmethode übergeben wird.

import { DefaultAzureCredential } from "@azure/identity";

// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();

Das resultierende Anmeldeinformationstoken kann dann an fromTokenCredential übergeben werden, um eine Verbindung mit IoT Hub für jeden SDK-Client herzustellen, der Microsoft Entra-Anmeldeinformationen akzeptiert:

fromTokenCredential erfordert zwei Parameter:

Die Azure-Dienst-URL – Die Azure-Dienst-URL sollte im Format {Your Entra domain URL}.azure-devices.net ohne ein https://-Präfix vorliegen. Beispiel: MyAzureDomain.azure-devices.net.
Das Azure-Anmeldeinformationstoken

In diesem Beispiel werden die Azure-Anmeldeinformationen mithilfe von DefaultAzureCredential erlangt. Die Azure-Domänen-URL und Anmeldeinformationen werden dann an Registry.fromTokenCredential bereitgestellt, um die Verbindung mit IoT Hub zu erstellen.

const { DefaultAzureCredential } = require("@azure/identity");

let Registry = require('azure-iothub').Registry;

// Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

// Set environment variables
process.env['AZURE_CLIENT_SECRET'] = clientSecretValue;
process.env['AZURE_CLIENT_ID'] = clientID;
process.env['AZURE_TENANT_ID'] = tenantID;

// Acquire a credential object
const credential = new DefaultAzureCredential()

// Create an instance of the IoTHub registry
hostName = 'MyAzureDomain.azure-devices.net';
let registry = Registry.fromTokenCredential(hostName,credential);

Codebeispiele

Arbeitsbeispiele für die Microsoft Entra-Dienstauthentifizierung finden Sie in Azure-Identitätsbeispielen.

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:

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.

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.

Freigeben über

Erste Schritte mit Gerätezwillingen

Voraussetzungen

Übersicht

Erstellen einer Geräteanwendung

Hinzufügen des NuGet-Gerätepakets

Mit einem Gerät verbinden

Abrufen eines Gerätezwillings und Untersuchung der gemeldeten Eigenschaften

Aktualisieren gemeldeter Eigenschaften von Gerätezwillingen

Erstellen eines Rückrufhandlers zum Aktualisieren gewünschter Eigenschaften

Beispiel für ein SDK-Gerät

Erstellen einer Back-End-Anwendung

Hinzufügen des NuGet-Dienstpakets

Herstellen einer Verbindung mit dem IoT-Hub

Herstellen einer Verbindung mithilfe einer SAS-Richtlinie

Verbinden mit Microsoft Entra

Konfigurieren der Microsoft Entra-App

Authentifizieren mithilfe von DefaultAzureCredential

Codebeispiel

Lesen und Aktualisieren von Feldern für Gerätezwillinge

Lesen und Aktualisieren von Tags für Gerätezwillinge

Aktualisieren von Tags mithilfe eines Zwillingsobjekts

Aktualisieren von Tags mithilfe einer JSON-Zeichenfolge

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

Andere Methoden zur Aktualisierung von Zwillingen

Erstellen einer Zwillingsabfrage

Beispiel des SDK-Diensts

Übersicht

Erstellen einer Geräteanwendung

Geräte-Importanweisungen

Stellen Sie eine Verbindung mit dem Gerät her.

Abrufen und Ansehen eines Gerätezwillings

Aktualisieren der gemeldeten Eigenschaften des Gerätezwillings

Aktualisierungen der gewünschten Eigenschaften abonnieren

Beispiel für ein SDK-Gerät

Erstellen einer Back-End-Anwendung

Dienst-Importanweisungen

Herstellen der Verbindung mit dem IoT Hub

Herstellen einer Verbindung mithilfe einer SAS-Richtlinie

Verbinden mit Microsoft Entra

Konfigurieren der Microsoft Entra-App

Authentifizieren mithilfe von DefaultAzureCredential

Authentifizieren mit ClientSecretCredentialBuilder

Andere Authentifizierungsklassen

Codebeispiele

Aktualisieren der Felder von Gerätezwillingen

Erstellen einer Zwillingsabfrage

Beispiel des SDK-Diensts

Übersicht

Erstellen einer Geräteanwendung

Mit einem Gerät verbinden

Abrufen eines Gerätezwillings und Untersuchen der gemeldeten Eigenschaften

Patchen der gemeldeten Eigenschaften von Gerätezwillingen

Patchhandler für eingehende gewünschte Eigenschaften

Beispiele für SDK-Geräte

Erstellen einer Back-End-Anwendung

Herstellen einer Verbindung mit dem IoT-Hub

Herstellen einer Verbindung mithilfe einer SAS-Richtlinie

Verbinden mit Microsoft Entra

Konfigurieren der Microsoft Entra-App

Authentifizieren mithilfe von DefaultAzureCredential

Codebeispiele

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

Erstellen einer Zwillingsabfrage

Beispiel des SDK-Diensts

Übersicht

Erstellen einer Geräteanwendung

Installieren der SDK-Pakete

Auswählen eines Transportprotokolls

Erstellen eines Clientmoduls

Erstellen Sie ein Protokollmodul

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

Öffnen der Verbindung mit IoT Hub

Abrufen eines Gerätezwillings und Untersuchen der gemeldeten Eigenschaften

Aktualisieren gemeldeter Eigenschaften von Gerätezwillingen

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

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

Beispiele für Geräte-SDK