Importbegrepp för Azure Device Update för IoT Hub
Om du vill distribuera en uppdatering till enheter med Azure Device Update för IoT Hub importerar du först uppdateringen till enhetsuppdateringstjänsten, som lagrar den importerade uppdateringen och distribuerar den till enheter. Den här artikeln innehåller en översikt över några viktiga begrepp att förstå när det gäller att importera uppdateringar.
Importera manifest
Ett importmanifest är en JSON-fil som definierar viktig information om den uppdatering som du importerar. Du skickar både importmanifestet och tillhörande uppdateringsfil eller filer, till exempel ett uppdateringspaket för inbyggd programvara, som en del av importprocessen. Metadata som definierats i importmanifestet används för att mata in uppdateringen. En del av metadata används också vid distributionen, till exempel för att verifiera om en uppdatering är korrekt installerad.
Följande JSON-kod visar ett exempel på en importmanifestfil:
{
"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"
}
Avsnitten i importmanifestfilen representerar viktiga enhetsuppdateringsbegrepp enligt beskrivningen i följande avsnitt. Information om det fullständiga importmanifestschemat finns i Importera JSON-schema för manifest.
Uppdatera identitet
Uppdateringsidentiteten eller updateId är den unika identifieraren för en uppdatering i Enhetsuppdatering och innehåller följande egenskaper:
- Providern är den entitet som skapar eller ansvarar för uppdateringen. Providern är ofta ett företagsnamn.
- Namn är identifieraren för en uppdateringsklass. Namnet är ofta en enhetsklass eller ett modellnamn.
- Version är ett tal som skiljer uppdateringen från andra med samma provider och namn.
Till exempel:
{
"updateId": {
"provider": "Contoso",
"name": "Toaster",
"version": "1.0"
}
}
Kommentar
updateId Används endast av enhetsuppdateringstjänsten och skiljer sig från programvarukomponentidentiteterna på enheterna.
Kompatibilitet
Avsnittet Kompatibilitet använder ett eller flera godtyckliga nyckel/värde-par för att definiera de enheter som kan installera en uppdatering. Endast enheter som rapporterar egenskaper som matchar kompatibilitetsvärdena är berättigade att distribuera uppdateringen. Du kan göra en uppdatering kompatibel med flera enhetsklasser genom att inkludera fler än en uppsättning egenskaper för enhetskompatibilitet.
I följande exempel visas en uppdatering som bara kan distribueras till enheter som rapporterar Contoso och Toaster som enhetstillverkare och modell.
{
"compatibility": [
{
"manufacturer": "Contoso",
"model": "Toaster"
}
]
}
Instruktioner
Avsnittet Instruktioner innehåller den information eller de steg som krävs för att enhetsagenten ska kunna installera uppdateringen. Den enklaste uppdateringen innehåller ett enda infogat steg som kör uppdateringsnyttolastfilen med hjälp av en hanterare som är registrerad hos enhetsagenten. I följande exempel visas ett avsnitt med instruktioner i ett enda steg.
{
"instructions": {
"steps": [
{
"handler": "microsoft/swupdate:2",
"files": [
"contoso.toaster.1.0.swu"
]
}
]
}
}
Kommentar
Egenskapen handler motsvarar updateType egenskapen i importmanifestet version 3.0 eller äldre.
En uppdatering kan innehålla mer än ett steg, som i följande exempel:
{
"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"
]
}
]
}
}
En uppdatering kan innehålla referenssteg som instruerar enhetsagenten att installera en annan uppdatering med sitt eget importmanifest och upprätta en överordnad och underordnad uppdateringsrelation. En uppdatering kan innehålla valfri kombination av infogade steg och referenssteg.
En uppdatering för en brödrost kan till exempel innehålla två underordnade uppdateringar:
{
"instructions": {
"steps": [
{
"type": "reference",
"updateId": {
"provider": "Contoso",
"name": "Toaster.HeatingElement",
"version": "1.0"
}
},
{
"type": "reference",
"updateId": {
"provider": "Contoso",
"name": "Toaster.Sensors",
"version": "1.0"
}
}
]
}
}
Filer
Avsnittet Filer i importmanifestet innehåller uppdateringsnyttolastfilmetadata som name, sizeoch hash. Enhetsuppdatering använder dessa metadata för integritetsverifiering under importprocessen och vidarebefordrar samma information till enhetsagenten för integritetsverifiering före installationen.
Kommentar
En överordnad uppdatering som endast innehåller referenssteg definierar inte några uppdateringsnyttolastfiler.
Skapa ett importmanifest
Det är möjligt att skapa ett JSON-importmanifest manuellt med hjälp av en textredigerare, men Azure CLI förenklar processen avsevärt. När du är redo att prova att skapa ett importmanifest kan du använda instruktionsguiden.
Viktigt!
Om du vill importera till enhetsuppdateringstjänsten via Azure Portal måste ett JSON-filnamn för importmanifest sluta med .importmanifest.json.
Dricks
Du kan använda Visual Studio Code för att aktivera automatisk komplettering och JSON-schemavalidering när du skapar ett importmanifest.
Uppdatera importgränser
Vissa gränser tillämpas för varje enhetsuppdatering för IoT Hub-instansen. Om du inte redan har granskat dem kan du läsa Begränsningar för enhetsuppdatering.