Azure Device Update voor IoT Hub-importconcepten
Als u een update wilt implementeren op apparaten met behulp van Azure Device Update voor IoT Hub, importeert u eerst de update in de Device Update-service, waarin de geïmporteerde update wordt opgeslagen en geïmplementeerd op apparaten. Dit artikel bevat een overzicht van enkele belangrijke concepten die u moet begrijpen wanneer 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 -bestanden, zoals een firmware-updatepakket, als onderdeel van het importproces. De metagegevens die in het importmanifest zijn gedefinieerd, worden gebruikt om de update op te nemen. Sommige metagegevens worden ook gebruikt tijdens de implementatie, bijvoorbeeld om te controleren of een update juist is geïnstalleerd.
De volgende JSON-code toont een voorbeeld van een manifestbestand voor importeren:
{
"updateId": {
"provider": "Contoso",
"name": "Toaster",
"version": "1.0"
},
"isDeployable": false,
"compatibility": [
{
"manufacturer": "Contoso",
"model": "Toaster"
}
],
"instructions": {
"steps": [
{
"handler": "microsoft/swupdate:2",
"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"
}
De secties van het importmanifestbestand vertegenwoordigen belangrijke concepten van Device Update, zoals beschreven in de volgende secties. Zie Het JSON-schema voor het importeren van manifesten voor meer informatie over het volledige importmanifestschema.
Identiteit bijwerken
De update-id of updateId is de unieke id voor een update in Device Update en bevat de volgende eigenschappen:
- Provider is de entiteit die de update maakt of verantwoordelijk is. Provider is vaak een bedrijfsnaam.
- De naam is de id voor een updateklasse. De naam is vaak een apparaatklasse of modelnaam.
- Versie is een getal dat deze update onderscheidt van anderen met dezelfde provider en naam.
Bijvoorbeeld:
{
"updateId": {
"provider": "Contoso",
"name": "Toaster",
"version": "1.0"
}
}
Notitie
De updateId wordt alleen gebruikt door de Device Update-service en verschilt van de identiteiten van softwareonderdelen op de apparaten.
Compatibiliteit
In de sectie Compatibiliteit worden een of meer willekeurige sleutel-waardeparen gebruikt om de apparaten te definiëren die een update kunnen installeren. Alleen apparaten die eigenschappen rapporteren die overeenkomen met de compatibiliteitswaarden, komen in aanmerking voor het implementeren van de update. U kunt een update compatibel maken met meerdere apparaatklassen door meer dan één set apparaatcompatibiliteitseigenschappen op te halen.
In het volgende voorbeeld ziet u een update die alleen kan worden geïmplementeerd op apparaten die Contoso en Broodrooster rapporteren als fabrikant en model van het apparaat.
{
"compatibility": [
{
"manufacturer": "Contoso",
"model": "Toaster"
}
]
}
Instructies
De sectie Instructies bevat de benodigde informatie of stappen voor de apparaatagent om de update te installeren. De eenvoudigste update bevat één inlinestap waarmee het payloadbestand van de update wordt uitgevoerd met behulp van een handler die is geregistreerd bij de apparaatagent. In het volgende voorbeeld ziet u een sectie met instructies voor één stap.
{
"instructions": {
"steps": [
{
"handler": "microsoft/swupdate:2",
"files": [
"contoso.toaster.1.0.swu"
]
}
]
}
}
Notitie
De handler eigenschap is gelijk aan de updateType eigenschap in importmanifestversie 3.0 of ouder.
Een update kan meer dan één stap bevatten, zoals in het volgende voorbeeld:
{
"instructions": {
"steps": [
{
"description": "pre-install script",
"handler": "microsoft/script:1",
"handlerProperties": {
"arguments": "--pre-install"
},
"files": [
"configure.sh"
]
},
{
"description": "firmware package",
"handler": "microsoft/swupdate:2",
"files": [
"contoso.toaster.1.0.swu"
]
}
]
}
}
Een update kan referentiestappen bevatten die de apparaatagent instrueren om een andere update te installeren met een eigen importmanifest, waardoor een bovenliggende en onderliggende updaterelatie tot stand wordt gebracht. Een update kan elke combinatie van inline- en referentiestappen bevatten.
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"
}
}
]
}
}
Bestanden
De sectie Bestanden van het importmanifest bevat metagegevens van payloadbestanden zoals name, sizeen hash. Device Update gebruikt deze metagegevens voor integriteitsvalidatie tijdens het importproces en stuurt dezelfde informatie door naar de apparaatagent voor integriteitsvalidatie vóór de installatie.
Notitie
Een bovenliggende update die alleen referentiestappen bevat, definieert geen nettoladingbestanden voor updates.
Een importmanifest maken
Hoewel het mogelijk is om handmatig een JSON-importmanifest te maken met behulp van een teksteditor, vereenvoudigt de Azure CLI het proces aanzienlijk. Wanneer u klaar bent om het maken van een importmanifest uit te proberen, kunt u de handleiding gebruiken.
Belangrijk
Als u wilt importeren in de Device Update-service via Azure Portal, moet de JSON-bestandsnaam van een importmanifest eindigen met .importmanifest.json.
Tip
U kunt Visual Studio Code gebruiken om automatisch aanvullen en JSON-schemavalidatie in te schakelen wanneer u een importmanifest maakt.
Importlimieten bijwerken
Bepaalde limieten worden afgedwongen voor elke Device Update voor IoT Hub-exemplaar. Als u deze nog niet hebt bekeken, raadpleegt u Limieten voor apparaatupdates.