Opis bliźniaczych reprezentacji urządzeń i korzystanie z nich w usłudze IoT Hub
Bliźniacze reprezentacje urządzeń to dokumenty JSON, które przechowują informacje o stanie urządzenia, w tym metadane, konfiguracje i warunki. Usługa Azure IoT Hub utrzymuje bliźniaczą reprezentację urządzenia dla każdego urządzenia połączonego z usługą IoT Hub.
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 urządzenia: tagi, żądane właściwości i zgłoszone właściwości.
- Operacje, które aplikacje urządzenia i zaplecze rozwiązania mogą wykonywać na bliźniaczych reprezentacjach urządzeń.
Użyj bliźniaczych reprezentacji urządzeń, aby:
Przechowywanie metadanych specyficznych dla urządzenia w chmurze. Na przykład lokalizacja automatu.
Zgłoś bieżące informacje o stanie, takie jak dostępne możliwości i warunki z aplikacji urządzenia. Na przykład czy urządzenie jest połączone z centrum IoT za pośrednictwem sieci komórkowej, czy Wi-Fi.
Synchronizuj stan długotrwałych przepływów pracy między aplikacją urządzenia i aplikacjami zaplecza. Na przykład gdy aplikacja zaplecza określa nową wersję oprogramowania układowego do zainstalowania, a aplikacja urządzenia zgłasza różne etapy procesu aktualizacji.
Wykonywanie zapytań dotyczących metadanych, konfiguracji lub stanu urządzenia.
Aby uzyskać więcej informacji na temat używania zgłaszanych właściwości, komunikatów z urządzenia do chmury lub przekazywania plików, zobacz Wskazówki dotyczące komunikacji między urządzeniami i chmurą.
Aby uzyskać więcej informacji na temat używania żądanych właściwości, metod bezpośrednich lub komunikatów z chmury do urządzenia, zobacz Wskazówki dotyczące komunikacji między chmurą i urządzeniem.
Aby dowiedzieć się, jak bliźniacze reprezentacje urządzeń odnoszą się do modelu urządzenia używanego przez urządzenie Usługi Azure IoT Plug and Play, zobacz Omówienie cyfrowych reprezentacji bliźniaczych usługi IoT Plug and Play.
Bliźniacze reprezentacje urządzeń
Bliźniacze reprezentacje urządzeń przechowują informacje dotyczące urządzeń, które:
Aplikacje urządzeń i aplikacje zaplecza mogą służyć do synchronizowania warunków i konfiguracji urządzeń.
Zaplecze rozwiązania może służyć do wykonywania zapytań i docelowych długotrwałych operacji.
Cykl życia bliźniaczej reprezentacji urządzenia jest połączony z odpowiednią tożsamością urządzenia. Bliźniacze reprezentacje urządzeń są tworzone niejawnie i usuwane po utworzeniu lub usunięciu tożsamości urządzenia w usłudze IoT Hub.
Bliźniacza reprezentacja urządzenia 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 aplikacji urządzeń.
Żądane właściwości. Używane wraz z zgłaszanymi właściwościami do synchronizowania konfiguracji lub warunków urządzenia. Aplikacje zaplecza mogą ustawiać żądane właściwości, a aplikacja urządzenia może je odczytywać. Aplikacja urządzenia 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 urządzenia. Aplikacja urządzenia 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 urządzenia. Katalog główny dokumentu JSON bliźniaczej reprezentacji urządzenia zawiera właściwości tylko do odczytu z odpowiedniej tożsamości urządzenia przechowywanej w rejestrze tożsamości. Właściwości
connectionStateUpdatedTimeigenerationIdnie są uwzględniane.
Poniższy przykład przedstawia dokument JSON bliźniaczej reprezentacji urządzenia:
{
"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
}
}
}
Obiekt główny zawiera właściwości tożsamości urządzenia oraz obiekty kontenera dla tags właściwości i reported oraz desired . Kontener properties zawiera niektóre elementy tylko do odczytu ($metadata i $version) opisane w sekcjach Metadane bliźniaczej reprezentacji urządzenia i Optymistyczna współbieżność .
Przykład zgłaszanej właściwości
W poprzednim przykładzie bliźniacze reprezentacje urządzenia zawierają zgłoszoną batteryLevel właściwość. Ta właściwość umożliwia wykonywanie zapytań i działanie na urządzeniach na podstawie ostatniego zgłoszonego poziomu baterii. Inne przykłady obejmują możliwości urządzenia raportowania aplikacji urządzenia 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 urządzenia 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 urządzenia są używane przez zaplecze rozwiązania i aplikację urządzenia do synchronizowania konfiguracji telemetrii dla tego urządzenia. 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 urządzenia jest powiadamiana o zmianie natychmiast, jeśli urządzenie jest połączone. Jeśli nie jest połączony, aplikacja urządzenia jest zgodna z przepływem ponownego łączenia urządzenia podczas nawiązywania połączenia. Następnie aplikacja urządzenia 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 śledzi wyniki operacji konfiguracji na wielu urządzeniach przez wykonywanie zapytań dotyczących bliźniaczych reprezentacji urządzeń.
Uwaga
Powyższe fragmenty kodu to przykłady, zoptymalizowane pod kątem czytelności, jednego ze sposobów kodowania konfiguracji urządzenia i jego stanu. Usługa IoT Hub nie nakłada określonego schematu dla żądanej reprezentacji urządzenia i zgłoszonych właściwości bliźniaczych reprezentacji urządzenia.
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.
Za pomocą bliźniaczych reprezentacji można synchronizować długotrwałe operacje, takie jak aktualizacje oprogramowania układowego. Aby uzyskać więcej informacji na temat sposobu używania właściwości do synchronizowania i śledzenia długotrwałej operacji na urządzeniach, zobacz Używanie żądanych właściwości do konfigurowania urządzeń.
Operacje zaplecza
Zaplecze rozwiązania działa na bliźniaczej reprezentacji urządzenia przy użyciu następujących operacji niepodzielnych, uwidocznionych za pośrednictwem protokołu HTTPS:
Pobieranie bliźniaczej reprezentacji urządzenia według identyfikatora. Ta operacja zwraca dokument bliźniaczej reprezentacji urządzenia, w tym tagi i żądane i zgłoszone właściwości systemu.
Częściowo zaktualizuj bliźniacze reprezentacje urządzenia. Ta operacja częściowo aktualizuje tagi lub żądane właściwości w bliźniaczej reprezentacji urządzenia. 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 urządzenia, 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ń nietelemetrycznych.
Wszystkie poprzednie operacje obsługują optymistyczną współbieżność i wymagają uprawnienia ServiceConnect zgodnie z definicją w temacie Kontrola dostępu do usługi IoT Hub.
Oprócz tych operacji zaplecze rozwiązania może wykonywać następujące czynności:
Wykonywanie zapytań dotyczących bliźniaczych reprezentacji urządzeń przy użyciu języka zapytań przypominającego usługę IoT Hub w języku SQL.
Wykonywanie operacji na dużych zestawach bliźniaczych reprezentacji urządzeń przy użyciu zadań.
Operacje na urządzeniach
Aplikacja urządzenia działa na bliźniaczej reprezentacji urządzenia przy użyciu następujących operacji niepodzielnych:
Pobieranie bliźniaczej reprezentacji urządzenia. Ta operacja zwraca dokument bliźniaczej reprezentacji urządzenia (w tym żądane i zgłaszane właściwości systemu) dla aktualnie połączonego urządzenia. (Tagi nie są widoczne dla aplikacji urządzeń).
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 urządzenia.
Obserwowanie żądanych właściwości. Obecnie połączone urządzenie może otrzymywać powiadomienia o aktualizacjach żądanych właściwości, gdy się one zdarzają.
Wszystkie poprzednie operacje wymagają uprawnienia DeviceConnect zgodnie z definicją w temacie 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. Aby uzyskać więcej informacji na temat szczegółów elementów pierwotnych usługi IoT Hub na potrzeby synchronizacji żądanych właściwości, zobacz Przepływ ponownego łączenia urządzenia.
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.Uwaga
Zapytania usługi IoT Hub używane w routingu komunikatów nie obsługują białych znaków ani żadnego z następujących znaków w ramach nazwy klucza:
()<>@,;:\"/?={}.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 urządzenia
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łędem wszystkie operacje, które zwiększają rozmiar tagsproperties/desireddokumentów , lub properties/reported powyżej limitu.
Metadane bliźniaczej reprezentacji urządzenia
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 urządzenia. 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": {
"$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
}
}
...
}
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 urządzeń mają właściwość etagETag , 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ść. Ta właściwość jest jedyną opcją zapewnienia spójności w operacjach obejmujących tags kontener.
Żądane i zgłoszone właściwości bliźniaczej reprezentacji urządzenia mają $version również wartość, która ma być przyrostowa. Podobnie jak w przypadku elementu ETag, można użyć właściwości version, aby wymusić spójność aktualizacji. Na przykład aplikacja urządzenia 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 urządzenia obserwująca żądane właściwości) musi uzgodnić wyścigi między wynikiem operacji pobierania a powiadomieniem o aktualizacji. Sekcja Przepływ ponownego łączenia urządzenia zawiera więcej informacji.
Przepływ ponownego łączenia urządzenia
Usługa IoT Hub nie zachowuje żądanych powiadomień o aktualizacji właściwości dla odłączonych urządzeń. Wynika z tego, że urządzenie, które 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 urządzenia łączy się z centrum IoT Hub.
- Aplikacja urządzenia subskrybuje powiadomienia o aktualizacji żądanych właściwości.
- Aplikacja urządzenia pobiera pełny dokument dla żądanych właściwości.
Aplikacja urządzenia 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 artykuły usługi IoT Hub: