Förstå och använda modultvillingar i IoT Hub

Under varje enhetsidentitet i IoT Hub kan du skapa upp till 50 modulidentiteter. Each module identity implicitly generates a module twin. På samma sätt som enhetstvillingar är modultvillingar JSON-dokument som lagrar information om modultillstånd, inklusive metadata, konfigurationer och villkor. Azure IoT Hub maintains a module twin for each module that you connect to 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.

Module identity and module twin provide the same capabilities as device identity and device twin but at a finer granularity. 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. We aim at supporting all the device twin functionality at module twin level by module twin general availability.

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.

• The solution back end can use to query and target long-running operations.

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.

A module twin is a JSON document that includes:

• Tags. 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 fråga efter dem.

• Egenskaper för modulens identitet. The root of the module twin JSON document contains the read-only properties from the corresponding module identity stored in the identity registry.

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. The properties container contains some read-only elements ($metadata and $version) described in the Module twin metadata and Optimistic concurrency sections.

Exempel på rapporterad egenskap

In the previous example, the module twin contains a batteryLevel reported property. 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.

Exempel på önskad egenskap

In the previous example, the telemetryConfig module twin desired and reported properties are used by the back-end apps and the module app to synchronize the telemetry configuration for this module. Till exempel:

1. En serverdelsapp anger önskad egenskap med önskat konfigurationsvärde. Här är delen av dokumentet med önskad egenskapsuppsättning:

   ...
   "desired": {
       "telemetryConfig": {
           "sendFrequency": "5m"
       },
       ...
   },
   ...
   

2. 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 status egenskapen). Här är den del av de rapporterade egenskaperna:

   "reported": {
       "telemetryConfig": {
           "sendFrequency": "5m",
           "status": "success"
       }
       ...
   }
   

3. A back-end app can track the results of the configuration operation across many modules, by querying module twins.

Backend-åtgärder

Back-end apps operate on the module twin using the following atomic operations, exposed through HTTPS:

• Retrieve module twin by ID. Den här åtgärden returnerar modultvillingdokumentet, inklusive taggar och önskade och rapporterade systemegenskaper.

• Partially update module twin. This operation partially updates the tags or desired properties in a module twin. Den partiella uppdateringen uttrycks som ett JSON-dokument som lägger till eller uppdaterar en egenskap. Egenskaper som anges till null tas bort. I följande exempel skapas en ny önskad egenskap med värdet {"newProperty": "newValue"}, skriver över det befintliga värdet existingProperty för med "otherNewValue"och tar bort otherOldProperty. 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. This operation notifies when the twin is modified. To receive module twin change notifications, your IoT solution needs to create a route and to set the Data Source equal to 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. To learn more about the properties and body returned in the twin notification message, see Non-telemetry event schemas.

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:

• Retrieve module twin. 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"
                                               }
                                           }
                                       }
                                   }
                               }
                           }
                       }
                   }
               }
           }
       },
       ...
  }
  

Module twin size

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. These totals are exclusive of read-only elements like $version and $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 maintains the timestamp of the last update for each JSON object in module twin desired and reported properties. 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.

Optimistic concurrency

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 back-end-appar för att säkerställa konsekvens. Det här alternativet säkerställer konsekvens i åtgärder som involverar containern tags .

Module twin desired and reported properties also have a $version value that is guaranteed to be incremental. På samma sätt som med en ETag kan du använda versionsvärdet för att säkerställa konsekvens vid uppdateringar. Till exempel en modulapp för en rapporterad funktion eller en bakgrundsapp för en önskad funktion.

Versioner är också användbara när en observationsagent, till exempel en modulapp som observerar de önskade egenskaperna, måste hantera konkurrenssituationer 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 kapplöpningar mellan uppdateringsmeddelanden och fullständig inhämtning måste följande flöde säkerställas:

1. Modulappen ansluter till en IoT-hubb.
2. Modulappen prenumererar på uppdateringar av önskade egenskaper.
3. Modulappen hämtar det fullständiga dokumentet för önskade egenskaper.

The module app can ignore all notifications with $version less or equal than the version of the full retrieved document. 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:

• Get started with IoT Hub module identity and module twin using .NET back end and .NET device