Förstå och använda enhetstvillingar i IoT Hub
Enhetstvillingar är JSON-dokument som lagrar information om enhetstillstånd, inklusive metadata, konfigurationer och villkor. Azure IoT Hub lagrar en enhetstvilling för varje enhet som du ansluter till IoT Hub.
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 enhetstvillingen: taggar, önskade egenskaper och rapporterade egenskaper.
- De åtgärder som enheten och serverdelsprogram kan utföra på enhetstvillingar.
Använd enhetstvillingar för att:
Lagra enhetsspecifika metadata i molnet. Till exempel platsen för en varuautomat.
Rapportera aktuell tillståndsinformation, till exempel tillgängliga funktioner och villkor från din enhetsapp. Till exempel om en enhet är ansluten till din IoT-hubb via mobilnät eller WiFi.
Synkronisera tillståndet för långvariga arbetsflöden mellan enhetsappen och serverdelsappen. När lösningens serverdel till exempel anger den nya versionen av den inbyggda programvaran som ska installeras, och enhetsappen rapporterar de olika stegen i uppdateringsprocessen.
Fråga efter enhetens metadata, konfiguration eller tillstånd.
Mer 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ägledning för kommunikation från moln till enhet.
Information om hur enhetstvillingar relaterar till enhetsmodellen som används av en Azure IoT Plug and Play-enhet finns i Förstå digitala tvillingar med IoT Plug and Play.
Enhetstvillingar
Enhetstvillingar lagrar enhetsinformation som:
Enhets- och serverdelar kan användas för att synkronisera enhetsförhållanden och konfiguration.
Lösningens serverdel kan användas för att fråga efter och rikta långvariga åtgärder.
Livscykeln för en enhetstvilling är länkad till dess motsvarande enhetsidentitet. Enhetstvillingar skapas och tas bort implicit när en enhetsidentitet skapas eller tas bort i IoT Hub.
En enhetstvilling ä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 enhetsappar.
Önskade egenskaper. Används tillsammans med rapporterade egenskaper för att synkronisera enhetskonfiguration eller -villkor. Lösningens serverdel kan ange önskade egenskaper och enhetsappen kan läsa dem. Enhetsappen kan också ta emot meddelanden om ändringar i önskade egenskaper.
Rapporterade egenskaper. Används tillsammans med önskade egenskaper för att synkronisera enhetskonfiguration eller -villkor. Enhetsappen kan ange rapporterade egenskaper och lösningens serverdel kan läsa och köra frågor mot dem.
Egenskaper för enhetsidentitet. Roten för JSON-dokumentet för enhetstvillingen innehåller skrivskyddade egenskaper från motsvarande enhetsidentitet som lagras i identitetsregistret. Egenskaper
connectionStateUpdatedTimeochgenerationIdkommer inte att inkluderas.
I följande exempel visas ett JSON-dokument för enhetstvillingar:
{
"deviceId": "devA",
"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
}
}
}
Rotobjektet innehåller enhetens identitetsegenskaper 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 Enhetstvillingmetametadata och Optimistisk samtidighet.
Exempel på rapporterad egenskap
I föregående exempel innehåller enhetstvillingen en batteryLevel egenskap som rapporteras av enhetsappen. Den här egenskapen gör det möjligt att köra frågor mot och arbeta på enheter baserat på den senaste rapporterade batterinivån. Andra exempel är enhetsappen som rapporterar enhetsfunktioner 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 enhetstelemetri 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 enhetstvillingen av lösningens serverdel och enhetsappen för att synkronisera telemetrikonfigurationen för den här enheten. 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" }, ... },Enhetsappen meddelas om ändringen omedelbart om enheten är ansluten. Om den inte är ansluten följer enhetsappen enhetens återanslutningsflöde när den ansluter. Enhetsappen 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 spårar resultatet av konfigurationsåtgärden på många enheter genom att fråga enhetstvillingar .
Kommentar
Föregående kodfragment är exempel, optimerade för läsbarhet, på ett sätt att koda en enhetskonfiguration och dess status. IoT Hub tillämpar inte något specifikt schema för den önskade enhetstvillingen och rapporterade egenskaper i enhetstvillingarna.
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.
Du kan använda tvillingar för att synkronisera långvariga åtgärder, till exempel uppdateringar av inbyggd programvara. Mer information om hur du använder egenskaper för att synkronisera och spåra en tidskrävande åtgärd mellan enheter finns i Använda önskade egenskaper för att konfigurera enheter.
Backend-åtgärder
Lösningens serverdel fungerar på enhetstvillingen med hjälp av följande atomiska åtgärder som exponeras via HTTPS:
Hämta enhetstvillingen efter ID. Den här åtgärden returnerar enhetstvillingdokumentet, inklusive taggar och önskade och rapporterade systemegenskaper.
Uppdatera enhetstvillingen delvis. Med den här åtgärden kan lösningens serverdel delvis uppdatera taggarna eller önskade egenskaper i en enhetstvilling. 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 för icke-telemetri.
Alla föregående åtgärder stöder optimistisk samtidighet och kräver behörigheten Tjänst Anslut enligt definitionen i Kontrollera åtkomst till IoT Hub.
Utöver dessa åtgärder kan lösningens serverdel:
Fråga enhetstvillingarna med det SQL-liknande IoT Hub-frågespråket.
Utför åtgärder på stora uppsättningar enhetstvillingar med hjälp av jobb.
Enhetsåtgärder
Enhetsappen körs på enhetstvillingen med följande atomiska åtgärder:
Hämta enhetstvilling. Den här åtgärden returnerar enhetstvillingdokumentet (inklusive önskade och rapporterade systemegenskaper) för den anslutna enheten. (Taggar visas inte för enhetsappar.)
Uppdatera delvis rapporterade egenskaper. Den här åtgärden möjliggör partiell uppdatering av de rapporterade egenskaperna för den anslutna enheten. 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 anslutna enheten kan välja att meddelas om uppdateringar av önskade egenskaper när de inträffar. Enheten 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 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. Mer information om IoT Hub-primitiver för synkronisering av önskade egenskaper finns i Flödet för återanslutning av enheter.
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.Kommentar
IoT Hub-frågor som används i Meddelanderoutning stöder inte blanksteg eller något av följande tecken som en del av ett nyckelnamn:
()<>@,;:\"/?={}.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" } } } } } } } } } } }, ... }
Enhetstvillingstorlek
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:
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å tagsdokumenten , properties/desiredeller properties/reported över gränsen.
Metadata för enhetstvillingar
IoT Hub underhåller tidsstämpeln för den senaste uppdateringen för varje JSON-objekt i önskade och rapporterade egenskaper för enhetstvillingar. 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": {
"$lastUpdated": "2016-03-31T16:35:48.789Z"
},
"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.
Enhetstvillingar har en ETag-egenskap etag, 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. Den här egenskapen är det enda alternativet för att säkerställa konsekvens i åtgärder som omfattar containern tags .
Enhetstvillingens ö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 enhetsapp för en rapporterad egenskap eller lösningens serverdel för en önskad egenskap.
Versioner är också användbara när en observerande agent (till exempel enhetsappen som observerar önskade egenskaper) måste stämma av tävlingar mellan resultatet av en hämtningsåtgärd och ett uppdateringsmeddelande. Avsnittet Flöde för återanslutning av enhet innehåller mer information.
Flöde för återanslutning av enhet
IoT Hub bevarar inte önskade egenskapsuppdateringsmeddelanden för frånkopplade enheter. Härav följer att en enhet 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:
- Enhetsappen ansluter till en IoT-hubb.
- Enhetsappen prenumererar på uppdateringar av önskade egenskaper.
- Enhetsappen hämtar det fullständiga dokumentet för önskade egenskaper.
Enhetsappen 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 IoT Hub-artiklar: