Förstå och använda modultvillingar i IoT Hub
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.
Den här artikeln förutsätter att du läser Förstå och använda enhetstvillingar i IoT Hub först.
På enhetssidan kan du med SDK:er (IoT Hub Device Software Development Kit) 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. Olika avdelningar i företaget styr varje sensor. Du kan skapa en modul för varje sensor så att en avdelning bara kan skicka jobb eller direktmetoder till sensorn som de styr, 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 enhetsprogram och lösningens serverdel 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 backend-appar 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. Serverdelsappar 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 serverdelsappar 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
}
}
}
På den översta nivån innehåller ett modultvillingobjekt modulidentitetsegenskaper 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 rapporterad egenskap. 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 du är intresserad av det senaste kända värdet för en egenskap. Använd meddelanden från enhet till moln om du vill bearbeta modultelemetri i sekvenser av tidsstämplade händelser, till exempel tidsserier.
Exempel på önskad egenskap
I föregående exempel används modultvillingens telemetryConfig önskade och rapporterade egenskaper av serverdelsapparna och modulappen för att synkronisera telemetrikonfigurationen för den här modulen. Till exempel:
En serverdelsapp 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" } ... }En serverdelsapp 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
Serverdelsappar 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. Den här åtgärden uppdaterar delvis 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. Den här åtgärden skriver helt över alla befintliga önskade egenskaper och ersätter ett nytt JSON-dokument för
properties/desired.Ersätt taggar. Den här åtgärden skriver helt över alla befintliga taggar och ersätter ett nytt JSON-dokument för
tags.Ta emot tvillingaviseringar. Den här åtgärden meddelar när tvillingen ändras. För att få meddelanden om ändring av modultvillingar 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 ServiceConnect-behörigheten enligt definitionen i artikeln Kontrollera åtkomst till IoT Hub.
Utöver dessa åtgärder kan backend-appar 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.
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.
Alla föregående åtgärder kräver behörigheten DeviceConnect 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 tagsför , 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:
IoT Hub beräknar kumulativt och lägger till längden på varje egenskaps 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 egenskapen etag i villkorsstyrda uppdateringsåtgärder från serverdelsappar för att säkerställa konsekvens. Det här alternativet säkerställer konsekvens i åtgärder som involverar containern tags .
Modultvillingens önskade och rapporterade egenskaper har också ett $version värde som garanterat är inkrementellt. På samma sätt som med en ETag kan du använda versionsvärdet för att framtvinga konsekvens för uppdateringar. Till exempel en modulapp för en rapporterad egenskap eller en serverdelsapp 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: