Informatie over het identiteitsregister in uw IoT-hub

  • Artikel

Elke IoT-hub heeft een identiteitsregister waarin informatie wordt opgeslagen over de apparaten en modules die verbinding mogen maken met de IoT-hub. Voordat een apparaat of module verbinding kan maken met een IoT-hub, moet er een vermelding zijn voor dat apparaat of die module in het identiteitsregister van de IoT-hub. Een apparaat of module moet ook worden geverifieerd met de IoT-hub op basis van referenties die zijn opgeslagen in het identiteitsregister.

De apparaat- of module-id die is opgeslagen in het identiteitsregister, is hoofdlettergevoelig.

Op hoog niveau is het identiteitsregister een rest-compatibele verzameling apparaat- of module-id-resources. Wanneer u een vermelding toevoegt in het identiteitsregister, maakt IoT Hub een set resources per apparaat, zoals de wachtrij die cloud-naar-apparaat-berichten bevat.

Gebruik het identiteitsregister wanneer u het volgende moet doen:

  • Richt apparaten of modules in die verbinding maken met uw IoT-hub.
  • Beheer de toegang per apparaat/per module tot het apparaat of de modulegerichte eindpunten van uw hub.

Registerbewerkingen voor identiteit

In het IoT Hub identiteitsregister worden de volgende bewerkingen weergegeven:

  • Apparaat- of module-id maken
  • Apparaat- of module-id bijwerken
  • Apparaat- of module-id ophalen op id
  • Apparaat- of module-id verwijderen
  • Maximaal 1000 identiteiten weergeven
  • Apparaat-id's exporteren naar Azure Blob Storage
  • Apparaat-id's importeren uit Azure Blob Storage

Al deze bewerkingen kunnen optimistische gelijktijdigheid gebruiken, zoals opgegeven in RFC7232.

Belangrijk

De enige manier om alle identiteiten in het identiteitsregister van een IoT-hub op te halen, is door de functionaliteit Exporteren te gebruiken.

Een IoT Hub-identiteitsregister:

  • Bevat geen toepassingsmetagegevens.

Belangrijk

Gebruik het identiteitsregister alleen voor apparaatbeheer- en inrichtingsbewerkingen. Bewerkingen met een hoge doorvoer tijdens runtime mogen niet afhankelijk zijn van het uitvoeren van bewerkingen in het identiteitsregister. Het controleren van de verbindingsstatus van een apparaat voordat een opdracht wordt verzonden, wordt bijvoorbeeld niet ondersteund. Controleer de bandbreedte voor het identiteitsregister.

Notitie

Het kan enkele seconden duren voordat een apparaat- of module-id na het maken beschikbaar is voor ophalen. Probeer get de apparaat- of module-id's opnieuw te gebruiken in geval van fouten.

Apparaten uitschakelen

U kunt apparaten uitschakelen door de statuseigenschap van een identiteit in het identiteitsregister bij te werken. Normaal gesproken gebruikt u deze eigenschap in twee scenario's:

  • Tijdens een inrichtingsindelingsproces. Zie Apparaatinrichting voor meer informatie.

  • Als u denkt dat een apparaat is gecompromitteerd of om welke reden dan ook onbevoegd is geworden.

    Belangrijk

    IoT Hub controleert geen certificaatintrekkingslijsten bij het verifiëren van apparaten met verificatie op basis van certificaten. Als u een apparaat hebt dat moet worden geblokkeerd om verbinding te maken met IoT Hub vanwege een mogelijk gecompromitteerd certificaat, moet u het apparaat uitschakelen in het identiteitsregister.

Deze functie is niet beschikbaar voor modules.

Zie Een apparaat in een IoT-hub uitschakelen of verwijderen voor meer informatie.

Apparaat-id's importeren en exporteren

Gebruik asynchrone bewerkingen op het eindpunt van de IoT Hub resourceprovider om apparaat-id's bulksgewijs te exporteren vanuit het identiteitsregister van een IoT-hub. Exports zijn langlopende taken die gebruikmaken van een door de klant geleverde blobcontainer om apparaatidentiteitsgegevens op te slaan die worden gelezen uit het identiteitsregister.

Gebruik asynchrone bewerkingen op het eindpunt van de IoT Hub resourceprovider om apparaat-id's bulksgewijs te importeren in het identiteitsregister van een IoT-hub. Importbewerkingen zijn langlopende taken die gegevens in een door de klant geleverde blobcontainer gebruiken om apparaatidentiteitsgegevens naar het identiteitsregister te schrijven.

Zie REST API's voor IoT Hub resourceprovider voor meer informatie over de API's voor importeren en exporteren. Zie Bulksgewijs beheer van IoT Hub apparaatidentiteiten voor meer informatie over het uitvoeren van import- en exporttaken.

Apparaatidentiteiten kunnen ook worden geëxporteerd en geïmporteerd vanuit een IoT-hub met behulp van de service-API via de REST API of een van de IoT Hub Service SDK's.

Apparaatinrichting

De apparaatgegevens die een bepaalde IoT-oplossing opslaat, zijn afhankelijk van de specifieke vereisten van die oplossing. Maar een oplossing moet minimaal apparaat-id's en verificatiesleutels opslaan. Azure IoT Hub bevat een identiteitsregister waarin waarden voor elk apparaat kunnen worden opgeslagen, zoals id's, verificatiesleutels en statuscodes. Een oplossing kan andere Azure-services, zoals Table Storage, Blob Storage of Azure Cosmos DB, gebruiken om andere apparaatgegevens op te slaan.

Apparaatinrichting is het proces van het toevoegen van de initiële apparaatgegevens aan de winkels in uw oplossing. Als u wilt dat een nieuw apparaat verbinding kan maken met uw hub, moet u een apparaat-id en sleutels toevoegen aan het IoT Hub-identiteitsregister. Als onderdeel van het inrichtingsproces moet u mogelijk apparaatspecifieke gegevens in andere oplossingsarchieven initialiseren. U kunt ook de Azure IoT Hub Device Provisioning Service gebruiken om zero-touch, Just-In-Time-inrichting in te schakelen voor een of meer IoT-hubs zonder menselijke tussenkomst. Zie de documentatie van de inrichtingsservice voor meer informatie.

Meldingen over de levenscyclus van apparaten en modules

IoT Hub kunt uw IoT-oplossing op de hoogte stellen wanneer een apparaat-id wordt gemaakt of verwijderd door levenscyclusmeldingen te verzenden. Hiervoor moet uw IoT-oplossing een route maken en de gegevensbron instellen op DeviceLifecycleEvents. Standaard worden er geen meldingen over de levenscyclus verzonden, dat wil gezegd dat dergelijke routes niet al bestaan. Door een route te maken met gegevensbron die gelijk is aan DeviceLifecycleEvents, worden levenscyclus-gebeurtenissen verzonden voor zowel apparaat-id's als module-id's; De inhoud van het bericht verschilt echter, afhankelijk van het feit of de gebeurtenissen worden gegenereerd voor module-id's of apparaatidentiteiten. Merk op dat voor IoT Edge modules de stroom voor het maken van module-identiteiten anders is dan voor andere modules, waardoor voor IoT Edge modules de melding voor maken alleen wordt verzonden als de bijbehorende IoT Edge Apparaat voor de bijgewerkte IoT Edge module-id wordt uitgevoerd. Voor alle andere modules worden levenscyclusmeldingen verzonden wanneer de module-id aan de IoT Hub-zijde wordt bijgewerkt. Zie Niet-telemetriegebeurtenisschema's voor meer informatie over de eigenschappen en de hoofdtekst die in het meldingsbericht worden geretourneerd.

Eigenschappen van apparaat-id

Apparaat-id's worden weergegeven als JSON-documenten met de volgende eigenschappen:

Eigenschap Opties Description
deviceId vereist, alleen-lezen voor updates Een hoofdlettergevoelige tekenreeks (maximaal 128 tekens) met ASCII 7-bits alfanumerieke tekens plus bepaalde speciale tekens: - . % _ * ? ! ( ) , : = @ $ '. De speciale tekens: + # worden niet ondersteund.
generationId vereist, alleen-lezen Een door IoT Hub gegenereerde, hoofdlettergevoelige tekenreeks van maximaal 128 tekens. Deze waarde wordt gebruikt om apparaten met dezelfde deviceId te onderscheiden wanneer ze zijn verwijderd en opnieuw zijn gemaakt.
etag vereist, alleen-lezen Een tekenreeks die een zwakke ETag voor de apparaat-id vertegenwoordigt, volgens RFC7232.
verificatie optioneel Een samengesteld object met verificatiegegevens en beveiligingsmaterialen. Zie Verificatiemechanisme in de REST API-documentatie voor meer informatie.
mogelijkheden optioneel De set mogelijkheden van het apparaat. Bijvoorbeeld of het apparaat een edge-apparaat is of niet. Zie Apparaatmogelijkheden in de REST API-documentatie voor meer informatie.
deviceScope optioneel Het bereik van het apparaat. In edge-apparaten, automatisch gegenereerd en onveranderbaar. Afgeschaft op niet-edge-apparaten. In onderliggende (leaf)-apparaten stelt u deze eigenschap echter in op dezelfde waarde als de eigenschap parentScopes (de deviceScope van het bovenliggende apparaat) voor compatibiliteit met eerdere versies van de API. Zie IoT Edge als gateway: Bovenliggende en onderliggende relaties voor meer informatie.
parentScopes optioneel Het bereik van het directe bovenliggende apparaat van een onderliggend apparaat (de waarde van de eigenschap deviceScope van het bovenliggende apparaat). In Edge-apparaten is de waarde leeg als het apparaat geen bovenliggend item heeft. Op niet-edge-apparaten is de eigenschap niet aanwezig als het apparaat geen bovenliggend item heeft. Zie IoT Edge als gateway: Bovenliggende en onderliggende relaties voor meer informatie.
status vereist Een toegangsindicator. Kan worden ingeschakeld of uitgeschakeld. Als ingeschakeld, mag het apparaat verbinding maken. Als dit apparaat is uitgeschakeld, heeft dit apparaat geen toegang tot een apparaatgericht eindpunt.
statusReason optioneel Een tekenreeks van 128 tekens lang waarin de reden voor de status van de apparaatidentiteit wordt opgeslagen. Alle UTF-8-tekens zijn toegestaan.
statusUpdateTime alleen-lezen Een tijdelijke indicator met de datum en tijd van de laatste statusupdate.
connectionState alleen-lezen Een veld dat de verbindingsstatus aangeeft: Verbonden of Verbroken. Dit veld vertegenwoordigt de IoT Hub weergave van de verbindingsstatus van het apparaat. Belangrijk: dit veld mag alleen worden gebruikt voor ontwikkelings-/foutopsporingsdoeleinden. De verbindingsstatus wordt alleen bijgewerkt voor apparaten die MQTT of AMQP gebruiken. Het is ook gebaseerd op pings op protocolniveau (MQTT-pings of AMQP-pings) en kan een maximale vertraging van slechts 5 minuten hebben. Om deze redenen kunnen er fout-positieven zijn, zoals niet-verbonden apparaten die zijn gerapporteerd als verbonden.
connectionStateUpdatedTime alleen-lezen Een tijdelijke indicator met de datum en de laatste keer dat de verbindingsstatus is bijgewerkt.
lastActivityTime alleen-lezen Een tijdelijke indicator die de datum en de laatste keer weergeeft waarop het apparaat is verbonden, een bericht heeft ontvangen of verzonden. Deze eigenschap is uiteindelijk consistent, maar kan worden uitgesteld tot 5 tot 10 minuten. Daarom mag het niet worden gebruikt in productiescenario's.

Notitie

De verbindingsstatus kan alleen de IoT Hub weergave van de status van de verbinding vertegenwoordigen. Updates van deze status kan worden vertraagd, afhankelijk van de netwerkomstandigheden en configuraties.

Notitie

Momenteel bieden de apparaat-SDK's geen ondersteuning voor het gebruik van de + tekens en # in de deviceId.

Eigenschappen van module-identiteit

Module-identiteiten worden weergegeven als JSON-documenten met de volgende eigenschappen:

Eigenschap Opties Description
deviceId vereist, alleen-lezen voor updates Een hoofdlettergevoelige tekenreeks (maximaal 128 tekens) met ASCII 7-bits alfanumerieke tekens plus bepaalde speciale tekens: - . + % _ # * ? ! ( ) , : = @ $ '.
moduleId vereist, alleen-lezen voor updates Een hoofdlettergevoelige tekenreeks (maximaal 128 tekens) met ASCII 7-bits alfanumerieke tekens plus bepaalde speciale tekens: - . + % _ # * ? ! ( ) , : = @ $ '.
generationId vereist, alleen-lezen Een door IoT Hub gegenereerde, hoofdlettergevoelige tekenreeks van maximaal 128 tekens. Deze waarde wordt gebruikt om apparaten met dezelfde deviceId te onderscheiden wanneer ze zijn verwijderd en opnieuw zijn gemaakt.
etag vereist, alleen-lezen Een tekenreeks die een zwakke ETag voor de apparaat-id vertegenwoordigt, volgens RFC7232.
verificatie optioneel Een samengesteld object met verificatiegegevens en beveiligingsmaterialen. Zie Verificatiemechanisme in de REST API-documentatie voor meer informatie.
beheerdDoor optioneel Identificeert wie deze module beheert. Deze waarde is bijvoorbeeld 'IoT Edge' als de edge-runtime eigenaar is van deze module.
cloudToDeviceMessageCount alleen-lezen Het aantal cloud-naar-module-berichten dat momenteel in de wachtrij staat om naar de module te worden verzonden.
connectionState alleen-lezen Een veld dat de verbindingsstatus aangeeft: Verbonden of Verbroken. Dit veld vertegenwoordigt de IoT Hub weergave van de verbindingsstatus van het apparaat. Belangrijk: dit veld mag alleen worden gebruikt voor ontwikkelings-/foutopsporingsdoeleinden. De verbindingsstatus wordt alleen bijgewerkt voor apparaten die MQTT of AMQP gebruiken. Het is ook gebaseerd op pings op protocolniveau (MQTT-pings of AMQP-pings) en kan een maximale vertraging van slechts 5 minuten hebben. Om deze redenen kunnen er fout-positieven zijn, zoals niet-verbonden apparaten die zijn gerapporteerd als verbonden.
connectionStateUpdatedTime alleen-lezen Een tijdelijke indicator met de datum en de laatste keer dat de verbindingsstatus is bijgewerkt.
lastActivityTime alleen-lezen Een tijdelijke indicator die de datum en de laatste keer weergeeft waarop het apparaat is verbonden, een bericht heeft ontvangen of verzonden.

Notitie

Momenteel bieden de apparaat-SDK's geen ondersteuning voor het gebruik van de + tekens en # in de deviceId en moduleId.

Aanvullend referentiemateriaal

Andere naslagartikelen in de ontwikkelaarshandleiding voor IoT Hub zijn:

  • IoT Hub-eindpunten beschrijft de verschillende eindpunten die elke IoT-hub beschikbaar maakt voor runtime- en beheerbewerkingen.

  • Beperking en quota beschrijft de quota en beperkingsgedrag dat van toepassing is op de IoT Hub-service.

  • Azure IoT-apparaat- en service-SDK's vermeldt de verschillende taal-SDK's die u kunt gebruiken wanneer u zowel apparaat- als service-apps ontwikkelt die communiceren met IoT Hub.

  • IoT Hub querytaal beschrijft de querytaal die u kunt gebruiken om informatie op te halen uit IoT Hub over de dubbels en taken van uw apparaat.

  • IoT Hub MQTT-ondersteuning biedt meer informatie over IoT Hub ondersteuning voor het MQTT-protocol.

Volgende stappen

Nu u hebt geleerd hoe u het IoT Hub-identiteitsregister gebruikt, bent u mogelijk geïnteresseerd in de volgende artikelen in de IoT Hub ontwikkelaarshandleiding:

Als u het gebruik van de IoT Hub Device Provisioning Service wilt verkennen om zero-touch, Just-In-Time-inrichting in te schakelen, raadpleegt u: