Importera uppdateringar till Enhetsuppdatering för IoT Hub

För att kunna distribuera en uppdatering till enheter från Enhetsuppdatering för IoT Hub måste du först importera uppdateringen till enhetsuppdateringstjänsten. Den här artikeln innehåller en översikt över några viktiga begrepp att förstå när det gäller att importera uppdateringar.

Importmanifest

Ett importmanifest är en JSON-fil som definierar viktig information om uppdateringen 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 definieras i importmanifestet används för att mata in uppdateringen. En del av metadata används också vid distributionstillfället, till exempel för att verifiera om en uppdatering har installerats korrekt.

Till exempel:

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

Importmanifestet innehåller flera objekt som representerar viktig enhetsuppdatering för IoT Hub-begrepp. Dessa objekt beskrivs i det här avsnittet. Information om det fullständiga importschemat finns i Importera JSON-schema för manifest.

Uppdatera identitet

Uppdateringsidentiteten eller updateId är den unika identifieraren för en uppdatering i Enhetsuppdatering för IoT Hub. Den består av tre delar:

• Provider: entitet som skapar eller är direkt ansvarig för uppdateringen. Det är ofta ett företagsnamn.
• Namn: identifierare för en uppdateringsklass. Det är ofta en enhetsklass eller ett modellnamn.
• Version: ett versionsnummer som skiljer den här uppdateringen från andra som har samma provider och namn.

Till exempel:

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

Kompatibilitet

Kompatibilitet definierar kriterierna för en enhet som kan installera uppdateringen. Den innehåller enhetsegenskaper som är en uppsättning godtyckliga nyckelvärdepar som rapporteras från en enhet. Endast enheter med matchande egenskaper är berättigade till distribution. En uppdatering kan vara kompatibel med flera enhetsklasser genom att ha fler än en uppsättning enhetsegenskaper.

Här är ett exempel på en uppdatering som bara kan distribueras till en enhet som rapporterar Contoso och Toaster som enhetstillverkare och modell.

{
  "compatibility": [
    {
      "deviceManufacturer": "Contoso",
      "deviceModel": "Toaster"
    }
  ]
}

Instruktion

Delen Instruktioner innehåller nödvändig information eller nödvändiga steg för att enhetsagenten ska kunna installera uppdateringen. Den enklaste uppdateringen innehåller ett enda infogat steg. Det steget kör den inkluderade nyttolastfilen med hjälp av en hanterare som registrerats med enhetsagenten:

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

En uppdatering kan innehålla mer än ett steg:

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

En uppdatering kan innehålla referenssteg som instruerar enhetsagenten att installera en annan uppdatering med sitt eget importmanifest, och upprättar därmed en huvud- och underliggande uppdateringsrelation. En uppdatering för en brödrost kan till exempel innehålla två deluppdateringar.

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

Delen Filer innehåller metadata för uppdateringsnyttolastfiler som deras namn, storlekar och hash. Enhetsuppdatering för IoT Hub använder dessa metadata för integritetsverifiering under importen. Samma information vidarebefordras sedan till enhetsagenten för att upprepa integritetsverifieringen före installationen.

Skapa ett importmanifest

Du kan använda valfri textredigerare för att skapa en JSON-fil för importmanifestet. Det finns också exempelskript för att skapa importmanifest programmatiskt i Azure/iot-hub-device-update på GitHub.

Begränsningar vid import av uppdateringar

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.

Nästa steg

• Mer information om importprocessen finns i Förbereda en uppdatering för import.
• Granska schemat för importmanifestet.