Freigeben über

Importieren von Updates in Device Update für IoT Hub

  • Artikel

Wenn Sie ein Update aus Device Update für IoT Hub auf Geräten bereitstellen möchten, müssen Sie es zuerst in den Device Update-Dienst 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 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.

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 ein wichtiges Device Update for IoT Hub-Konzepte darstellen. Diese Elemente werden in diesem Abschnitt erläutert. Informationen zum vollständigen Importschema finden Sie im JSON-Schema des Importmanifests.

Update-Identität

Die Update-Identität (updateId) ist der eindeutige Bezeichner für ein Update in Device Update for IoT Hub. Sie besteht aus drei Teilen:

  • Anbieter: Entität, die das Update erstellt oder direkt verantwortlich für dieses ist. Oft ist dies ein Firmenname.
  • Name: Bezeichner für eine Klasse von Updates. Dies ist oft eine Geräteklasse oder ein Modellname.
  • Version: Versionsnummer, die dieses Update von anderen mit demselben Anbieter und Namen unterscheidet.

Beispiel:

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

Hinweis

updateId wird nur vom Device Update for IoT Hub-Dienst verwendet und kann sich von der Identität der tatsächlichen Softwarekomponente auf dem Gerät unterscheiden.

Kompatibilität

Die Kompatibilität definiert die Kriterien eines Geräts, auf dem das Update installiert werden kann. Sie enthält Geräteeigenschaften, die eine Menge beliebiger Schlüssel-Wert-Paare sind, die von einem Gerät gemeldet werden. Nur Geräte mit übereinstimmenden Eigenschaften werden in die Bereitstellung einbezogen. Ein Update kann mit mehreren Geräteklassen kompatibel sein, wenn es mehrere Sätze von Geräteeigenschaften umfasst.

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 Teil Anweisungen enthält die erforderlichen Informationen oder Schritte, damit der Geräte-Agent das Update installieren kann. Das einfachste Update enthält nur einen einzelnen Inlineschritt. In diesem Schritt wird die enthaltene Nutzdatendatei mithilfe eines Handlers ausgeführt, der beim Geräte-Agent registriert ist:

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

Tipp

handler entspricht in Importmanifestversion 3.0 oder früher updateType.

Ein Update kann mehrere Schritte umfassen:

{
  "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-Agent anweisen, ein weiteres Update mit einem eigenen Importmanifest zu installieren und eine Beziehung zwischen über- und untergeordneten Updates zu erstellen. 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"
        }
      }
    ]
  }
}

Hinweis

Ein Update kann eine beliebige Kombination aus Inline- und Referenzschritten enthalten.

Dateien

Der Teil Dateien enthält die Metadaten der Nutzdatendateien des Updates wie Namen, Größen und Hashwerte. Device Update for IoT Hub verwendet diese Metadaten für die Integritätsprüfung während des Importvorgangs. Die gleichen Informationen werden dann an den Geräte-Agent weitergeleitet, um die Integritätsprüfung vor der Installation zu wiederholen.

Hinweis

Ein Update, das nur Referenzschritte umfasst, enthält keine Nutzdatendatei für das Update im übergeordneten Update.

Erstellen eines Importmanifests

Sie können einen beliebigen Text-Editor verwenden, um eine Importmanifestdatei im JSON-Format zu erstellen. Es gibt auch Beispielskripts für das programmgesteuerte Erstellen eines Importmanifests in Azure/iot-hub-device-update auf GitHub.

Wichtig

Der JSON-Dateiname des Importmanifests muss auf .importmanifest.json enden, wenn er über das Azure-Portal importiert wird.

Tipp

Verwenden Sie Visual Studio Code, um AutoVervollständigen und die JSON-Schemavalidierung beim Erstellen eines Importmanifests zu aktivieren.

Grenzwerte für den Import von Updates

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.

Nächste Schritte