Share via

Kom igång med enhetstvillingar (Python)

  • Artikel

Enhetstvillingar är JSON-dokument som lagrar information om enhetstillstånd, som metadata, konfigurationer och villkor. IoT Hub bevarar en enhetstvilling för varje enhet som ansluter till den.

Kommentar

De funktioner som beskrivs i den här artikeln är endast tillgängliga på standardnivån för IoT Hub. Mer information om de grundläggande och standard-/kostnadsfria IoT Hub-nivåerna finns i Välj rätt IoT Hub-nivå för din lösning.

Använd enhetstvillingar för att:

  • Lagra enhetsmetadata från lösningens serverdel.

  • Rapportera aktuell tillståndsinformation, till exempel tillgängliga funktioner och villkor, till exempel den anslutningsmetod som används, från enhetsappen.

  • Synkronisera tillståndet för långvariga arbetsflöden, till exempel inbyggd programvara och konfigurationsuppdateringar, mellan en enhetsapp och en serverdelsapp.

  • Fråga efter enhetens metadata, konfiguration eller tillstånd.

Enhetstvillingar är utformade för synkronisering och för att köra frågor mot enhetskonfigurationer och villkor. Mer information om enhetstvillingar, inklusive när du ska använda enhetstvillingar, finns i Förstå enhetstvillingar.

IoT Hubs lagrar enhetstvillingar som innehåller följande element:

  • Taggar. Enhetsmetadata är endast tillgängliga för lösningens serverdel.

  • Önskade egenskaper. JSON-objekt som kan ändras av lösningens serverdel och kan observeras av enhetsappen.

  • Rapporterade egenskaper. JSON-objekt kan ändras av enhetsappen och kan läsas av lösningens serverdel.

Taggar och egenskaper får inte innehålla matriser, men kan innehålla kapslade objekt.

Följande bild visar enhetstvillingorganisationen:

Skärmbild av ett konceptdiagram för enhetstvillingar.

Dessutom kan lösningens serverdel köra frågor mot enhetstvillingar baserat på alla ovanstående data. Mer information om enhetstvillingar finns i Förstå enhetstvillingar. Mer information om frågor finns i IoT Hub-frågespråk.

Den här artikeln visar hur du gör följande:

  • Använd en simulerad enhetsapp för att rapportera dess anslutningskanal som en rapporterad egenskap på enhetstvillingen.

  • Fråga enheter från serverdelsappen med filter på taggarna och egenskaperna som skapades tidigare.

I den här artikeln skapar du två Python-konsolappar:

  • AddTagsAndQuery.py: en serverdelsapp som lägger till taggar och frågar enhetstvillingar.

  • Rapport Anslut ivity.py: en simulerad enhetsapp som ansluter till din IoT-hubb och rapporterar dess anslutningsvillkor.

Kommentar

Mer information om de SDK-verktyg som är tillgängliga för att skapa både enhets- och serverdelsappar finns i Azure IoT SDK:er.

Förutsättningar

  • Ett aktivt Azure-konto. (Om du inte har något konto kan du skapa ett kostnadsfritt konto på bara några minuter.)

  • En IoT-hubb. Skapa en med CLI eller Azure-portalen.

  • En registrerad enhet. Registrera en i Azure-portalen.

  • Python version 3.7 eller senare rekommenderas. Se till att använda en 32-bitars eller 64-bitars installation beroende på vad som krävs för din konfiguration. Se till att du lägger till Python i den plattformsspecifika miljövariabeln när du uppmanas att göra det under installationen.

  • Kontrollera att port 8883 är öppen i brandväggen. Enhetsexemplet i den här artikeln använder MQTT-protokollet, som kommunicerar via port 8883. Den här porten kan blockeras i vissa företags- och utbildningsnätverksmiljöer. Mer information och sätt att kringgå det här problemet finns i Anslut ing to IoT Hub (MQTT).

Hämta IoT Hub-anslutningssträng

I den här artikeln skapar du en serverdelstjänst som lägger till önskade egenskaper till en enhetstvilling och sedan frågar identitetsregistret för att hitta alla enheter med rapporterade egenskaper som har uppdaterats i enlighet med detta. Tjänsten behöver behörigheten för tjänstanslutning för att ändra önskade egenskaper för en enhetstvilling, och den behöver registerläsningsbehörighet för att köra frågor mot identitetsregistret. Det finns ingen standardprincip för delad åtkomst som bara innehåller dessa två behörigheter, så du måste skapa en.

Följ dessa steg för att skapa en princip för delad åtkomst som beviljar behörigheter för tjänstanslutning och registerläsning och få en anslutningssträng för den här principen:

  1. I Azure-portalen väljer du Resursgrupper. Välj den resursgrupp där hubben finns och välj sedan din hubb i listan över resurser.

  2. I den vänstra rutan i hubben väljer du Principer för delad åtkomst.

  3. Välj Lägg till princip för delad principåtkomst på den översta menyn ovanför listan med principer.

  4. I fönstret Lägg till princip för delad åtkomst till höger anger du ett beskrivande namn för din princip, till exempel serviceAndRegistryRead. Under Behörigheter väljer du Registerläsning och tjänst Anslut och väljer sedan Lägg till.

    Skärmbild som visar hur du lägger till en ny princip för delad åtkomst.

  5. Välj din nya princip i listan över principer.

  6. Välj kopieringsikonen för den primära anslutningssträng och spara värdet.

    Skärmdump som visar hur du hämtar anslutningssträng.

Mer information om principer och behörigheter för delad åtkomst i IoT Hub finns i Åtkomstkontroll och behörigheter.

Skapa en tjänstapp som uppdaterar önskade egenskaper och frågar tvillingar

I det här avsnittet skapar du en Python-konsolapp som lägger till platsmetadata till enhetstvillingen som är associerad med ditt {Enhets-ID}. Appen frågar IoT Hub efter enheter som finns i USA och frågar sedan enheter som rapporterar en mobilnätverksanslutning.

  1. Öppna en kommandotolk i arbetskatalogen och installera Azure IoT Hub Service SDK för Python.

    pip install azure-iot-hub

  2. Skapa en ny AddTagsAndQuery.py fil med hjälp av en textredigerare.

  3. Lägg till följande kod för att importera de moduler som krävs från SDK:n:

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

  4. Lägg till följande kod: Ersätt [IoTHub Connection String] med IoT-hubben anslutningssträng du kopierade i Hämta IoT Hub-anslutningssträng. Ersätt [Device Id] med enhets-ID :t (namnet) från din registrerade enhet i IoT-hubben.

    IOTHUB_CONNECTION_STRING = "[IoTHub Connection String]"
DEVICE_ID = "[Device Id]"

  5. Lägg till följande kod i filen 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")

    IoTHubRegistryManager-objektet exponerar alla metoder som krävs för att interagera med enhetstvillingar från tjänsten. Koden initierar först IoTHubRegistryManager-objektet , uppdaterar sedan enhetstvillingen för DEVICE_ID och kör slutligen två frågor. Den första väljer endast enhetstvillingar för enheter som finns i Redmond43-anläggningen och den andra förfinar frågan för att endast välja de enheter som också är anslutna via ett mobilnät.

  6. Lägg till följande kod i slutet av AddTagsAndQuery.py för att implementera funktionen iothub_service_sample_run :

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

    iothub_service_sample_run()

  7. Kör programmet med:

    python AddTagsAndQuery.py

    Du bör se en enhet i resultatet för frågan som frågar efter alla enheter som finns i Redmond43 och ingen för frågan som begränsar resultatet till enheter som använder ett mobilnät. I nästa avsnitt skapar du en enhetsapp som använder ett mobilnät och kör frågan igen för att se hur den ändras.

    Skärmbild av den första frågan som visar alla enheter i Redmond.

Skapa en enhetsapp som uppdaterar rapporterade egenskaper

I det här avsnittet skapar du en Python-konsolapp som ansluter till din hubb som ditt {Enhets-ID} och uppdaterar sedan enhetstvillingens rapporterade egenskaper för att bekräfta att den är ansluten med ett mobilnät.

  1. Från en kommandotolk i arbetskatalogen installerar du Azure IoT Hub Device SDK för Python:

    pip install azure-iot-device

  2. Skapa en ny rapport Anslut ivity.py fil med hjälp av en textredigerare.

  3. Lägg till följande kod för att importera de moduler som krävs från enhetens SDK:

    import time
from azure.iot.device import IoTHubModuleClient

  4. Lägg till följande kod: [IoTHub Device Connection String] Ersätt platshållarvärdet med den enhet anslutningssträng du såg när du registrerade en enhet i IoT Hub:

    CONNECTION_STRING = "[IoTHub Device Connection String]"

  5. Lägg till följande kod i filen Report Anslut ivity.py för att instansiera en klient och implementera funktionerna för enhetstvillingar:

    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

  6. Lägg till följande kod i slutet av rapporten Anslut ivity.py för att köra programmet:

    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()

  7. Kör enhetsappen:

    python ReportConnectivity.py

    Du bör se en bekräftelse på att de rapporterade egenskaperna för enhetstvillingen har uppdaterats.

    uppdatera rapporterade egenskaper från enhetsappen

  8. Nu när enheten har rapporterat sin anslutningsinformation bör den visas i båda frågorna. Gå tillbaka och kör frågorna igen:

    python AddTagsAndQuery.py

    Den här gången bör ditt {Enhets-ID} visas i båda frågeresultaten.

    andra frågan i tjänstappen

    I enhetsappen ser du en bekräftelse på att den önskade egenskapstvillingkorrigeringen som skickades av tjänstappen togs emot.

    ta emot önskade egenskaper i enhetsappen

Den här artikeln innehåller följande avsnitt:

  • Enhetsmetadata har lagts till som taggar från en serverdelsapp
  • Rapporterad anslutningsinformation för enheter i enhetstvillingen
  • Efterfrågade information om enhetstvillingen med hjälp av frågespråket IoT Hub

Nästa steg

Om du vill ta reda på hur du: