Apparaattweeling begrijpen en gebruiken in IoT Hub

Apparaattweelingen zijn JSON-documenten die informatie over de apparaattoestand bevatten, 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. Raadpleeg How to choose the right IoT Hub tier (De juiste IoT Hub-prijscategorie kiezen) voor meer informatie over de Basic- en Standard/gratis-prijscategorieën van IoT Hub.

In dit artikel wordt het volgende beschreven:

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

Gebruik apparaattweelingen voor het volgende:

  • Apparaatspecifieke metagegevens opslaan in de cloud. Bijvoorbeeld de implementatielocatie van een verkoopautomaat.

  • Huidige statusinformatie rapporteren, zoals beschikbare mogelijkheden en voorwaarden van uw apparaat-app. Een apparaat is bijvoorbeeld via mobiel of wi-fi verbonden met uw IoT-hub.

  • Synchroniseer de status van langlopende werkstromen tussen de apparaat-app en de back-end-app. Bijvoorbeeld wanneer de back-end van de oplossing de nieuwe firmwareversie op te geven die moet worden geïnstalleerd en de apparaat-app de verschillende fasen van het updateproces rapporteert.

  • Een query uitvoeren op de metagegevens, configuratie of status van uw apparaat.

Raadpleeg 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 Understand IoT Plug en Play digital twins (IoT-apparatenen digitale tweelingen begrijpen) voor meer informatie over hoe apparaattweeling zich verhoudt tot het apparaatmodel dat wordt gebruikt door een Azure IoT Plug en Play-apparaat.

Apparaattweeling

Apparaattweelingen slaan apparaatgerelateerde gegevens op die:

  • Apparaat- en back-ends kunnen worden gebruikt om apparaatvoorwaarden en -configuratie te synchroniseren.

  • De back-end van de oplossing kan gebruiken om langdurige bewerkingen op te vragen en te richten.

De levenscyclus van een apparaat dubbel is gekoppeld aan de bijbehorende apparaat-id. Apparaattweelingen worden impliciet gemaakt en verwijderd wanneer een apparaat-id wordt gemaakt of verwijderd in IoT Hub.

Een apparaat dubbel is een JSON-document dat het volgende bevat:

  • Tags. Een sectie van het JSON-document waar de back-end van de oplossing naar kan lezen en schrijven. Tags zijn niet zichtbaar voor apparaat-apps.

  • Gewenste eigenschappen. Samen met gerapporteerde eigenschappen gebruikt om 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 over wijzigingen in de gewenste eigenschappen.

  • Gerapporteerde eigenschappen. Wordt samen met de gewenste eigenschappen gebruikt om 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 de apparaat-id. De hoofdmap van het JSON-document van de apparaat dubbel bevat de alleen-lezen eigenschappen van de bijbehorende apparaat-id die is opgeslagen in het identiteitsregister. Eigenschappen connectionStateUpdatedTime en worden niet generationId opgenomen.

Schermopname van eigenschappen van apparaattwee

In het volgende voorbeeld ziet u een JSON-document voor apparaattwee:

{
    "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": {
        "$etag": "123",
        "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 zijn de eigenschappen van de apparaat-id en containerobjecten voor tags en reported zowel als desired eigenschappen. De container bevat enkele alleen-lezenelementen ( , en ) die worden beschreven in de secties Metagegevens apparaat dubbel en properties $metadata $etag $version Optimistische gelijktijdigheid.

Voorbeeld van gerapporteerde eigenschap

In het vorige voorbeeld bevat de apparaattweeling 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 accuniveau. Andere voorbeelden zijn de apparaatmogelijkheden of connectiviteitsopties voor apparaat-app-rapportage.

Notitie

Gerapporteerde eigenschappen vereenvoudigen scenario's waarin 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 apparaattwee gebruikt door de back-end van de oplossing en de apparaat-app om de telemetrieconfiguratie voor telemetryConfig dit apparaat te synchroniseren. Bijvoorbeeld:

  1. De back-end van de oplossing stelt de gewenste eigenschap in met de gewenste configuratiewaarde. Hier 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 deze is verbonden of bij de eerste keer opnieuw verbinding maken. 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 bijhouden door een query uit te voeren op apparaattweelingen.

Notitie

De voorgaande codefragmenten zijn voorbeelden, geoptimaliseerd voor leesbaarheid, van één manier om een apparaatconfiguratie en de status ervan te coderen. IoT Hub geen specifiek schema voor de gewenste en gerapporteerde eigenschappen van de apparaattweeling voor de apparaattweeling.

U kunt tweelingen 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 om een langdurige bewerking op apparaten te synchroniseren en bij te houden.

Back-endbewerkingen

De back-end van de oplossing werkt op de apparaat dubbel met behulp van de volgende atomische bewerkingen, die worden blootgesteld via HTTPS:

  • Haal de apparaat dubbel op op id. Deze bewerking retourneert het document van de apparaattweeling, inclusief tags en gewenste en gerapporteerde systeemeigenschappen.

  • Apparaat dubbel gedeeltelijk bijwerken. Met deze bewerking kan de back-end van de oplossing de tags of gewenste eigenschappen in een apparaat dubbel gedeeltelijk bijwerken. De gedeeltelijke update wordt uitgedrukt als een JSON-document waarin een eigenschap wordt toegevoegd of bijgewerkt. Eigenschappen die zijn ingesteld null op worden verwijderd. In het volgende voorbeeld wordt een nieuwe gewenste eigenschap gemaakt met waarde , wordt de bestaande waarde van overschreven {"newProperty": "newValue"} existingProperty met en wordt "otherNewValue" otherOldProperty verwijderd. 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 .

  • Vervang tags. 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 een melding ontvangen wanneer de tweeling wordt gewijzigd. Hiervoor moet uw IoT-oplossing een route maken en de gegevensbron instellen op twinChangeEvents. Standaard bestaan dergelijke routes niet, dus er worden geen dubbele meldingen verzonden. Als de wijzigingsfrequentie 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 staten nodig heeft, moet u apparaat-naar-cloud-berichten gebruiken. Het dubbele meldingsbericht bevat eigenschappen en de body.

    • Eigenschappen

      Name Waarde
      $content-type application/json
      $iothub-enqueuedtime Tijdstip waarop de melding is verzonden
      $iothub-message-source twinChangeEvents
      $content-codering utf-8
      deviceId Id van het apparaat
      hubName Naam van IoT Hub
      operationTimestamp ISO8601-tijdstempel van bewerking
      iothub-message-schema twinChangeNotification
      opType replaceTwin of updateTwin

      Eigenschappen van het berichtsysteem worden vooraf laten gaan door het $ symbool.

    • Hoofdtekst

      Deze sectie bevat alle dubbele wijzigingen in een JSON-indeling. Deze maakt gebruik van dezelfde indeling als een patch, met het verschil dat deze alle dubbele secties kan bevatten: tags, properties.reported, properties.desired en dat deze de elementen '$metadata' bevat. Bijvoorbeeld:

      {
        "properties": {
            "desired": {
                "$metadata": {
                    "$lastUpdated": "2016-02-30T16:24:48.789Z"
                },
                "$version": 1
            },
            "reported": {
                "$metadata": {
                    "$lastUpdated": "2016-02-30T16:24:48.789Z"
                },
                "$version": 1
            }
        }
      }
      

Alle voorgaande bewerkingen ondersteunen optimistische gelijktijdigheid en vereisen de machtiging ServiceConnect, zoals gedefinieerd in Toegang totIoT Hub .

Naast deze bewerkingen kan de back-end van de oplossing:

  • Query's uitvoeren op de apparaattweeling SQL de IoT Hub querytaal.

  • Voer bewerkingen uit op grote sets apparaattweeling met behulp van taken.

Apparaatbewerkingen

De apparaat-app werkt op de apparaat dubbel met behulp van de volgende atomische bewerkingen:

  • Haal de apparaat dubbel op. Deze bewerking retourneert het document van de apparaattweeling (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 kunt u de gerapporteerde eigenschappen van het momenteel verbonden apparaat gedeeltelijk bijwerken. Deze bewerking maakt gebruik van dezelfde JSON-update-indeling die de back-end van de oplossing 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 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 tottoegang tot IoT Hub.

Met de apparaat-SDK's van Azure IoT kunt u de voorgaande bewerkingen eenvoudig gebruiken vanuit veel talen en platformen. Zie Apparaat opnieuw verbinden voor meer informatie over de IoT Hub 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, sleutelgevoelig en maximaal 1 kB lang. Toegestane tekens sluiten UNICODE-besturingselementtekens (segmenten C0 en C1) . en , en SP $ uit.

  • 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.

    • 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 apparaat dubbel

IoT Hub dwingt een groottelimiet van 8 kB af voor de waarde van , en een groottelimiet van 32 kB elk voor tags de waarde van en properties/desired properties/reported . Deze totalen zijn exclusief alleen-lezen elementen $etag zoals $version , en $metadata/$lastUpdated .

De grootte van de tweeling wordt als volgt berekend:

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

  • 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 UTF8-gecodeerde tekenreeksen wordt berekend door alle tekens te tellen, met uitzondering van UNICODE-besturingselementtekens (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 documenten , of groter maken tags properties/desired dan de properties/reported limiet.

Metagegevens van apparaattwee

IoT Hub onderhoudt de tijdstempel van de laatste update voor elk JSON-object in de gewenste en gerapporteerde eigenschappen van de apparaat dubbel. De tijdstempels zijn in UTC en gecodeerd in de ISO8601-indeling YYYY-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 op elk niveau bewaard (niet alleen de bladeren van de JSON-structuur) om updates te behouden die objectsleutels verwijderen.

Optimistische gelijktijdigheid

Tags, gewenste en gerapporteerde eigenschappen bieden allemaal ondersteuning voor optimistische gelijktijdigheid. Tags hebben een ETag, volgens RFC7232,die de JSON-weergave van de tag vertegenwoordigt. U kunt ETags gebruiken in voorwaardelijke updatebewerkingen vanuit de back-end van de oplossing om consistentie te garanderen.

De gewenste en gerapporteerde eigenschappen van de apparaat dubbel hebben geen ETags, maar hebben een waarde die $version 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 observeert) de resultaten van een op te halen bewerking en een updatemelding moet afstemmen. De sectie Stroom voor apparaat opnieuw verbinden biedt meer informatie.

Stroom voor opnieuw verbinden van apparaat

IoT Hub gewenste updatemeldingen voor niet-verbonden apparaten blijven niet behouden. 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 een communicatie tussen updatemeldingen en het volledig ophalen, moet de volgende stroom worden gegarandeerd:

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

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

Notitie

Deze logica is al geïmplementeerd in de SDK's voor Azure IoT-apparaten. Deze beschrijving is alleen nuttig als de apparaat-app geen SDK's voor Azure IoT-apparaten kan gebruiken en de MQTT-interface rechtstreeks moet programmeren.

Aanvullend referentiemateriaal

Andere naslagonderwerpen in de IoT Hub ontwikkelaarshandleiding zijn onder andere:

  • In IoT Hub eindpunten worden de verschillende eindpunten beschreven die door elke IoT-hub worden beschreven voor run-time- en beheerbewerkingen.

  • In het artikel Beperking en quota worden de quota beschreven die van toepassing zijn op de IoT Hub-service en het beperkingsgedrag dat u kunt verwachten wanneer u de service gebruikt.

  • In het artikel Azure IoT Device and Service SDK's vindt u de verschillende taal-SDK's die u kunt gebruiken bij het ontwikkelen van apparaat- en service-apps die communiceren met IoT Hub.

  • Het artikel IoT Hub querytaal voor apparaattweeling, taken en berichtroutering beschrijft de IoT Hub-querytaal die u kunt gebruiken om informatie op te halen uit IoT Hub over uw apparaattweelingen en taken.

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

Volgende stappen

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

Als u enkele van de concepten wilt uitproberen die in dit artikel worden beschreven, bekijkt u de IoT Hub zelfstudies: