Freigeben über

Azure Device Update for IoT Hub: apt-Manifest

  • Artikel

In diesem Artikel wird das apt-Manifest vorgestellt. Dabei handelt es sich um eine JSON-Datei, in der die vom apt-Updatehandler benötigten Updatedetails beschrieben werden. Sie können diese Datei wie jedes andere Update in Device Update importieren. Weitere Informationen finden Sie unter Importieren eines Updates in Device Update for IoT Hub.

Wenn Sie ein apt-Manifest als Update an einen Device Update-Agent übermitteln, 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 apt-Updatetyp und Updatehandler. Diese Unterstützung ermöglicht es dem Device Update-Agent, die installierten Debian-Pakete auszuwerten und die benötigten Pakete zu aktualisieren.

Sie können ein apt-Manifest verwenden, um den Device Update-Agent selbst 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. Anschließend können Sie dieses apt-Manifest importieren und über die Device Update-Pipeline bereitstellen.

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: Ein Name für dieses passende Manifest. Es kann ein beliebiger aussagekräftiger Name oder eine beliebige ID sein, der bzw. die zu Ihrem Szenario passt. Beispiel: contoso-iot-edge.
  • Version: Eine Versionsnummer für dieses apt-Manifest, z. B. 1.0.0.0
  • Pakete: Eine Liste von Objekten, die paketspezifische Eigenschaften enthalten.
    • Name: Der Name oder die ID des Pakets, etwa iotedge
    • Version: Die gewünschten Versionskriterien für das Paket, z. B. 1.0.8-2

Versionsverwaltung

Das apt-Manifest unterstützt nur genaue Versionsnummern. Die Versionsnummer ist die gewünschte Debian-Paketversion im Format <epoch>:<upstream_version>-<debian_revision>. Dabei ist epoch eine ganze Zahl ohne Vorzeichen, und upstream_version beginnt mit einer Zahl und kann alphanumerische Zeichen sowie Zeichen wie ., ,, +, - und ~ enthalten. Der Versionswert sollte kein Gleichheitszeichen enthalten.

Zum Beispiel sind "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. Version 1.0.8 ist gleichbedeutend mit 1.0.8-0.

Wenn die Version ausgelassen wird, installiert Device Update die aktuelle verfügbare Version des angegebenen Pakets. 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 aktuelle 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.

Daher ist es beim Installieren einer bestimmten Version eines Pakets am besten, auch die expliziten Versionen der abhängigen Pakete einzuschließen, die installiert werden sollen. Weitere Informationen finden Sie unter Auflösen einer Abhängigkeit von einer festen Version in einem Debian-/Ubuntu-Paket durch „apt-get“ nicht möglich.

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.

Installierte Kriterien

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

Entfernen des Pakets

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

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

Beispielsweise entfernt das folgende apt-Manifest das Paket contoso1 von allen Geräten, auf denen es bereitgestellt war:

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

Richtlinien für die Erstellung eines apt-Manifests

Beachten Sie beim Erstellen eines apt-Manifests die folgenden Richtlinien:

  • Stellen Sie sicher, dass das apt-Manifest eine wohlgeformte JSON-Datei ist.

  • Legen Sie für jedes apt-Manifest eine eindeutige Version fest. 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 Inhalts des Quellpaketrepositorys.

  • Führen Sie die Pakete im apt-Manifest in der Reihenfolge auf, in der sie installiert oder 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 (etwa iotedge 1.0.9-1) installieren, schließen Sie auch die expliziten Versionen der abhängigen Pakete ein, die installiert werden sollen, z. B. libiothsm 1.0.9-1.

  • Es ist zwar nicht erforderlich, aber eine kumulative Gestaltung des apt-Manifests verhindert, dass Geräte in einen unbekannten Zustand versetzt werden. Ein kumulatives Update stellt sicher, dass Ihre Geräte über die gewünschte Version der einzelnen relevanten Pakete verfügen, auch wenn das Gerät ein Update aufgrund eines Installationsfehlers oder des Offlinezustands übersprungen hat.

    Betrachten Sie etwa das folgende apt-Basismanifest:

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

    Das folgende Update der Version 2.0 enthält das Paket contoso2, aber nicht das Paketcontoso1. Alle Geräte, die das Update 2.0 erhalten, verfügen möglicherweise nicht über das Paket contoso1.

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

    Das folgende kumulative Update der Version 2.0 enthält sowohl das Paket contoso1 als auch das Paket contoso2:

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

Zugehöriger Inhalt