Mehrstufige geordnete Ausführung

Die mehrstufige geordnete Ausführung ermöglicht es Ihnen, Vor- und Nachinstallationsaufgaben auszuführen, wenn Sie ein Over-the-Air-Update bereitstellen. Diese Funktion ist Teil des Schemas „Public Preview Refresh Update Manifest v4“.

Lesen Sie die Dokumentation zum Updatemanifest, bevor Sie die folgenden Änderungen als Teil des Public Preview Refresh-Releases (Aktualisierung der öffentlichen Vorschau) überprüfen.

Bei mehrstufiger geordneter Ausführung gibt es zwei Arten von Schritten:

• Inline-Schritt (Standard)
• Referenzschritt

Ein Beispiel für ein Updatemanifest mit einem Inline-Schritt:

{
    "updateId": {...},
    "isDeployable": true,
    "compatibility": [
        {
            "manufacturer": "du-device",
            "model": "e2e-test"
        }
    ],
    "instructions": {
        "steps": [
            {
                "description": "Example APT update that install libcurl4-doc on a host device.",
                "handler": "microsoft/apt:1",
                "files": [
                    "apt-manifest-1.0.json"
                ],
                "handlerProperties": {
                    "installedCriteria": "apt-update-test-1.0"
                }
            }
        ]
    },
    "manifestVersion": "4.0",
    "importedDateTime": "2021-11-16T14:54:55.8858676Z",
    "createdDateTime": "2021-11-16T14:50:47.3511877Z"
}

Ein Beispiel für ein Updatemanifest mit zwei Inline-Schritten:

{
    "updateId": {...},
    "isDeployable": true,
    "compatibility": [
        {
            "manufacturer": "du-device",
            "model": "e2e-test"
        }
    ],
    "instructions": {
        "steps": [
            {
                "description": "Install libcurl4-doc on host device",
                "handler": "microsoft/apt:1",
                "files": [
                    "apt-manifest-1.0.json"
                ],
                "handlerProperties": {
                    "installedCriteria": "apt-update-test-2.2"
                }
            },
            {
                "description": "Install tree on host device",
                "handler": "microsoft/apt:1",
                "files": [
                    "apt-manifest-tree-1.0.json"
                ],
                "handlerProperties": {
                    "installedCriteria": "apt-update-test-tree-2.2"
                }
            }
        ]
    },
    "manifestVersion": "4.0",
    "importedDateTime": "2021-11-16T20:21:33.6514738Z",
    "createdDateTime": "2021-11-16T20:19:29.4019035Z"
}

Ein Beispiel für ein Updatemanifest mit einem Referenzschritt:

• Das übergeordnete Update, das auf ein untergeordnetes Update verweist

  {
      "updateId": {...},
      "isDeployable": true,
      "compatibility": [
          {
              "manufacturer": "du-device",
              "model": "e2e-test"
          }
      ],
      "instructions": {
          "steps": [
              {
                  "type": "reference",
                  "description": "Cameras Firmware Update",
                  "updateId": {
                      "provider": "contoso",
                      "name": "virtual-camera",
                      "version": "1.2"
                  }
              }
          ]
      },
      "manifestVersion": "4.0",
      "importedDateTime": "2021-11-17T07:26:14.7484389Z",
      "createdDateTime": "2021-11-17T07:22:10.6014567Z"
  }
  

• Das untergeordnete Update mit Inlineschritten

  {
      "updateId": {
          "provider": "contoso",
          "name": "virtual-camera",
          "version": "1.2"
      },
      "isDeployable": false,
      "compatibility": [
          {
              "group": "cameras"
          }
      ],
      "instructions": {
          "steps": [
              {
                  "description": "Cameras Update - pre-install step",
                  "handler": "microsoft/script:1",
                  "files": [
                      "contoso-camera-installscript.sh"
                  ],
                  "handlerProperties": {
                      "scriptFileName": "contoso-camera-installscript.sh",
                      "arguments": "--pre-install-sim-success --component-name --component-name-val --component-group --component-group-val --component-prop path --component-prop-val path",
                      "installedCriteria": "contoso-virtual-camera-1.2-step-0"
                  }
              },
              {
                  "description": "Cameras Update - firmware installation (failure - missing file)",
                  "handler": "microsoft/script:1",
                  "files": [
                      "contoso-camera-installscript.sh",
                      "camera-firmware-1.1.json"
                  ],
                  "handlerProperties": {
                      "scriptFileName": "missing-contoso-camera-installscript.sh",
                      "arguments": "--firmware-file camera-firmware-1.1.json --component-name --component-name-val --component-group --component-group-val --component-prop path --component-prop-val path",
                      "installedCriteria": "contoso-virtual-camera-1.2-step-1"
                  }
              },
              {
                  "description": "Cameras Update - post-install step",
                  "handler": "microsoft/script:1",
                  "files": [
                      "contoso-camera-installscript.sh"
                  ],
                  "handlerProperties": {
                      "scriptFileName": "contoso-camera-installscript.sh",
                      "arguments": "--post-install-sim-success --component-name --component-name-val --component-group --component-group-val --component-prop path --component-prop-val path",
                      "installedCriteria": "contoso-virtual-camera-1.2-stop-2"
                  }
              }
          ]
      },
      "referencedBy": [
          {
              "provider": "DU-Client-Eng",
              "name": "MSOE-Update-Demo",
              "version": "3.1"
          }
      ],
      "manifestVersion": "4.0",
      "importedDateTime": "2021-11-17T07:26:14.7376536Z",
      "createdDateTime": "2021-11-17T07:22:09.2232968Z",
      "etag": "\"ad7a553d-24a8-492b-9885-9af424d44d58\""
  }
  

Hinweis

Im Updatemanifest sollte jeder Schritt eine andere installedCriteria-Zeichenfolge haben, wenn mithilfe dieser Zeichenfolge bestimmt wird, ob der Schritt ausgeführt werden soll oder nicht.

Übergeordnete Updates und untergeordnete Updates

Wenn Updatemanifeste aufeinander verweisen, wird das Manifest auf oberster Ebene als übergeordnetes Update und ein in einem Referenzschritt angegebenes Manifest als untergeordnetes Update bezeichnet.

Zurzeit kann ein untergeordnetes Update keine Referenzschritte enthalten. Diese Einschränkung wird zum Zeitpunkt des Imports überprüft, und wenn sie nicht befolgt wird, schlägt der Import fehl.

Inlineschritte in einem übergeordneten Update

In einem übergeordneten Update angegebene Inlineschritte werden auf das Hostgerät angewendet. Hier wird das Objekt „ADUC_WorkflowData“ an einen Schritthandler (auch als „Update-Inhaltshandler“ bezeichnet) übergeben und enthält nicht die Selected Components-Daten. Der Handler für diese Art von Schritt sollte keinComponent-Aware-Handler sein.

Der Schritte-Inhaltshandler wendet IsInstalled-Prüfungslogik für jeden Schritt an. Der Schritthandler des Geräteupdate-Agents überprüft, ob ein bestimmtes Update bereits installiert wurde. Dazu überprüft er, ob bei „IsInstalled()“ der Ergebniscode „900“ (d. h. „true“) ausgegeben wird. Wenn ein Update bereits installiert wurde und die erneute Installation eines Updates, das sich bereits auf dem Gerät befindet, vermieden werden soll, überspringt der Geräteupdate-Agent zukünftige Schritte. Wir verwenden ihn nämlich zur Bestimmung, ob ein Schritt ausgeführt werden soll oder nicht.

Zum Melden eines Updateergebnisses muss das Ergebnis einer Ausführung des Schritthandlers in der Struktur „ADUC_Result“ in eine gewünschte Ergebnisdatei geschrieben werden, wie in der Option „--result-file“ angegeben. Dann wird basierend auf Ergebnissen der Ausführung bei Erfolg 0 und bei allen schwerwiegenden Fehlern -1 oder 0xFF zurückgegeben.

Weitere Informationen finden Sie unter Schritte des Inhaltshandlers und Implementieren eines benutzerdefinierten komponentenbezogenen Inhaltshandlers.

Referenzschritte in einem übergeordneten Update

In einem übergeordneten Update angegebene Referenzschritte werden auf Komponenten auf dem Hostgerät angewendet oder mit ihm verbunden. Ein Referenzschritt ist ein Schritt, der den Updatebezeichner eines anderen Updates enthält, das als „untergeordnetes Update“ bezeichnet wird.

Beim Verarbeiten eines Referenzschritts lädt der Schritthandler eine in den Referenzschrittdaten angegebene Manifestdatei für getrennte Updates herunter und überprüft dann die Dateiintegrität. Als Nächstes analysiert der Schritthandler das untergeordnete Updatemanifest und erstellt ein ADUC_Workflow-Objekt (auch als „untergeordnete Workflowdaten“ bezeichnet), indem er die Daten aus dem untergeordneten Updatemanifest und Informationen zu Datei-URLs aus dem übergeordneten Updatemanifest kombiniert. Außerdem ist bei diesen untergeordneten Workflowdaten die Eigenschaft „level“ (Ebene) auf „1“ festgelegt.

Hinweis

Zurzeit können untergeordnete Updates keine Referenzschritte enthalten.

Getrennte Updatemanifeste

Um Bereitstellungsfehler aufgrund von Größenbeschränkungen bei IoT Hub-Zwillingsdaten zu vermeiden, wird jedes große Updatemanifest in Form einer JSON-Datendatei übermittelt, die auch als getrenntes Updatemanifest bezeichnet wird.

Wenn ein Update mit umfangreichem Inhalt in Device Update for IoT Hub importiert wird, enthält das generierte Updatemanifest eine weitere Nutzdatendatei namens Detached Update Manifest mit den vollständigen Daten des Updatemanifests.

Die Eigenschaft UpdateManifest im Geräte- oder Modulzwilling enthält die Informationen zur Datei mit dem getrennten Updatemanifest.

Beim Verarbeiten des Änderungsereignisses der „PnP“-Eigenschaft lädt der Geräteupdate-Agent die Datei mit dem getrennten Updatemanifest automatisch herunter und erstellt ein „ADUC_WorkflowData“ Objekt, das die vollständigen Daten des Updatemanifests enthält.