Opis bliźniaczych reprezentacji urządzeń i korzystanie z nich w usłudze IoT Hub

Artykuł
02/22/2024

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 zaplecza 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 a aplikacją zaplecza. Na przykład gdy zaplecze rozwiązania 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:

Urządzenia i zaplecza mogą służyć do synchronizowania warunków i konfiguracji urządzenia.
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 zaplecze rozwiązania może odczytywać dane i zapisywać je. 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. Zaplecze rozwiązania może ustawić żądane właściwości, a aplikacja urządzenia może je odczytać. 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 zaplecze rozwiązania może 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 connectionStateUpdatedTime i generationId nie zostaną uwzględnione.

Diagram that shows which applications interact with which device twin properties.

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ą właściwość zgłoszoną batteryLevel przez aplikację urządzenia. 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 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 urządzenia w postaci sekwencji zdarzeń znacznika czasu, 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:

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 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 status przy 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 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 umożliwia zapleczu rozwiązania częściowe aktualizowanie tagów lub żądanych 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 null zostaną usunięte. W poniższym przykładzie zostanie utworzona nowa żądana właściwość z wartością {"newProperty": "newValue"}, zastępuje istniejącą wartość existingProperty elementu za pomocą "otherNewValue"elementu i usuwa otherOldPropertyelement . Ż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ń nietelemetrycznych.

Wszystkie poprzednie operacje obsługują optymistyczną współbieżność i wymagają uprawnień Service Połączenie 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. 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łączone urządzenie może otrzymywać powiadomienia o aktualizacjach żądanych właściwości, gdy się one zdarzają. Urządzenie 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 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:

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łę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ść 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 urządzenia 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 urządzenia 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 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

Teraz znasz już bliźniacze reprezentacje urządzeń, możesz zainteresować się następującymi tematami przewodników deweloperów usługi IoT Hub:

Aby wypróbować niektóre pojęcia opisane w tym artykule, zobacz następujące samouczki dotyczące usługi IoT Hub:

Opis bliźniaczych reprezentacji urządzeń i korzystanie z nich w usłudze IoT Hub

Bliźniacze reprezentacje urządzeń

Przykład zgłaszanej właściwości

Przykład żądanej właściwości

Operacje zaplecza

Operacje na urządzeniach

Format tagów i właściwości

Rozmiar bliźniaczej reprezentacji urządzenia

Metadane bliźniaczej reprezentacji urządzenia

Optymistyczna współbieżność

Przepływ ponownego łączenia urządzenia

Następne kroki

Dodatkowe zasoby