Bearbeiten einer Gerätevorlage
Eine Gerätevorlage enthält ein Modell, das beschreibt, wie ein Gerät mit IoT Central interagiert. Dieses Modell definiert die Funktionen des Geräts und wie IoT Central damit interagiert. Geräte können Telemetrie- und Eigenschaftswerte an IoT Central senden, und IoT Central kann Eigenschaftenupdates und Befehle an ein Gerät senden. IoT Central verwendet das Modell auch zum Definieren von Interaktionen mit IoT Central-Features wie Aufträgen, Regeln und Exporten.
Änderungen am Modell in einer Gerätevorlage können sich auf ihre gesamte Anwendung auswirken, einschließlich aller verbundenen Geräte. Änderungen an einer Funktion, die von Regeln, Exporten, Gerätegruppen oder Aufträgen verwendet wird, können dazu führen, dass sie sich unerwartet verhalten oder überhaupt nicht funktionieren. Wenn Sie beispielsweise eine Telemetriedefinition aus einer Vorlage entfernen, geschieht Folgendes:
- IoT Central kann diesen Wert nicht mehr interpretieren. IoT Central zeigt Gerätedaten, die es nicht als nicht modellierte Daten interpretieren kann, auf der Seite Rohdaten des Geräts an.
- IoT Central bezieht den Wert nicht mehr in Datenexporte ein.
Damit Sie unbeabsichtigte Folgen der Bearbeitung einer Gerätevorlage besser vermeiden können, enthält dieser Artikel Empfehlungen, die auf Ihrer aktuellen Phase des Entwicklungslebenszyklus basieren. Im Allgemeinen gilt: Je früher Sie sich im Entwicklungslebenszyklus befinden, desto toleranter können Sie bei Änderungen an der Gerätevorlage sein.
Weitere Informationen zu Gerätevorlagen und deren Erstellung finden Sie unter Was sind Gerätevorlagen? und Einrichten einer Gerätevorlage.
Informationen zum Verwalten von Gerätevorlagen mithilfe der IoT Central-REST-API finden Sie unter Verwenden der IoT Central-REST-API zum Verwalten von Gerätevorlagen.
Ändern einer Gerätevorlage
Additive Änderungen, z. B. das Hinzufügen einer Funktion oder Schnittstelle zu einem Modell, sind Nonbreaking Changes. Sie können additive Änderungen an einem Modell in jeder beliebigen Phase des Entwicklungslebenszyklus vornehmen.
Breaking Changes umfassen das Entfernen von Teilen eines Modells oder aber das Ändern eines Funktionsnamens oder Schematyps. Diese Änderungen können dazu führen, dass Anwendungsfeatures wie Regeln, Exporte oder Dashboards Fehlermeldungen anzeigen und nicht mehr funktionieren.
In frühen Phasen der Geräteentwicklung, während Sie Ihr Gerätemodell noch entwerfen und testen, ist die Toleranz bei direkt am Modell vorgenommenen Änderungen größer. Bevor Sie Produktionsgeräte mit einer Gerätevorlage verbinden, können Sie die Vorlage direkt bearbeiten. IoT Central wendet diese Änderungen automatisch auf Geräte an, wenn Sie die Gerätevorlage veröffentlichen.
Nachdem Sie Produktionsgeräte an eine Gerätevorlage angefügt haben, werten Sie die Auswirkung von Änderungen aus, bevor Sie eine Gerätevorlage bearbeiten. Sie sollten keine Breaking Changes an einer Gerätevorlage in der Produktion vornehmen. Wenn Sie solche Änderungen vornehmen möchten, erstellen Sie eine neue Version der Gerätevorlage. Testen Sie die neue Gerätevorlage, und migrieren Sie Ihre Produktionsgeräte dann bei einer geplanten Ausfallzeit zur neuen Vorlage.
Aktualisieren einer IoT Edge-Gerätevorlage
Bei einem IoT Edge-Gerät gruppiert das Modell Funktionen nach Modulen, die den auf dem Gerät ausgeführten IoT Edge-Modulen entsprechen. Das Bereitstellungsmanifest ist ein separates JSON-Dokument, das ein IoT Edge Gerät informiert, welche Module installiert und wie sie konfiguriert werden sollen sowie welche Eigenschaften die Module haben. Wenn Sie ein Bereitstellungsmanifest ändern, können Sie die Gerätevorlage so aktualisieren, dass sie die im Manifest definierten Module und Eigenschaften enthält:
- Navigieren Sie in der Gerätevorlage zum Knoten Module.
- Wählen Sie auf der Seite Modulzusammenfassung die Option Module aus Manifest importieren aus.
- Wählen Sie das entsprechende Bereitstellungsmanifest und dann Importieren aus.
Weitere Informationen finden Sie unter IoT Edge-Geräte und IoT Central.
Bearbeiten und Veröffentlichen von Aktionen
Die folgenden Aktionen sind hilfreich, wenn Sie eine Gerätevorlage bearbeiten:
- Speichern Sie sie. Wenn Sie einen Teil Ihrer Gerätevorlage ändern, wird durch das Speichern der Änderungen ein Entwurf erstellt, zu dem Sie zurückkehren können. Diese Änderungen wirken sich noch nicht auf verbundene Geräte aus. Alle aus dieser Vorlage erstellten Geräte erhalten die gespeicherten Änderungen erst, wenn Sie die Vorlage veröffentlichen.
- Veröffentlichung: Wenn Sie die Gerätevorlage veröffentlichen, werden alle gespeicherten Änderungen auf vorhandene Geräteinstanzen angewendet. Neu erstellte Geräteinstanzen verwenden immer die neueste veröffentlichte Vorlage.
- Versionieren einer Vorlage. Wenn Sie eine Gerätevorlage versionieren, erstellt sie eine neue Vorlage mit allen zuletzt gespeicherten Änderungen. Änderungen an einer neuen Version wirken sich nicht auf vorhandene Geräteinstanzen aus. Weitere Informationen finden Sie unter Versionieren einer Gerätevorlage.
- Versionieren einer Schnittstelle. Wenn Sie eine Schnittstelle versionieren, erstellt sie eine neue Schnittstelle mit allen zuletzt gespeicherten Funktionen. Sie können eine Schnittstelle an mehreren Stellen in einer Vorlage wiederverwenden. Deshalb ändert eine Änderung an einem Verweis auf eine Schnittstelle alle Stellen in der Vorlage, die diese Schnittstelle verwenden. Wenn Sie eine Schnittstelle versionieren, ändert sich dieses Verhalten, weil die neue Version jetzt eine separate Schnittstelle ist. Weitere Informationen finden Sie unter Versionieren einer Schnittstelle.
- Migrieren eines Geräts. Wenn Sie ein Gerät migrieren, wird die Geräteinstanz von einer Gerätevorlage zu einer anderen ausgetauscht. Die Gerätemigration kann eine kurze Zeit dauern, während IoT Central die Änderungen verarbeitet. Weitere Informationen finden Sie unter Migrieren eines Geräts zwischen Versionen.
Versionsnummern
Sowohl Gerätemodelle als auch Schnittstellen haben Versionsnummern. Bei unterschiedlichen Versionsnummern können Modelle oder Schnittstellen einen @id-Wert gemeinsam nutzen und gleichzeitig einen Verlauf von Updates bereitstellen. Versionsnummern werden nur erhöht, wenn Sie eine Versionierung der Vorlage oder Schnittstelle wählen oder aber die Versionsnummer absichtlich ändern. Sie sollten eine Versionsnummer ändern, wenn Sie eine größere Änderung an einer Vorlage oder Schnittstelle vornehmen.
Der folgende Codeausschnitt zeigt das Gerätemodell für ein Thermostatgerät. Das Gerätemodell hat eine einzige Schnittstelle. Die Versionsnummer, 1, wird am Ende des Felds @id angezeigt.
{
"@context": "dtmi:dtdl:context;2",
"@id": "dtmi:com:example:Thermostat;1",
"@type": "Interface",
"displayName": "Thermostat",
"description": "Reports current temperature and provides desired temperature control.",
"contents": [
// ...
]
}
Wählen Sie zum Anzeigen dieser Informationen auf der IoT Central-Benutzeroberfläche im Gerätevorlagen-Editor die Option Identität anzeigen aus:
Versionieren einer Gerätevorlage
So versionieren Sie eine Gerätevorlage
- Wechseln Sie zur Seite Gerätevorlagen.
- Wählen Sie die Gerätevorlage aus, die Sie versionieren möchten.
- Wählen Sie oben auf der Seite Version aus, und geben Sie der Vorlage einen neuen Namen. IoT Central schlägt einen neuen Namen vor, den Sie bearbeiten können.
- Klicken Sie auf Erstellen.
Sie haben jetzt eine neue Vorlage mit einer eindeutigen Identität erstellt, die an vorhandene Geräte nicht angefügt wird.
Versionieren einer Schnittstelle
So erstellen Sie eine neue Version einer Schnittstelle
- Wechseln Sie zur Seite Gerätevorlagen.
- Wählen Sie Ihre Gerätevorlage aus, die sich im Entwurfsmodus befindet.
- Wählen Sie die veröffentlichte Schnittstelle aus, die Sie versionieren und bearbeiten möchten.
- Wählen Sie oben auf der Schnittstellenseite Version aus.
- Klicken Sie auf Erstellen.
Sie haben jetzt eine neue Schnittstelle mit einer eindeutigen Identität erstellt, die mit der vorherigen Schnittstellenversion nicht synchronisiert wird.
Migrieren eines Geräts zwischen verschiedenen Versionen
Es lassen sich mehrere Versionen der Gerätevorlage erstellen. Im Laufe der Zeit werden Sie über mehrere angeschlossene Geräte verfügen, die diese Gerätevorlagen verwenden. Sie können Geräte von einer Version Ihrer Gerätevorlage zu einer anderen migrieren. Die folgenden Schritte beschreiben, wie Sie ein Gerät migrieren:
Wechseln Sie zur Seite Geräte.
Wählen Sie das Gerät aus, das Sie zu einer anderen Version migrieren möchten.
Wählen Sie Migrieren aus:
Wählen Sie die Gerätevorlage mit der Versionsnummer, zu der Sie das Gerät migrieren möchten, und dann Migrieren aus.
Tipp
Sie können mithilfe eines Auftrags alle Geräte in einer Gerätegruppe gleichzeitig zu einer neuen Gerätevorlage migrieren.