Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Im Rahmen des Gerätelebenszyklus müssen Sie Möglicherweise Ihre IoT-Geräte von Ihrem Back-End-Dienst konfigurieren. Wenn Sie eine gewünschte Konfiguration an Ihre Geräte senden, möchten Sie auch Status- und Complianceupdates von diesen Geräten empfangen. Sie können beispielsweise einen Zielbetriebstemperaturbereich für ein Gerät festlegen oder Firmwareversionsinformationen von Ihren Geräten sammeln.
Um Zustandsinformationen zwischen einem Gerät und einem IoT-Hub zu synchronisieren, verwenden Sie Geräte-Zwillinge. Ein Geräte-Twin ist ein JSON-Dokument, das einem bestimmten Gerät zugeordnet ist und von IoT Hub in der Cloud gespeichert wird, in dem Sie sie abfragen können. Ein Gerätetwin enthält die gewünschten Eigenschaften, die gemeldeten Eigenschaften und Tags.
- Eine gewünschte Eigenschaft wird von einer Back-End-Anwendung festgelegt und von einem Gerät gelesen.
- Eine gemeldete Eigenschaft wird von einem Gerät festgelegt und von einer Back-End-Anwendung gelesen.
- Ein Tag wird von einer Back-End-Anwendung festgelegt und nie an ein Gerät gesendet. Sie verwenden Tags, um Ihre Geräte zu organisieren.
In diesem Lernprogramm erfahren Sie, wie Sie die gewünschten und gemeldeten Eigenschaften zum Synchronisieren von Statusinformationen verwenden.
In diesem Lernprogramm führen Sie die folgenden Aufgaben aus:
- Erstellen Sie einen IoT-Hub, und fügen Sie der Identitätsregistrierung ein Testgerät hinzu.
- Verwenden Sie die gewünschten Eigenschaften, um Statusinformationen an Ihr simuliertes Gerät zu senden.
- Verwenden Sie gemeldete Eigenschaften, um Zustandsinformationen von Ihrem simulierten Gerät zu empfangen.
Wenn Sie noch kein Azure-Abonnement haben, erstellen Sie ein kostenloses Konto, bevor Sie beginnen.
Voraussetzungen
In diesem Lernprogramm wird die Azure CLI zum Erstellen von Cloudressourcen verwendet. Wenn Sie bereits über einen IoT-Hub verfügen, auf dem ein Gerät registriert ist, können Sie diese Schritte überspringen. Es gibt zwei Möglichkeiten zum Ausführen von CLI-Befehlen:
Verwenden Sie die Bash-Umgebung in Azure Cloud Shell. Weitere Informationen finden Sie unter Azure Cloud Shell-Schnellstart: Bash.
Wenn Sie CLI-Referenzbefehle lieber lokal ausführen möchten, installieren Sie die Azure CLI. Wenn Sie mit Windows oder macOS arbeiten, sollten Sie die Azure CLI in einem Docker-Container ausführen. Weitere Informationen finden Sie unter Ausführen der Azure CLI in einem Docker-Container.
- Melden Sie sich mit dem Befehl az login bei der Azure CLI an.
- Installieren Sie die Azure CLI-Erweiterungen bei der ersten Verwendung, wenn Sie dazu aufgefordert werden. Weitere Informationen zu Erweiterungen finden Sie unter Verwenden von Erweiterungen mit der Azure CLI.
- Führen Sie az version aus, um die installierte Version und die abhängigen Bibliotheken zu ermitteln. Führen Sie az upgrade aus, um auf die neueste Version zu aktualisieren.
Die beiden Beispielanwendungen, die Sie in diesem Lernprogramm ausführen, werden mit Node.jsgeschrieben. Sie benötigen Node.js v10.x.x oder höher auf Ihrem Entwicklungscomputer.
Sie können Node.js für mehrere Plattformen von nodejs.org herunterladen.
Sie können die aktuelle Version von Node.js auf Ihrem Entwicklungscomputer mit dem folgenden Befehl überprüfen:
node --version
Klonen sie, oder laden Sie das Beispiel Node.js Projekt aus Azure IoT-Beispielen für Node.jsherunter.
Stellen Sie sicher, dass der Port 8883 in Ihrer Firewall geöffnet ist. Im Beispiel des Geräts in diesem Lernprogramm wird das MQTT-Protokoll verwendet, das über Port 8883 kommuniziert. Dieser Port kann in einigen Unternehmens- und Bildungsnetzwerkumgebungen blockiert werden. Weitere Informationen und Möglichkeiten, dieses Problem zu umgehen, finden Sie unter "Connecting to IoT Hub (MQTT)".
Einrichten von Azure-Ressourcen
Um dieses Lernprogramm abzuschließen, muss Ihr Azure-Abonnement einen IoT-Hub mit einem Gerät enthalten, das der Geräteidentitätsregistrierung hinzugefügt wurde. Der Eintrag in der Geräteidentitätsregistrierung ermöglicht es dem simulierten Gerät, das Sie in diesem Lernprogramm ausführen, eine Verbindung mit Ihrem Hub herzustellen.
Wenn Sie noch keinen IoT-Hub in Ihrem Abonnement eingerichtet haben, können Sie eins mit dem folgenden CLI-Skript einrichten. Dieses Skript verwendet den Namen tutorial-iot-hub mit einer Zufallszahl, die für den IoT-Hubnamen angefügt wird. Sie können diesen Namen durch Ihren eigenen global eindeutigen Namen ersetzen, wenn Sie ihn ausführen. Das Skript erstellt die Ressourcengruppe und den Hub in der Region Zentral-USA , die Sie in eine Region ändern können, die Ihnen näher ist. Das Skript ruft Ihre IoT Hub-Dienstverbindungszeichenfolge ab, die Sie im Back-End-Beispiel zum Herstellen einer Verbindung mit Ihrem IoT-Hub verwenden:
let "randomIdentifier=$RANDOM*$RANDOM"
hubname="tutorial-iot-hub-$randomIdentifier"
location=centralus
# Install the IoT extension if it's not already installed:
az extension add --name azure-iot
# Create a resource group:
az group create --name tutorial-iot-hub-rg --location $location
# Create your free-tier IoT hub. You can only have one free IoT hub per subscription.
# Change the sku to S1 to create a standard-tier hub if necessary.
az iot hub create --name $hubname --location $location --resource-group tutorial-iot-hub-rg --partition-count 2 --sku F1
# Make a note of the service connection string, you need it later:
az iot hub connection-string show --hub-name $hubname --policy-name service -o table
In diesem Lernprogramm wird ein simuliertes Gerät namens MyTwinDevice verwendet. Das folgende Skript fügt dieses Gerät ihrer Identitätsregistrierung hinzu und ruft seine Verbindungszeichenfolge ab:
# Create the device in the identity registry:
az iot hub device-identity create --device-id MyTwinDevice --hub-name $hubname --resource-group tutorial-iot-hub-rg
# Retrieve the device connection string, you need this later:
az iot hub device-identity connection-string show --device-id MyTwinDevice --hub-name $hubname --resource-group tutorial-iot-hub-rg -o table
Senden von Statusinformationen an ein Gerät
Sie verwenden die gewünschten Eigenschaften, um Statusinformationen von einer Back-End-Anwendung an ein Gerät zu senden. In diesem Abschnitt erfahren Sie, wie Sie:
- Konfigurieren Sie ein Gerät, um die gewünschten Eigenschaften zu empfangen und zu verarbeiten.
- Senden Sie die gewünschten Eigenschaften von einer Back-End-Anwendung an ein Gerät.
Beispiel für gewünschte Eigenschaften
Sie können ihre gewünschten Eigenschaften auf jede Weise strukturieren, die für Ihre Anwendung praktisch ist. In diesem Beispiel wird eine Eigenschaft der obersten Ebene namens fanOn verwendet und die verbleibenden Eigenschaften in separate Komponenten gruppiert. Der folgende JSON-Codeausschnitt zeigt die Struktur der gewünschten Eigenschaften, die in diesem Lernprogramm verwendet werden. Der JSON-Code befindet sich in der datei desired.json.
{
"fanOn": "true",
"components": {
"system": {
"id": "17",
"units": "farenheit",
"firmwareVersion": "9.75"
},
"wifi" : {
"channel" : "6",
"ssid": "my_network"
},
"climate" : {
"minTemperature": "68",
"maxTemperature": "76"
}
}
}
Empfangen der gewünschten Eigenschaften in einer Geräteanwendung
Um den simulierten Gerätebeispielcode anzuzeigen, der die gewünschten Eigenschaften empfängt, navigieren Sie zum Ordner "iot-hub/Tutorials/DeviceTwins " im Beispiel Node.js Projekts, das Sie heruntergeladen haben. Öffnen Sie dann die SimulatedDevice.js Datei in einem Text-Editor.
In den folgenden Abschnitten wird der Code beschrieben, der auf dem simulierten Gerät ausgeführt wird, das auf die gewünschten Eigenschaftenänderungen reagiert, die von der Back-End-Anwendung gesendet werden.
Abrufen des Geräte-Twin-Objekts
Wenn Sie Ihr Gerät beim IoT-Hub registriert haben, erhalten Sie eine Geräteverbindungszeichenfolge als Ausgabe. Eine Geräteverbindungszeichenfolge wird vom Gerät verwendet, um sich mit seiner registrierten Identität in der Cloud zu authentifizieren. Mit dem folgenden Code wird eine Verbindung mit Ihrem IoT-Hub mithilfe einer Geräteverbindungszeichenfolge hergestellt:
// Get the device connection string from a command line argument
var connectionString = process.argv[2];
Der folgende Code ruft einen Zwilling aus dem Clientobjekt ab:
// Get the device twin
client.getTwin(function(err, twin) {
if (err) {
console.error(chalk.red('Could not get device twin'));
} else {
console.log(chalk.green('Device twin created'));
Handlers erstellen
Sie können Handler für die gewünschten Eigenschaftenupdates erstellen, die auf Aktualisierungen auf unterschiedlichen Ebenen in der JSON-Hierarchie reagieren. In diesem Handler werden beispielsweise alle gewünschten Eigenschaftsänderungen angezeigt, die von einer Back-End-Anwendung an das Gerät gesendet werden. Die Delta-Variable enthält die gewünschten Eigenschaften, die vom Back-End der Lösung gesendet werden:
// Handle all desired property updates
twin.on('properties.desired', function(delta) {
console.log(chalk.yellow('\nNew desired properties received in patch:'));
Der folgende Handler reagiert nur auf Änderungen, die an der fanOn-gewünschten Eigenschaft vorgenommen wurden:
// Handle changes to the fanOn desired property
twin.on('properties.desired.fanOn', function(fanOn) {
console.log(chalk.green('\nSetting fan state to ' + fanOn));
// Update the reported property after processing the desired property
reportedPropertiesPatch.fanOn = fanOn ? fanOn : '{unknown}';
});
Handler für mehrere Eigenschaften
Im Beispiel für die gewünschten Eigenschaften JSON für dieses Lernprogramm enthält der Klimaknoten unter Komponenten zwei Eigenschaften, minTemperature und maxTemperature.
Das lokale Twin-Objekt eines Geräts speichert einen vollständigen Satz von gewünschten und gemeldeten Eigenschaften. Das vom Back-End gesendete Delta aktualisiert möglicherweise nur eine Teilmenge der gewünschten Eigenschaften. Wenn das simulierte Gerät im folgenden Codeausschnitt ein Update nur für entweder minTemperature oder maxTemperature erhält, verwendet es den Wert im lokalen Zwilling für den anderen Wert, um das Gerät zu konfigurieren.
// Handle desired properties updates to the climate component
twin.on('properties.desired.components.climate', function(delta) {
if (delta.minTemperature || delta.maxTemperature) {
console.log(chalk.green('\nUpdating desired tempertures in climate component:'));
console.log('Configuring minimum temperature: ' + twin.properties.desired.components.climate.minTemperature);
console.log('Configuring maximum temperture: ' + twin.properties.desired.components.climate.maxTemperature);
// Update the reported properties and send them to the hub
reportedPropertiesPatch.minTemperature = twin.properties.desired.components.climate.minTemperature;
reportedPropertiesPatch.maxTemperature = twin.properties.desired.components.climate.maxTemperature;
sendReportedProperties();
}
});
Behandeln von Einfüge-, Aktualisierungs- und Löschvorgängen
Die vom Back-End gesendeten gewünschten Eigenschaften geben nicht an, welche Operation für eine bestimmte gewünschte Eigenschaft ausgeführt wird. Ihr Code muss den Vorgang aus der aktuellen Gruppe der gewünschten Eigenschaften, die lokal gespeichert sind, und die vom Hub gesendeten Änderungen ableiten.
Der folgende Codeausschnitt zeigt, wie das simulierte Gerät Einfüge-, Aktualisierungs- und Löschvorgänge in der Liste der Komponenten in den gewünschten Eigenschaften behandelt. Sie können sehen, wie Nullwerte verwendet werden, um anzugeben, dass eine Komponente gelöscht werden soll:
// Keep track of all the components the device knows about
var componentList = {};
// Use this componentList list and compare it to the delta to infer
// if anything was added, deleted, or updated.
twin.on('properties.desired.components', function(delta) {
if (delta === null) {
componentList = {};
}
else {
Object.keys(delta).forEach(function(key) {
if (delta[key] === null && componentList[key]) {
// The delta contains a null value, and the
// device has a record of this component.
// Must be a delete operation.
console.log(chalk.green('\nDeleting component ' + key));
delete componentList[key];
} else if (delta[key]) {
if (componentList[key]) {
// The delta contains a component, and the
// device has a record of it.
// Must be an update operation.
console.log(chalk.green('\nUpdating component ' + key + ':'));
console.log(JSON.stringify(delta[key]));
// Store the complete object instead of just the delta
componentList[key] = twin.properties.desired.components[key];
} else {
// The delta contains a component, and the
// device has no record of it.
// Must be an add operation.
console.log(chalk.green('\nAdding component ' + key + ':'));
console.log(JSON.stringify(delta[key]));
// Store the complete object instead of just the delta
componentList[key] = twin.properties.desired.components[key];
}
}
});
}
});
Senden der gewünschten Eigenschaften aus einer Back-End-Anwendung
Sie haben gesehen, wie ein Gerät Handler für den Empfang von gewünschten Eigenschaftenupdates implementiert. In diesem Abschnitt wird gezeigt, wie Sie die gewünschten Eigenschaftenänderungen von einer Back-End-Anwendung an ein Gerät senden.
Um den simulierten Gerätebeispielcode anzuzeigen, der die gewünschten Eigenschaften empfängt, navigieren Sie zum Ordner "iot-hub/Tutorials/DeviceTwins " im Beispiel Node.js Projekts, das Sie heruntergeladen haben. Öffnen Sie dann die ServiceClient.js Datei in einem Text-Editor.
Der folgende Codeausschnitt zeigt, wie Sie eine Verbindung mit der Geräteidentitätsregistrierung herstellen und auf den Zwilling für ein bestimmtes Gerät zugreifen:
// Create a device identity registry object
var registry = Registry.fromConnectionString(connectionString);
// Get the device twin and send desired property update patches at intervals.
// Print the reported properties after some of the desired property updates.
registry.getTwin(deviceId, async (err, twin) => {
if (err) {
console.error(err.message);
} else {
console.log('Got device twin');
Der folgende Codeausschnitt zeigt verschiedene gewünschte Eigenschaftspatches, die die Back-End-Anwendung an das Gerät sendet.
// Turn the fan on
var twinPatchFanOn = {
properties: {
desired: {
patchId: "Switch fan on",
fanOn: "false",
}
}
};
// Set the maximum temperature for the climate component
var twinPatchSetMaxTemperature = {
properties: {
desired: {
patchId: "Set maximum temperature",
components: {
climate: {
maxTemperature: "92"
}
}
}
}
};
// Add a new component
var twinPatchAddWifiComponent = {
properties: {
desired: {
patchId: "Add WiFi component",
components: {
wifi: {
channel: "6",
ssid: "my_network"
}
}
}
}
};
// Update the WiFi component
var twinPatchUpdateWifiComponent = {
properties: {
desired: {
patchId: "Update WiFi component",
components: {
wifi: {
channel: "13",
ssid: "my_other_network"
}
}
}
}
};
// Delete the WiFi component
var twinPatchDeleteWifiComponent = {
properties: {
desired: {
patchId: "Delete WiFi component",
components: {
wifi: null
}
}
}
};
Der folgende Codeausschnitt zeigt, wie die Back-End-Anwendung eine gewünschte Eigenschaftsaktualisierung an ein Gerät sendet:
// Send a desired property update patch
async function sendDesiredProperties(twin, patch) {
twin.update(patch, (err, twin) => {
if (err) {
console.error(err.message);
} else {
console.log(chalk.green(`\nSent ${twin.properties.desired.patchId} patch:`));
console.log(JSON.stringify(patch, null, 2));
}
});
}
Empfangen von Statusinformationen von einem Gerät
Ihre Back-End-Anwendung empfängt Statusinformationen von einem Gerät als gemeldete Eigenschaften. Ein Gerät legt die gemeldeten Eigenschaften fest und sendet sie an Ihren Hub. Eine Back-End-Anwendung kann die aktuellen Werte der gemeldeten Eigenschaften vom Gerätezwilling lesen, der in Ihrem Hub gespeichert ist.
Senden gemeldeter Eigenschaften von einem Gerät
Sie können Aktualisierungen für Werte von gemeldeten Eigenschaften als Patch senden. Der folgende Codeausschnitt zeigt eine Vorlage für den Patch, den das simulierte Gerät sendet. Das simulierte Gerät aktualisiert die Felder im Patch, bevor es an den Hub gesendet wird:
// Create a patch to send to the hub
var reportedPropertiesPatch = {
firmwareVersion:'1.2.1',
lastPatchReceivedId: '',
fanOn:'',
minTemperature:'',
maxTemperature:''
};
Das simulierte Gerät verwendet die folgende Funktion, um den Patch zu senden, der die gemeldeten Eigenschaften enthält, an den Hub:
// Send the reported properties patch to the hub
function sendReportedProperties() {
twin.properties.reported.update(reportedPropertiesPatch, function(err) {
if (err) throw err;
console.log(chalk.blue('\nTwin state reported'));
console.log(JSON.stringify(reportedPropertiesPatch, null, 2));
});
}
Eigenschaften des gemeldeten Prozesses
Eine Back-End-Anwendung greift über das Gerät Twin auf die aktuellen gemeldeten Eigenschaftswerte für ein Gerät zu. Der folgende Codeausschnitt zeigt, wie die Back-End-Anwendung die gemeldeten Eigenschaftswerte für das simulierte Gerät liest:
// Display the reported properties from the device
function printReportedProperties(twin) {
console.log("Last received patch: " + twin.properties.reported.lastPatchReceivedId);
console.log("Firmware version: " + twin.properties.reported.firmwareVersion);
console.log("Fan status: " + twin.properties.reported.fanOn);
console.log("Min temperature set: " + twin.properties.reported.minTemperature);
console.log("Max temperature set: " + twin.properties.reported.maxTemperature);
}
Ausführen der Anwendungen
In diesem Abschnitt führen Sie die beiden Beispielanwendungen aus, um zu beobachten, dass eine Back-End-Anwendung die gewünschten Eigenschaftsupdates an eine simulierte Geräteanwendung sendet.
Zum Ausführen der simulierten Geräte- und Back-End-Anwendungen benötigen Sie die Verbindungszeichenfolgen für Geräte und Dienste. Sie haben sich die Verbindungszeichenfolgen notiert, als Sie am Anfang dieses Tutorials die Ressourcen erstellt haben.
Um die simulierte Geräteanwendung auszuführen, öffnen Sie eine Shell oder ein Eingabeaufforderungsfenster, und navigieren Sie zum Ordner "iot-hub/Tutorials/DeviceTwins" im heruntergeladenen Node.js Projekt. Führen Sie dann die folgenden Befehle aus:
npm install
node SimulatedDevice.js "{your device connection string}"
Um die Back-End-Anwendung auszuführen, öffnen Sie eine andere Shell oder ein Eingabeaufforderungsfenster. Navigieren Sie dann im heruntergeladenen Node.js Projekt zum Ordner "iot-hub/Tutorials/DeviceTwins ". Führen Sie dann die folgenden Befehle aus:
npm install
node ServiceClient.js "{your service connection string}"
Beobachten Sie gewünschte Eigenschaftenaktualisierungen
Der folgende Screenshot zeigt die Ausgabe der simulierten Geräteanwendung und hebt hervor, wie ein Update für das gewünschte Attribut "maxTemperature" behandelt wird. Sie können sehen, wie sowohl der Handler der obersten Ebene als auch die Klimakomponentenhandler ausgeführt werden:
Im folgenden Screenshot ist die Ausgabe der Back-End-Anwendung dargestellt, und das Senden einer Aktualisierung der gewünschten Eigenschaft maxTemperature ist hervorgehoben:
Beobachten gemeldeter Eigenschaftenupdates
Der folgende Screenshot zeigt die Ausgabe der simulierten Geräteanwendung und hebt hervor, wie eine gemeldete Eigenschaftsaktualisierung an Ihren Hub gesendet wird:
Der folgende Screenshot zeigt die Ausgabe der Back-End-Anwendung und hebt hervor, wie sie ein gemeldetes Eigenschaftenupdate von einem Gerät empfängt und verarbeitet:
Bereinigen von Ressourcen
Wenn Sie das nächste Lernprogramm abschließen möchten, verlassen Sie die Ressourcengruppe und den IoT-Hub, um sie später wiederzuverwenden.
Wenn Sie den IoT-Hub nicht mehr benötigen, löschen Sie ihn und die Ressourcengruppe im Portal. Wählen Sie dazu die Lernprogramm-iot-hub-rg-Ressourcengruppe aus, die Ihren IoT-Hub enthält, und wählen Sie "Löschen" aus.
Alternativ können Sie die CLI verwenden:
# Delete your resource group and its contents
az group delete --name tutorial-iot-hub-rg
Nächste Schritte
In diesem Lernprogramm haben Sie gelernt, wie Sie Zustandsinformationen zwischen Ihren Geräten und Ihrem IoT-Hub synchronisieren. Wechseln Sie zum nächsten Lernprogramm, um zu erfahren, wie Sie Geräte-Zwillinge verwenden, um den Geräteaktualisierungsprozess zu implementieren.