Wprowadzenie do bliźniaczych reprezentacji urządzeń (interfejs wiersza polecenia platformy Azure)

• Interfejs wiersza polecenia
• .NET
• Python
• Node.js
• Java

Bliźniacze reprezentacje urządzeń to dokumenty JSON, które przechowują informacje o stanie urządzenia, takie jak metadane, konfiguracje i warunki. Usługa IoT Hub utrzymuje bliźniacze reprezentację urządzenia dla każdego urządzenia, które łączy się z nim.

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.

Użyj bliźniaczych reprezentacji urządzeń, aby:

• Przechowywanie metadanych urządzenia z zaplecza rozwiązania.

• Zgłoś bieżące informacje o stanie, takie jak dostępne możliwości i warunki, na przykład użyta metoda łączności z poziomu aplikacji urządzenia.

• Synchronizuj stan długotrwałych przepływów pracy, takich jak aktualizacje oprogramowania układowego i konfiguracji, między aplikacją urządzenia a aplikacją zaplecza.

• Wykonywanie zapytań dotyczących metadanych, konfiguracji lub stanu urządzenia.

Bliźniacze reprezentacje urządzeń są przeznaczone do synchronizacji i wykonywania zapytań dotyczących konfiguracji i warunków urządzeń. Aby uzyskać więcej informacji o bliźniaczych reprezentacjach urządzeń, w tym o tym, kiedy używać bliźniaczych reprezentacji urządzeń, zobacz Omówienie bliźniaczych reprezentacji urządzeń.

Centra IoT przechowują bliźniacze reprezentacje urządzeń, które zawierają następujące elementy:

• Tagi. Metadane urządzenia dostępne tylko przez zaplecze rozwiązania.

• Żądane właściwości. Obiekty JSON modyfikowalne przez zaplecze rozwiązania i można je zaobserwować przez aplikację urządzenia.

• Zgłoszone właściwości. Obiekty JSON modyfikowalne przez aplikację urządzenia i czytelne dla zaplecza rozwiązania.

Tagi i właściwości nie mogą zawierać tablic, ale mogą zawierać zagnieżdżone obiekty.

Poniższa ilustracja przedstawia organizację bliźniaczej reprezentacji urządzenia:

Ponadto zaplecze rozwiązania może wykonywać zapytania dotyczące bliźniaczych reprezentacji urządzeń na podstawie wszystkich powyższych danych. Aby uzyskać więcej informacji na temat bliźniaczych reprezentacji urządzeń, zobacz Omówienie bliźniaczych reprezentacji urządzeń. Aby uzyskać więcej informacji na temat wykonywania zapytań, zobacz Język zapytań usługi IoT Hub.

W tym artykule pokazano, w jaki sposób wykonać następujące czynności:

• Użyj symulowanego urządzenia, aby zgłosić swój kanał łączności jako zgłoszoną właściwość na bliźniaczej reprezentacji urządzenia.

• Wykonywanie zapytań dotyczących urządzeń przy użyciu filtrów w utworzonych wcześniej tagach i właściwościach.

Aby uzyskać więcej informacji na temat używania zgłaszanych właściwości bliźniaczej reprezentacji urządzenia, zobacz Wskazówki dotyczące komunikacji między urządzeniami i chmurą.

W tym artykule pokazano, jak utworzyć dwie sesje interfejsu wiersza polecenia platformy Azure:

• Sesja, która tworzy symulowane urządzenie. Urządzenie symulowane zgłasza swój kanał łączności jako zgłoszoną właściwość na odpowiedniej bliźniaczej reprezentacji urządzenia po zainicjowaniu.

• Sesja, która aktualizuje tagi bliźniaczej reprezentacji urządzenia dla symulowanego urządzenia, a następnie wysyła zapytania do urządzeń z centrum IoT. Zapytania używają filtrów na podstawie tagów i właściwości, które zostały wcześniej zaktualizowane w obu sesjach.

Wymagania wstępne

• Interfejs wiersza polecenia platformy Azure. Możesz również uruchomić polecenia w tym artykule przy użyciu usługi Azure Cloud Shell, interaktywnej powłoki interfejsu wiersza polecenia działającej w przeglądarce lub w aplikacji, takiej jak Terminal Windows. Jeśli używasz usługi Cloud Shell, nie musisz instalować żadnych elementów. Jeśli wolisz używać interfejsu wiersza polecenia lokalnie, ten artykuł wymaga interfejsu wiersza polecenia platformy Azure w wersji 2.36 lub nowszej. Uruchom polecenie az --version, aby dowiedzieć się, jaka wersja jest używana. Aby zainstalować lokalnie lub uaktualnić interfejs wiersza polecenia platformy Azure, zobacz Instalowanie interfejsu wiersza polecenia platformy Azure.

• Centrum IoT. Utwórz go za pomocą interfejsu wiersza polecenia lub witryny Azure Portal.

• Upewnij się, że port 8883 jest otwarty w zaporze. Przykłady w tym artykule używają protokołu MQTT, który komunikuje się za pośrednictwem portu 8883. Ten port można zablokować w niektórych środowiskach sieci firmowych i edukacyjnych. Aby uzyskać więcej informacji i sposobów obejścia tego problemu, zobacz Połączenie do usługi IoT Hub (MQTT).

Przygotowywanie usługi Cloud Shell

Jeśli chcesz użyć usługi Azure Cloud Shell, musisz go najpierw uruchomić i skonfigurować. Jeśli używasz interfejsu wiersza polecenia lokalnie, przejdź do sekcji Przygotowywanie dwóch sesji interfejsu wiersza polecenia.

1. Wybierz ikonę usługi Cloud Shell z nagłówka strony w witrynie Azure Portal.

   

   Uwaga

   Jeśli po raz pierwszy użyto usługi Cloud Shell, zostanie wyświetlony monit o utworzenie magazynu, który jest wymagany do korzystania z usługi Cloud Shell. Wybierz subskrypcję, aby utworzyć konto magazynu i udział usługi Microsoft Azure Files.

2. Użyj selektora środowiska na pasku narzędzi usługi Cloud Shell, aby wybrać preferowane środowisko interfejsu wiersza polecenia. W tym artykule jest używane środowisko powłoki Bash . Możesz również użyć środowiska programu PowerShell .

   Uwaga

   Niektóre polecenia wymagają innej składni lub formatowania w środowiskach powłoki Bash i programu PowerShell . Aby uzyskać więcej informacji, zobacz Wskazówki na potrzeby pomyślnego korzystania z interfejsu wiersza polecenia platformy Azure.

   

Przygotowywanie dwóch sesji interfejsu wiersza polecenia

Następnie należy przygotować dwie sesje interfejsu wiersza polecenia platformy Azure. Jeśli używasz usługi Cloud Shell, uruchamiasz te sesje na oddzielnych kartach usługi Cloud Shell. W przypadku korzystania z lokalnego klienta interfejsu wiersza polecenia należy uruchomić oddzielne wystąpienia interfejsu wiersza polecenia. Użyj oddzielnych sesji interfejsu wiersza polecenia dla następujących zadań:

• Pierwsza sesja symuluje urządzenie IoT komunikujące się z centrum IoT.
• Druga sesja aktualizuje symulowane urządzenie i wysyła zapytanie do centrum IoT Hub.

1. Jeśli używasz usługi Cloud Shell, przejdź do następnego kroku. W przeciwnym razie uruchom polecenie az login w pierwszej sesji interfejsu wiersza polecenia, aby zalogować się do konta platformy Azure.

   Jeśli używasz usługi Cloud Shell, logujesz się automatycznie na swoje konto platformy Azure. Cała komunikacja między sesją interfejsu wiersza polecenia platformy Azure a centrum IoT jest uwierzytelniana i szyfrowana. W związku z tym ten artykuł nie wymaga dodatkowego uwierzytelniania, które będzie używane z rzeczywistym urządzeniem, takim jak parametry połączenia. Aby uzyskać więcej informacji na temat logowania przy użyciu interfejsu wiersza polecenia platformy Azure, zobacz Logowanie się przy użyciu interfejsu wiersza polecenia platformy Azure.

   az login
   

2. W pierwszej sesji interfejsu wiersza polecenia uruchom polecenie az extension add . Polecenie dodaje rozszerzenie Microsoft Azure IoT dla interfejsu wiersza polecenia platformy Azure do powłoki interfejsu wiersza polecenia. Rozszerzenie dodaje polecenia specyficzne dla usług IoT Hub, IoT Edge i IoT Device Provisioning Service (DPS) do interfejsu wiersza polecenia platformy Azure. Po zainstalowaniu rozszerzenia nie trzeba jej ponownie instalować w żadnej sesji usługi Cloud Shell.

   az extension add --name azure-iot
   

   Uwaga

   W tym artykule jest używana najnowsza wersja rozszerzenia Usługi Azure IoT o nazwie azure-iot. Starsza wersja nosi nazwę azure-cli-iot-ext. Jednocześnie powinna być zainstalowana tylko jedna wersja. Możesz użyć polecenia az extension list , aby zweryfikować aktualnie zainstalowane rozszerzenia.

   Użyj az extension remove --name azure-cli-iot-ext polecenia , aby usunąć starszą wersję rozszerzenia.

   Użyj az extension add --name azure-iot polecenia , aby dodać nową wersję rozszerzenia.

   Aby zobaczyć, jakie rozszerzenia zostały zainstalowane, użyj polecenia az extension list.

3. Otwórz drugą sesję interfejsu wiersza polecenia. Jeśli używasz usługi Cloud Shell w przeglądarce, wybierz ikonę Otwórz nową sesję na pasku narzędzi pierwszej sesji interfejsu wiersza polecenia. Jeśli używasz interfejsu wiersza polecenia lokalnie, otwórz drugie wystąpienie interfejsu wiersza polecenia.

   

Tworzenie i symulowanie urządzenia

W tej sekcji utworzysz tożsamość urządzenia dla centrum IoT w pierwszej sesji interfejsu wiersza polecenia, a następnie zasymulujesz urządzenie przy użyciu tej tożsamości urządzenia. Symulowane urządzenie odpowiada na zadania zaplanowane w drugiej sesji interfejsu wiersza polecenia.

Aby utworzyć i uruchomić symulowane urządzenie:

1. W pierwszej sesji interfejsu wiersza polecenia uruchom polecenie az iot hub device-identity create , zastępując następujące symbole zastępcze odpowiednimi wartościami. To polecenie tworzy tożsamość urządzenia dla symulowanego urządzenia.

   {DeviceName}. Nazwa symulowanego urządzenia.

   {HubName}. Nazwa centrum IoT Hub.

   az iot hub device-identity create --device-id {DeviceName} --hub-name {HubName} 
   

2. W pierwszej sesji interfejsu wiersza polecenia uruchom polecenie az iot device simulate , zastępując następujące symbole zastępcze odpowiednimi wartościami. To polecenie symuluje urządzenie utworzone w poprzednim kroku. Polecenie konfiguruje również symulowane urządzenie w celu raportowania kanału łączności jako zgłaszanej właściwości na odpowiadającej bliźniaczej reprezentacji urządzenia po zainicjowaniu.

   {DeviceName}. Nazwa symulowanego urządzenia.

   {HubName}. Nazwa centrum IoT Hub.

   az iot device simulate --device-id {DeviceName} --hub-name {HubName} \
                          --init-reported-properties '{"connectivity":{"type": "cellular"}}'
   

   Napiwek

   Domyślnie polecenie az iot device simulate wysyła 100 komunikatów z urządzenia do chmury z interwałem 3 sekund między komunikatami. Symulacja kończy się po wysłaniu wszystkich komunikatów. Jeśli chcesz, aby symulacja działała dłużej, możesz użyć parametru --msg-count , aby określić więcej komunikatów lub parametru --msg-interval , aby określić dłuższy interwał między komunikatami. Możesz również ponownie uruchomić polecenie, aby ponownie uruchomić symulowane urządzenie.

Aktualizowanie bliźniaczej reprezentacji urządzenia

Po utworzeniu tożsamości urządzenia bliźniacze reprezentacja urządzenia jest tworzona niejawnie w usłudze IoT Hub. W tej sekcji użyjesz drugiej sesji interfejsu wiersza polecenia, aby zaktualizować zestaw tagów na bliźniaczej reprezentacji urządzenia skojarzonej z tożsamością urządzenia utworzoną w poprzedniej sekcji. Tagi bliźniaczych reprezentacji urządzeń umożliwiają organizowanie urządzeń w rozwiązaniach IoT i zarządzanie nimi. Aby uzyskać więcej informacji na temat zarządzania urządzeniami przy użyciu tagów, zobacz Jak zarządzać urządzeniami przy użyciu tagów bliźniaczych reprezentacji urządzeń w usłudze Azure IoT Hub.

1. Upewnij się, że symulowane urządzenie w pierwszej sesji interfejsu wiersza polecenia jest uruchomione. Jeśli nie, uruchom je ponownie, uruchamiając ponownie polecenie az iot device simulate z obszaru Tworzenie i symulowanie urządzenia.

2. W drugiej sesji interfejsu wiersza polecenia uruchom polecenie az iot hub device-twin update , zastępując następujące symbole zastępcze odpowiednimi wartościami. W tym przykładzie aktualizujemy wiele tagów na bliźniaczej reprezentacji urządzenia dla tożsamości urządzenia utworzonej w poprzedniej sekcji.

   {DeviceName}. Nazwa urządzenia.

   {HubName}. Nazwa centrum IoT Hub.

   az iot hub device-twin update --device-id {DeviceName} --hub-name {HubName} \
                                 --tags '{"location":{"region":"US","plant":"Redmond43"}}'
   

3. W drugiej sesji interfejsu wiersza polecenia upewnij się, że odpowiedź JSON pokazuje wyniki operacji aktualizacji. W poniższym przykładzie odpowiedzi JSON użyliśmy SampleDevice symbolu zastępczego {DeviceName} w poleceniu interfejsu az iot hub device-twin update wiersza polecenia.

   {
     "authenticationType": "sas",
     "capabilities": {
       "iotEdge": false
     },
     "cloudToDeviceMessageCount": 0,
     "connectionState": "Connected",
     "deviceEtag": "MTA2NTU1MDM2Mw==",
     "deviceId": "SampleDevice",
     "deviceScope": null,
     "etag": "AAAAAAAAAAI=",
     "lastActivityTime": "0001-01-01T00:00:00+00:00",
     "modelId": "",
     "moduleId": null,
     "parentScopes": null,
     "properties": {
       "desired": {
         "$metadata": {
           "$lastUpdated": "2023-02-21T10:40:10.5062402Z"
         },
         "$version": 1
       },
       "reported": {
         "$metadata": {
           "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
           "connectivity": {
             "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
             "type": {
               "$lastUpdated": "2023-02-21T10:40:43.8539917Z"
             }
           }
         },
         "$version": 2,
         "connectivity": {
           "type": "cellular"
         }
       }
     },
     "status": "enabled",
     "statusReason": null,
     "statusUpdateTime": "0001-01-01T00:00:00+00:00",
     "tags": {
       "location": {
         "plant": "Redmond43",
         "region": "US"
       }
     },
     "version": 4,
     "x509Thumbprint": {
       "primaryThumbprint": null,
       "secondaryThumbprint": null
     }
   }
   

Wykonywanie zapytań względem centrum IoT Hub pod kątem bliźniaczych reprezentacji urządzeń

Usługa IoT Hub uwidacznia bliźniacze reprezentacje urządzeń centrum IoT jako kolekcję dokumentów o nazwie urządzenia. W tej sekcji używasz drugiej sesji interfejsu wiersza polecenia do wykonywania dwóch zapytań w zestawie bliźniaczych reprezentacji urządzeń dla centrum IoT: pierwsze zapytanie wybiera tylko bliźniacze reprezentacje urządzeń znajdujących się w zakładzie Redmond43 , a drugie uściśli zapytanie, aby wybrać tylko urządzenia, które są również połączone za pośrednictwem sieci komórkowej. Oba zapytania zwracają tylko pierwsze 100 urządzeń w zestawie wyników. Aby uzyskać więcej informacji na temat zapytań bliźniaczych reprezentacji urządzeń, zobacz Zapytania dotyczące urządzeń i bliźniaczych reprezentacji modułów usługi IoT Hub.

1. Upewnij się, że symulowane urządzenie w pierwszej sesji interfejsu wiersza polecenia jest uruchomione. Jeśli nie, uruchom je ponownie, uruchamiając ponownie polecenie az iot device simulate z obszaru Tworzenie i symulowanie urządzenia.

2. W drugiej sesji interfejsu wiersza polecenia uruchom polecenie az iot hub query , zastępując następujące symbole zastępcze odpowiednimi wartościami. W tym przykładzie filtrujemy zapytanie w celu zwrócenia tylko bliźniaczych reprezentacji urządzeń znajdujących się w zakładzie Redmond43 .

   {HubName}. Nazwa centrum IoT Hub.

   az iot hub query --hub-name {HubName} \
                    --query-command "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'" \
                    --top 100
   

3. W drugiej sesji interfejsu wiersza polecenia upewnij się, że odpowiedź JSON pokazuje wyniki zapytania.

   {
     "authenticationType": "sas",
     "capabilities": {
       "iotEdge": false
     },
     "cloudToDeviceMessageCount": 0,
     "connectionState": "Connected",
     "deviceEtag": "MTA2NTU1MDM2Mw==",
     "deviceId": "SampleDevice",
     "deviceScope": null,
     "etag": "AAAAAAAAAAI=",
     "lastActivityTime": "0001-01-01T00:00:00+00:00",
     "modelId": "",
     "moduleId": null,
     "parentScopes": null,
     "properties": {
       "desired": {
         "$metadata": {
           "$lastUpdated": "2023-02-21T10:40:10.5062402Z"
         },
         "$version": 1
       },
       "reported": {
         "$metadata": {
           "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
           "connectivity": {
             "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
             "type": {
               "$lastUpdated": "2023-02-21T10:40:43.8539917Z"
             }
           }
         },
         "$version": 2,
         "connectivity": {
           "type": "cellular"
         }
       }
     },
     "status": "enabled",
     "statusReason": null,
     "statusUpdateTime": "0001-01-01T00:00:00+00:00",
     "tags": {
       "location": {
         "plant": "Redmond43",
         "region": "US"
       }
     },
     "version": 4,
     "x509Thumbprint": {
       "primaryThumbprint": null,
       "secondaryThumbprint": null
     }
   }
   

4. W drugiej sesji interfejsu wiersza polecenia uruchom polecenie az iot hub query , zastępując następujące symbole zastępcze odpowiednimi wartościami. W tym przykładzie filtrujemy zapytanie w celu zwrócenia tylko bliźniaczych reprezentacji urządzeń znajdujących się w zakładzie Redmond43 , które są również połączone za pośrednictwem sieci komórkowej.

   {HubName}. Nazwa centrum IoT Hub.

   az iot hub query --hub-name {HubName} \
                    --query-command "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' \
                                     AND properties.reported.connectivity.type = 'cellular'" \
                    --top 100
   

5. W drugiej sesji interfejsu wiersza polecenia upewnij się, że odpowiedź JSON pokazuje wyniki zapytania. Wyniki tego zapytania powinny być zgodne z wynikami poprzedniego zapytania w tej sekcji.

W tym artykule opisano następujące zagadnienia:

• Dodano metadane urządzenia jako tagi z sesji interfejsu wiersza polecenia platformy Azure
• Symulowano urządzenie, które zgłosiło informacje o łączności urządzenia w bliźniaczej reprezentacji urządzenia
• Odpytywanie informacji o bliźniaczej reprezentacji urządzenia przy użyciu języka zapytań przypominającego usługę IoT Hub w sesji interfejsu wiersza polecenia platformy Azure

Następne kroki

Aby dowiedzieć się, jak:

• Wysyłanie danych telemetrycznych z urządzeń— zobacz Szybki start: wysyłanie danych telemetrycznych z urządzenia IoT Plug and Play do usługi Azure IoT Hub.

• Konfigurowanie urządzeń przy użyciu żądanych właściwości bliźniaczej reprezentacji urządzenia, zobacz Samouczek: konfigurowanie urządzeń z poziomu usługi zaplecza.

• Interaktywne sterowanie urządzeniami, takimi jak włączanie wentylatora z aplikacji kontrolowanej przez użytkownika, zobacz Szybki start: kontrolowanie urządzenia podłączonego do centrum IoT.