Not
Åtkomst till den här sidan kräver auktorisering. Du kan prova att logga in eller ändra kataloger.
Åtkomst till den här sidan kräver auktorisering. Du kan prova att ändra kataloger.
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.
Anteckning
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å och storlek 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 enhetsprogram och lösningens serverdel 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 backend-appar. Till exempel när en serverdelsapp 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:
Appar för enheter och bakgrundsappar kan användas för att synkronisera enhetsstatus och konfigureringar.
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 backend-appar 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. Serverdelsappar 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 serverdelsappar kan läsa och ställa frågor till 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. Egenskaperna
connectionStateUpdatedTimeochgenerationIdingår inte.
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 Enhetstvillingmetadata och Optimistisk samtidighet.
Exempel på rapporterad egenskap
I föregående exempel innehåller enhetstvillingen (device twin) en batteryLevel rapporterad egenskap. Den här egenskapen gör det möjligt att ställa frågor till och arbeta med enheter baserat på den senaste rapporterade batterinivån. Andra exempel är enhetsappen som rapporterar enhetsfunktioner eller anslutningsalternativ.
Anteckning
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 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 backend och enhetsappen för att synkronisera telemetrikonfigurationen för den här enheten. 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" }, ... },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" } ... }En backend-applikation spårar resultatet från konfigurationsåtgärden på många enheter genom att göra förfrågningar till 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 med ID. Den här operationen returnerar enhetstvillingens dokument, inklusive taggar och önskade och rapporterade systemegenskaper.
Delvis uppdatering av device twin. Den här åtgärden uppdaterar delvis 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. 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 ta emot meddelanden om enhetstvillingändringar 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 innehåll som returneras i tvillingsmeddelandet finns i Händelsescheman för icke-telemetri.
Alla föregående åtgärder stöder optimistisk samtidighet och kräver ServiceConnect-behörigheten enligt definitionen i Kontrollera åtkomst till IoT Hub.
Utöver dessa åtgärder kan lösningens serverdel:
Utför en förfrågan om 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å device twin med följande atomära operationer:
Hämta enhetstvillingar. Den här åtgärden returnerar tvillingdokument för enheten (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.
Observera önskade egenskaper. Den anslutna enheten 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 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.Anteckning
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" } } } } } } } } } } }, ... }
Storlek på enhetstvilling
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 exkluderar 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å tagsdokumenten , properties/desiredeller properties/reported över gränsen.
Metadata för enhetstvillingar
IoT Hub bibehåller tidsstämpeln för den senaste uppdateringen för varje JSON-objekt i enhetstvillingens önskade och rapporterade egenskaper. 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 konkurrens
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 med en ETag kan du använda versionsegenskapen för att säkerställa konsekvens vid uppdateringar. Till exempel en app för enhet för en rapporterad parameter eller en backend-app för en önskad parameter.
Versioner är också användbara när en observerande agent (till exempel enhetsappen som övervakar önskade egenskaper) måste stämma av konkurrenssituationer 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 kapplöpningar mellan uppdateringsmeddelanden och fullständig hämtning av data 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: