Förstå och använda modultvillingar i IoT Hub
Den här artikeln förutsätter att du har läst Förstå och använda enhetstvillingar i IoT Hub först. Under varje enhetsidentitet i IoT Hub kan du skapa upp till 50 modulidentiteter. Varje modulidentitet genererar implicit en modultvilling. På samma sätt som enhetstvillingar är modultvillingar JSON-dokument som lagrar information om modultillstånd, inklusive metadata, konfigurationer och villkor. Azure IoT Hub har en modultvilling för varje modul som du ansluter till IoT Hub.
På enhetssidan gör IoT Hub-enhets-SDK:er att du kan skapa moduler där var och en öppnar en oberoende anslutning till IoT Hub. Med den här funktionen kan du använda separata namnområden för olika komponenter på enheten. Du har till exempel en varuautomat som har tre olika sensorer. Varje sensor styrs av olika avdelningar i ditt företag. Du kan skapa en modul för varje sensor. På så sätt kan varje avdelning bara skicka jobb eller direkta metoder till sensorn som de kontrollerar, vilket undviker konflikter och användarfel.
Modulidentitet och modultvilling har samma funktioner som enhetsidentitet och enhetstvilling, men med en finare kornighet. Den här finare kornigheten gör det möjligt för kompatibla enheter, till exempel operativsystembaserade enheter eller enheter med inbyggd programvara som hanterar flera komponenter, att isolera konfiguration och villkor för var och en av dessa komponenter. Modulidentitet och modultvillingar ger en hanteringsavgränsning av problem när du arbetar med IoT-enheter som har modulära programvarukomponenter. Vi strävar efter att stödja alla enhetstvillingfunktioner på modultvillingnivå efter modultvillingens allmänna tillgänglighet.
Kommentar
De funktioner som beskrivs i den här artikeln är endast tillgängliga på standardnivån för IoT Hub. Mer information om de grundläggande och standard-/kostnadsfria IoT Hub-nivåerna finns i Välj rätt IoT Hub-nivå för din lösning.
I den här artikeln beskrivs:
- Strukturen för modultvillingen: taggar, önskade och rapporterade egenskaper.
- De åtgärder som modulerna och serverdelarna kan utföra på modultvillingar.
Information om hur du använder rapporterade egenskaper, meddelanden från enhet till moln eller filuppladdning finns i Vägledning för kommunikation från enhet till moln.
Mer information om hur du använder önskade egenskaper, direkta metoder eller meddelanden från moln till enhet finns i vägledningen för kommunikation från moln till enhet.
Modultvillingar
Modultvillingar lagrar modulrelaterad information som:
Moduler på enheten och IoT Hub kan användas för att synkronisera modulvillkor och konfiguration.
Lösningens serverdel kan användas för att fråga efter och rikta långvariga åtgärder.
Livscykeln för en modultvilling är länkad till motsvarande modulidentitet. Modultvillingar skapas och tas bort implicit när en modulidentitet skapas eller tas bort i IoT Hub.
En modultvilling är ett JSON-dokument som innehåller:
Taggar. Ett avsnitt i JSON-dokumentet som lösningens serverdel kan läsa från och skriva till. Taggar visas inte för moduler på enheten. Taggar anges för frågesyfte.
Önskade egenskaper. Används tillsammans med rapporterade egenskaper för att synkronisera modulkonfiguration eller -villkor. Lösningens serverdel kan ange önskade egenskaper och modulappen kan läsa dem. Modulappen kan också ta emot meddelanden om ändringar i önskade egenskaper.
Rapporterade egenskaper. Används tillsammans med önskade egenskaper för att synkronisera modulkonfiguration eller villkor. Modulappen kan ange rapporterade egenskaper och lösningens serverdel kan läsa och köra frågor mot dem.
Egenskaper för modulidentitet. Roten för JSON-dokumentet för modultvillingen innehåller skrivskyddade egenskaper från motsvarande modulidentitet som lagras i identitetsregistret.
I följande exempel visas ett JSON-dokument för modultvillingar:
{
"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
}
}
}
I rotobjektet finns egenskaperna för modulidentitet och containerobjekt för tags och både reported och desired egenskaper. Containern properties innehåller några skrivskyddade element ($metadata och $version) som beskrivs i avsnitten Modultvillingmetadata och Optimistisk samtidighet.
Exempel på rapporterad egenskap
I föregående exempel innehåller modultvillingen en batteryLevel egenskap som rapporteras av modulappen. Den här egenskapen gör det möjligt att köra frågor mot och arbeta med moduler baserat på den senaste rapporterade batterinivån. Andra exempel är modulappens rapporteringsmodulfunktioner eller anslutningsalternativ.
Kommentar
Rapporterade egenskaper förenklar scenarier där lösningens serverdel är intresserad av det senaste kända värdet för en egenskap. Använd meddelanden från enhet till moln om lösningens serverdel behöver bearbeta modultelemetri i form av sekvenser av tidsstämplade händelser, till exempel tidsserier.
Exempel på önskad egenskap
I föregående exempel används de telemetryConfig önskade och rapporterade egenskaperna för modultvillingen av lösningens serverdel och modulappen för att synkronisera telemetrikonfigurationen för den här modulen. Till exempel:
Lösningens serverdel anger önskad egenskap med önskat konfigurationsvärde. Här är delen av dokumentet med önskad egenskapsuppsättning:
... "desired": { "telemetryConfig": { "sendFrequency": "5m" }, ... }, ...Modulappen meddelas om ändringen omedelbart om modulen är ansluten. Om den inte är ansluten följer modulappen modulens återanslutningsflöde när den ansluter. Modulappen rapporterar sedan den uppdaterade konfigurationen (eller ett feltillstånd med hjälp av
statusegenskapen). Här är den del av de rapporterade egenskaperna:"reported": { "telemetryConfig": { "sendFrequency": "5m", "status": "success" } ... }Lösningens serverdel kan spåra resultatet av konfigurationsåtgärden i många moduler genom att fråga modultvillingar .
Kommentar
Föregående kodfragment är exempel, optimerade för läsbarhet, på ett sätt att koda en modulkonfiguration och dess status. IoT Hub har inget specifikt schema för modultvillingens önskade och rapporterade egenskaper i modultvillingarna.
Viktigt!
IoT Plug and Play definierar ett schema som använder flera ytterligare egenskaper för att synkronisera ändringar till önskade och rapporterade egenskaper. Om din lösning använder IoT Plug and Play måste du följa Plug and Play-konventionerna när du uppdaterar tvillingegenskaperna. Mer information och ett exempel finns i Skrivbara egenskaper i IoT Plug and Play.
Backend-åtgärder
Lösningens serverdel fungerar på modultvillingen med hjälp av följande atomiska åtgärder som exponeras via HTTPS:
Hämta modultvillingen efter ID. Den här åtgärden returnerar modultvillingdokumentet, inklusive taggar och önskade och rapporterade systemegenskaper.
Uppdatera delvis modultvillingen. Med den här åtgärden kan lösningens serverdel delvis uppdatera taggarna eller önskade egenskaper i en modultvilling. Den partiella uppdateringen uttrycks som ett JSON-dokument som lägger till eller uppdaterar en egenskap. Egenskaper som anges till
nulltas bort. I följande exempel skapas en ny önskad egenskap med värdet{"newProperty": "newValue"}, skriver över det befintliga värdetexistingPropertyför med"otherNewValue"och tar bortotherOldProperty. Inga andra ändringar görs i befintliga önskade egenskaper eller taggar:{ "properties": { "desired": { "newProperty": { "nestedProperty": "newValue" }, "existingProperty": "otherNewValue", "otherOldProperty": null } } }Ersätt önskade egenskaper. Med den här åtgärden kan lösningens serverdel helt skriva över alla befintliga önskade egenskaper och ersätta ett nytt JSON-dokument med
properties/desired.Ersätt taggar. Med den här åtgärden kan lösningens serverdel helt skriva över alla befintliga taggar och ersätta ett nytt JSON-dokument med
tags.Ta emot tvillingaviseringar. Med den här åtgärden kan lösningens serverdel meddelas när tvillingen ändras. För att göra det måste din IoT-lösning skapa en väg och ange datakällan lika med twinChangeEvents. Som standard finns det ingen sådan väg, så inga tvillingaviseringar skickas. Om ändringshastigheten är för hög eller av andra orsaker, till exempel interna fel, kan IoT Hub bara skicka ett meddelande som innehåller alla ändringar. Om ditt program behöver tillförlitlig granskning och loggning av alla mellanliggande tillstånd bör du därför använda meddelanden från enhet till moln. Mer information om egenskaper och brödtext som returneras i tvillingmeddelandet finns i Händelsescheman som inte är telemetri.
Alla föregående åtgärder stöder optimistisk samtidighet och kräver behörigheten Tjänst Anslut enligt definitionen i artikeln Kontrollera åtkomst till IoT Hub.
Utöver dessa åtgärder kan lösningens serverdel köra frågor mot modultvillingarna med hjälp av SQL-liknande IoT Hub-frågespråk.
Modulåtgärder
Modulappen körs på modultvillingen med hjälp av följande atomiska åtgärder:
Hämta modultvilling. Den här åtgärden returnerar modultvillingdokumentet (inklusive önskade och rapporterade systemegenskaper) för den för närvarande anslutna modulen.
Uppdatera delvis rapporterade egenskaper. Den här åtgärden möjliggör partiell uppdatering av de rapporterade egenskaperna för den för närvarande anslutna modulen. Den här åtgärden använder samma JSON-uppdateringsformat som lösningens serverdel använder för en partiell uppdatering av önskade egenskaper.
Observera önskade egenskaper. Den för närvarande anslutna modulen kan välja att meddelas om uppdateringar av önskade egenskaper när de inträffar. Modulen får samma form av uppdatering (partiell eller fullständig ersättning) som körs av lösningens serverdel.
Alla föregående åtgärder kräver behörigheten Enhet Anslut enligt definitionen i artikeln Kontrollera åtkomst till IoT Hub.
Azure IoT-enhets-SDK:er gör det enkelt att använda föregående åtgärder från många språk och plattformar.
Format för taggar och egenskaper
Taggar, önskade egenskaper och rapporterade egenskaper är JSON-objekt med följande begränsningar:
Nycklar: Alla nycklar i JSON-objekt är UTF-8-kodade, skiftlägeskänsliga och upp till 1 KB långa. Tillåtna tecken exkluderar UNICODE-kontrolltecken (segmenten C0 och C1), och
.,$och SP.Värden: Alla värden i JSON-objekt kan vara av följande JSON-typer: booleskt värde, tal, sträng, objekt. Matriser stöds också.
Heltal kan ha ett minsta värde på -4503599627370496 och ett maximalt värde på 4503599627370495.
Strängvärden är UTF-8-kodade och kan ha en maximal längd på 4 KB.
Djup: Det maximala djupet för JSON-objekt i taggar, önskade egenskaper och rapporterade egenskaper är 10. Följande objekt är till exempel giltigt:
{ ... "tags": { "one": { "two": { "three": { "four": { "five": { "six": { "seven": { "eight": { "nine": { "ten": { "property": "value" } } } } } } } } } } }, ... }
Storlek på modultvilling
IoT Hub tillämpar en storleksgräns på 8 KB på värdet för tags, och en storleksgräns på 32 KB vardera på värdet properties/desired för och properties/reported. Dessa summor är uteslutande för skrivskyddade element som $version och $metadata/$lastUpdated.
Tvillingstorleken beräknas på följande sätt:
För varje egenskap i JSON-dokumentet beräknar IoT Hub kumulativt och lägger till längden på egenskapens nyckel och värde.
Egenskapsnycklar betraktas som UTF8-kodade strängar.
Enkla egenskapsvärden betraktas som UTF8-kodade strängar, numeriska värden (8 byte) eller booleska värden (4 byte).
Storleken på UTF8-kodade strängar beräknas genom att alla tecken räknas, exklusive UNICODE-kontrolltecken (segmenten C0 och C1).
Komplexa egenskapsvärden (kapslade objekt) beräknas baserat på den aggregerade storleken på de egenskapsnycklar och egenskapsvärden som de innehåller.
IoT Hub avvisar med ett fel alla åtgärder som skulle öka storleken på dessa dokument över gränsen.
Metadata för modultvillingar
IoT Hub underhåller tidsstämpeln för den senaste uppdateringen för varje JSON-objekt i önskade och rapporterade egenskaper för modultvillingar. Tidsstämplarna är i UTC och kodade i ISO8601 format YYYY-MM-DDTHH:MM:SS.mmmZ.
Till exempel:
{
...
"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
}
}
...
}
Den här informationen sparas på alla nivåer (inte bara bladen i JSON-strukturen) för att bevara uppdateringar som tar bort objektnycklar.
Optimistisk samtidighet
Taggar, önskade egenskaper och rapporterade egenskaper stöder alla optimistisk samtidighet. Om du behöver garantera ordningen på uppdateringar av tvillingegenskaper kan du överväga att implementera synkronisering på programnivå genom att vänta på återanrop av rapporterade egenskaper innan du skickar nästa uppdatering.
Modultvillingar har en ETag (etag -egenskap), enligt RFC7232, som representerar tvillingens JSON-representation. Du kan använda etag egenskapen i villkorsstyrda uppdateringsåtgärder från lösningens serverdel för att säkerställa konsekvens. Det här är det enda alternativet för att säkerställa konsekvens i åtgärder som omfattar containern tags .
Modultvillingens önskade och rapporterade egenskaper har också ett $version värde som garanterat är inkrementellt. På samma sätt som en ETag kan versionen användas av uppdateringsparten för att framtvinga konsekvens för uppdateringar. Till exempel en modulapp för en rapporterad egenskap eller lösningens serverdel för en önskad egenskap.
Versioner är också användbara när en observationsagent (till exempel modulappen som observerar önskade egenskaper) måste stämma av lopp mellan resultatet av en hämtningsåtgärd och ett uppdateringsmeddelande. Avsnittet Modulåteranslutningsflöde innehåller mer information.
Återanslutningsflöde för modul
IoT Hub bevarar inte önskade egenskapsuppdateringsmeddelanden för frånkopplade moduler. Härav följer att en modul som ansluter måste hämta dokumentet med fullständiga önskade egenskaper, förutom att prenumerera på uppdateringsmeddelanden. Med tanke på risken för raser mellan uppdateringsmeddelanden och fullständig hämtning måste följande flöde säkerställas:
- Modulappen ansluter till en IoT-hubb.
- Modulappen prenumererar på uppdateringar av önskade egenskaper.
- Modulappen hämtar det fullständiga dokumentet för önskade egenskaper.
Modulappen kan ignorera alla meddelanden med mindre eller lika med $version versionen av det fullständiga hämtade dokumentet. Den här metoden är möjlig eftersom IoT Hub garanterar att versionerna alltid ökar.
Nästa steg
Om du vill prova några av de begrepp som beskrivs i den här artikeln kan du läsa följande självstudier för IoT Hub: