Importieren von Updates in Device Update für IoT Hub

Um ein Update von Device Update für IoT Hub auf Geräten bereitzustellen, müssen Sie dieses Update zuerst in den Geräteupdatedienst importieren. 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 zum zu importierenden Update definiert. Sie übermitteln sowohl Das Importmanifest als auch die zugeordnete Updatedatei oder -dateien (z. B. ein Firmwareupdatepaket) als Teil des Importvorgangs. Die im Importmanifest definierten Metadaten werden verwendet, um das Update aufzunehmen. Einige der Metadaten werden auch zur Bereitstellungszeit verwendet, z. B. um zu überprüfen, ob ein Update ordnungsgemäß installiert wurde.

Beispiel:

{
  "updateId": {
    "provider": "Contoso",
    "name": "Toaster",
    "version": "1.0"
  },
  "isDeployable": false,
  "compatibility": [
    {
      "deviceManufacturer": "Contoso",
      "deviceModel": "Toaster"
    }
  ],
  "instructions": {
    "steps": [
      {
        "handler": "microsoft/swupdate:1",
        "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": "4.0"
}

Das Importmanifest enthält mehrere Elemente, die wichtige Geräteupdates für IoT Hub-Konzepte darstellen. Diese Elemente werden in diesem Abschnitt beschrieben. Informationen zum vollständigen Importschema finden Sie im JSON-Schema des Importmanifests.

Identität aktualisieren

Die Updateidentität oder updateId ist der eindeutige Bezeichner für ein Update im Geräteupdate für IoT Hub. Es besteht aus drei Teilen:

• Anbieter: Entität, die für das Update erstellt oder direkt verantwortlich ist. Es wird oft ein Firmenname sein.
• Name: Bezeichner für eine Klasse von Updates. Es ist häufig eine Geräteklasse oder ein Modellname.
• Version: Eine Versionsnummer, die dieses Update von anderen unterscheidet, die denselben Anbieter und Namen haben.

Beispiel:

{
  "updateId": {
    "provider": "Contoso",
    "name": "Toaster",
    "version": "1.0"
  }
}

Kompatibilität

Kompatibilität definiert die Kriterien eines Geräts, das das Update installieren kann. Es enthält Geräteeigenschaften, bei denen es sich um einen Satz beliebiger Schlüsselwertpaare handelt, die von einem Gerät gemeldet werden. Nur Geräte mit übereinstimmenden Eigenschaften sind für die Bereitstellung berechtigt. Ein Update kann mit mehreren Geräteklassen kompatibel sein, indem mehrere Geräteeigenschaften vorhanden sind.

Hier ist ein Beispiel für ein Update, das nur auf einem Gerät bereitgestellt werden kann, das Contoso und Toaster als Gerätehersteller und -modell meldet.

{
  "compatibility": [
    {
      "deviceManufacturer": "Contoso",
      "deviceModel": "Toaster"
    }
  ]
}

Anweisungen

Der Abschnitt "Anweisungen" enthält die erforderlichen Informationen oder Schritte für den Geräte-Agent, um das Update zu installieren. Das einfachste Update enthält einen einzelnen Inlineschritt. Dieser Schritt führt die enthaltene Nutzlastdatei mithilfe eines Handlers aus, der beim Geräte-Agent registriert ist:

{
  "instructions": {
    "steps": [
      {
        "handler": "microsoft/swupdate:1",
        "files": [
          "contoso.toaster.1.0.swu"
        ]
      }
    ]
  }
}

Ein Update kann mehrere Schritte enthalten:

{
  "instructions": {
    "steps": [
      {
        "description": "pre-install script",
        "handler": "microsoft/script:1",
        "handlerProperties": {
          "arguments": "--pre-install"
        },
        "files": [
          "configure.sh"
        ]
      },
      {
        "description": "firmware package",
        "handler": "microsoft/swupdate:1",
        "files": [
          "contoso.toaster.1.0.swu"
        ]
      }
    ]
  }
}

Ein Update kann Referenzschritte enthalten, die den Geräte-Agenten anweisen, ein anderes Update zusammen mit seinem eigenen Importmanifest insgesamt zu installieren und so eine Beziehung zwischen übergeordneten und untergeordneten Aktualisierungen herstellen. 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 Teil "Dateien" enthält die Metadaten von Updatenutzlastdateien wie Namen, Größen und Hash. Geräteupdate für IoT Hub verwendet diese Metadaten für die Integritätsüberprüfung während des Importvorgangs. Die gleichen Informationen werden dann an den Geräte-Agent weitergeleitet, um die Integritätsüberprüfung vor der Installation zu wiederholen.

Erstellen eines Importmanifests

Sie können einen beliebigen Text-Editor verwenden, um eine JSON-Manifestdatei zu erstellen. Es gibt auch Beispielskripts zum programmgesteuerten Erstellen des Importmanifests in Azure/iot-hub-device-update auf GitHub.

Beschränkungen beim Importieren von Updates

Für jede Device Update for IoT Hub-Instanz werden bestimmte Grenzwerte erzwungen. Wenn Sie sie noch nicht überprüft haben, lesen Sie die Geräteaktualisierungsgrenzwerte.

Nächste Schritte

• Weitere Informationen zum Importvorgang finden Sie unter Ein Update zum Import vorbereiten.
• Überprüfen Sie das Importmanifestschema.