Apparaatdubbels begrijpen en gebruiken in IoT Hub
Apparaatdubbels zijn JSON-documenten die apparaatstatusgegevens opslaan, waaronder metagegevens, configuraties en voorwaarden. Azure IoT Hub onderhoudt een apparaatdubbel voor elk apparaat dat u verbindt met IoT Hub.
Notitie
De functies die in dit artikel worden beschreven, zijn alleen beschikbaar in de standaardlaag van de IoT Hub. Zie De juiste IoT Hub-laag voor uw oplossing kiezen voor meer informatie over de Basic- en Standard-/gratis IoT Hub-lagen.
In dit artikel wordt het volgende beschreven:
- De structuur van de apparaatdubbel: tags, gewenste eigenschappen en gerapporteerde eigenschappen.
- De bewerkingen die apparaten en back-endtoepassingen kunnen uitvoeren op apparaatdubbels.
Apparaatdubbels gebruiken om:
Sla apparaatspecifieke metagegevens op in de cloud. Bijvoorbeeld de locatie van een verkoopautomaat.
Huidige statusinformatie rapporteren, zoals beschikbare mogelijkheden en voorwaarden van uw apparaat-app. Bijvoorbeeld of een apparaat is verbonden met uw IoT-hub via mobiel of WiFi.
Synchroniseer de status van langlopende werkstromen tussen de apparaat-app en de back-end-app. Wanneer de back-end van de oplossing bijvoorbeeld de nieuwe firmwareversie opgeeft die moet worden geïnstalleerd en de apparaat-app de verschillende fasen van het updateproces rapporteert.
Voer een query uit op de metagegevens, configuratie of status van uw apparaat.
Zie de richtlijnen voor apparaat-naar-cloud-communicatie voor meer informatie over het gebruik van gerapporteerde eigenschappen, apparaat-naar-cloud-berichten of het uploaden van bestanden.
Zie de richtlijnen voor cloud-naar-apparaat-communicatie voor meer informatie over het gebruik van gewenste eigenschappen, directe methoden of cloud-naar-apparaat-berichten.
Zie IoT-Plug en Play digitale dubbels voor meer informatie over hoe apparaatdubbels betrekking hebben op het apparaatmodel dat wordt gebruikt door een Azure IoT-Plug en Play-apparaat.
Apparaatdubbels
Apparaatdubbels slaan apparaatgerelateerde informatie op die:
Apparaat- en back-ends kunnen worden gebruikt om apparaatvoorwaarden en -configuratie te synchroniseren.
De back-end van de oplossing kan worden gebruikt voor het uitvoeren van query's en het doel van langlopende bewerkingen.
De levenscyclus van een apparaatdubbel is gekoppeld aan de bijbehorende apparaat-id. Apparaatdubbels worden impliciet gemaakt en verwijderd wanneer een apparaat-id wordt gemaakt of verwijderd in IoT Hub.
Een apparaatdubbel is een JSON-document met:
Tags. Een sectie van het JSON-document waarnaar de back-end van de oplossing kan lezen en schrijven. Tags zijn niet zichtbaar voor apparaat-apps.
Gewenste eigenschappen. Wordt samen met gerapporteerde eigenschappen gebruikt om de apparaatconfiguratie of -voorwaarden te synchroniseren. De back-end van de oplossing kan gewenste eigenschappen instellen en de apparaat-app kan deze lezen. De apparaat-app kan ook meldingen ontvangen van wijzigingen in de gewenste eigenschappen.
Gerapporteerde eigenschappen. Wordt samen met de gewenste eigenschappen gebruikt om de apparaatconfiguratie of -voorwaarden te synchroniseren. De apparaat-app kan gerapporteerde eigenschappen instellen en de back-end van de oplossing kan deze lezen en er query's op uitvoeren.
Eigenschappen van apparaat-id's. De hoofdmap van het JSON-document van de apparaatdubbel bevat de alleen-lezen eigenschappen van de bijbehorende apparaat-id die is opgeslagen in het identiteitsregister. Eigenschappen
connectionStateUpdatedTimeengenerationIdworden niet opgenomen.
In het volgende voorbeeld ziet u een JSON-document met apparaatdubbels:
{
"deviceId": "devA",
"etag": "AAAAAAAAAAc=",
"status": "enabled",
"statusReason": "provisioned",
"statusUpdateTime": "0001-01-01T00:00:00",
"connectionState": "connected",
"lastActivityTime": "2015-02-30T16:24:48.789Z",
"cloudToDeviceMessageCount": 0,
"authenticationType": "sas",
"x509Thumbprint": {
"primaryThumbprint": null,
"secondaryThumbprint": null
},
"version": 2,
"tags": {
"deploymentLocation": {
"building": "43",
"floor": "1"
}
},
"properties": {
"desired": {
"telemetryConfig": {
"sendFrequency": "5m"
},
"$metadata" : {...},
"$version": 1
},
"reported": {
"telemetryConfig": {
"sendFrequency": "5m",
"status": "success"
},
"batteryLevel": 55,
"$metadata" : {...},
"$version": 4
}
}
}
Het hoofdobject bevat de eigenschappen van de apparaat-id en containerobjecten voor tags en zowel reported als desired eigenschappen. De properties container bevat enkele alleen-lezen elementen ($metadata en $version) die worden beschreven in de secties Apparaatdubbelmetagegevens en Optimistische gelijktijdigheid .
Voorbeeld van gerapporteerde eigenschap
In het vorige voorbeeld bevat de apparaatdubbel een batteryLevel eigenschap die wordt gerapporteerd door de apparaat-app. Met deze eigenschap kunt u query's uitvoeren op apparaten op basis van het laatst gerapporteerde batterijniveau. Andere voorbeelden zijn de apparaatfuncties of connectiviteitsopties voor het rapporteren van apparaat-apps.
Notitie
Gerapporteerde eigenschappen vereenvoudigen scenario's waarbij de back-end van de oplossing geïnteresseerd is in de laatst bekende waarde van een eigenschap. Gebruik apparaat-naar-cloud-berichten als de back-end van de oplossing telemetrie van apparaten moet verwerken in de vorm van reeksen tijdstempelgebeurtenissen, zoals tijdreeksen.
Voorbeeld van gewenste eigenschap
In het vorige voorbeeld worden de gewenste en gerapporteerde eigenschappen van de telemetryConfig apparaatdubbel gebruikt door de back-end van de oplossing en de apparaat-app om de telemetrieconfiguratie voor dit apparaat te synchroniseren. Voorbeeld:
De back-end van de oplossing stelt de gewenste eigenschap in met de gewenste configuratiewaarde. Dit is het gedeelte van het document met de gewenste eigenschappenset:
"desired": { "telemetryConfig": { "sendFrequency": "5m" }, ... },De apparaat-app wordt onmiddellijk op de hoogte gesteld van de wijziging als het apparaat is verbonden. Als deze niet is verbonden, volgt de apparaat-app de stroom voor opnieuw verbinden van het apparaat wanneer deze verbinding maakt. De apparaat-app rapporteert vervolgens de bijgewerkte configuratie (of een foutvoorwaarde met behulp van de
statuseigenschap). Dit is het gedeelte van de gerapporteerde eigenschappen:"reported": { "telemetryConfig": { "sendFrequency": "5m", "status": "success" } ... }De back-end van de oplossing kan de resultaten van de configuratiebewerking op veel apparaten bijhouden door een query uit te voeren op apparaatdubbels.
Notitie
De voorgaande codefragmenten zijn voorbeelden, geoptimaliseerd voor leesbaarheid, van één manier om een apparaatconfiguratie en de status ervan te coderen. IoT Hub legt geen specifiek schema op voor de gewenste en gerapporteerde eigenschappen van de apparaatdubbel in de apparaatdubbels.
Belangrijk
IoT Plug en Play definieert een schema dat verschillende aanvullende eigenschappen gebruikt om wijzigingen naar gewenste en gerapporteerde eigenschappen te synchroniseren. Als uw oplossing Gebruikmaakt van IoT-Plug en Play, moet u de Plug en Play conventies volgen bij het bijwerken van de eigenschappen van dubbels. Zie Beschrijfbare eigenschappen in IoT Plug en Play voor meer informatie en een voorbeeld.
U kunt twins gebruiken om langlopende bewerkingen, zoals firmware-updates, te synchroniseren. Zie Gewenste eigenschappen gebruiken om apparaten te configureren voor meer informatie over het gebruik van eigenschappen voor het synchroniseren en bijhouden van een langdurige bewerking op verschillende apparaten.
Back-endbewerkingen
De back-end van de oplossing werkt op de apparaatdubbel met behulp van de volgende atomische bewerkingen, weergegeven via HTTPS:
Apparaatdubbel ophalen op id. Deze bewerking retourneert het apparaatdubbeldocument, inclusief tags en gewenste en gerapporteerde systeemeigenschappen.
Gedeeltelijk bijwerken van apparaatdubbel. Met deze bewerking kan de back-end van de oplossing de tags of gewenste eigenschappen in een apparaatdubbel gedeeltelijk bijwerken. De gedeeltelijke update wordt uitgedrukt als een JSON-document waarmee een eigenschap wordt toegevoegd of bijgewerkt. Eigenschappen die zijn ingesteld op
nullworden verwijderd. In het volgende voorbeeld wordt een nieuwe gewenste eigenschap met waarde{"newProperty": "newValue"}gemaakt, wordt de bestaande waardeexistingPropertyoverschreven met"otherNewValue"en wordt verwijderdotherOldProperty. Er worden geen andere wijzigingen aangebracht in bestaande gewenste eigenschappen of tags:{ "properties": { "desired": { "newProperty": { "nestedProperty": "newValue" }, "existingProperty": "otherNewValue", "otherOldProperty": null } } }Vervang de gewenste eigenschappen. Met deze bewerking kan de back-end van de oplossing alle bestaande gewenste eigenschappen volledig overschrijven en een nieuw JSON-document vervangen door
properties/desired.Tags vervangen. Met deze bewerking kan de back-end van de oplossing alle bestaande tags volledig overschrijven en een nieuw JSON-document vervangen door
tags.Dubbelmeldingen ontvangen. Met deze bewerking kan de back-end van de oplossing worden gewaarschuwd wanneer de dubbel wordt gewijzigd. Hiervoor moet uw IoT-oplossing een route maken en de gegevensbron instellen die gelijk is aan twinChangeEvents. Er bestaat standaard geen dergelijke route, dus er worden geen dubbelmeldingen verzonden. Als de wijzigingssnelheid te hoog is of om andere redenen, zoals interne fouten, kan de IoT Hub slechts één melding verzenden die alle wijzigingen bevat. Als uw toepassing daarom betrouwbare controle en logboekregistratie van alle tussenliggende statussen nodig heeft, moet u apparaat-naar-cloud-berichten gebruiken. Zie Nontelemetry-gebeurtenisschema's voor meer informatie over de eigenschappen en hoofdtekst die worden geretourneerd in het meldingsbericht van de dubbel.
Alle voorgaande bewerkingen ondersteunen optimistische gelijktijdigheid en vereisen de machtiging Service Verbinding maken, zoals gedefinieerd in Toegang tot IoT Hub beheren.
Naast deze bewerkingen kan de back-end van de oplossing:
Voer een query uit op de apparaatdubbels met behulp van de SQL-achtige IoT Hub-querytaal.
Voer bewerkingen uit op grote sets apparaatdubbels met behulp van taken.
Apparaatbewerkingen
De apparaat-app werkt op de apparaatdubbel met behulp van de volgende atomische bewerkingen:
Apparaatdubbel ophalen. Met deze bewerking wordt het document met de apparaatdubbel geretourneerd (inclusief de gewenste en gerapporteerde systeemeigenschappen) voor het momenteel verbonden apparaat. (Tags zijn niet zichtbaar voor apparaat-apps.)
Gerapporteerde eigenschappen gedeeltelijk bijwerken. Met deze bewerking kan de gedeeltelijke update van de gerapporteerde eigenschappen van het momenteel verbonden apparaat worden bijgewerkt. Deze bewerking maakt gebruik van dezelfde JSON-updateindeling die door de back-end van de oplossing wordt gebruikt voor een gedeeltelijke update van de gewenste eigenschappen.
Bekijk de gewenste eigenschappen. Het momenteel verbonden apparaat kan ervoor kiezen om op de hoogte te worden gesteld van updates voor de gewenste eigenschappen wanneer deze plaatsvinden. Het apparaat ontvangt dezelfde vorm van update (gedeeltelijke of volledige vervanging) die wordt uitgevoerd door de back-end van de oplossing.
Voor alle voorgaande bewerkingen is de machtiging Apparaat Verbinding maken vereist, zoals gedefinieerd in Toegang tot IoT Hub beheren.
Met de SDK's voor Azure IoT-apparaten kunt u eenvoudig de voorgaande bewerkingen van veel talen en platforms gebruiken. Zie De stroom voor opnieuw verbinden van apparaten voor meer informatie over ioT Hub-primitieven voor synchronisatie van gewenste eigenschappen.
Indeling van tags en eigenschappen
Tags, gewenste eigenschappen en gerapporteerde eigenschappen zijn JSON-objecten met de volgende beperkingen:
Sleutels: Alle sleutels in JSON-objecten zijn UTF-8 gecodeerd, hoofdlettergevoelig en maximaal 1 kB lang. Toegestane tekens sluiten UNICODE-besturingstekens (segmenten C0 en C1) en
.,$en SP uit.Notitie
IoT Hub-query's die worden gebruikt in berichtroutering bieden geen ondersteuning voor witruimte of een van de volgende tekens als onderdeel van een sleutelnaam:
()<>@,;:\"/?={}.Waarden: Alle waarden in JSON-objecten kunnen van de volgende JSON-typen zijn: Booleaanse waarde, getal, tekenreeks, object. Matrices worden ook ondersteund.
Gehele getallen kunnen een minimumwaarde van -4503599627370496 en een maximumwaarde van 4503599627370495 hebben.
Tekenreekswaarden zijn UTF-8 gecodeerd en kunnen een maximale lengte van 4 kB hebben.
Diepte: De maximale diepte van JSON-objecten in tags, gewenste eigenschappen en gerapporteerde eigenschappen is 10. Het volgende object is bijvoorbeeld geldig:
{ ... "tags": { "one": { "two": { "three": { "four": { "five": { "six": { "seven": { "eight": { "nine": { "ten": { "property": "value" } } } } } } } } } } }, ... }
Grootte van apparaatdubbel
IoT Hub dwingt een limiet van 8 kB af voor de waarde van en een limiet van tags32 kB voor elke grootte van properties/desired en properties/reported. Deze totalen zijn exclusief van alleen-lezen elementen zoals $version en $metadata/$lastUpdated.
De grootte van de dubbel wordt als volgt berekend:
Voor elke eigenschap in het JSON-document berekent IoT Hub cumulatief de lengte van de sleutel en waarde van de eigenschap.
Eigenschapssleutels worden beschouwd als UTF8-gecodeerde tekenreeksen.
Eenvoudige eigenschapswaarden worden beschouwd als UTF8-gecodeerde tekenreeksen, numerieke waarden (8 bytes) of Booleaanse waarden (4 bytes).
De grootte van door UTF8 gecodeerde tekenreeksen wordt berekend door alle tekens te tellen, met uitzondering van UNICODE-besturingstekens (segmenten C0 en C1).
Complexe eigenschapswaarden (geneste objecten) worden berekend op basis van de geaggregeerde grootte van de eigenschapssleutels en eigenschapswaarden die ze bevatten.
IoT Hub weigert met een fout alle bewerkingen die de grootte van de tags, properties/desiredof properties/reported documenten boven de limiet zouden vergroten.
Metagegevens van apparaatdubbel
IoT Hub onderhoudt de tijdstempel van de laatste update voor elk JSON-object in de gewenste en gerapporteerde eigenschappen van de apparaatdubbel. De tijdstempels zijn in UTC en gecodeerd in de ISO8601-indelingYYYY-MM-DDTHH:MM:SS.mmmZ.
Voorbeeld:
{
...
"properties": {
"desired": {
"telemetryConfig": {
"sendFrequency": "5m"
},
"$metadata": {
"telemetryConfig": {
"sendFrequency": {
"$lastUpdated": "2016-03-30T16:24:48.789Z"
},
"$lastUpdated": "2016-03-30T16:24:48.789Z"
},
"$lastUpdated": "2016-03-30T16:24:48.789Z"
},
"$version": 23
},
"reported": {
"telemetryConfig": {
"sendFrequency": "5m",
"status": "success"
},
"batteryLevel": "55%",
"$metadata": {
"telemetryConfig": {
"sendFrequency": {
"$lastUpdated": "2016-03-31T16:35:48.789Z"
},
"status": {
"$lastUpdated": "2016-03-31T16:35:48.789Z"
},
"$lastUpdated": "2016-03-31T16:35:48.789Z"
},
"batteryLevel": {
"$lastUpdated": "2016-04-01T16:35:48.789Z"
},
"$lastUpdated": "2016-04-01T16:24:48.789Z"
},
"$version": 123
}
}
...
}
Deze informatie wordt op elk niveau bewaard (niet alleen de bladeren van de JSON-structuur) om updates te behouden die objectsleutels verwijderen.
Optimistische gelijktijdige uitvoering
Tags, gewenste eigenschappen en gerapporteerde eigenschappen ondersteunen optimistische gelijktijdigheid. Als u de volgorde van updates van eigenschappen van dubbels wilt garanderen, kunt u overwegen synchronisatie op toepassingsniveau te implementeren door te wachten op callback van gerapporteerde eigenschappen voordat u de volgende update verzendt.
Apparaatdubbels hebben een ETag (etag eigenschap), volgens RFC7232, die de JSON-weergave van de dubbel vertegenwoordigt. U kunt de etag eigenschap gebruiken in voorwaardelijke updatebewerkingen vanuit de back-end van de oplossing om consistentie te garanderen. Dit is de enige optie voor het garanderen van consistentie in bewerkingen die betrekking hebben op de tags container.
Gewenste en gerapporteerde eigenschappen van apparaatdubbels hebben ook een $version waarde die gegarandeerd incrementeel is. Net als bij een ETag kan de versie door de update party worden gebruikt om consistentie van updates af te dwingen. Bijvoorbeeld een apparaat-app voor een gerapporteerde eigenschap of de back-end van de oplossing voor een gewenste eigenschap.
Versies zijn ook handig wanneer een waarneemagent (zoals de apparaat-app die de gewenste eigenschappen observeren) races moet afstemmen tussen het resultaat van een ophaalbewerking en een updatemelding. De sectie Apparaat voor het opnieuw verbinden van stroom biedt meer informatie.
Stroom voor opnieuw verbinden van apparaat
De gewenste eigenschappen worden niet bewaard voor niet-verbonden apparaten. Hier volgt dat een apparaat dat verbinding maakt, het volledige document met gewenste eigenschappen moet ophalen, naast het abonneren op updatemeldingen. Gezien de mogelijkheid van races tussen updatemeldingen en volledig ophalen, moet de volgende stroom worden gegarandeerd:
- De apparaat-app maakt verbinding met een IoT-hub.
- Apparaat-app abonneert zich op updates van gewenste eigenschappen.
- Met de apparaat-app wordt het volledige document opgehaald voor de gewenste eigenschappen.
De apparaat-app kan alle meldingen negeren met $version minder of gelijk aan de versie van het volledige opgehaalde document. Deze aanpak is mogelijk omdat IoT Hub garandeert dat versies altijd oplopen.
Volgende stappen
Nu u meer hebt geleerd over apparaatdubbels, bent u mogelijk geïnteresseerd in de volgende onderwerpen over ioT Hub-ontwikkelaarshandleiding:
- Moduledubbels begrijpen en gebruiken in IoT Hub
- Een directe methode aanroepen op een apparaat
- Taken op meerdere apparaten plannen
Raadpleeg de volgende IoT Hub-zelfstudies om een aantal van de concepten uit te proberen die in dit artikel worden beschreven: