디바이스 쌍 시작(Python)

아티클
03/05/2024

디바이스 쌍은 메타데이터, 구성, 조건을 비롯한 디바이스 상태 정보를 저장하는 JSON 문서입니다. IoT Hub는 여기에 연결하는 각 디바이스에 대해 하나의 디바이스 쌍을 유지합니다.

참고 항목

이 문서에서 설명하는 기능은 IoT Hub의 표준 계층에서만 사용할 수 있습니다. 기본 및 표준/무료 IoT Hub 계층에 대한 자세한 내용은 솔루션에 적합한 IoT Hub 계층 선택을 참조하세요.

디바이스 쌍의 용도:

솔루션 백 엔드의 디바이스 메타데이터를 저장합니다.
디바이스 앱의 사용 가능한 기능 및 상태(예: 사용된 연결 방법)와 같은 현재 상태 정보를 보고합니다.
디바이스 앱과 백 엔드 앱 간에 장기 실행 워크플로(예: 펌웨어 및 구성 업데이트)의 상태를 동기화합니다.
디바이스 메타데이터, 구성 또는 상태를 쿼리합니다.

디바이스 쌍은 디바이스 구성 및 상태를 동기화하고 쿼리하기 위해 설계되었습니다. 디바이스 쌍을 사용하는 경우를 포함한 디바이스 쌍에 대한 자세한 내용은 디바이스 쌍 이해를 참조하세요.

IoT 허브는 다음 요소를 포함하는 디바이스 쌍을 저장합니다.

태그. 솔루션 백 엔드만 액세스할 수 있는 디바이스 메타데이터입니다.
desired 속성. 솔루션 백 엔드에서 수정할 수 있고 디바이스 앱에서 관찰할 수 있는 JSON 개체입니다.
reported 속성. 디바이스 앱에서 수정할 수 있고 솔루션 백 엔드에서 읽을 수 있는 JSON 개체입니다.

태그 및 속성은 배열을 포함할 수 없지만 중첩된 개체를 포함할 수 있습니다.

다음 그림은 디바이스 쌍 조직을 보여 줍니다.

디바이스 쌍 개념 다이어그램의 스크린샷

또한 솔루션 백 엔드는 위의 모든 데이터를 기반으로 하는 디바이스 쌍을 쿼리할 수 있습니다. 디바이스 쌍에 대한 자세한 내용은 디바이스 쌍 이해를 참조하세요. 쿼리에 대한 자세한 내용은 IoT Hub 쿼리 언어를 참조하세요.

이 문서는 다음을 수행하는 방법을 보여줍니다.

시뮬레이션된 디바이스 앱을 사용하여 해당 연결 채널을 디바이스 쌍의 reported 속성으로 보고합니다.
이전에 만든 태그 및 속성에 필터를 사용하여 백 엔드 앱에서 디바이스를 쿼리합니다.

이 문서에서는 다음 두 개의 Python 콘솔 앱을 만듭니다.

AddTagsAndQuery.py: 태그를 추가하고 디바이스 쌍을 쿼리하는 백 엔드 앱입니다.
ReportConnectivity.py: IoT Hub에 연결하고 연결 상태를 보고하는 시뮬레이션된 디바이스 앱입니다.

참고 항목

디바이스 및 백 엔드 앱을 모두 빌드하는 데 사용할 수 있는 SDK 도구에 대한 자세한 내용은 Azure IoT SDK를 참조하세요.

필수 조건

활성 Azure 계정. 계정이 없는 경우 몇 분 만에 무료 계정을 만들 수 있습니다.
IoT 허브. CLI 또는 Azure Portal을 사용하여 만듭니다.
등록된 디바이스. Azure Portal에 하나를 등록합니다.
Python 버전 3.7 이상을 사용하는 것이 좋습니다. 설치 프로그램의 요구 사항에 따라 32비트 또는 64비트 설치를 사용해야 합니다. 설치하는 동안 메시지가 나타나면 플랫폼별 환경 변수에 Python을 추가해야 합니다.
방화벽에서 포트 8883이 열려 있는지 확인합니다. 이 문서의 디바이스 샘플은 포트 8883을 통해 통신하는 MQTT 프로토콜을 사용합니다. 이 포트는 일부 회사 및 교육용 네트워크 환경에서 차단될 수 있습니다. 이 문제를 해결하는 자세한 내용과 방법은 IoT Hub에 연결(MQTT)을 참조하세요.

IoT Hub 연결 문자열 가져오기

이 문서에서는 디바이스 쌍에 원하는 속성을 추가하고 ID 레지스트리를 쿼리하여 그에 따라 업데이트된 보고된 속성이 있는 모든 디바이스를 찾는 백 엔드 서비스를 만듭니다. 서비스는 디바이스 쌍의 원하는 속성을 수정하려면 서비스 연결 권한이 필요하며, ID 레지스트리를 쿼리하기 위한 레지스트리 읽기 권한이 필요합니다. 이러한 두 가지 권한만 포함하는 기본 공유 액세스 정책은 없으므로 만들어야 합니다.

서비스 연결 및 레지스트리 읽기 권한을 부여하는 공유 액세스 정책을 만들고 이 정책에 대한 연결 문자열을 가져오려면 다음 단계를 수행합니다.

Azure Portal에서 리소스 그룹을 선택합니다. 허브가 있는 리소스 그룹을 선택한 다음, 리소스 목록에서 허브를 선택합니다.
허브의 왼쪽 창에서 공유 액세스 정책을 선택합니다.
정책 목록 위의 상단 메뉴에서 공유 정책 액세스 정책 추가를 선택합니다.
오른쪽의 공유 액세스 정책 추가 창에서 정책에 사용할 설명형 이름(예: serviceAndRegistryRead)을 입력합니다. 권한에서 레지스트리 읽기 및 서비스 연결을 선택한 다음 추가를 선택합니다.
정책 목록에서 새 정책을 선택합니다.
기본 연결 문자열의 복사 아이콘을 선택하고 값을 저장합니다.

IoT Hub 공유 액세스 정책 및 사용 권한에 대한 자세한 내용은 액세스 제어 및 권한을 참조하세요.

원하는 속성을 업데이트하고 쌍을 쿼리하는 서비스 앱 만들기

이 섹션에서는 {디바이스 ID}와 연결된 디바이스 쌍에 위치 메타데이터를 추가하는 Python 콘솔 앱을 만듭니다. 앱은 미국에 있는 디바이스에 대한 IoT 허브를 쿼리한 다음, 셀룰러 네트워크 연결을 보고하는 디바이스를 쿼리합니다.

작업 디렉터리에서 명령 프롬프트를 열고 Python용 Azure IoT Hub 서비스 SDK를 설치합니다.
```
pip install azure-iot-hub
```
텍스트 편집기를 사용하여 새 AddTagsAndQuery.py 파일을 만듭니다.

SDK 서비스에서 필요한 모듈을 가져오는 다음 코드를 추가합니다.

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

다음 코드를 추가합니다. [IoTHub Connection String]을 IoT Hub 연결 문자열 가져오기에서 복사한 IoT hub 연결 문자열로 바꿉니다. [Device Id]를 IoT 허브에 등록된 디바이스의 디바이스 ID(이름)로 바꿉니다.
```
IOTHUB_CONNECTION_STRING = "[IoTHub Connection String]"
DEVICE_ID = "[Device Id]"
```

다음 코드를 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 개체는 서비스의 디바이스 쌍과 상호 작용하는 데 필요한 모든 메서드를 표시합니다. 코드는 먼저 IoTHubRegistryManager 개체를 초기화한 다음, DEVICE_ID에 대한 디바이스 쌍을 업데이트하고, 마지막으로 두 개의 쿼리를 실행합니다. 첫 번째는 Redmond43 공장에 있는 디바이스의 디바이스 쌍만 선택하고, 두 번째는 셀룰러 네트워크를 통해 연결된 디바이스만 선택하도록 쿼리를 구체화합니다.

AddTagsAndQuery.py의 끝부분에 다음 코드를 추가하고 iothub_service_sample_run 함수를 구현합니다.

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

    iothub_service_sample_run()

다음으로 애플리케이션을 실행합니다.
```
python AddTagsAndQuery.py
```
Redmond43에 위치한 모든 디바이스를 요청하는 쿼리에 대한 결과로는 하나의 디바이스를 보고 셀룰러 네트워크를 사용하는 디바이스에 대해서는 결과를 제한하는 쿼리에 대한 결과로는 아무 디바이스도 볼 수 없어야 합니다. 다음 섹션에서는 셀룰러 네트워크를 사용하는 디바이스 앱을 만들고 이 쿼리를 다시 실행하여 변경 방법을 확인합니다.

보고된 속성을 업데이트하는 디바이스 앱 만들기

이 섹션에서는 {디바이스 ID}로 허브에 연결하는 Python 콘솔 앱을 만든 다음, 셀룰러 네트워크를 사용하여 연결되도록 디바이스 쌍의 reported 속성을 업데이트합니다.

작업 디렉터리의 명령 프롬프트에서 Python용 Azure IoT Hub 디바이스 SDK를 설치합니다.
```
pip install azure-iot-device
```
텍스트 편집기를 사용하여 새 ReportConnectivity.py 파일을 만듭니다.
디바이스 SDK에서 필요한 모듈을 가져오는 다음 코드를 추가합니다.
```
import time
from azure.iot.device import IoTHubModuleClient
```
다음 코드를 추가합니다. [IoTHub Device Connection String] 자리 표시자 값을 IoT Hub에서 디바이스를 등록할 때 확인한 디바이스 연결 문자열로 바꿉니다.
```
CONNECTION_STRING = "[IoTHub Device Connection String]"
```

다음 코드를 ReportConnectivity.py 파일에 추가하여 클라이언트를 인스턴스화하고 디바이스 쌍 기능을 구현합니다.

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

ReportConnectivity.py의 끝부분에 다음 코드를 추가하여 애플리케이션을 실행합니다.

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

디바이스 앱 실행:
```
python ReportConnectivity.py
```
디바이스 쌍 reported 속성이 업데이트되었다는 확인 메시지가 표시됩니다.
디바이스가 연결 정보를 보고했으므로 두 쿼리 모두에 나타나야 합니다. 뒤로 돌아가서 쿼리를 다시 실행합니다.
```
python AddTagsAndQuery.py
```
이번에는 {디바이스 ID}가 두 쿼리 결과에 모두 나타나야 합니다.

디바이스 앱에서 서비스 앱이 보낸 desired 속성 쌍 패치가 수신되었다는 확인 메시지가 표시됩니다.

이 문서에서는 다음 작업을 수행합니다.

백 엔드 앱에서 태그로 디바이스 메타데이터 추가
디바이스 쌍에서 보고된 디바이스 연결 정보
IoT Hub 쿼리 언어를 사용하여 디바이스 쌍 정보 쿼리

다음 단계

방법을 알아보려면 다음을 참조하세요.

디바이스에서 원격 분석을 보냅니다. 빠른 시작: IoT 플러그 앤 플레이 디바이스에서 Azure IoT Hub로 원격 분석 보내기 문서를 참조하세요.
디바이스 쌍의 desired 속성을 사용하여 디바이스를 구성합니다. 자습서: 백 엔드 서비스에서 디바이스 구성을 참조하세요.
사용자가 제어하는 앱에서 팬을 켜는 것과 같이 대화형으로 디바이스를 제어합니다. 빠른 시작: IoT Hub에 연결된 디바이스 제어를 참조하세요.