Concepten voor software-updates (preview)

Gebruik Software updates, een mogelijkheid van Azure Device Registry, om over-the-air-updates op grote schaal aan je apparaten te leveren. Importeer updates in een Azure Device Registry-naamruimte en gebruik vervolgens jobs en groepen in die naamruimte om ze op apparaten uit te brengen.

Toepasselijkheid van service

Software-updates en apparaatupdates voor IoT Hub

Software-updates brengen over-the-air updatemogelijkheden naar het Azure Device Registry. Het gebruikt hetzelfde importmanifestformaat als Device Update for IoT Hub, en laat je updates beheren op naamruimteniveau door gebruik te maken van Azure Device Registry-groepen en -taken.

Gebruik de volgende richtlijnen om de juiste optie te kiezen:

Houd de volgende overwegingen in gedachten als je al Device Update voor IoT Hub gebruikt:

• Je kunt niet beide op dezelfde IoT-hub gebruiken. In deze preview kun je software-updates alleen gebruiken met IoT-hubs waarvoor nog geen bestaand Device Update for IoT Hub-exemplaar bestaat. Om software-updates te proberen, verbind je een IoT hub die Device Update for IoT Hub niet gebruikt met jouw naamruimte.
• Apparaten gebruiken een andere client. Apparaten die de Device Update agent draaien, kunnen geen updates ontvangen via software-updates. Om software-updates te ontvangen, gebruikt een apparaat de client van softwareupdates in de unified Azure IoT SDK's (preview).

Hoe software-updates werken

Je schakelt software-updates in op een Azure Device Registry-naamruimte, hetzij bij het instellen van de naamruimte of later. Om te leren hoe, zie Get started with Azure Device Registry (preview). De functionaliteit introduceert de volgende componenten:

• Software-update: Een update die je importeert in een naamruimte. Een software-update bestaat uit één of meer updatebestanden en een importmanifest. Nadat je een software-update hebt geïmporteerd, is deze beschikbaar voor software-update-taken en onboarding-update-taken in die naamruimte.
• Software-updateopdracht: Past een software-update toe op de compatibele apparaten in een doelgroep met apparaten.
• Onboarding update-taak: Past een software-update toe op compatibele apparaten wanneer ze tijdens de onboarding controleren op updates, voordat ze zich registreren en beginnen te werken.
• Software updates client: Het deel van de unified Azure IoT SDK's (preview) dat je apparaatapplicatie gebruikt om software-updates te controleren, te downloaden en te installeren, en om de resultaten te rapporteren.

Een typische updateflow ziet er als volgt uit:

1. Je uploadt de updatebestanden en het importmanifest naar een Azure Storage-container.
2. Je importeert de software-update in je naamruimte.
3. Je maakt een taak aan die gericht is op een groep of, voor onboarding, op de namespace.
4. Elk apparaat controleert op updates en rapporteert zijn compatibiliteitseigenschappen. Als het apparaat compatibel is, ontvangt het de update.
5. Het apparaat downloadt en installeert de update, en rapporteert vervolgens het resultaat. Je houdt de voortgang en de resultaten op apparaatniveau in de jobuitvoering in de gaten.

Softwareupdates

Een software-update bestaat uit twee componenten die je samen uploadt:

• Bestanden bijwerken: De payload die het apparaat installeert. De payload kan een firmware-image, een softwarepakket, een script of meerdere gerelateerde bestanden zijn.
• Importmanifest: Een JSON-bestand met de .importmanifest.json extensie die de update beschrijft. Het importmanifest vermeldt:
  • Update-identiteit: De provider, naam en versie die de update uniek identificeren. De provider en naam samen identificeren een updatefamilie, zoals alle versies van de firmware voor één apparaatmodel.
  • Compatibiliteitseigenschappen: De apparaateigenschappen die bepalen welke apparaten de update kunnen installeren. Voor meer informatie, zie Apparaatcompatibiliteit.
  • Installatie-instructies: De installatiestappen, hun volgorde en de handler voor elke stap. De handler vertelt het apparaat hoe die stap moet worden toegepast, bijvoorbeeld door een pakket te installeren, een script uit te voeren of een image te schrijven.
  • Bestandsmetadata: De naam, grootte en hash van elk updatebestand. De dienst gebruikt de hashes om de bestandsintegriteit bij import te verifiëren, en het apparaat kan ze gebruiken om elk bestand te verifiëren vóór installatie.

Elke software-update vereist een importmanifest. Als je probeert updatebestanden te importeren zonder een importmanifest, mislukt de import. Wanneer je importeert, kun je optioneel de updatebestanden scannen op malware. Malware-scannen is beschikbaar in geselecteerde regio's. Voor stapsgewijze instructies, zie Importeren van een software-update.

Het volgende voorbeeld toont een importmanifest voor een image-gebaseerde update:

{
  "updateId": {
    "provider": "Contoso",
    "name": "IrrigationControllerV2-Image",
    "version": "1.3.0"
  },
  "isDeployable": true,
  "compatibility": [
    {
      "manufacturer": "Contoso",
      "model": "IrrigationControllerV2"
    }
  ],
  "instructions": {
    "steps": [
      {
        "type": "inline",
        "description": "Update the device image to version 1.3.0",
        "handler": "microsoft/swupdate:1",
        "files": [
          "contoso-irrigation-controller-v2-1.3.0.swu"
        ],
        "handlerProperties": {
          "installedCriteria": "1.3.0"
        }
      }
    ]
  },
  "files": [
    {
      "filename": "contoso-irrigation-controller-v2-1.3.0.swu",
      "sizeInBytes": 112738816,
      "hashes": {
        "sha256": "wPdNKUSmWTZkR6Pum9oR/EIzdn5AvON4dsXME+/gHVw="
      }
    }
  ],
  "createdDateTime": "2026-10-01T06:56:51.2002204Z",
  "manifestVersion": "5.0"
}

Software-updates gebruiken hetzelfde importmanifestformaat als Device Update voor IoT Hub. Om te leren hoe je een importmanifest opstelt, zie:

• Schema voor importmanifest
• Geordende uitvoering in meerdere stappen

Apparaatcompatibiliteit

De compatibiliteitseigenschappen in een importmanifest bepalen welke apparaten een software-update kunnen installeren. Wanneer een apparaat controleert op updates, rapporteert het zijn eigen compatibiliteitseigenschappen. Azure Device Registry vergelijkt deze eigenschappen met de compatibiliteitseigenschappen die in de software-update zijn opgegeven.

Je definieert compatibiliteitseigenschappen als naam-waardeparen. Elke software-update moet ten minste één compatibiliteitseigenschap declareren. manufacturer En model zijn veelvoorkomende keuzes, maar ze zijn niet verplicht. Gebruik alle eigenschappen die bij je vloot passen, zoals region of environment.

De compatibility sectie van het importmanifest is een array van eigenschapssets. Voorbeeld:

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

Matching werkt als volgt:

• Een apparaat moet aan elke eigenschap in een set voldoen. De voorgaande update geldt alleen voor apparaten die zowel manufacturer als model en Contoso als IrrigationControllerV2 rapporteren. Het geldt niet voor een Contoso-apparaat SoilSensorV1, of voor een IrrigationControllerV2 apparaat dat een andere fabrikant opgeeft.
• Een apparaat hoeft maar met één set overeen te komen. Als je meer dan één property set declareert, kan een enkele software-update op meerdere apparaattypes worden toegepast.
• Elke property set behoort tot één updatefamilie. Je kunt niet exact dezelfde set compatibiliteitskenmerken gebruiken met meer dan één provider- en naamcombinatie. Plan uw updatefamilies en compatibiliteitseigenschappen samen. Voor meer informatie, zie Concepten importeren.

Een groep kan apparaten bevatten met verschillende compatibiliteitseigenschappen. Een software-updatetaak past de update alleen toe op de compatibele apparaten in de aparatengroep. Als een groep bijvoorbeeld 18 IrrigationControllerV2 apparaten en zes SoilSensorV1 apparaten bevat, wordt een update voor IrrigationControllerV2 apparaten toegepast op de 18 compatibele apparaten. De zes SoilSensorV1 apparaten zijn niet beïnvloed.

Taken, groepen en uitrolgedrag

Je deployt een software-update door een job in de namespace aan te maken. Software-updates ondersteunen twee soorten taaktypen:

Een software-updateklus stopt niet nadat deze de apparaten heeft bereikt die compatibel zijn wanneer deze wordt gestart. Terwijl de taakuitvoering actief is, blijft de update toepassen op:

• Apparaten die offline waren toen de taak begon, nadat ze opnieuw verbinding hebben gemaakt en op updates hebben gecontroleerd.
• Apparaten die tot de doelgroep behoren. Het groepslidmaatschap wordt niet automatisch bijgewerkt: nieuwe apparaten worden de volgende keer dat je het lidmaatschap vernieuwt aan de groep toegevoegd. Zie In de cache opgeslagen lidmaatschap en vernieuwing voor meer informatie.
• Apparaten die in aanmerking komen voor de update, bijvoorbeeld, omdat hun gerapporteerde compatibiliteitseigenschappen veranderen.

Een onboarding-updatetaak blijft actief totdat je deze beëindigt, dus compatibele apparaten blijven de update ontvangen terwijl ze worden onboarded.

Voor jobstatussen, planning en monitoring, zie Concepten van jobs (preview).

Overwegingen bij de Device SDK

Apparaten ontvangen software-updates via de software updates-client in de unified Azure IoT SDK's (preview). Houd de volgende overwegingen in gedachten bij het plannen van de software van je apparaat:

• Ondersteunde apparaten: In deze preview is de software updates-client voornamelijk bedoeld voor Linux-gebaseerde apparaten met meer dan 32 MB beschikbaar geheugen.
• Integratie: De SDK is een bibliotheek, geen kant-en-klare agent. Je integreert de software-updateclient in je apparaatapplicatie en levert de logica die downloadt, installeert en updates toepast op je hardware. Microsoft biedt voorbeelden aan om je op weg te helpen.
• Twee manieren om updates te controleren: Een apparaat dat wordt toegevoegd controleert onboarding-updates voordat het geregistreerd wordt. Een geregistreerd apparaat controleert via een software-updatetaak op software-updates. De app op je apparaat bepaalt wanneer je op updates moet controleren.
• Connectiviteit: Het apparaat controleert op updates en rapporteert resultaten via zijn Device Provisioning Service-verbinding. Het heeft geen apart eindpunt of credential nodig om updates te ontvangen.
• Beveiliging: Voordat het updatebestanden downloadt, verifieert de softwareupdate-client de handtekening van de update-informatie die het van de dienst ontvangt. Apparaten downloaden updatebestanden alleen via HTTPS, dus update-inhoud wordt altijd versleuteld tijdens het verzenden. Zorg ervoor dat je apparaten uitgaande HTTPS-verbindingen kunnen maken om updatebestanden te downloaden.
• Statusrapportage: Na een installatiepoging rapporteert het apparaat het resultaat, inclusief foutcodes als de installatie mislukte. Het resultaat verschijnt in de resultaten op apparaatniveau van de taakuitvoering.
• Jouw verantwoordelijkheid: Je bent verantwoordelijk voor het valideren van de integratie in je eigen omgeving, inclusief herstelgedrag als een installatie mislukt of het apparaat opnieuw opstart tijdens een update.

Preview-beperkingen

De huidige preview heeft de volgende beperkingen:

• Software-updates ondersteunen apparaten die met IoT Hub zijn verbonden. Azure IoT-bewerkingen-apparaten en -assets worden in deze preview niet ondersteund.
• Je kunt geen software-updates gebruiken met een IoT hub die een bestaande Device Update voor IoT Hub-instantie heeft.
• Elke software-update vereist een importmanifest. Je kunt geen importmanifest maken in het Azure-portaal.
• De software-update-client ondersteunt momenteel geen proxy-updates of updates die referentiestappen gebruiken (ouder- en kindupdates).

Voor limieten die gelden voor geïmporteerde updates, zoals de maximale updategrootte, zie Device Update for IoT Hub limits. Voor limieten die van toepassing zijn op groepen en jobs, zie Groepconcepten (preview) en Jobsconcepten (preview).

Verwante onderwerpen

• Importeer een software-update
• Rol een software-update uit naar een groep
• Rol een onboarding-update uit in een namespace
• Concepten groeperen (preview-versie)
• Jobsconcepten (previewversie)
• Unified Azure IoT SDKs (preview)