Apparaatdubbels in IoT Hub begrijpen en gebruiken

Apparaatdubbels zijn JSON-documenten die informatie over de apparaatstatus 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 lagen Basic en Standard/free IoT Hub.

In dit artikel wordt het volgende beschreven:

  • De structuur van de apparaatdubbel: tags, gewenste en gerapporteerde eigenschappen.
  • De bewerkingen die apparaat-apps en back-ends kunnen uitvoeren op apparaatdubbels.

Gebruik apparaatdubbels voor het volgende:

  • Sla apparaatspecifieke metagegevens op in de cloud. Bijvoorbeeld de implementatielocatie van een verkoopautomaat.

  • De huidige statusgegevens, zoals beschikbare mogelijkheden en voorwaarden, rapporteren vanuit uw apparaat-app. Bijvoorbeeld of een apparaat is verbonden met uw IoT-hub via een mobiel netwerk of Wi-Fi.

  • Synchroniseer de status van langlopende werkstromen tussen apparaat-app en back-end-app. Wanneer de back-end van de oplossing bijvoorbeeld de nieuwe firmwareversie aangeeft 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.

Raadpleeg De richtlijnen voor apparaat-naar-cloud-communicatie voor hulp bij het gebruik van gerapporteerde eigenschappen, apparaat-naar-cloud-berichten of het uploaden van bestanden.

Raadpleeg Richtlijnen voor cloud-naar-apparaat-communicatie voor hulp bij het gebruik van gewenste eigenschappen, directe methoden of cloud-naar-apparaat-berichten.

Zie Inzicht in IoT Plug en Play digitale dubbels voor meer informatie over hoe apparaatdubbels zich verhouden tot 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 om query's uit te voeren op 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 dat het volgende bevat:

  • Tags. Een sectie van het JSON-document waaruit de back-end van de oplossing kan lezen en waarnaar kan worden geschreven. Tags zijn niet zichtbaar voor apparaat-apps.

  • Gewenste eigenschappen. Wordt samen met gerapporteerde eigenschappen gebruikt om de configuratie of voorwaarden van het apparaat 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. De hoofdmap van het JSON-document van de apparaatdubbel bevat de alleen-lezen-eigenschappen van de bijbehorende apparaat-id die zijn opgeslagen in het identiteitsregister. Eigenschappen connectionStateUpdatedTime en generationId worden niet opgenomen.

Schermopname van eigenschappen van apparaatdubbels

In het volgende voorbeeld ziet u een JSON-document met een apparaatdubbel:

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

In het hoofdobject bevinden zich de eigenschappen van de apparaatidentiteit en containerobjecten voor tags en reported en eigenschappen desired . De properties container bevat enkele alleen-lezen elementen ($metadata en ) die $versionworden beschreven in de secties Metagegevens van apparaatdubbel 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 apparaat-app die apparaatmogelijkheden of connectiviteitsopties rapporteert.

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 van 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. Bijvoorbeeld:

  1. 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"
        },
        ...
    },
    
  2. De apparaat-app wordt onmiddellijk op de hoogte gesteld van de wijziging als het apparaat is verbonden. Als de app niet is verbonden, volgt de apparaat-app de stroom voor opnieuw verbinding maken van het apparaat wanneer deze verbinding maakt. De apparaat-app rapporteert vervolgens de bijgewerkte configuratie (of een foutvoorwaarde met behulp van de status eigenschap). Dit is het gedeelte van de gerapporteerde eigenschappen:

    "reported": {
        "telemetryConfig": {
            "sendFrequency": "5m",
            "status": "success"
        }
        ...
    }
    
  3. De back-end van de oplossing kan de resultaten van de configuratiebewerking op veel apparaten volgen 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 apparaatdubbel en gerapporteerde eigenschappen in de apparaatdubbels.

Belangrijk

IoT Plug en Play definieert een schema dat gebruikmaakt van verschillende aanvullende eigenschappen om wijzigingen te synchroniseren met gewenste en gerapporteerde eigenschappen. Als uw oplossing gebruikmaakt van IoT Plug en Play, moet u de Plug en Play-conventies volgen bij het bijwerken van dubbeleigenschappen. Zie Schrijfbare eigenschappen in IoT Plug en Play voor meer informatie en een voorbeeld.

U kunt dubbels 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, beschikbaar gemaakt via HTTPS:

  • Haal de apparaatdubbel op op id. Met deze bewerking wordt het document met de apparaatdubbel geretourneerd, inclusief tags en gewenste en gerapporteerde systeemeigenschappen.

  • Apparaatdubbel gedeeltelijk bijwerken. 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 null worden verwijderd. In het volgende voorbeeld wordt een nieuwe gewenste eigenschap met waarde {"newProperty": "newValue"}gemaakt, wordt de bestaande waarde van existingProperty overschreven met "otherNewValue"en wordt otherOldPropertyverwijderd. 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 gelijk stellen aan twinChangeEvents. Standaard bestaat een dergelijke route niet, 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 Niet-telemetriegebeurtenisschema's voor meer informatie over de eigenschappen en de hoofdtekst die worden geretourneerd in het meldingsbericht van de dubbel.

Alle voorgaande bewerkingen ondersteunen Optimistische gelijktijdigheid en vereisen de machtiging ServiceConnect, zoals gedefinieerd in Toegang tot IoT Hub beheren.

Naast deze bewerkingen kan de back-end van de oplossing het volgende doen:

  • Voer een query uit op de apparaatdubbels met behulp van de SQL-achtige IoT Hub querytaal.

  • Bewerkingen uitvoeren 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. Deze bewerking retourneert het document van de apparaatdubbel (inclusief de gewenste en gerapporteerde systeemeigenschappen) voor het apparaat dat momenteel is verbonden. (Tags zijn niet zichtbaar voor apparaat-apps.)

  • Gerapporteerde eigenschappen gedeeltelijk bijwerken. Met deze bewerking wordt de gedeeltelijke update van de gerapporteerde eigenschappen van het momenteel verbonden apparaat ingeschakeld. Deze bewerking maakt gebruik van dezelfde JSON-updateindeling die de back-end van de oplossing gebruikt voor een gedeeltelijke update van de gewenste eigenschappen.

  • Bekijk de gewenste eigenschappen. Het apparaat dat momenteel is verbonden, kan ervoor kiezen om op de hoogte te worden gesteld van updates van 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 DeviceConnect vereist, zoals gedefinieerd in Toegang tot IoT Hub beheren.

Met de Azure IoT-apparaat-SDK's kunt u eenvoudig de voorgaande bewerkingen gebruiken vanuit veel talen en platforms. Zie Apparaatstroom voor opnieuw verbinding maken voor meer informatie over de details van 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 met UTF-8 gecodeerd, hoofdlettergevoelig en maximaal 1 kB lang. Toegestane tekens zijn exclusief UNICODE-besturingstekens (segmenten C0 en C1), en ., $en SP.

    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 groottelimiet van 8 kB af voor de waarde van , en een limiet van tags32 kB voor elk de waarde van properties/desired en properties/reported. Deze totalen zijn exclusief alleen-lezenelementen, zoals $version en $metadata/$lastUpdated.

De grootte van een dubbel wordt als volgt berekend:

  • Voor elke eigenschap in het JSON-document wordt IoT Hub cumulatief berekend en wordt de lengte van de sleutel en waarde van de eigenschap opgeteld.

  • Eigenschapssleutels worden beschouwd als tekenreeksen met UTF8-codering.

  • Eenvoudige eigenschapswaarden worden beschouwd als tekenreeksen met UTF8-codering, numerieke waarden (8 bytes) of Booleaanse waarden (4 bytes).

  • De grootte van 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 aggregatiegrootte 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 behoudt 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.

Bijvoorbeeld:

{
    ...
    "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 bewaard op elk niveau (niet alleen de bladen van de JSON-structuur) om updates te behouden die objectsleutels verwijderen.

Optimistische gelijktijdigheid

Tags, gewenste eigenschappen en gerapporteerde eigenschappen ondersteunen allemaal optimistische gelijktijdigheid. Als u de volgorde van updates van dubbeleigenschappen wilt garanderen, kunt u overwegen om 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 tweeling vertegenwoordigt. U kunt de etag eigenschap in voorwaardelijke updatebewerkingen van de back-end van de oplossing gebruiken om consistentie te garanderen. Dit is de enige optie om consistentie te garanderen in bewerkingen waarbij de tags container betrokken is.

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 bijwerkende partij 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 observerende agent (zoals de apparaat-app die de gewenste eigenschappen observeert) races moet afstemmen tussen het resultaat van een ophaalbewerking en een updatemelding. In de sectie Apparaatstroom voor opnieuw verbinding maken vindt u meer informatie.

Stroom voor opnieuw verbinding maken van apparaat

IoT Hub behoudt geen updatemeldingen voor gewenste eigenschappen voor niet-verbonden apparaten. Hieruit volgt dat een apparaat dat verbinding maakt, het volledige gewenste eigenschappendocument moet ophalen, naast het abonneren op updatemeldingen. Gezien de mogelijkheid van races tussen updatemeldingen en volledig ophalen, moet de volgende stroom worden gegarandeerd:

  1. Apparaat-app maakt verbinding met een IoT-hub.
  2. Apparaat-app is geabonneerd op updatemeldingen voor gewenste eigenschappen.
  3. De apparaat-app haalt het volledige document op voor de gewenste eigenschappen.

De apparaat-app kan alle meldingen negeren met $version minder of gelijk aan de versie van het volledig opgehaalde document. Deze aanpak is mogelijk omdat IoT Hub garandeert dat versies altijd worden verhoogd.

Aanvullend referentiemateriaal

Andere naslagonderwerpen in de ontwikkelaarshandleiding voor IoT Hub zijn:

Volgende stappen

Nu u meer hebt geleerd over apparaatdubbels, bent u mogelijk geïnteresseerd in de volgende onderwerpen over de IoT Hub ontwikkelaarshandleiding:

Raadpleeg de volgende IoT Hub zelfstudies om enkele van de concepten uit te proberen die in dit artikel worden beschreven: