apt-Manifest für Device Update

  • Artikel

Das apt-Manifest ist eine JSON-Datei, in der die vom apt-Updatehandler benötigten Details zu einem Update beschrieben werden. Diese Datei kann in Device Update for IoT Hub wie jedes andere Update importiert werden.

Weitere Informationen finden Sie unter Importieren eines Updates in Device Update for IoT Hub.

Übersicht

Wenn ein apt-Manifest als Update an einen Device Update-Agent übermittelt wird, verarbeitet der Agent das Manifest und führt die erforderlichen Vorgänge aus. Diese Vorgänge umfassen das Herunterladen und Installieren der in der apt-Manifestdatei angegebenen Pakete und ihrer Abhängigkeiten aus einem bestimmten Repository.

Device Update unterstützt den updateType „apt“ und den apt-Updatehandler. Diese Unterstützung ermöglicht es dem Device Update-Agent, die installierten Debian-Pakete auszuwerten und die benötigten Pakete zu aktualisieren.

Schema

Eine apt-Manifestdatei ist eine JSON-Datei mit einem Schema mit Versionsverwaltung.

{
    "name": "<name>",
    "version": "<version>",
    "packages": [
        {
            "name": "<package name>",
            "version": "<version specifier>"
        }
    ]
}

Zum Beispiel:

{
    "name": "contoso-iot-edge",
    "version": "1.0.0.0",
    "packages": [
        {
            "name" : "thermocontrol",
            "version" : "1.0.1"
        },
        {
            "name" : "tempreport",
            "version" : "2.0.0"
        }
    ]
}

Jedes apt-Manifest umfasst die folgenden Eigenschaften:

  • Name: Der Name für dieses apt-Manifest. Dies kann ein beliebiger Name oder eine ID sein, die für Ihre Szenarien sinnvoll ist. Beispiel: contoso-iot-edge.
  • Version: Eine Versionsnummer für dieses apt-Manifest. Beispiel: 1.0.0.0.
  • Pakete: Eine Liste von Objekten, die paketspezifische Eigenschaften enthalten.
    • Name: Der Name oder die ID des Pakets. Beispiel: iotedge.
    • Version: Die gewünschten Versionskriterien für das Paket. Beispiel: 1.0.8-2. Der Versionswert sollte kein Gleichheitszeichen enthalten. Wenn die Version ausgelassen wird, erfolgt die Installation der neuesten verfügbaren Version des angegebenen Pakets.

Derzeit wird nur die exakte Versionsnummer unterstützt. Die Versionsnummer ist die gewünschte Debian-Paketversion im Format [epoch:]upstream_version[-debian_revision], wobei epoch eine ganze Zahl ohne Vorzeichen ist und upstream_version alphanumerische Zeichen und Zeichen wie „.“, „+“, „-“ und „~“ enthalten kann. Es sollte mit einer Ziffer beginnen.

Hinweis

„1.0.8“ ist gleich „1.0.8-0“.

Zum Beispiel ist "name":"iotedge" und "version":"1.0.8-2" gleichbedeutend mit der Installation eines Pakets mit dem Befehl apt-get install iotedge=1.0.8-2.

Weitere Informationen zur Versionsverwaltung von Debian-Paketen finden Sie im Leitfaden zu den Debian-Richtlinien.

Hinweis

Der apt-Paket-Manager ignoriert die von einem Paket angegebenen Anforderungen zur Versionsverwaltung, wenn die zu installierenden abhängigen Pakete automatisch aufgelöst werden. Wenn keine expliziten Versionen von abhängigen Paketen angegeben werden, wird die neueste Version verwendet, auch wenn das Paket selbst eine strikte Anforderung (=) an eine bestimmte Version stellt. Diese automatische Auflösung kann zu Fehlern bezüglich einer nicht erfüllten Abhängigkeit führen. Weitere Informationen

Wenn Sie eine bestimmte Version des Azure IoT Edge-Sicherheitsdaemons aktualisieren, sollten Sie die gewünschte Version des aziot-edge-Pakets und des abhängigen aziot-identity-service-Pakets in Ihr apt-Manifest aufnehmen. Weitere Informationen finden Sie unter Aktualisieren von IoT Edge.

Ein APT-Manifest kann verwendet werden, um den Device Update-Agent und seine Abhängigkeiten zu aktualisieren. Führen Sie den Namen des Device Update-Agents und die gewünschte Version im APT-Manifest auf, wie bei jedem anderen Paket auch. Dieses APT-Manifest kann dann über die Device Update for IoT Hub-Pipeline importiert und bereitgestellt werden.

Entfernen von Paketen

Sie können ein APT-Manifest auch dazu verwenden, um installierte Pakete von Ihrem Gerät zu entfernen. Mit einem einzelnen apt-Manifest können Sie mehrere Pakete entfernen, hinzufügen und aktualisieren.

Fügen Sie ein Minuszeichen „-“ nach dem Paketnamen hinzu, um ein Paket zu entfernen. Sie sollten keine Versionsnummer für die Pakete einbeziehen, die Sie entfernen. Wenn Sie Pakete über ein apt-Manifest entfernen, werden die Abhängigkeiten und Konfigurationen nicht entfernt.

Zum Beispiel:

{
    "name": "contoso-video",
    "version": "2.0.0.1",
    "packages": [
        {
            "name" : "foo-"
        }
    ]
}

Dieses apt-Manifest entfernt das Paket „foo“ von den Geräten, auf denen es bereitgestellt wird.

Die installierten Kriterien für ein apt-Manifest lauten <name>-<version>, wobei <name> der Name und <version> die Version des apt-Manifests ist. Beispiel: contoso-iot-edge-1.0.0.0.

Richtlinien zum Erstellen eines apt-Manifests

Beim Erstellen des apt-Manifests sind einige Richtlinien zu beachten:

  • Stellen Sie immer sicher, dass das apt-Manifest eine wohlgeformte JSON-Datei ist.
  • Jedes apt-Manifest sollte über eine eindeutige Version verfügen. Versuchen Sie, eine standardisierte Methodik zur Erhöhung der Version des apt-Manifests zu entwickeln, sodass sie für Ihre Szenarien sinnvoll ist und leicht befolgt werden kann.
  • Wenn es um den gewünschten Zustand der einzelnen Pakete geht, geben Sie den genauen Namen und die Version des Pakets an, das Sie auf Ihrem Gerät installieren möchten. Überprüfen Sie die Werte immer anhand des Paketrepositorys, das Sie als Quelle für das Paket verwenden möchten.
  • Stellen Sie sicher, dass die Pakete im apt-Manifest in der Reihenfolge aufgeführt sind, in der sie installiert/entfernt werden sollen.
  • Überprüfen Sie die Installation von Paketen immer auf einem Testgerät, um sicherzustellen, dass Sie das gewünschte Ergebnis erhalten.
  • Wenn Sie eine bestimmte Version eines Pakets installieren (z. B. iotedge 1.0.9-1), ist es eine bewährte Methode, im apt-Manifest auch die expliziten Versionen der abhängigen Pakete anzugeben, die installiert werden sollen (z. B. libiothsm 1.0.9-1).
  • Obwohl es nicht vorgeschrieben ist, sollten Sie immer sicherstellen, dass Ihr apt-Manifest kumulativ ist, um zu vermeiden, dass Ihr Gerät in einen unbekannten Zustand wechselt. Ein kumulatives Update stellt sicher, dass Ihre Geräte über die gewünschte Version der einzelnen Pakete verfügen, die Ihnen wichtig sind, selbst wenn das Gerät eine apt-Updatebereitstellung übersprungen hat, da bei der Installation ein Fehler aufgetreten ist oder es offline genommen wurde.

Zum Beispiel:

apt-Basismanifest

{
    "name": "contoso-iot-edge",
    "version": "1.0",
    "packages": [
        {
            "name": "foo",
            "version": "1.0.1"
        }
    ]
}

Ungültiges Update

Dieses Update enthält das Paket „bar“, aber nicht das Paket „foo“.

{
    "name": "contoso-iot-edge",
    "version": "2.0",
    "packages": [
        {
            "name": "bar",
            "version": "3.0.2"
        }
    ]
}

Gültiges Update

Dieses Update enthält das Paket „foo“ und auch das Paket „bar“.

{
    "name": "contoso-iot-edge",
    "version": "2.0",
    "packages": [
        {
            "name": "foo",
            "version": "1.0.1"
        },
        {
            "name": "bar",
            "version": "3.0.2"
        }
    ]
}

Nächste Schritte

Importieren eines Updates in Device Update