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 mit ihnen interagiert. Geräte können Telemetrie- und Eigenschaftswerte an IoT Central senden, IoT Central kann Eigenschaftsaktualisierungen und Befehle an ein Gerät senden. IoT Central verwendet auch das Modell, um Interaktionen mit IoT Central-Features wie Aufträgen, Regeln und Exporten zu definieren.

Ä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:

• IoT Central kann diesen Wert nicht mehr interpretieren. IoT Central zeigt Gerätedaten an, die nicht als nicht modellierte Daten auf der Raw-Datenseite des Geräts interpretiert werden können.
• IoT Central enthält den Wert nicht mehr in irgendeinem Datenexport.

Damit Sie unbeabsichtigte Folgen beim Bearbeiten einer Gerätevorlage vermeiden können, enthält dieser Artikel Empfehlungen basierend auf Ihrer aktuellen Entwicklungslebenszyklusstufe. Im Allgemeinen, je früher Sie sich im Entwicklungslebenszyklus befinden, desto toleranter können Sie änderungen an Gerätevorlagen sein.

Weitere Informationen zu Gerätevorlagen und zum Erstellen einer Vorlage finden Sie unter "Was sind Gerätevorlagen?" und erstellen Sie eine Gerätevorlage in Ihrer Azure IoT Central-Anwendung.

Informationen zum Verwalten von Gerätevorlagen mithilfe der IoT Central REST-API finden Sie unter Verwendung 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 Phase des Entwicklungslebenszyklus vornehmen.

Zu den wichtigsten Änderungen gehören das Entfernen von Teilen eines Modells oder 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 das Modell noch entwerfen und testen, gibt es eine größere Toleranz für änderungen direkt an Ihrem Gerätemodell. Bevor Sie Produktionsgeräte mit einer Gerätevorlage verbinden, können Sie die Gerätevorlage 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, bewerten Sie die Auswirkungen aller Änderungen, bevor Sie eine Gerätevorlage bearbeiten. Sie sollten keine Breaking Changes an einer Gerätevorlage in der Produktion vornehmen. Um solche Änderungen vorzunehmen, erstellen Sie eine neue Version der Gerätevorlage. Testen Sie die neue Gerätevorlage, und migrieren Sie dann Ihre Produktionsgeräte zu 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 ioT Edge-Modulen entsprechen, die auf dem Gerät ausgeführt werden. Das Bereitstellungsmanifest ist ein separates JSON-Dokument, das einem IoT Edge-Gerät angibt, welche Module installiert werden sollen, wie sie konfiguriert werden sollen und welche Eigenschaften das Modul hat. Wenn Sie ein Bereitstellungsmanifest ändern, können Sie die Gerätevorlage aktualisieren, um die module und Eigenschaften einzuschließen, die im Manifest definiert sind:

1. Navigieren Sie in der Gerätevorlage zum Knoten "Module ".
2. Wählen Sie auf der Zusammenfassungsseite "Module " die Option "Module aus Manifest importieren" aus.
3. 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 nützlich, wenn Sie eine Gerätevorlage bearbeiten:

• Speichern. Wenn Sie einen Teil Ihrer Gerätevorlage ändern, wird beim 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 geräte, die aus dieser Vorlage erstellt wurden, verfügen nicht über die gespeicherten Änderungen, bis Sie sie veröffentlichen.
• Veröffentlichen. 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.
• Version einer Vorlage. Wenn Sie eine Gerätevorlage versionieren, wird eine neue Vorlage mit allen neuesten gespeicherten Änderungen erstellt. Änderungen an einer neuen Version wirken sich nicht auf vorhandene Geräteinstanzen aus. Weitere Informationen finden Sie unter „Eine Gerätevorlage versionieren“.
• Versionieren einer Schnittstelle. Wenn Sie eine Schnittstelle versionieren, wird eine neue Schnittstelle mit allen neuesten gespeicherten Funktionen erstellt. Sie können eine Schnittstelle an mehreren Stellen innerhalb einer Vorlage wiederverwenden. Aus diesem Grund ändert eine Änderung an einem Verweis auf eine Schnittstelle alle Stellen in der Vorlage, die die Schnittstelle verwenden. Wenn Sie eine Schnittstelle versionieren, ändert sich dieses Verhalten, da die neue Version jetzt eine separate Schnittstelle ist. Weitere Informationen finden Sie unter Version einer Schnittstelle.
• Migrieren eines Geräts. Wenn Sie ein Gerät migrieren, wechselt die Geräteinstanz von einer Gerätevorlage in eine andere. Die Gerätemigration kann eine kurze Verzögerung verursachen, während IoT Central die Änderungen verarbeitet. Weitere Informationen finden Sie unter Migrieren eines Geräts über Versionen hinweg.

Versionsnummern

Sowohl Gerätemodelle als auch Schnittstellen weisen Versionsnummern auf. Mit 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 die Vorlage oder Schnittstelle versionieren oder die Versionsnummer absichtlich ändern. Sie sollten eine Versionsnummer ändern, wenn Sie eine wichtige Änderung an einer Vorlage oder Schnittstelle vornehmen.

Der folgende Codeausschnitt zeigt das Gerätemodell für ein Thermometergerät. Das Gerätemodell verfügt über eine einzige Schnittstelle. Sie können die Versionsnummer am 1Ende des@id Felds sehen.

{
  "@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": [
    // ...
  ]
}

Um diese Informationen auf der IoT Central UI anzuzeigen, wählen Sie " Identität bearbeiten" im Gerätevorlagen-Editor aus:

Version einer Gerätevorlage

So versionieren Sie eine Gerätevorlage:

1. Wechseln Sie zur Seite "Gerätevorlagen ".
2. Wählen Sie die Gerätevorlage aus, die Sie versionieren möchten.
3. 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.
4. Wählen Sie "Erstellen" aus.

Jetzt haben Sie eine neue Vorlage mit einer eindeutigen Identität erstellt, die nicht mit vorhandenen Geräten verknüpft ist.

Version einer Schnittstelle

So versionieren Sie eine Schnittstelle:

1. Wechseln Sie zur Seite "Gerätevorlagen ".
2. Wählen Sie die Gerätevorlage aus, die Sie in einem Entwurfsmodus haben.
3. Wählen Sie die veröffentlichte Schnittstelle aus, die Sie versionieren und bearbeiten möchten.
4. Wählen Sie oben auf der Schnittstellenseite " Version " aus.
5. Wählen Sie "Erstellen" aus.

Jetzt haben Sie eine neue Schnittstelle mit einer eindeutigen Identität erstellt, die nicht mit der vorherigen Schnittstellenversion synchronisiert wird.

Migrieren eines Geräts über Versionen hinweg

Sie können mehrere Versionen der Gerätevorlage erstellen. Im Laufe der Zeit verfügen Sie über mehrere verbundene Geräte mit diesen Gerätevorlagen. 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:

1. Wechseln Sie zur Seite "Geräte ".

2. Wählen Sie das Gerät aus, das Sie zu einer anderen Version migrieren müssen.

3. Wählen Sie "Migrieren" aus:

   

4. Wählen Sie die Gerätevorlage mit der Version aus, zu der Sie das Gerät migrieren möchten, und wählen Sie "Migrieren" aus.

Tipp

Sie können einen Auftrag verwenden, um alle Geräte in einer Gerätegruppe gleichzeitig zu einer neuen Gerätevorlage zu migrieren.