Updates importeren in Device Update for IoT Hub

  • Artikel

Als u een update wilt implementeren op apparaten vanuit Device Update for IoT Hub, moet u die update eerst importeren in de Device Update-service. De geïmporteerde update wordt opgeslagen in de Device Update-service en kan van daaruit worden geïmplementeerd op apparaten. Dit artikel bevat een overzicht van enkele belangrijke concepten die u moet begrijpen als het gaat om het importeren van updates.

Manifest importeren

Een importmanifest is een JSON-bestand dat belangrijke informatie definieert over de update die u importeert. U verzendt zowel uw importmanifest als het bijbehorende updatebestand of de bijbehorende updatebestanden (zoals een firmware-updatepakket) als onderdeel van het importproces. De metagegevens die zijn gedefinieerd in het importmanifest, worden gebruikt om de update op te nemen. Sommige metagegevens worden ook gebruikt tijdens de implementatie, bijvoorbeeld om te controleren of een update correct is geïnstalleerd.

Bijvoorbeeld:

{
  "updateId": {
    "provider": "Contoso",
    "name": "Toaster",
    "version": "1.0"
  },
  "isDeployable": false,
  "compatibility": [
    {
      "manufacturer": "Contoso",
      "model": "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": "5.0"
}

Het importmanifest bevat verschillende items die belangrijke apparaatupdates voor IoT Hub concepten vertegenwoordigen. Deze items worden in deze sectie beschreven. Zie JSON-schema importeren voor meer informatie over het volledige importschema.

Identiteit bijwerken

De update-id of updateId is de unieke id voor een update in Device Update for IoT Hub. Het bestaat uit drie delen:

  • Provider: entiteit die de update maakt of rechtstreeks verantwoordelijk is voor de update. Het is vaak een bedrijfsnaam.
  • Naam: id voor een klasse updates. Dit is vaak de naam van een apparaatklasse of model.
  • Versie: een versienummer dat deze update onderscheidt van anderen met dezelfde provider en naam.

Bijvoorbeeld:

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

Notitie

UpdateId wordt alleen gebruikt door de Device Update-service en kan afwijken van de identiteit van de werkelijke softwareonderdelen op het apparaat.

Compatibiliteit

Compatibiliteit definieert de criteria van een apparaat dat de update kan installeren. Het bevat apparaateigenschappen die een set willekeurige sleutelwaardeparen zijn die worden gerapporteerd vanaf een apparaat. Alleen apparaten met overeenkomende eigenschappen komen in aanmerking voor implementatie. Een update kan compatibel zijn met meerdere apparaatklassen door meer dan één set apparaateigenschappen te hebben.

Hier volgt een voorbeeld van een update die alleen kan worden geïmplementeerd op een apparaat dat Contoso en Broodrooster rapporteert als de fabrikant en het model van het apparaat.

{
  "compatibility": [
    {
      "manufacturer": "Contoso",
      "model": "Toaster"
    }
  ]
}

Instructies

Het gedeelte Instructies bevat de benodigde informatie of stappen voor de apparaatagent om de update te installeren. De eenvoudigste update bevat één inlinestap. In deze stap wordt het opgenomen nettoladingbestand uitgevoerd met behulp van een handler die is geregistreerd bij de apparaatagent:

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

Tip

handler is gelijk aan updateType in het importmanifest versie 3.0 of ouder.

Een update kan meer dan één stap bevatten:

{
  "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"
        ]
      }
    ]
  }
}

Een update kan referentiestappen bevatten waarmee de apparaatagent wordt geïnstrueerd om een andere update met een eigen importmanifest te installeren, waardoor een bovenliggende en onderliggende updaterelatie tot stand wordt gebracht. Een update voor een broodrooster kan bijvoorbeeld twee onderliggende updates bevatten:

{
  "instructions": {
    "steps": [
      {
        "type": "reference",
        "updateId": {
          "provider": "Contoso",
          "name": "Toaster.HeatingElement",
          "version": "1.0"
        }
      },
      {
        "type": "reference",
        "updateId": {
          "provider": "Contoso",
          "name": "Toaster.Sensors",
          "version": "1.0"
        }
      }
    ]
  }
}

Notitie

Een update kan een combinatie van inline- en verwijzingsstappen bevatten.

Bestanden

Het onderdeel Bestanden bevat de metagegevens van nettoladingbestanden bijwerken, zoals hun namen, grootten en hash. Device Update voor IoT Hub gebruikt deze metagegevens voor integriteitsvalidatie tijdens het importproces. Dezelfde informatie wordt vervolgens doorgestuurd naar de apparaatagent om de integriteitsvalidatie vóór de installatie te herhalen.

Notitie

Een update die alleen referentiestappen bevat, bevat geen nettoladingbestand voor de update in de bovenliggende update.

Een importmanifest maken

Hoewel het mogelijk is om handmatig een JSON-importmanifest te maken met behulp van een teksteditor, vereenvoudigt de Azure-opdrachtregelinterface (CLI) het proces aanzienlijk. Wanneer u klaar bent om het maken van een importmanifest te proberen, kunt u de handleiding gebruiken.

Belangrijk

Een JSON-bestandsnaam van een importmanifest moet eindigen op .importmanifest.json wanneer deze wordt geïmporteerd via Azure Portal.

Tip

Gebruik Visual Studio Code om automatisch aanvullen en JSON-schemavalidatie in te schakelen bij het maken van een importmanifest.

Limieten voor het importeren van updates

Bepaalde limieten worden afgedwongen voor elke Device Update voor IoT Hub exemplaar. Zie Limieten voor Apparaatupdates als u deze nog niet hebt bekeken.

Volgende stappen