Importkonzepte für Device Update for IoT Hub
Um ein Update auf Geräten mit Azure Device Update for IoT Hub bereitzustellen, importieren Sie zuerst das Update in Device Update, wo das importierte Update für die Bereitstellung auf Geräten gespeichert und auf Geräten bereitgestellt wird. Dieser Artikel bietet eine Übersicht über einige wichtige Konzepte, die Sie beim Importieren von Updates verstehen müssen.
Importmanifest
Ein Importmanifest ist eine JSON-Datei, die wichtige Informationen zu dem gerade importierten Update definiert. Sie übermitteln sowohl Ihr Importmanifest als auch die zugeordneten Updatedateien, z. B. ein Firmwareupdate-Paket, im Rahmen des Importvorgangs. Die im Importmanifest definierten Metadaten werden zum Erfassen des Updates verwendet. Einige der Metadaten werden auch zum Zeitpunkt der Bereitstellung verwendet, beispielsweise zur Überprüfung, ob ein Update richtig installiert wurde.
Der folgende JSON-Code zeigt ein Beispiel einer Importmanifestdatei:
{
"updateId": {
"provider": "Contoso",
"name": "Toaster",
"version": "1.0"
},
"isDeployable": false,
"compatibility": [
{
"manufacturer": "Contoso",
"model": "Toaster"
}
],
"instructions": {
"steps": [
{
"handler": "microsoft/swupdate:2",
"files": [
"firmware.swu"
],
"handlerProperties": {
"installedCriteria": "1.0"
}
}
]
},
"files": [
{
"filename": "firmware.swu",
"sizeInBytes": 7558,
"hashes": {
"sha256": "/CD7Sn6fiknWa3NgcFjGlJ+ccA81s1QAXX4oo5GHiFA="
}
}
],
"createdDateTime": "2022-01-19T06:23:52.6996916Z",
"manifestVersion": "5.0"
}
Die Abschnitte der Importmanifestdatei stellen wichtige Konzepte für Geräteupdates dar, wie in den folgenden Abschnitten beschrieben. Informationen zum vollständigen Importmanifestschema finden Sie im JSON-Schema des Importmanifests.
Update-Identität
Die Update-Identität oder updateId ist der eindeutige Bezeichner für ein Update in Device Update und enthält die folgenden Eigenschaften:
- Anbieter ist die Entität, die das Update erstellt oder für es verantwortlich ist. Anbieter ist oft ein Unternehmensname.
- Name ist der Bezeichner für eine Update-Klasse. Name ist oft eine Geräteklasse oder ein Modellname.
- Version ist eine Nummer, die dieses Update von anderen mit denselben Anbietern und Namen unterscheidet.
Beispiel:
{
"updateId": {
"provider": "Contoso",
"name": "Toaster",
"version": "1.0"
}
}
Hinweis
Die updateId wird nur vom Device Update for IoT Hub-Dienst verwendet und unterscheidet sich von der Identität der tatsächlichen Softwarekomponente auf den Geräten.
Kompatibilität
Im Abschnitt Kompatibilität werden ein oder mehrere beliebige Schlüssel-Wert-Paare verwendet, um die Geräte zu definieren, auf denen ein Update installieren werden kann. Nur Geräte, die Eigenschaften melden, die mit den Kompatibilitätswerten übereinstimmen, sind für die Bereitstellung des Updates berechtigt. Sie können ein Update mit mehreren Geräteklassen kompatibel machen, indem Sie mehr als einen Satz von Gerätekompatibilitätseigenschaften einbeziehen.
Im Folgenden sehen Sie ein Beispiel für ein Update, das nur auf Geräten bereitgestellt werden kann, die Contoso und Toaster als Gerätehersteller und Modell melden.
{
"compatibility": [
{
"manufacturer": "Contoso",
"model": "Toaster"
}
]
}
Anweisungen
Der Abschnitt Anweisungen enthält die erforderlichen Informationen oder Schritte, damit der Geräte-Agent das Update installieren kann. Die einfachste Aktualisierung enthält einen einzelnen Inline-Schritt, der die Update-Nutzdatendatei mithilfe eines Handlers ausführt, der beim Geräte-Agent registriert ist. Das folgende Beispiel zeigt einen Anleitungsabschnitt mit einem Schritt.
{
"instructions": {
"steps": [
{
"handler": "microsoft/swupdate:2",
"files": [
"contoso.toaster.1.0.swu"
]
}
]
}
}
Hinweis
Die Eigenschaft handler entspricht der Eigenschaft updateType in der Importmanifestversion 3.0 oder früher.
Ein Update kann mehrere Schritte umfassen, wie im folgenden Beispiel beschrieben:
{
"instructions": {
"steps": [
{
"description": "pre-install script",
"handler": "microsoft/script:1",
"handlerProperties": {
"arguments": "--pre-install"
},
"files": [
"configure.sh"
]
},
{
"description": "firmware package",
"handler": "microsoft/swupdate:2",
"files": [
"contoso.toaster.1.0.swu"
]
}
]
}
}
Ein Update kann Referenzschritte enthalten, die den Geräte-Agent anweisen, ein weiteres Update mit einem eigenen Importmanifest zu installieren und eine Beziehung zwischen über- und untergeordneten Updates zu erstellen. Ein Update kann eine beliebige Kombination aus Inline- und Referenzschritten enthalten.
Beispielsweise kann ein Update für einen Toaster zwei untergeordnete Updates enthalten:
{
"instructions": {
"steps": [
{
"type": "reference",
"updateId": {
"provider": "Contoso",
"name": "Toaster.HeatingElement",
"version": "1.0"
}
},
{
"type": "reference",
"updateId": {
"provider": "Contoso",
"name": "Toaster.Sensors",
"version": "1.0"
}
}
]
}
}
Dateien
Der Abschnitt Dateien des Importmanifests enthält Metadaten der Update-Nutzdatendatei wie name, size und hash. Device Update verwendet diese Metadaten für die Integritätsprüfung während des Importvorgangs und leitet dieselben Informationen zur Integritätsprüfung vor der Installation an den Geräte-Agent weiter.
Hinweis
Ein übergeordnetes Update, das nur Referenzschritte umfasst, definiert keine Nutzdatendateien für das Update.
Erstellen eines Importmanifests
Es ist zwar möglich, ein JSON-Importmanifest mithilfe eines Text-Editors manuell zu erstellen, aber die Azure CLI vereinfacht den Prozess erheblich. Wenn Sie die Erstellung eines Importmanifests ausprobieren möchten, befolgen Sie die Anleitung.
Wichtig
Um über das Azure-Portal in den Device Update-Service importiert zu werden, muss ein Importmanifest-JSON-Dateiname mit .importmanifest.json enden.
Tipp
Sie können Visual Studio Code verwenden, um AutoVervollständigen und die JSON-Schemavalidierung beim Erstellen eines Importmanifests zu aktivieren.
Importbeschränkungen aktualisieren
Für jede Device Update for IoT Hub-Instanz werden bestimmte Grenzwerte erzwungen. Wenn Sie diese noch nicht überprüft haben, lesen Sie Grenzwerte für Device Update.