Importera uppdateringar till enhetsuppdatering för IoT Hub

  • Artikel

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 importerade uppdateringen lagras i enhetsuppdateringstjänsten och kan distribueras därifrån 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 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 distributionen, till exempel för att verifiera om en uppdatering har installerats korrekt.

Exempel:

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

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 manifestets JSON-schema.

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.

Exempel:

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

Anteckning

UpdateId används endast av enhetsuppdateringstjänsten och kan skilja sig från identiteterna för faktiska programvarukomponenter på enheten.

Kompatibilitet

Kompatibilitet definierar kriterierna för en enhet som kan installera uppdateringen. Den innehåller enhetsegenskaper som är en uppsättning godtyckliga nyckel/värde-par 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": [
    {
      "manufacturer": "Contoso",
      "model": "Toaster"
    }
  ]
}

Instruktioner

Delen Instruktioner innehåller nödvändig information eller de steg som krävs 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 är registrerad med enhetsagenten:

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

Tips

handler motsvarar updateType i importmanifestversion 3.0 eller äldre.

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 ett eget importmanifest helt och hållet och upprättar en överordnad och underordnad uppdateringsrelation. En uppdatering för ett popup-program 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"
        }
      }
    ]
  }
}

Anteckning

En uppdatering kan innehålla valfri kombination av infogade steg och referenssteg.

Filer

Delen Filer innehåller metadata för uppdateringsnyttolastfiler som 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.

Anteckning

En uppdatering som endast innehåller referenssteg har ingen uppdateringsnyttolastfil i den överordnade uppdateringen.

Skapa ett importmanifest

Även om det är möjligt att skapa ett importmanifest-JSON manuellt med hjälp av en textredigerare, förenklar Azure-kommandoradsgränssnittet (CLI) processen avsevärt. När du är redo att prova att skapa ett importmanifest kan du använda instruktionsguiden.

Viktigt

Ett JSON-filnamn för importmanifestet måste sluta med .importmanifest.json när det importeras via Azure Portal.

Tips

Använd Visual Studio Code för att aktivera automatisk komplettering och JSON-schemavalidering när du skapar ett importmanifest.

Begränsningar för import av uppdateringar

Vissa begränsningar tillämpas för varje enhetsuppdatering för IoT Hub instans. Om du inte redan har granskat dem kan du läsa Avsnittet om begränsningar för enhetsuppdatering.

Nästa steg