Erste Schritte mit IoT Hub Modulidentitäten und Modulzwillingen mittels Azure CLI

Artikel
08/28/2023

Modulidentitäten und Modulzwillinge ähneln den Geräteidentitäten und Gerätezwillingen von Azure IoT Hub, ermöglichen jedoch eine feinere Granularität. Genauso wie Azure IoT Hub-Geräteidentitäten und -Gerätezwillinge es einer Back-End-Anwendung ermöglichen, ein Gerät zu konfigurieren und Sichtbarkeit in den Zustand des Geräts zu gewähren, bieten Modulidentitäten und Modulzwillinge diese Funktionen für die einzelnen Komponenten eines Geräts. Auf geeigneten Geräten mit mehreren Komponenten (beispielsweise auf Betriebssystem- oder Firmwaregeräten) ermöglichen Modulidentitäten und Modulzwillinge isolierte Konfiguration und Zustände für jede Komponente.

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 eine Azure CLI-Sitzung erstellen, in der Sie Folgendes tun:

Erstellen Sie eine Geräteidentität, dann erstellen Sie eine Modulidentität für dieses Gerät.
Aktualisieren Sie einen Satz gewünschter Eigenschaften für den Modulzwilling, welcher der Modulidentität zugeordnet ist.

Voraussetzungen

Azure-Befehlszeilenschnittstelle. Sie können die Befehle in diesem Artikel auch mithilfe von Azure Cloud Shell ausführen. Diese interaktive CLI-Shell kann in Ihrem Browser oder einer Anwendung wie Windows Terminal ausgeführt werden. Bei Verwendung der Cloud Shell müssen Sie nichts installieren. Wenn Sie es vorziehen, die Befehlszeilenschnittstelle lokal zu verwenden, benötigen Sie für diesen Artikel mindestens die Azure CLI-Version 2.36. Führen Sie az --version aus, um die Version zu ermitteln. Informationen zur Installation oder zum Upgrade der Azure CLI finden Sie unter Installieren der Azure CLI.
Einen IoT Hub. Erstellen Sie einen mit der CLI oder dem Azure-Portal.
Stellen Sie sicher, dass der Port 8883 in Ihrer Firewall geöffnet ist. Die Beispiele in diesem Artikel verwenden das MQTT-Protokoll, das über Port 8883 kommuniziert. In einigen Netzwerkumgebungen einiger Unternehmen oder Bildungseinrichtungen kann dieser Port blockiert sein. Weitere Informationen und Problemumgehungen finden Sie unter Herstellen einer Verbindung mit IoT Hub (MQTT).

Modulauthentifizierung

Sie können symmetrische Schlüssel oder X.509-Zertifikate verwenden, um Modulidentitäten zu authentifizieren. Für die X.509-Zertifikatauthentifizierung muss das Zertifikat des Moduls seinen allgemeinen Namen (Common Name, CN) wie CN=<deviceid>/<moduleid> formatiert haben. Beispiel:

openssl req -new -key d1m1.key.pem -out d1m1.csr -subj "/CN=device01\/module01"

Vorbereiten von Cloud Shell

Wenn Sie Azure Cloud Shell verwenden möchten, müssen Sie den Dienst zuerst starten und konfigurieren. Falls Sie die CLI lokal nutzen, können Sie zum Abschnitt Vorbereiten einer CLI-Sitzung springen.

Wählen Sie im Azure-Portal in der Kopfzeile der Seite das Symbol Cloud Shell aus.

Hinweis

Falls Sie die Cloud Shell bisher noch nicht verwendet haben, werden Sie zum Erstellen von Speicher aufgefordert, der für die Nutzung der Cloud Shell erforderlich ist. Wählen Sie ein Abonnement aus, in dem ein Speicherkonto und eine Microsoft Azure Files-Freigabe erstellt werden sollen.
Verwenden Sie die Umgebungsauswahl auf der Cloud Shell-Symbolleiste, um Ihre bevorzugte CLI-Umgebung auszuwählen. In diesem Artikel wird die Bash-Umgebung verwendet. Sie können auch die PowerShell-Umgebung verwenden.

Hinweis

Einige Befehle erfordern eine andere Syntax oder Formatierung in der Bash- und der PowerShell-Umgebung. Weitere Informationen finden Sie unter Tipps zur erfolgreichen Verwendung der Azure CLI.

Vorbereiten einer CLI-Sitzung

Als Nächstes müssen Sie eine Azure CLI-Sitzung vorbereiten. Wenn Sie die Cloud Shell verwenden, führen Sie die Sitzung auf einer Cloud Shell-Registerkarte aus. Wenn Sie einen lokalen CLI-Client verwenden, führen Sie die Sitzung in einer CLI-Instanz aus.

Wenn Sie die Cloud Shell verwenden, fahren Sie direkt mit dem nächsten Schritt fort. Wenn nicht, führen Sie den Befehl az login in der CLI-Sitzung aus, um sich bei Ihrem Azure-Konto anzumelden.

Wenn Sie Cloud Shell verwenden, werden Sie automatisch bei Ihrem Azure-Konto angemeldet. Die gesamte Kommunikation zwischen Ihrer Azure CLI-Sitzung und Ihrem IoT-Hub ist authentifiziert und verschlüsselt. Bei diesem Artikel ist daher keine weitere Authentifizierung, z. B. per Verbindungszeichenfolge, wie bei einem echten Gerät erforderlich. Weitere Informationen zum Anmelden mit Azure CLI finden Sie unter Anmelden mit Azure CLI.
```
az login
```
Führen Sie in der CLI-Sitzung den Befehl az extension add aus. Der Befehl fügt Ihrer CLI-Shell die Microsoft Azure IoT-Erweiterung für Azure CLI hinzu. Die Erweiterung fügt der Azure-Befehlszeilenschnittstelle spezifische Befehle für IoT Hub, IoT Edge und IoT Device Provisioning Service (DPS) hinzu. Nachdem Sie die Erweiterung installiert haben, müssen Sie sie in Cloud Shell-Sitzungen nicht erneut installieren.
```
az extension add --name azure-iot
```
Hinweis

In diesem Artikel wird die neueste Version der Azure IoT-Erweiterung namens azure-iot verwendet. Die Legacy-Version heißt azure-cli-iot-ext. Es sollte jedoch jeweils nur eine Version installiert sein. Sie können den Befehl az extension list verwenden, um die derzeit installierten Erweiterungen zu überprüfen.

Verwenden Sie az extension remove --name azure-cli-iot-ext, um die Legacy-Version der Erweiterung zu entfernen.

Verwenden Sie az extension add --name azure-iot, um die neue Version der Erweiterung hinzuzufügen.

Verwenden Sie az extension list, um die installierten Erweiterungen anzuzeigen.

Erstellen einer Geräteidentität und einer Modulidentität

In diesem Abschnitt erstellen Sie in der CLI-Sitzung eine Geräteidentität für Ihren IoT-Hub und erstellen dann mithilfe dieser Geräteidentität eine Modulidentität. Sie können unter jeder Geräteidentität bis zu 50 Modulidentitäten erstellen.

So erstellen Sie eine Geräteidentität und eine Modulidentität:

Führen Sie in der CLI-Sitzung den Befehl az iot hub device-identity create aus, und ersetzen Sie die folgenden Platzhalter durch die entsprechenden Werte. Mit diesem Befehl wird die Geräteidentität für Ihr Modul erstellt.

{DeviceName}. Der Name Ihres Geräts.

{HubName}. Der Name Ihres IoT-Hubs.
```
az iot hub device-identity create --device-id {DeviceName} --hub-name {HubName} 
```
Führen Sie in der CLI-Sitzung den Befehl az iot hub module-identity create aus, und ersetzen Sie die folgenden Platzhalter durch die entsprechenden Werte. Mit diesem Befehl wird die Modulidentität für Ihr Modul unter der Geräteidentität erstellt, die Sie im vorherigen Schritt erstellt haben.

{DeviceName}. Der Name Ihres Geräts.

{HubName}. Der Name Ihres IoT-Hubs.

{ModuleName}. Der Name des Moduls Ihres Geräts.
```
az iot hub module-identity create --device-id {DeviceName} --hub-name {HubName} \
                                  --module-id {ModuleName}
```

Aktualisieren des Modulzwillings

Sobald eine Modulidentität erstellt wurde, wird implizit ein Gerätezwilling in IoT Hub erstellt. In diesem Abschnitt verwenden Sie die CLI-Sitzung, um einen Satz von gewünschten Eigenschaften auf dem Modulzwilling zu aktualisieren, welcher der Modulidentität zugeordnet ist, die Sie im vorherigen Abschnitt erstellt haben.

Führen Sie in der CLI-Sitzung den Befehl az iot hub module-twin update aus, und ersetzen Sie die folgenden Platzhalter durch die entsprechenden Werte. In diesem Beispiel aktualisieren wir mehrere gewünschte Eigenschaften für den Modulzwilling für die Modulidentität, die wir im vorherigen Abschnitt erstellt haben.

{DeviceName}. Der Name Ihres Geräts.

{HubName}. Der Name Ihres IoT-Hubs.

{ModuleName}. Der Name des Moduls Ihres Geräts.
```
az iot hub module-twin update --device-id {DeviceName} --hub-name {HubName} \
                              --module-id {ModuleName} \
                              --desired '{"conditions":{"temperature":{"warning":75, "critical":100}}}'
```

Bestätigen Sie in CLI-Sitzung, dass die JSON-Antwort die Ergebnisse des Aktualisierungsvorgangs anzeigt. Im folgenden JSON-Antwortbeispiel haben wir im CLI-Befehl az iot hub module-twin update die Werte SampleDevice und SampleModule für die Platzhalter {DeviceName} und {ModuleName} verwendet.

{
  "authenticationType": "sas",
  "capabilities": null,
  "cloudToDeviceMessageCount": 0,
  "connectionState": "Disconnected",
  "deviceEtag": "Mzg0OEN1NzW=",
  "deviceId": "SampleDevice",
  "deviceScope": null,
  "etag": "AAAAAAAAAAI=",
  "lastActivityTime": "0001-01-01T00:00:00+00:00",
  "modelId": "",
  "moduleId": "SampleModule",
  "parentScopes": null,
  "properties": {
    "desired": {
      "$metadata": {
        "$lastUpdated": "2023-02-17T21:26:10.5835633Z",
        "$lastUpdatedVersion": 2,
        "conditions": {
          "$lastUpdated": "2023-02-17T21:26:10.5835633Z",
          "$lastUpdatedVersion": 2,
          "temperature": {
            "$lastUpdated": "2023-02-17T21:26:10.5835633Z",
            "$lastUpdatedVersion": 2,
            "critical": {
              "$lastUpdated": "2023-02-17T21:26:10.5835633Z",
              "$lastUpdatedVersion": 2
            },
            "warning": {
              "$lastUpdated": "2023-02-17T21:26:10.5835633Z",
              "$lastUpdatedVersion": 2
            }
          }
        }
      },
      "$version": 2,
      "conditions": {
        "temperature": {
          "critical": 100,
          "warning": 75
        }
      }
    },
    "reported": {
      "$metadata": {
        "$lastUpdated": "0001-01-01T00:00:00Z"
      },
      "$version": 1
    }
  },
  "status": "enabled",
  "statusReason": null,
  "statusUpdateTime": "0001-01-01T00:00:00+00:00",
  "tags": null,
  "version": 3,
  "x509Thumbprint": {
    "primaryThumbprint": null,
    "secondaryThumbprint": null
  }
}

Nächste Schritte

Unter Planen und Übertragen von Aufträgen erfahren Sie, wie Sie mithilfe der Azure CLI Ihre IoT-Lösung erweitern und Aktualisierungen für Geräte planen.

Informationen zu weiteren ersten Schritten mit IoT Hub und Geräteverwaltungsmustern wie z. B. einem imagebasierten End-to-End-Update finden Sie unter Tutorial: Device Update for Azure IoT Hub unter Verwendung des Raspberry Pi 3 B+-Referenzimages.

Share via