Wprowadzenie do bliźniaczych reprezentacji urządzeń (Python)

Artykuł
04/07/2024

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:

Zrzut ekranu przedstawiający diagram koncepcji 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 aplikacji urządzenia symulowanego, 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ń z aplikacji zaplecza przy użyciu filtrów w utworzonych wcześniej tagach i właściwościach.

W tym artykule utworzysz dwie aplikacje konsolowe języka Python:

AddTagsAndQuery.py: aplikacja zaplecza, która dodaje tagi i wykonuje zapytania dotyczące bliźniaczych reprezentacji urządzeń.
Raport Połączenie ivity.py: symulowana aplikacja urządzenia, która łączy się z centrum IoT i zgłasza jej stan łączności.

Uwaga

Aby uzyskać więcej informacji na temat narzędzi zestawu SDK dostępnych do kompilowania aplikacji zarówno urządzeń, jak i zaplecza, zobacz Zestawy SDK usługi Azure IoT.

Wymagania wstępne

Aktywne konto platformy Azure. (Jeśli go nie masz, możesz utworzyć bezpłatne konto próbne w zaledwie kilka minut).
Centrum IoT. Utwórz go za pomocą interfejsu wiersza polecenia lub witryny Azure Portal.
Zarejestrowane urządzenie. Zarejestruj je w witrynie Azure Portal.
Zalecane jest użycie języka Python w wersji 3.7 lub nowszej . Upewnij się, że używasz 32-bitowej lub 64-bitowej instalacji zgodnie z wymaganiami konfiguracji. Po wyświetleniu monitu podczas instalacji upewnij się, że język Python został dodany do zmiennej środowiskowej specyficznej dla platformy.
Upewnij się, że port 8883 jest otwarty w zaporze. Przykład urządzenia w tym artykule używa protokołu MQTT, który komunikuje się za pośrednictwem portu 8883. Ten port może zostać zablokowany 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).

Pobieranie parametry połączenia centrum IoT

W tym artykule utworzysz usługę zaplecza, która dodaje żądane właściwości do bliźniaczej reprezentacji urządzenia, a następnie wysyła zapytanie do rejestru tożsamości w celu znalezienia wszystkich urządzeń z zgłoszonymi właściwościami, które zostały odpowiednio zaktualizowane. Usługa wymaga uprawnienia połączenia usługi, aby zmodyfikować żądane właściwości bliźniaczej reprezentacji urządzenia i potrzebuje uprawnień do odczytu rejestru w celu wykonywania zapytań dotyczących rejestru tożsamości. Nie ma domyślnych zasad dostępu współdzielonego, które zawierają tylko te dwa uprawnienia, więc musisz je utworzyć.

Aby utworzyć zasady dostępu współdzielonego, które udzielają uprawnień do nawiązywania połączenia z usługą i odczytu rejestru i uzyskiwania parametry połączenia dla tych zasad, wykonaj następujące kroki:

W witrynie Azure Portal wybierz pozycję Grupy zasobów. Wybierz grupę zasobów, w której znajduje się centrum, a następnie wybierz centrum z listy zasobów.
W okienku po lewej stronie centrum wybierz pozycję Zasady dostępu współdzielonego.
W górnym menu powyżej listy zasad wybierz pozycję Dodaj zasady dostępu współdzielonego.
W okienku Dodawanie zasad dostępu współdzielonego po prawej stronie wprowadź opisową nazwę zasad , taką jak serviceAndRegistryRead. W obszarze Uprawnienia wybierz pozycję Odczyt rejestru i usługa Połączenie, a następnie wybierz pozycję Dodaj.
Wybierz nowe zasady z listy zasad.
Wybierz ikonę kopiowania dla parametry połączenia podstawowej i zapisz wartość.

Aby uzyskać więcej informacji na temat zasad dostępu współdzielonego i uprawnień usługi IoT Hub, zobacz Kontrola dostępu i uprawnienia.

Tworzenie aplikacji usługi, która aktualizuje żądane właściwości i wysyła zapytania do bliźniaczych reprezentacji

W tej sekcji utworzysz aplikację konsolową języka Python, która dodaje metadane lokalizacji do bliźniaczej reprezentacji urządzenia skojarzonej z { Identyfikator urządzenia}. Aplikacja wysyła zapytanie do centrum IoT dla urządzeń znajdujących się w Stanach Zjednoczonych, a następnie wysyła zapytania do urządzeń, które zgłaszają połączenie sieciowe.

W katalogu roboczym otwórz wiersz polecenia i zainstaluj zestaw SDK usługi Azure IoT Hub dla języka Python.
```
pip install azure-iot-hub
```
Za pomocą edytora tekstów utwórz nowy plik AddTagsAndQuery.py .

Dodaj następujący kod umożliwiający zaimportowanie wymaganych modułów z zestawu SDK usługi:

import sys
from time import sleep
from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import Twin, TwinProperties, QuerySpecification, QueryResult

Dodaj następujący kod źródłowy języka. Zastąp element [IoTHub Connection String] parametry połączenia centrum IoT, który został skopiowany w parametry połączenia Pobierz centrum IoT Hub. Zastąp [Device Id] element identyfikatorem urządzenia (nazwą) zarejestrowanego urządzenia w centrum IoT.
```
IOTHUB_CONNECTION_STRING = "[IoTHub Connection String]"
DEVICE_ID = "[Device Id]"
```

Dodaj następujący kod do pliku AddTagsAndQuery.py :

def iothub_service_sample_run():
    try:
        iothub_registry_manager = IoTHubRegistryManager(IOTHUB_CONNECTION_STRING)

        new_tags = {
                'location' : {
                    'region' : 'US',
                    'plant' : 'Redmond43'
                }
            }

        twin = iothub_registry_manager.get_twin(DEVICE_ID)
        twin_patch = Twin(tags=new_tags, properties= TwinProperties(desired={'power_level' : 1}))
        twin = iothub_registry_manager.update_twin(DEVICE_ID, twin_patch, twin.etag)

        # Add a delay to account for any latency before executing the query
        sleep(1)

        query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'")
        query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
        print("Devices in Redmond43 plant: {}".format(', '.join([twin.device_id for twin in query_result.items])))

        print()

        query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity = 'cellular'")
        query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
        print("Devices in Redmond43 plant using cellular network: {}".format(', '.join([twin.device_id for twin in query_result.items])))

    except Exception as ex:
        print("Unexpected error {0}".format(ex))
        return
    except KeyboardInterrupt:
        print("IoT Hub Device Twin service sample stopped")

Obiekt IoTHubRegistryManager uwidacznia wszystkie metody wymagane do interakcji z bliźniaczymi reprezentacjami urządzeń z usługi. Kod najpierw inicjuje obiekt IoTHubRegistryManager , a następnie aktualizuje bliźniacza reprezentację urządzenia dla DEVICE_ID, a na koniec uruchamia dwa zapytania. Pierwszy wybiera tylko bliźniacze reprezentacje urządzeń znajdujące się w zakładzie Redmond43 , a drugi uściśli zapytanie, aby wybrać tylko urządzenia, które są również połączone za pośrednictwem sieci komórkowej.

Dodaj następujący kod na końcu AddTagsAndQuery.py , aby zaimplementować funkcję iothub_service_sample_run :

if __name__ == '__main__':
    print("Starting the Python IoT Hub Device Twin service sample...")
    print()

    iothub_service_sample_run()

Uruchom aplikację za pomocą:
```
python AddTagsAndQuery.py
```
Powinno zostać wyświetlone jedno urządzenie w wynikach zapytania z prośbą o wszystkie urządzenia znajdujące się w Redmond43 i żadne zapytanie, które ogranicza wyniki do urządzeń korzystających z sieci komórkowej. W następnej sekcji utworzysz aplikację urządzenia, która będzie używać sieci komórkowej i ponownie uruchomisz to zapytanie, aby zobaczyć, jak się zmienia.

Tworzenie aplikacji urządzenia, która aktualizuje zgłoszone właściwości

W tej sekcji utworzysz aplikację konsolową języka Python, która łączy się z centrum jako {Identyfikator urządzenia} , a następnie aktualizuje zgłoszone właściwości bliźniaczej reprezentacji urządzenia, aby potwierdzić, że jest połączona przy użyciu sieci komórkowej.

W wierszu polecenia w katalogu roboczym zainstaluj zestaw SDK urządzenia usługi Azure IoT Hub dla języka Python:
```
pip install azure-iot-device
```
Za pomocą edytora tekstów utwórz nowy plik Report Połączenie ivity.py.
Dodaj następujący kod, aby zaimportować wymagane moduły z zestawu SDK urządzenia:
```
import time
from azure.iot.device import IoTHubModuleClient
```
Dodaj następujący kod źródłowy języka. Zastąp wartość symbolu [IoTHub Device Connection String] zastępczego urządzeniem parametry połączenia, które zostało wyświetlone podczas rejestrowania urządzenia w usłudze IoT Hub:
```
CONNECTION_STRING = "[IoTHub Device Connection String]"
```

Dodaj następujący kod do pliku Report Połączenie ivity.py w celu utworzenia wystąpienia klienta i zaimplementowania funkcji bliźniaczych reprezentacji urządzenia:

def create_client():
    # Instantiate client
    client = IoTHubModuleClient.create_from_connection_string(CONNECTION_STRING)

    # Define behavior for receiving twin desired property patches
    def twin_patch_handler(twin_patch):
        print("Twin patch received:")
        print(twin_patch)

    try:
        # Set handlers on the client
        client.on_twin_desired_properties_patch_received = twin_patch_handler
    except:
        # Clean up in the event of failure
        client.shutdown()

    return client

Dodaj następujący kod na końcu raportu Połączenie ivity.py aby uruchomić aplikację:

def main():
    print ( "Starting the Python IoT Hub Device Twin device sample..." )
    client = create_client()
    print ( "IoTHubModuleClient waiting for commands, press Ctrl-C to exit" )

    try:
        # Update reported properties with cellular information
        print ( "Sending data as reported property..." )
        reported_patch = {"connectivity": "cellular"}
        client.patch_twin_reported_properties(reported_patch)
        print ( "Reported properties updated" )

        # Wait for program exit
        while True:
            time.sleep(1000000)
    except KeyboardInterrupt:
        print ("IoT Hub Device Twin device sample stopped")
    finally:
        # Graceful exit
        print("Shutting down IoT Hub Client")
        client.shutdown()

if __name__ == '__main__':
    main()

Uruchom aplikację urządzenia:
```
python ReportConnectivity.py
```
Powinno zostać wyświetlone potwierdzenie zaktualizowania zgłoszonych właściwości bliźniaczej reprezentacji urządzenia.
Teraz, gdy urządzenie zgłosiło informacje o łączności, powinno zostać wyświetlone w obu zapytaniach. Wróć i ponownie uruchom zapytania:
```
python AddTagsAndQuery.py
```
Tym razem { Identyfikator urządzenia} powinien zostać wyświetlony w obu wynikach zapytania.

W aplikacji urządzenia zobaczysz potwierdzenie odebrania żądanej poprawki bliźniaczej reprezentacji właściwości wysłanej przez aplikację usługi.

W tym artykule opisano następujące zagadnienia:

Dodano metadane urządzenia jako tagi z aplikacji zaplecza
Zgłoszone 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ń usługi IoT Hub

Następne kroki

Aby dowiedzieć się, jak:

Wysyłanie danych telemetrycznych z urządzeń znajduje się w artykule 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.

Share via