Share via

Moduledubbels begrijpen en gebruiken in IoT Hub

  • Artikel

In dit artikel wordt ervan uitgegaan dat u eerst Apparaatdubbels in IoT Hub hebt gelezen en gebruikt. In IoT Hub kunt u onder elke apparaat-id maximaal 50 module-id's maken. Elke module-id genereert impliciet een moduledubbel. Net als bij apparaatdubbels zijn moduledubbels JSON-documenten die modulestatusinformatie opslaan, waaronder metagegevens, configuraties en voorwaarden. Azure IoT Hub onderhoudt een moduledubbel voor elke module die u verbindt met IoT Hub.

Aan de apparaatzijde kunt u met de SDK's van het IoT Hub-apparaat modules maken waarbij elk apparaat een onafhankelijke verbinding met IoT Hub opent. Met deze functionaliteit kunt u afzonderlijke naamruimten gebruiken voor verschillende onderdelen op uw apparaat. U hebt bijvoorbeeld een verkoopautomaat met drie verschillende sensoren. Elke sensor wordt beheerd door verschillende afdelingen in uw bedrijf. U kunt voor elke sensor een module maken. Op deze manier kan elke afdeling alleen taken of directe methoden verzenden naar de sensor die ze beheren, conflicten en gebruikersfouten voorkomen.

Module-id's en moduledubbels bieden dezelfde mogelijkheden als apparaatidentiteit en apparaatdubbel, maar met een fijnere granulariteit. Dankzij deze fijnere granulariteit kunnen apparaten, zoals apparaten op basis van het besturingssysteem of firmwareapparaten die meerdere onderdelen beheren, configuratie en voorwaarden voor elk van deze onderdelen isoleren. Module-id's en moduledubbels bieden een beheerscheiding van problemen bij het werken met IoT-apparaten met modulaire softwareonderdelen. We streven ernaar alle functionaliteit voor apparaatdubbels op moduledubbelniveau te ondersteunen op moduledubbelniveau door algemene beschikbaarheid van moduledubbels.

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 moduledubbel: tags, gewenste en gerapporteerde eigenschappen.
  • De bewerkingen die de modules en back-ends kunnen uitvoeren op moduledubbels.

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 de richtlijnen voor cloud-naar-apparaatcommunicatie voor hulp bij het gebruik van gewenste eigenschappen, directe methoden of cloud-naar-apparaat-berichten.

Moduledubbels

Moduledubbels slaan modulegerelateerde informatie op die:

  • Modules op het apparaat en IoT Hub kunnen worden gebruikt om modulevoorwaarden 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 moduledubbel is gekoppeld aan de bijbehorende module-id. Modulesdubbels worden impliciet gemaakt en verwijderd wanneer een module-id wordt gemaakt of verwijderd in IoT Hub.

Een moduledubbel 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 modules op het apparaat. Tags worden ingesteld voor het uitvoeren van query's.

  • Gewenste eigenschappen. Wordt samen met gerapporteerde eigenschappen gebruikt om de configuratie of voorwaarden van de module te synchroniseren. De back-end van de oplossing kan gewenste eigenschappen instellen en de module-app kan deze lezen. De module-app kan ook meldingen ontvangen van wijzigingen in de gewenste eigenschappen.

  • Gerapporteerde eigenschappen. Wordt samen met de gewenste eigenschappen gebruikt om de configuratie of voorwaarden van de module te synchroniseren. De module-app kan gerapporteerde eigenschappen instellen en de back-end van de oplossing kan deze lezen en er query's op uitvoeren.

  • Eigenschappen van module-identiteit. De hoofdmap van het JSON-document van de moduledubbel bevat de alleen-lezen eigenschappen van de bijbehorende module-id die is opgeslagen in het identiteitsregister.

Architectural representation of device twin

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

{
    "deviceId": "devA",
    "moduleId": "moduleA",
    "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 module-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 moduledubbelmetagegevens en optimistische gelijktijdigheidssecties .

Voorbeeld van gerapporteerde eigenschap

In het vorige voorbeeld bevat de moduledubbel een batteryLevel eigenschap die wordt gerapporteerd door de module-app. Met deze eigenschap kunt u query's uitvoeren op modules op basis van het laatst gerapporteerde batterijniveau. Andere voorbeelden zijn de mogelijkheden van module-app-rapportagemodules of connectiviteitsopties.

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 modules 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 moduledubbel gebruikt door de back-end van de oplossing en de module-app om de telemetrieconfiguratie voor deze module te synchroniseren. Voorbeeld:

  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 module-app wordt onmiddellijk op de hoogte gesteld van de wijziging als de module is verbonden. Als deze niet is verbonden, volgt de module-app de stroom voor opnieuw verbinden van de module wanneer deze verbinding maakt. De module-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 in veel modules bijhouden door query's uit te voeren op moduledubbels.

Notitie

De voorgaande codefragmenten zijn voorbeelden, geoptimaliseerd voor leesbaarheid, van één manier om een moduleconfiguratie en de status ervan te coderen. IoT Hub legt geen specifiek schema op voor de gewenste en gerapporteerde eigenschappen van de moduledubbel in de moduledubbels.

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.

Back-endbewerkingen

De back-end van de oplossing werkt op de moduledubbel met behulp van de volgende atomische bewerkingen, weergegeven via HTTPS:

  • Moduledubbel ophalen op id. Deze bewerking retourneert het moduledubbeldocument, inclusief tags en gewenste en gerapporteerde systeemeigenschappen.

  • Gedeeltelijk update moduledubbel. Met deze bewerking kan de back-end van de oplossing de tags of gewenste eigenschappen in een moduledubbel 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 existingProperty overschreven met "otherNewValue"en wordt verwijderd otherOldProperty. 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 Gebeurtenisschema's voor niet-telemetrie voor meer informatie over de eigenschappen en hoofdtekst die in het meldingsbericht van de dubbel worden geretourneerd.

Alle voorgaande bewerkingen ondersteunen optimistische gelijktijdigheid en vereisen de machtiging Service Verbinding maken, zoals gedefinieerd in het artikel Toegang tot beheer tot IoT Hub.

Naast deze bewerkingen kan de back-end van de oplossing query's uitvoeren op de moduledubbels met behulp van de SQL-achtige IoT Hub-querytaal.

Modulebewerkingen

De module-app werkt op de moduledubbel met behulp van de volgende atomische bewerkingen:

  • Moduledubbel ophalen. Deze bewerking retourneert het moduledubbeldocument (inclusief de gewenste en gerapporteerde systeemeigenschappen) voor de momenteel verbonden module.

  • Gerapporteerde eigenschappen gedeeltelijk bijwerken. Met deze bewerking kunt u de gedeeltelijke update van de gerapporteerde eigenschappen van de momenteel verbonden module inschakelen. 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. De momenteel verbonden module kan ervoor kiezen om op de hoogte te worden gesteld van updates voor de gewenste eigenschappen wanneer deze plaatsvinden. De module 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 het artikel Beheertoegang tot IoT Hub.

Met de SDK's voor Azure IoT-apparaten kunt u eenvoudig de voorgaande bewerkingen van veel talen en platforms gebruiken.

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.

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

IoT Hub dwingt een limiet van 8 kB af voor de waarde van en een limiet van tags32 kB voor elke grootte properties/desired van 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 deze documenten boven de limiet zouden vergroten.

Metagegevens van moduledubbel

IoT Hub onderhoudt de tijdstempel van de laatste update voor elk JSON-object in de gewenste en gerapporteerde eigenschappen van de moduledubbel. 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": "5m",
                    "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.

Moduledubbels 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 moduledubbels 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 module-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 module-app die de gewenste eigenschappen observeren) races moet afstemmen tussen het resultaat van een ophaalbewerking en een updatemelding. De sectiemodulestroom voor opnieuw verbinden biedt meer informatie.

Stroom voor opnieuw verbinden van module

In IoT Hub blijven de meldingen voor updates van gewenste eigenschappen niet behouden voor niet-verbonden modules. Hier volgt dat een module die 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:

  1. Module-app maakt verbinding met een IoT-hub.
  2. Module-app abonneert zich op updates van gewenste eigenschappen.
  3. Module-app haalt het volledige document op voor de gewenste eigenschappen.

De module-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

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