Delen via

Moduledubbels begrijpen en gebruiken in IoT Hub

  • Artikel

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.

In dit artikel wordt ervan uitgegaan dat u eerst Apparaatdubbels in IoT Hub leest en gebruikt.

Aan de apparaatzijde kunt u met de Sdk's (Software Development Kits) voor IoT Hub-apparaten 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. Verschillende afdelingen in uw bedrijf beheren elke sensor. U kunt voor elke sensor een module maken, zodat een afdeling alleen taken of directe methoden kan verzenden naar de sensor die ze beheren, waardoor conflicten en gebruikersfouten worden 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 apparaattoepassingen en de back-end van de oplossing 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 back-end-apps kunnen 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. Back-end-apps kunnen 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 back-end-apps kunnen 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.

Architectuurweergave van apparaatdubbel

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

Op het hoogste niveau bevat een moduledubbelobject 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 gerapporteerde eigenschap. 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 u geïnteresseerd bent in de laatst bekende waarde van een eigenschap. Gebruik apparaat-naar-cloud-berichten als u moduletelemetrie wilt verwerken in 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-apps en de module-app om de telemetrieconfiguratie voor deze module te synchroniseren. Voorbeeld:

  1. Een back-end-app 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. Een back-end-app 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

Back-end-apps werken op de moduledubbel met behulp van de volgende atomische bewerkingen, beschikbaar via HTTPS:

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

  • Gedeeltelijk update moduledubbel. Met deze bewerking worden de tags of gewenste eigenschappen in een moduledubbel gedeeltelijk bijgewerkt. 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 worden alle bestaande gewenste eigenschappen volledig overschreven en wordt een nieuw JSON-document vervangen door properties/desired.

  • Tags vervangen. Met deze bewerking worden alle bestaande tags volledig overschreven en wordt een nieuw JSON-document vervangen door tags.

  • Dubbelmeldingen ontvangen. Deze bewerking meldt wanneer de tweeling wordt gewijzigd. Als u wijzigingsmeldingen voor moduledubbels wilt ontvangen, 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 ServiceConnect-machtiging , zoals gedefinieerd in het artikel Toegang tot beheer tot IoT Hub .

Naast deze bewerkingen kunnen back-end-apps 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.

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

Voor alle voorgaande bewerkingen is de machtiging DeviceConnect vereist, zoals gedefinieerd in het artikel Toegang tot beheer 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 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:

  • IoT Hub berekent cumulatief de lengte van de sleutel en waarde van elke 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 in voorwaardelijke updatebewerkingen van back-end-apps gebruiken om consistentie te garanderen. Deze optie zorgt voor 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 kunt u de versiewaarde gebruiken om consistentie van updates af te dwingen. Bijvoorbeeld een module-app voor een gerapporteerde eigenschap of een back-end-app 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: