Delen via

Inzicht in 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 in-flight cloud-naar-apparaat-berichten bevat.

Gebruik het identiteitsregister wanneer u het volgende moet doen:

  • Apparaten of modules inrichten die verbinding maken met uw IoT-hub.
  • Beheer per apparaat/per module toegang 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 is opgegeven in RFC7232.

Belangrijk

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

Een IoT Hub-identiteitsregister:

  • Bevat geen toepassingsmetagegevens.

Belangrijk

Gebruik alleen het identiteitsregister voor apparaatbeheer- en inrichtingsbewerkingen. Bewerkingen met hoge doorvoer tijdens runtime mogen niet afhankelijk zijn van het uitvoeren van bewerkingen in het identiteitsregister. Als u bijvoorbeeld de verbindingsstatus van een apparaat controleert voordat een opdracht wordt verzonden, is dit geen ondersteund patroon. Controleer de beperkingsfrequenties voor het identiteitsregister.

Notitie

Het kan enkele seconden duren voordat een apparaat- of module-id beschikbaar is voor het ophalen na het maken. Probeer get de bewerking van apparaat- of module-id's opnieuw 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 Device Provisioning (Device Provisioning) voor meer informatie.

  • Als u denkt dat een apparaat is aangetast of om welke reden dan ook niet geautoriseerd 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 aangetast 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 apparaatidentiteiten 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 apparaatidentiteiten bulksgewijs te importeren in het identiteitsregister van een IoT-hub. Importbewerkingen zijn langlopende taken die gebruikmaken van gegevens in een door de klant geleverde blobcontainer om apparaatidentiteitsgegevens naar het identiteitsregister te schrijven.

Zie REST API's van ioT Hub-resourceproviders voor meer informatie over de API's voor importeren en exporteren. Zie Bulkbeheer van IoT Hub-apparaatidentiteiten voor meer informatie over het uitvoeren van import- en exporttaken.

Apparaat-id's kunnen ook worden geëxporteerd en geïmporteerd uit 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 door een bepaalde IoT-oplossing worden opgeslagen, zijn afhankelijk van de specifieke vereisten van die oplossing. Maar in een oplossing moeten apparaat-id's en verificatiesleutels worden opgeslagen. Azure IoT Hub bevat een identiteitsregister waarmee waarden voor elk apparaat, zoals id's, verificatiesleutels en statuscodes, kunnen worden opgeslagen. 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 voor het toevoegen van de initiële apparaatgegevens aan de winkels in uw oplossing. Als u een nieuw apparaat wilt inschakelen om verbinding te 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 initialiseren in andere oplossingsarchieven. U kunt de Azure IoT Hub Device Provisioning Service ook gebruiken om Zero Touch- en 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 kan uw IoT-oplossing waarschuwen wanneer een apparaat-id wordt gemaakt of verwijderd door meldingen over de levenscyclus te verzenden. Hiervoor moet uw IoT-oplossing een route maken en de gegevensbron instellen die gelijk is aan DeviceLifecycleEvents. Standaard worden er geen meldingen over de levenscyclus verzonden, dat wil gezegd, dergelijke routes bestaan niet. 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, afhankelijk van of de gebeurtenissen worden gegenereerd voor module-id's of apparaat-id's. Zie Gebeurtenisschema's voor niet-telemetrie voor meer informatie over de eigenschappen en hoofdtekst die in het meldingsbericht worden geretourneerd.

Meldingen voor het maken van module-identiteiten verschillen voor IoT Edge-modules dan voor andere modules. Voor IoT Edge-modules wordt de melding alleen verzonden als het bijbehorende IoT Edge-apparaat wordt uitgevoerd. Voor alle andere modules worden levenscyclusmeldingen verzonden wanneer de module-identiteit wordt bijgewerkt aan de zijde van IoT Hub.

Eigenschappen van apparaat-id's

Apparaatidentiteiten worden weergegeven als JSON-documenten met de volgende eigenschappen:

Eigenschappen Opties Beschrijving
deviceId vereist, alleen-lezen voor updates Een hoofdlettergevoelige tekenreeks (maximaal 128 tekens lang) van 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 te onderscheiden met dezelfde deviceId wanneer ze zijn verwijderd en opnieuw zijn gemaakt.
etag vereist, alleen-lezen Een tekenreeks die een zwakke ETag vertegenwoordigt voor de apparaat-id, 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 Device Capabilities 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. Stel in onderliggende (leaf)-apparaten deze eigenschap echter in op dezelfde waarde als de eigenschap parentScopes (de deviceScope van het bovenliggende apparaat) voor achterwaartse compatibiliteit met eerdere versies van de API. Zie IoT Edge als gateway voor meer informatie: bovenliggende en onderliggende relaties.
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. In niet-edge-apparaten is de eigenschap niet aanwezig als het apparaat geen bovenliggend item heeft. Zie IoT Edge als gateway voor meer informatie: bovenliggende en onderliggende relaties.
status vereist Een toegangsindicator. Kan worden ingeschakeld of uitgeschakeld. Als dit is 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 die de reden voor de status van de apparaat-id opslaat. Alle UTF-8 tekens zijn toegestaan.
statusUpdateTime alleen-lezen Een tijdelijke indicator, met de datum en tijd van de laatste statusupdate.
verbindingsstatus 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.
connectionStateUpdatedTime alleen-lezen Een tijdelijke indicator, met de datum en laatste keer dat de verbindingsstatus is bijgewerkt.
lastActivityTime alleen-lezen Een tijdelijke indicator, met de datum en laatste keer dat het apparaat is verbonden, ontvangen of een bericht heeft verzonden. Deze eigenschap is uiteindelijk consistent, maar kan tot 5 tot 10 minuten worden uitgesteld. Daarom mag deze niet worden gebruikt in productiescenario's.

Notitie

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

Notitie

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

Eigenschappen van module-identiteit

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

Eigenschappen Opties Beschrijving
deviceId vereist, alleen-lezen voor updates Een hoofdlettergevoelige tekenreeks (maximaal 128 tekens lang) van ASCII 7-bits alfanumerieke tekens plus bepaalde speciale tekens: - . + % _ # * ? ! ( ) , : = @ $ '.
moduleId vereist, alleen-lezen voor updates Een hoofdlettergevoelige tekenreeks (maximaal 128 tekens lang) van 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 te onderscheiden met dezelfde deviceId wanneer ze zijn verwijderd en opnieuw zijn gemaakt.
etag vereist, alleen-lezen Een tekenreeks die een zwakke ETag vertegenwoordigt voor de apparaat-id, volgens RFC7232.
verificatie optioneel Een samengesteld object met verificatiegegevens en beveiligingsmaterialen. Zie verificatiemechanisme in de REST API-documentatie voor meer informatie.
managedBy 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 is geplaatst om naar de module te worden verzonden.
verbindingsstatus 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.
connectionStateUpdatedTime alleen-lezen Een tijdelijke indicator, met de datum en laatste keer dat de verbindingsstatus is bijgewerkt.
lastActivityTime alleen-lezen Een tijdelijke indicator, met de datum en laatste keer dat het apparaat is verbonden, ontvangen of een bericht heeft verzonden.

Notitie

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

Aanvullend referentiemateriaal

Andere naslagartikelen in de Ontwikkelaarshandleiding voor IoT Hub zijn:

Volgende stappen

Nu u hebt geleerd hoe u het IoT Hub-identiteitsregister kunt gebruiken, bent u mogelijk geïnteresseerd in de volgende artikelen over ioT Hub-ontwikkelaarshandleidingen:

Als u de IoT Hub Device Provisioning Service wilt gebruiken om Zero Touch, Just-In-Time-inrichting in te schakelen, raadpleegt u: