Opis bliźniaczych reprezentacji modułów i korzystanie z nich w usłudze IoT Hub
W tym artykule założono, że najpierw przeczytano informacje o bliźniaczych reprezentacjach urządzeń i używaniu ich 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.
Po stronie urządzenia zestawy SDK urządzeń 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. Każdy czujnik jest kontrolowany przez różne działy w firmie. Możesz utworzyć moduł dla każdego czujnika. Dzięki temu każdy dział może wysyłać zadania lub metody bezpośrednie tylko 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 moduły i zaplecza 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 zaplecze rozwiązania może odczytywać dane i zapisywać je. 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. Zaplecze rozwiązania może ustawić żądane właściwości, a aplikacja modułu może je odczytać. 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 zaplecze rozwiązania może 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
}
}
}
W obiekcie głównym znajdują się właściwości tożsamości modułu, a obiekty kontenera dla tags właściwości i i reported .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ą właściwość zgłaszaną batteryLevel przez aplikację modułu. 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 zaplecze rozwiązania jest zainteresowane ostatnią znaną wartością właściwości. Użyj komunikatów urządzenie-chmura, jeśli zaplecze rozwiązania musi przetwarzać dane telemetryczne modułu w postaci sekwencji 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 zaplecze rozwiązania i aplikację modułu w celu zsynchronizowania konfiguracji telemetrii dla tego modułu. Na przykład:
Zaplecze rozwiązania 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" } ... }Zaplecze rozwiązania może śledzić wyniki operacji konfiguracji w wielu modułach, wykonując zapytania dotyczące 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
Zaplecze rozwiązania działa 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 umożliwia zapleczu rozwiązania częściowe aktualizowanie tagów lub żądanych 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 umożliwia zapleczu rozwiązania całkowite zastąpienie wszystkich istniejących żądanych właściwości i zastąpienie nowego dokumentu JSON dla elementu
properties/desired.Zamień tagi. Ta operacja umożliwia zapleczu rozwiązania całkowite zastąpienie wszystkich istniejących tagów i zastąpienie nowego dokumentu JSON dla elementu
tags.Odbieranie powiadomień bliźniaczych. Ta operacja umożliwia powiadamianie zaplecza rozwiązania o modyfikacji bliźniaczej reprezentacji. W tym celu 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ą uprawnień Service Połączenie zgodnie z definicją w artykule Kontrola dostępu do usługi IoT Hub.
Oprócz tych operacji zaplecze rozwiązania może wykonywać zapytania dotyczące bliźniaczych reprezentacji modułów przy użyciu języka zapytań przypominającego usługę IoT Hub.
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. Ta operacja używa tego samego formatu aktualizacji JSON, którego zaplecze rozwiązania używa do częściowej aktualizacji żądanych właściwości.
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. Moduł otrzymuje tę samą formę aktualizacji (częściowe lub pełne zastąpienie) wykonywane przez zaplecze rozwiązania.
Wszystkie poprzednie operacje wymagają uprawnienia Device Połączenie 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:
Dla każdej właściwości w dokumencie JSON usługa IoT Hub zbiorczo oblicza i dodaje długość klucza i wartości 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 zaplecza rozwiązania, aby zapewnić spójność. Jest to jedyna opcja zapewnienia spójności 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, wersja może być używana przez stronę aktualizującą, aby wymusić spójność aktualizacji. Na przykład aplikacja modułu dla zgłaszanej właściwości lub zaplecza rozwiązania 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: