Opis bliźniaczych reprezentacji modułów i korzystanie z nich w usłudze IoT Hub
W usłudze IoT Hub w ramach każdej tożsamości urządzenia można utworzyć maksymalnie 50 tożsamości modułów. Każda tożsamość modułu niejawnie generuje bliźniacze reprezentacje modułu. 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. Usługa Azure IoT Hub utrzymuje bliźniacze reprezentacje modułu dla każdego modułu, który łączy się z usługą IoT Hub.
W tym artykule założono, że najpierw przeczytasz artykuł Understand and use device twins in IoT Hub (Informacje i używanie bliźniaczych reprezentacji urządzeń w usłudze IoT Hub ).
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.
Tożsamość modułu i bliźniacza reprezentacja modułu zapewniają takie same możliwości jak tożsamość urządzenia i bliźniacza reprezentacja urządzenia, ale w bardziej szczegółowym poziomie. Ten bardziej szczegółowy stopień szczegółowości umożliwia urządzeniom obsługującym obsługę, takim jak urządzenia oparte na systemie operacyjnym lub urządzenia układowe, które zarządzają wieloma składnikami, w celu odizolowania konfiguracji i warunków dla każdego z tych składników. Tożsamość modułu i bliźniacze reprezentacje modułów zapewniają rozdzielenie problemów związanych z zarządzaniem podczas pracy z urządzeniami IoT, które mają modułowe składniki oprogramowania. Dążymy do obsługi wszystkich funkcji bliźniaczej reprezentacji urządzenia na poziomie bliźniaczej reprezentacji modułu według ogólnej dostępności bliźniaczej reprezentacji modułu.
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 usługi IoT Hub dla rozwiązania.
W tym artykule opisano:
- Struktura bliźniaczej reprezentacji modułu: tagi, żądane i zgłoszone właściwości.
- Operacje, które aplikacje urządzenia i zaplecze rozwiązania mogą wykonywać na bliźniaczych reprezentacjach modułów.
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.
Bliźniacze reprezentacje modułów
Bliźniacze reprezentacje modułu przechowują informacje dotyczące modułu, które:
Moduły na urządzeniu i w usłudze IoT Hub mogą używać do synchronizowania warunków i konfiguracji modułów.
Zaplecze rozwiązania może służyć do wykonywania zapytań i docelowych długotrwałych operacji.
Cykl życia bliźniaczej reprezentacji modułu jest połączony z odpowiednią tożsamością modułu. Bliźniacze reprezentacje modułów są niejawnie tworzone i usuwane po utworzeniu lub usunięciu tożsamości modułu w usłudze IoT Hub.
Bliźniacza reprezentacja modułu to dokument JSON, który obejmuje:
Tagi. 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.
Właściwości tożsamości modułu. Katalog główny dokumentu JSON bliźniaczej reprezentacji modułu zawiera właściwości tylko do odczytu z odpowiedniej tożsamości modułu przechowywanej w rejestrze tożsamości.
Poniższy przykład przedstawia dokument JSON bliźniaczej reprezentacji modułu:
{
"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
}
}
}
Na najwyższym poziomie obiekt bliźniaczej reprezentacji modułu zawiera właściwości tożsamości modułu i obiekty kontenera zarówno dla tags , jak reported i właściwości desired . Kontener properties zawiera niektóre elementy tylko do odczytu ($metadata i $version) opisane w sekcjach Metadane bliźniaczej reprezentacji modułu i Optymistyczna współbieżność .
Przykład zgłaszanej właściwości
W poprzednim przykładzie bliźniacze reprezentacje modułu zawierają zgłoszoną batteryLevel właściwość. 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 modułu 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 komunikatów urządzenie-chmura, jeśli chcesz przetwarzać dane telemetryczne modułu w sekwencjach zdarzeń sygnatur czasowych, takich jak szeregi czasowe.
Przykład żądanej właściwości
W poprzednim przykładzie telemetryConfig żądane i zgłoszone właściwości bliźniaczej reprezentacji modułu są używane przez aplikacje zaplecza i aplikację modułu do synchronizowania konfiguracji telemetrii dla tego modułu. 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. Jeśli nie jest połączony, aplikacja modułu jest zgodna z przepływem ponownego łączenia modułu podczas nawiązywania połączenia. Następnie aplikacja modułu zgłasza zaktualizowaną konfigurację (lub warunek błędu
statusprzy użyciu właściwości). Oto część zgłoszonych właściwości:"reported": { "telemetryConfig": { "sendFrequency": "5m", "status": "success" } ... }Aplikacja zaplecza może śledzić wyniki operacji konfiguracji w wielu modułach, wysyłając zapytanie do bliźniaczych reprezentacji modułów.
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. Usługa IoT Hub nie nakłada określonego schematu dla żądanej reprezentacji modułu i zgłoszonych właściwości w bliźniaczych reprezentacjach modułu.
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. Aby uzyskać więcej informacji i przykład, zobacz Właściwości z możliwością zapisu w usłudze IoT Plug and Play.
Operacje zaplecza
Aplikacje zaplecza działają na bliźniaczej reprezentacji modułu przy użyciu następujących operacji niepodzielnych uwidocznionych za pośrednictwem protokołu HTTPS:
Pobieranie bliźniaczej reprezentacji modułu według identyfikatora. Ta operacja zwraca dokument bliźniaczej reprezentacji modułu, w tym tagi i żądane i zgłaszane właściwości systemu.
Częściowo zaktualizuj bliźniacze reprezentacje modułu. Ta operacja częściowo aktualizuje tagi lub żądane właściwości w bliźniaczej reprezentacji modułu. 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"}, zastępuje istniejącą wartośćexistingPropertyelementu za pomocą"otherNewValue"elementu i usuwaotherOldPropertyelement . Ż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. Ta operacja powiadamia o modyfikacji bliźniaczej reprezentacji. Aby otrzymywać powiadomienia o zmianie bliźniaczej reprezentacji modułu, rozwiązanie IoT musi utworzyć trasę i ustawić źródło danych równe twinChangeEvents. Domyślnie taka trasa nie istnieje, więc żadne powiadomienia bliźniaczej reprezentacji 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. Aby dowiedzieć się więcej o właściwościach i treści zwracanych w komunikacie powiadomienia bliźniaczej reprezentacji, zobacz Schematy zdarzeń nie telemetrii.
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 reprezentacji modułów przy użyciu języka zapytań przypominającego usługę IoT Hub sql.
Operacje modułu
Aplikacja modułu działa na bliźniaczej reprezentacji modułu przy użyciu następujących operacji niepodzielnych:
Pobieranie bliźniaczej reprezentacji modułu. Ta operacja zwraca dokument bliźniaczej reprezentacji modułu (w tym żądane i zgłaszane właściwości systemu) dla aktualnie połączonego modułu.
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.
Obserwowanie żądanych 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, wielkość liter i długość do 1 KB. Dozwolone znaki wykluczają znaki sterujące UNICODE (segmenty C0 i C1) oraz
.,$i SP.Wartości: Wszystkie wartości w obiektach JSON mogą być następującymi typami JSON: wartość logiczna, liczba, ciąg, obiekt. Tablice są również obsługiwane.
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 bliźniaczej reprezentacji modułu
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. Te sumy są wyłącznie elementami tylko do odczytu, takimi jak $version i $metadata/$lastUpdated.
Rozmiar bliźniaczej reprezentacji jest obliczany w następujący sposób:
Usługa IoT Hub zbiorczo oblicza i dodaje długość klucza i wartości każdej właściwości.
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).
Złożone wartości właściwości (obiekty zagnieżdżone) są obliczane na podstawie zagregowanego rozmiaru kluczy właściwości i wartości właściwości, które zawierają.
Usługa IoT Hub odrzuca błędy wszystkich operacji, które zwiększyłyby rozmiar tych dokumentów powyżej limitu.
Metadane bliźniaczej reprezentacji modułu
Usługa IoT Hub utrzymuje znacznik czasu ostatniej aktualizacji dla każdego obiektu JSON w żądanych i zgłoszonych właściwościach bliźniaczej reprezentacji modułu. Znaczniki czasu są w formacie UTC i zakodowane w formacie YYYY-MM-DDTHH:MM:SS.mmmZISO8601 .
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.
Optymistyczna współbieżność
Tagi, żądane właściwości i zgłoszone właściwości obsługują optymistyczną współbieżność. Jeśli musisz zagwarantować kolejność aktualizacji właściwości bliźniaczej reprezentacji, rozważ zaimplementowanie synchronizacji na poziomie aplikacji przez oczekiwanie na wywołanie zwrotne zgłoszonych właściwości przed wysłaniem następnej aktualizacji.
Bliźniacze reprezentacje modułów mają właściwość ETag (etag zgodnie z RFC7232, która reprezentuje reprezentację JSON reprezentacji bliźniaczej reprezentacji. Możesz użyć etag właściwości w operacjach aktualizacji warunkowej z aplikacji zaplecza, aby zapewnić spójność. Ta opcja zapewnia spójność operacji obejmujących tags kontener.
Żądane i zgłoszone właściwości bliźniaczej reprezentacji modułu mają $version również wartość, która ma być przyrostowa. 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.
Wersje są również przydatne w przypadku obserwowania agenta (takiego jak aplikacja modułu obserwująca żądane właściwości) musi uzgodnić wyścigi między wynikiem operacji pobierania a powiadomieniem o aktualizacji. W sekcji 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:
- Aplikacja modułu łączy się z centrum 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.
Aplikacja modułu może ignorować wszystkie powiadomienia z mniejszą lub równą wersją $version pełnego pobranego dokumentu. 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: