Nuta
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
W usłudze IoT Hub w ramach każdej tożsamości urządzenia można utworzyć maksymalnie 50 tożsamości modułów. Each module identity implicitly generates a module twin. Podobnie jak bliźniacze reprezentacje urządzeń, bliźniacze reprezentacje modułów to dokumenty JSON, które przechowują informacje o stanie modułu, w tym metadane, konfiguracje i warunki. Azure IoT Hub maintains a module twin for each module that you connect to IoT Hub.
This article assumes that you read Understand and use device twins in IoT Hub first.
Po stronie urządzenia zestawy SDK (SOFTWARE Development Kit) usługi IoT Hub umożliwiają tworzenie modułów, w których każde z nich otwiera niezależne połączenie z usługą IoT Hub. Ta funkcja umożliwia używanie oddzielnych przestrzeni nazw dla różnych składników na urządzeniu. Na przykład masz automat z trzema różnymi czujnikami. Różne działy w firmie kontrolują każdy czujnik. Możesz utworzyć moduł dla każdego czujnika, aby dział mógł wysyłać zadania lub metody bezpośrednie do czujnika, który kontroluje, unikając konfliktów i błędów użytkowników.
Module identity and module twin provide the same capabilities as device identity and device twin but at a finer granularity. This finer granularity enables capable devices, such as operating system-based devices or firmware devices managing multiple components, to isolate configuration and conditions for each of those components. Module identity and module twins provide a management separation of concerns when working with IoT devices that have modular software components. We aim at supporting all the device twin functionality at module twin level by module twin general availability.
Uwaga
Funkcje opisane w tym artykule są dostępne tylko w warstwie Standardowa usługi IoT Hub. Aby uzyskać więcej informacji na temat warstw podstawowej i standardowej/bezpłatnej usługi IoT Hub, zobacz Wybieranie odpowiedniej warstwy i rozmiaru usługi IoT Hub dla rozwiązania.
W tym artykule opisano:
- Struktura modułu bliźniaczego: tagi, żądane i zgłoszone właściwości.
- Operacje, które aplikacje urządzeń i zaplecze systemu mogą wykonywać na bliźniaczych modułach.
Zapoznaj się ze wskazówkami dotyczącymi komunikacji urządzenie-chmura, aby uzyskać wskazówki dotyczące używania zgłaszanych właściwości, komunikatów z urządzenia do chmury lub przekazywania plików.
Zapoznaj się ze wskazówkami dotyczącymi komunikacji chmura-urządzenie, aby uzyskać wskazówki dotyczące korzystania z żądanych właściwości, metod bezpośrednich lub komunikatów z chmury do urządzenia.
Module twins
Module twins store module-related information that:
Modules on the device and IoT Hub can use to synchronize module conditions and configuration.
The solution back end can use to query and target long-running operations.
The lifecycle of a module twin is linked to the corresponding module identity. Modules twins are implicitly created and deleted when a module identity is created or deleted in IoT Hub.
Bliźniak modułu to dokument JSON, który zawiera:
Tags. Sekcja dokumentu JSON, do którego aplikacje zaplecza mogą odczytywać i zapisywać dane. Tagi nie są widoczne dla modułów na urządzeniu. Tagi są ustawiane na potrzeby wykonywania zapytań.
Żądane właściwości. Używane wraz z zgłaszanymi właściwościami do synchronizowania konfiguracji lub warunków modułu. Aplikacje zaplecza mogą ustawiać żądane właściwości, a aplikacja modułu może je odczytywać. Aplikacja modułu może również otrzymywać powiadomienia o zmianach we żądanych właściwościach.
Zgłoszone właściwości. Używane wraz z żądanymi właściwościami do synchronizowania konfiguracji lub warunków modułu. Aplikacja modułu może ustawić zgłaszane właściwości, a aplikacje zaplecza mogą je odczytywać i wykonywać względem nich zapytania.
Module identity properties. The root of the module twin JSON document contains the read-only properties from the corresponding module identity stored in the identity registry.
The following example shows a module twin JSON document:
{
"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
}
}
}
At the top level, a module twin object contains the module identity properties and container objects for tags and both reported and desired properties. Kontener properties zawiera niektóre elementy tylko do odczytu ($metadata i $version) opisane w sekcjach Metadane bliźniaka modułu i Optymistyczna współbieżność.
Przykład zgłaszanej właściwości
In the previous example, the module twin contains a batteryLevel reported property. Ta właściwość umożliwia wykonywanie zapytań i działanie modułów na podstawie ostatniego zgłoszonego poziomu baterii. Inne przykłady obejmują możliwości modułu raportowania aplikacji lub opcje łączności.
Uwaga
Zgłoszone właściwości upraszczają scenariusze, w których interesuje Cię ostatnia znana wartość właściwości. Użyj wiadomości urządzenie-chmura, jeśli chcesz przetwarzać dane telemetryczne modułu w sekwencjach zdarzeń oznaczonych znacznikami czasowymi, takich jak ciągi czasowe.
Przykład żądanej właściwości
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. Na przykład:
Aplikacja zaplecza ustawia żądaną właściwość z żądaną wartością konfiguracji. Oto część dokumentu z żądanym zestawem właściwości:
... "desired": { "telemetryConfig": { "sendFrequency": "5m" }, ... }, ...Aplikacja modułu jest powiadamiana o zmianie natychmiast, jeśli moduł jest połączony. If it's not connected, the module app follows the module reconnection flow when it connects. Następnie aplikacja modułu zgłasza zaktualizowaną konfigurację (lub warunek błędu przy użyciu właściwości
status). Oto część zgłoszonych właściwości:"reported": { "telemetryConfig": { "sendFrequency": "5m", "status": "success" } ... }A back-end app can track the results of the configuration operation across many modules, by querying module twins.
Uwaga
Powyższe fragmenty kodu to przykłady, zoptymalizowane pod kątem czytelności, jeden ze sposobów kodowania konfiguracji modułu i jego stanu. IoT Hub does not impose a specific schema for the module twin desired and reported properties in the module twins.
Ważne
Usługa IoT Plug and Play definiuje schemat, który używa kilku dodatkowych właściwości do synchronizowania zmian żądanych i zgłoszonych właściwości. Jeśli rozwiązanie korzysta z technologii IoT Plug and Play, podczas aktualizowania właściwości bliźniaczych należy postępować zgodnie z konwencjami Plug and Play. For more information and an example, see Writable properties in IoT Plug and Play.
Operacje zaplecza
Back-end apps operate on the module twin using the following atomic operations, exposed through HTTPS:
Retrieve module twin by ID. Ta operacja zwraca dokument modułu bliźniaczego, zawierający tagi oraz wymagane i zgłaszane właściwości systemu.
Częściowo zaktualizuj bliźniaczy moduł. Ta operacja częściowo aktualizuje tagi lub żądane właściwości w bliźniaczym module. Aktualizacja częściowa jest wyrażana jako dokument JSON, który dodaje lub aktualizuje dowolną właściwość. Właściwości ustawione na
nullzostaną usunięte. W poniższym przykładzie zostanie utworzona nowa żądana właściwość z wartością{"newProperty": "newValue"}, istniejąca wartośćexistingPropertyzostanie zastąpiona przez"otherNewValue", aotherOldPropertyzostanie usunięta. Żadne inne zmiany nie są wprowadzane do istniejących żądanych właściwości lub tagów:{ "properties": { "desired": { "newProperty": { "nestedProperty": "newValue" }, "existingProperty": "otherNewValue", "otherOldProperty": null } } }Zamień żądane właściwości. Ta operacja całkowicie zastępuje wszystkie istniejące żądane właściwości i zastępuje nowy dokument JSON dla elementu
properties/desired.Zamień tagi. Ta operacja całkowicie zastępuje wszystkie istniejące tagi i zastępuje nowy dokument JSON dla elementu
tags.Odbieranie powiadomień bliźniaczych. 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. Domyślnie taka trasa nie istnieje, więc żadne podwójne powiadomienia nie są wysyłane. Jeśli współczynnik zmian jest zbyt wysoki lub z innych powodów, takich jak awarie wewnętrzne, usługa IoT Hub może wysłać tylko jedno powiadomienie zawierające wszystkie zmiany. W związku z tym, jeśli aplikacja wymaga niezawodnego inspekcji i rejestrowania wszystkich stanów pośrednich, należy użyć komunikatów z urządzenia do chmury. To learn more about the properties and body returned in the twin notification message, see Non-telemetry event schemas.
Wszystkie poprzednie operacje obsługują optymistyczną współbieżność i wymagają uprawnienia ServiceConnect zgodnie z definicją w artykule Kontrola dostępu do usługi IoT Hub .
Oprócz tych operacji aplikacje zaplecza mogą wykonywać zapytania dotyczące bliźniaczych modułów przy użyciu języka zapytań przypominającego SQL IoT Hub.
Operacje modułu
The module app operates on the module twin using the following atomic operations:
Retrieve module twin. This operation returns the module twin document (including desired and reported system properties) for the currently connected module.
Częściowo aktualizuj zgłoszone właściwości. Ta operacja umożliwia częściową aktualizację zgłoszonych właściwości aktualnie połączonego modułu.
Obserwuj pożądane właściwości. Obecnie połączony moduł może otrzymywać powiadomienia o aktualizacjach żądanych właściwości w momencie ich wystąpienia.
Wszystkie poprzednie operacje wymagają uprawnienia DeviceConnect zgodnie z definicją w artykule Kontrola dostępu do usługi IoT Hub.
Zestawy SDK urządzeń Azure IoT ułatwiają korzystanie z poprzednich operacji z wielu języków i platform.
Format tagów i właściwości
Tagi, żądane właściwości i zgłaszane właściwości to obiekty JSON z następującymi ograniczeniami:
Klucze: Wszystkie klucze w obiektach JSON są zakodowane w formacie UTF-8, rozróżniające wielkość liter i mają do 1 KB długości. Allowed characters exclude UNICODE control characters (segments C0 and C1), and
.,$, and SP.Wartości: Wszystkie wartości w obiektach JSON mogą być następującymi typami JSON: wartość logiczna, liczba, ciąg, obiekt. Arrays are also supported.
Liczby całkowite mogą mieć minimalną wartość -4503599627370496 i maksymalną wartość 4503599627370495.
Wartości ciągów są zakodowane w formacie UTF-8 i mogą mieć maksymalną długość 4 KB.
Głębokość: maksymalna głębokość obiektów JSON w tagach, żądanych właściwości i zgłoszonych właściwości wynosi 10. Na przykład następujący obiekt jest prawidłowy:
{ ... "tags": { "one": { "two": { "three": { "four": { "five": { "six": { "seven": { "eight": { "nine": { "ten": { "property": "value" } } } } } } } } } } }, ... }
Rozmiar modułu typu twin
Usługa IoT Hub wymusza limit rozmiaru 8 KB dla wartości tagsi limit rozmiaru 32 KB dla wartości properties/desired i properties/reported. These totals are exclusive of read-only elements like $version and $metadata/$lastUpdated.
Rozmiar łóżka pojedynczego jest obliczany w następujący sposób:
IoT Hub cumulatively computes and adds the length of each property's key and value.
Klucze właściwości są traktowane jako ciągi zakodowane w formacie UTF8.
Proste wartości właściwości są uznawane za ciągi zakodowane w formacie UTF8, wartości liczbowe (8 bajtów) lub wartości logiczne (4 bajty).
Rozmiar ciągów zakodowanych w formacie UTF8 jest obliczany przez zliczanie wszystkich znaków, z wyłączeniem znaków kontrolnych UNICODE (segmenty C0 i C1).
Complex property values (nested objects) are computed based on the aggregate size of the property keys and property values that they contain.
IoT Hub rejects with an error all operations that would increase the size of those documents above the limit.
Module twin metadata
IoT Hub maintains the timestamp of the last update for each JSON object in module twin desired and reported properties. Znaczniki czasu są w formacie UTC i zakodowane w . Na przykład:
{
...
"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
}
}
...
}
Te informacje są przechowywane na każdym poziomie (nie tylko liście struktury JSON), aby zachować aktualizacje, które usuwają klucze obiektów.
Optimistic concurrency
Tags, desired properties, and reported properties all support optimistic concurrency. If you need to guarantee order of twin property updates, consider implementing synchronization at the application level by waiting for reported properties callback before sending the next update.
Module twins have an ETag (etag property), as per RFC7232, that represents the twin's JSON representation. Możesz użyć właściwości etag w operacjach aktualizacji warunkowej z aplikacji serwerowych, aby zapewnić spójność. Ta opcja zapewnia spójność operacji obejmujących tags kontener.
Module twin desired and reported properties also have a $version value that is guaranteed to be incremental. Podobnie jak w przypadku elementu ETag, możesz użyć wartości wersji, aby wymusić spójność aktualizacji. Na przykład aplikacja modułu dla zgłaszanej właściwości lub aplikacji zaplecza dla żądanej właściwości.
Versions are also useful when an observing agent (such as the module app observing the desired properties) must reconcile races between the result of a retrieve operation and an update notification. Sekcja Przepływ ponownego łączenia modułu zawiera więcej informacji.
Przepływ ponownego łączenia modułu
Usługa IoT Hub nie zachowuje żądanych powiadomień o aktualizacji właściwości dla odłączonych modułów. Wynika z tego, że moduł, który nawiązuje połączenie, musi pobrać pełny żądany dokument właściwości, oprócz subskrybowania powiadomień o aktualizacji. Biorąc pod uwagę możliwość wyścigów między powiadomieniami o aktualizacji i pełnym pobieraniem, należy zapewnić następujący przepływ:
- Moduł aplikacji łączy się z IoT hub.
- Aplikacja modułu subskrybuje powiadomienia o aktualizacji żądanych właściwości.
- Aplikacja modułu pobiera pełny dokument dla żądanych właściwości.
The module app can ignore all notifications with $version less or equal than the version of the full retrieved document. Takie podejście jest możliwe, ponieważ usługa IoT Hub gwarantuje, że wersje są zawsze przyrostowe.
Następne kroki
Aby wypróbować niektóre pojęcia opisane w tym artykule, zobacz następujące samouczki dotyczące usługi IoT Hub: