Module twins begrijpen en gebruiken in IoT Hub

In IoT Hub kunt u onder elke apparaat-id maximaal 50 module-id's maken. Elke module-identiteit genereert impliciet een moduledubbelganger. Net als bij apparaatdubbels zijn moduledubbels JSON-documenten die modulestatusinformatie opslaan, waaronder metagegevens, configuraties en voorwaarden. Azure IoT Hub onderhoudt een moduletweeling voor elke module die u aansluit op IoT Hub.

In dit artikel wordt ervan uitgegaan dat u eerst Apparaat-tweelingen in IoT Hub begrijpt en gebruikt leest.

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-identiteit en module-tweeling bieden dezelfde mogelijkheden als apparaat-identiteit en apparaat-tweeling, 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 module-tweelingen bieden een beheer van gescheiden verantwoordelijkheden bij het werken met IoT-apparaten met modulaire softwareonderdelen. We streven ernaar alle functionaliteit voor apparaat twins op module twin niveau te ondersteunen bij de algemene beschikbaarheid van module twins.

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

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.

Dubbele modules

Moduletweelingen 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 om query's uit te voeren en langlopende bewerkingen aan te sturen.

De levenscyclus van een module-tweeling is gekoppeld aan de bijbehorende module-identiteit. Module-tweelingen worden impliciet aangemaakt en verwijderd wanneer een module-identiteit wordt aangemaakt 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.

• Module-identiteits eigenschappen. De root van het JSON-document van de moduletweeling bevat de alleen-lezen eigenschappen van de bijbehorende module-identiteit die is opgeslagen in het identiteitsregister.

Het volgende voorbeeld toont een JSON-document van een duplicaat van een module.

{
    "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 Module twin metadata en Optimistic concurrency.

Voorbeeld van gerapporteerde eigenschap

In het vorige voorbeeld bevat de module-tweeling 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.

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 module-tweelingen op te vragen.

Achtergrondprocessen

Back-end-apps werken op de module-tweeling met behulp van de volgende atomische bewerkingen, beschikbaar gesteld via HTTPS.

• Module-tweeling ophalen aan de hand van ID. Deze bewerking retourneert het moduledubbeldocument, inclusief tags en gewenste en gerapporteerde systeemeigenschappen.

• Gedeeltelijk bijwerken module-twin. Met deze bewerking worden de tags en gewenste eigenschappen in een moduletweeling 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 moduletweelingen wilt ontvangen, moet uw IoT-oplossing een route maken en de gegevensbron instellen op 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 de hoofdtekst die worden geretourneerd in het twin meldingsbericht.

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. Arrays 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"
                                               }
                                           }
                                       }
                                   }
                               }
                           }
                       }
                   }
               }
           }
       },
       ...
  }
  

Module tweepersoons maat

IoT Hub legt een limiet van 8 kB op voor de waarde van tags, en een limiet van 32 kB voor elke waarde van properties/desired en properties/reported. Deze totalen zijn exclusief "alleen-lezen" elementen zoals $version en $metadata/$lastUpdated.

Tweepersoonsgrootte wordt als volgt bepaald:

• IoT Hub berekent en voegt cumulatief de lengte van de sleutel en de waarde van elke eigenschap toe.

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

IoT Hub onderhoudt de tijdstempel van de laatste update voor elk JSON-object in de gewenste en gerapporteerde eigenschappen van de module-tweeling. 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.

Optimistisch gelijktijdigheidsbeheer

Tags, gewenste eigenschappen en gerapporteerde eigenschappen ondersteunen optimistische gelijktijdigheid. Als u de volgorde van bijwerkingen van tweelingeigenschappen wilt garanderen, kunt u overwegen synchronisatie op toepassingsniveau te implementeren door te wachten op de terugroepactie van gerapporteerde eigenschappen voordat u de volgende update verzendt.

Tweelingmodules hebben een ETag-eigenschap (etag), volgens RFC7232, die de JSON-weergave van de tweelingmodule 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 module twins hebben ook een $version waarde waarvan gegarandeerd wordt dat deze 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 worden meldingen voor updates van gewenste eigenschappen niet bewaard voor modules die niet verbonden zijn. 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 racevoorwaarden tussen updatemeldingen en volledige gegevensophaling, moet het volgende proces gewaarborgd worden:

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 met $version negeren die minder dan of gelijk zijn 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:

• Aan de slag met IoT Hub module-identiteit en moduletwin met behulp van een .NET-backend en een .NET-apparaat