Udostępnij za pomocą

Zrozumieć i używać bliźniacze urządzenia w usłudze IoT Hub

Bliźniaki 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 i rozmiaru 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ądzeń i zaplecze rozwiązania mogą wykonywać na bliźniakach urządzeń.

Użyj bliźniaków 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źniaki urządzeń

Bliźniacze urządzenia 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źniaczego modelu urządzenia jest powiązany z odpowiadającą mu 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źniak 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 urządzenia dotyczące tożsamości. Korzeń 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 są uwzględniane.

Diagram pokazujący, które aplikacje współdziałają z właściwościami bliźniaczej reprezentacji urządzenia.

Poniższy przykład przedstawia dokument JSON bliźniaczego cyfrowego 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 obejmujące zarówno tags, jak i reported oraz desired właściwości. Kontener properties zawiera niektóre elementy tylko do odczytu ($metadata i $version) opisane w sekcjach Metadane bliźniaczej struktury urządzenia i Optymistyczna współbieżność.

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

W poprzednim przykładzie bliźniak urządzenia zawiera 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ą aplikację urządzenia raportującą możliwości 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ądzenia do chmury, jeśli chcesz przetwarzać dane telemetryczne urządzenia w postaci sekwencji zdarzeń znaczników czasowych, takich jak szeregi czasowe.

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

W poprzednim przykładzie pożądane i zgłoszone właściwości bliźniaka urządzenia są wykorzystywane przez zaplecze rozwiązania i aplikację urządzenia w celu synchronizacji konfiguracji telemetrii dla tego urządzenia. Na przykład:

  1. 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"
    },
    ...
},

  2. Aplikacja urządzenia jest powiadamiana o zmianie natychmiast, jeśli urządzenie jest połączone. Jeśli nie jest połączony, aplikacja urządzenia podąża za przepływem ponownego łączenia urządzenia podczas nawiązywania połączenia. Następnie aplikacja urządzenia zgłasza zaktualizowaną konfigurację (lub warunek błędu, korzystając z właściwości status). Oto część zgłoszonych właściwości:

    "reported": {
    "telemetryConfig": {
        "sendFrequency": "5m",
        "status": "success"
    }
    ...
}

  3. Aplikacja zaplecza śledzi wyniki operacji konfiguracji na wielu urządzeniach poprzez zapytania dotyczące bliźniaków 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 na właściwości żądane i zgłoszone w bliźniaczych właściwościach 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 zapisowalne właściwości w IoT Plug and Play.

Za pomocą bliźniaczych systemów 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

Rozwiązanie działa w tle na urządzeniu bliźniaczym przy użyciu następujących operacji atomowych, uwidocznionych za pośrednictwem protokołu HTTPS.

  • Pobierz bliźniaka urządzenia według identyfikatora. Ta operacja zwraca dokument urządzenia w trybie bliźniaczym, w tym tagi oraz żądane i zgłoszone właściwości systemu.

  • Częściowo zaktualizuj bliźniaka 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 null zostaną usunięte. W poniższym przykładzie jest tworzona nowa żądana właściwość z wartością {"newProperty": "newValue"}, istniejąca wartość existingProperty jest zastępowana wartością "otherNewValue", a otherOldProperty jest usuwany. Ż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, gdy bliźniak zostanie zmodyfikowany. Aby otrzymywać powiadomienia o zmianach bliźniaczych 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 nie są wysyłane powiadomienia bliźniacze. 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 ciele zwracanym w wiadomości powiadomienia bliźniaka, 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ń IoT Hub przypominającego język SQL.

  • Wykonuj operacje na dużych zestawach bliźniaczych urządzeń przy użyciu zadań.

Operacje na urządzeniach

Aplikacja urządzenia działa na cyfrowym bliźniaku urządzenia przy użyciu następujących operacji niepodzielnych.

  • Pobieranie cyfrowej bliźniaczki urządzenia. Ta operacja zwraca dokument bliźniaczy urządzenia (w tym żądane i zgłaszane właściwości systemu) dla obecnie 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.

  • Obserwuj żądane 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, przy czym wielkość liter ma znaczenie, a długość może wynosić do 1 KB. Dozwolone znaki wykluczają znaki sterujące UNICODE (segmenty C0 i C1), ., $, oraz 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źniaczego modelu 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 nie uwzględniają elementów tylko do odczytu, takich jak $version i $metadata/$lastUpdated.

Rozmiar pojedynczy 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 wszystkie operacje z błędem, które zwiększają rozmiar tags, properties/desired, lub też properties/reported dokumentów powyżej limitu.

Metadane cyfrowego bliźniaka urządzenia

IoT Hub przechowuje znacznik czasu ostatniej aktualizacji dla każdego obiektu JSON w żądanych i raportowanych właściwościach bliźniaczym urządzeniu. Znaczniki czasu są w formacie UTC i zakodowane w YYYY-MM-DDTHH:MM:SS.mmmZ .

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, rozważ zaimplementowanie synchronizacji na szczeblu aplikacji poprzez oczekiwanie na informację zwrotną o raportowanych właściwościach, zanim wyślesz następną aktualizację.

Bliźniaki urządzeń mają właściwość ETag, zgodnie z RFC7232, która odnosi się do reprezentacji JSON bliźniaka. Możesz użyć właściwości etag w operacjach warunkowej aktualizacji z poziomu 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ą również wartość $version gwarantowaną jako przyrostową. 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, gdy obserwujący agent (tak jak aplikacja urządzenia obserwująca żądane właściwości) musi rozwiązać konflikty między wynikiem operacji pobrania 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:

  1. Aplikacja łączy się z centrum IoT.
  2. Aplikacja urządzenia subskrybuje powiadomienia o aktualizacji żądanych właściwości.
  3. Aplikacja urządzenia pobiera pełny dokument dla żądanych właściwości.

Aplikacja urządzenia może ignorować wszystkie powiadomienia, których wersja jest mniejsza lub równa $version wersji 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:

  • Last updated on