디바이스 쌍 시작(.NET)

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

참고 항목

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

디바이스 쌍의 용도:

  • 솔루션 백 엔드의 디바이스 메타데이터를 저장합니다.

  • 디바이스 앱의 사용 가능한 기능 및 상태(예: 사용된 연결 방법)와 같은 현재 상태 정보를 보고합니다.

  • 디바이스 앱과 백 엔드 앱 간에 장기 실행 워크플로(예: 펌웨어 및 구성 업데이트)의 상태를 동기화합니다.

  • 디바이스 메타데이터, 구성 또는 상태를 쿼리합니다.

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

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

  • 태그. 솔루션 백 엔드만 액세스할 수 있는 디바이스 메타데이터입니다.

  • desired 속성. 솔루션 백 엔드에서 수정할 수 있고 디바이스 앱에서 관찰할 수 있는 JSON 개체입니다.

  • reported 속성. 디바이스 앱에서 수정할 수 있고 솔루션 백 엔드에서 읽을 수 있는 JSON 개체입니다.

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

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

Screenshot of a device twin concept diagram.

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

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

  • 시뮬레이션된 디바이스 앱을 사용하여 해당 연결 채널을 디바이스 쌍의 reported 속성으로 보고합니다.

  • 이전에 만든 태그 및 속성에 필터를 사용하여 백 엔드 앱에서 디바이스를 쿼리합니다.

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

  • AddTagsAndQuery: 태그를 추가하고 디바이스 쌍을 쿼리하는 백 엔드 앱입니다.

  • ReportConnectivity: IoT Hub에 연결하고 연결 상태를 보고하는 시뮬레이션된 디바이스 앱입니다.

참고 항목

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

필수 조건

  • Visual Studio.

  • IoT 허브. CLI 또는 Azure Portal을 사용하여 만듭니다.

  • 등록된 디바이스. Azure Portal에 하나를 등록합니다.

  • 방화벽에서 포트 8883이 열려 있는지 확인합니다. 이 문서의 디바이스 샘플은 포트 8883을 통해 통신하는 MQTT 프로토콜을 사용합니다. 이 포트는 일부 회사 및 교육용 네트워크 환경에서 차단될 수 있습니다. 이 문제를 해결하는 자세한 내용과 방법은 IoT Hub에 연결(MQTT)을 참조하세요.

IoT Hub 연결 문자열 가져오기

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

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

  1. Azure Portal에서 리소스 그룹을 선택합니다. 허브가 있는 리소스 그룹을 선택한 다음, 리소스 목록에서 허브를 선택합니다.

  2. 허브의 왼쪽 창에서 공유 액세스 정책을 선택합니다.

  3. 정책 목록 위의 상단 메뉴에서 공유 정책 액세스 정책 추가를 선택합니다.

  4. 오른쪽의 공유 액세스 정책 추가 창에서 정책에 사용할 설명형 이름(예: serviceAndRegistryRead)을 입력합니다. 권한에서 레지스트리 읽기서비스 연결을 선택한 다음 추가를 선택합니다.

    Screen capture that shows how to add a new shared access policy.

  5. 정책 목록에서 새 정책을 선택합니다.

  6. 기본 연결 문자열의 복사 아이콘을 선택하고 값을 저장합니다.

    Screen capture that shows how to retrieve the connection string.

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

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

이 섹션에서는 myDeviceId로 허브에 연결하는 .NET 콘솔 앱을 만든 다음, reported 속성을 업데이트하여 셀룰러 네트워크를 사용하여 연결되었는지 확인합니다.

  1. Visual Studio를 열고 새 프로젝트 만들기를 선택합니다.

  2. 콘솔 앱(.NET Framework), 다음을 차례로 선택합니다.

  3. 새 프로젝트 구성에서 프로젝트 이름을 ReportConnectivity로 지정한 후, 다음을 선택합니다.

  4. 솔루션 탐색기에서 ReportConnectivity 프로젝트를 마우스 오른쪽 단추로 클릭한 다음, NuGet 패키지 관리를 선택합니다.

  5. 기본 .NET Framework를 유지한 다음, 만들기를 선택하여 프로젝트를 만듭니다.

  6. 찾아보기를 선택하고 Microsoft.Azure.Devices.Client를 검색한 후 선택합니다. 설치를 선택합니다.

    이 단계에서는 Azure IoT 디바이스 SDK NuGet 패키지 및 해당 종속 항목에 참조를 다운로드, 설치 및 추가합니다.

  7. Program.cs 파일 위에 다음 using 문을 추가합니다.

    using Microsoft.Azure.Devices.Client;
    using Microsoft.Azure.Devices.Shared;
    using Newtonsoft.Json;
    
  8. Program 클래스에 다음 필드를 추가합니다. {device connection string}을 IoT Hub에 디바이스를 등록할 때 본 디바이스 연결 문자열로 바꿉니다.

    static string DeviceConnectionString = "HostName=<yourIotHubName>.azure-devices.net;DeviceId=<yourIotDeviceName>;SharedAccessKey=<yourIotDeviceAccessKey>";
    static DeviceClient Client = null;
    
  9. Program 클래스에 다음 메서드를 추가합니다.

    public static async void InitClient()
    {
        try
        {
            Console.WriteLine("Connecting to hub");
            Client = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
              TransportType.Mqtt);
            Console.WriteLine("Retrieving twin");
            await Client.GetTwinAsync();
        }
        catch (Exception ex)
        {
            Console.WriteLine();
            Console.WriteLine("Error in sample: {0}", ex.Message);
        }
    }
    

    Client 개체는 서비스의 디바이스 쌍을 조작하는 데 필요한 모든 메서드를 표시합니다. 위에 표시된 코드는 Client 개체를 초기화한 다음 myDeviceId에 대한 디바이스 쌍을 검색합니다.

  10. Program 클래스에 다음 메서드를 추가합니다.

    public static async void ReportConnectivity()
    {
        try
        {
            Console.WriteLine("Sending connectivity data as reported property");
    
            TwinCollection reportedProperties, connectivity;
            reportedProperties = new TwinCollection();
            connectivity = new TwinCollection();
            connectivity["type"] = "cellular";
            reportedProperties["connectivity"] = connectivity;
            await Client.UpdateReportedPropertiesAsync(reportedProperties);
        }
        catch (Exception ex)
        {
            Console.WriteLine();
            Console.WriteLine("Error in sample: {0}", ex.Message);
        }
    }
    

    위의 코드는 myDeviceId의 reported 속성을 연결 정보로 업데이트합니다.

  11. 마지막으로 Main 메서드에 다음 줄을 추가합니다.

    try
    {
        InitClient();
        ReportConnectivity();
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error in sample: {0}", ex.Message);
    }
    Console.WriteLine("Press Enter to exit.");
    Console.ReadLine();
    
  12. 솔루션 탐색기에서 솔루션을 마우스 오른쪽 단추로 클릭하고 시작 프로젝트 설정을 선택합니다.

  13. 퍼블릭 속성>시작 프로젝트에서 여러 개의 시작 프로젝트를 선택합니다. ReportConnectivity의 경우 작업으로 시작을 선택합니다. 확인 을 선택하여 변경 내용을 저장합니다.

  14. ReportConnectivity 프로젝트를 마우스 오른쪽 단추로 클릭하고 디버그를 선택한 후 새 인스턴스 시작을 선택하여 이 앱을 실행합니다. 앱이 쌍 정보를 가져오면 연결을 보고된 속성으로 보내는 메시지가 표시됩니다.

    Run device app to report connectivity

    디바이스가 연결 정보를 보고한 후에는 두 쿼리 모두에 나타나야 합니다.

  15. AddTagsAndQuery 프로젝트를 마우스 오른쪽 단추로 클릭하고 디버그>새 인스턴스 시작을 선택하여 쿼리를 다시 실행합니다. 이번에는 myDeviceId가 두 쿼리 결과에 모두 나타나야 합니다.

    Device connectivity reported successfully

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

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

  1. Visual Studio에서 파일 > 새로 만들기 > 프로젝트를 선택합니다. 새 프로젝트 만들기에서 C#에 대해 콘솔 앱(.NET Framework)을 선택한 후 다음을 선택합니다.

  2. 새 프로젝트 구성에서 프로젝트 이름을 AddTagsAndQuery로 지정하고 다음을 선택합니다.

    Screenshot of how to create a new Visual Studio project.

  3. .NET Framework의 기본 버전을 수락한 다음 만들기를 선택하여 프로젝트를 만듭니다.

  4. 솔루션 탐색기에서 AddTagsAndQuery 프로젝트를 마우스 오른쪽 단추로 클릭한 다음, NuGet 패키지 관리를 선택합니다.

  5. 찾아보기를 선택하고 Microsoft.Azure.Devices를 검색한 후 선택합니다. 설치를 선택합니다.

    NuGet Package Manager window

    이 단계에서는 Azure IoT 서비스 SDK NuGet 패키지 및 해당 종속 항목에 참조를 다운로드, 설치 및 추가합니다.

  6. Program.cs 파일 위에 다음 using 문을 추가합니다.

    using Microsoft.Azure.Devices;
    
  7. Program 클래스에 다음 필드를 추가합니다. {iot hub connection string}IoT Hub 연결 문자열 가져오기에서 복사한 IoT hub 연결 문자열로 바꿉니다.

    static RegistryManager registryManager;
    static string connectionString = "{iot hub connection string}";
    
  8. Program 클래스에 다음 메서드를 추가합니다.

    public static async Task AddTagsAndQuery()
    {
        var twin = await registryManager.GetTwinAsync("myDeviceId");
        var patch =
            @"{
                tags: {
                    location: {
                        region: 'US',
                        plant: 'Redmond43'
                    }
                }
            }";
        await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);
    
        var query = registryManager.CreateQuery(
          "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
        var twinsInRedmond43 = await query.GetNextAsTwinAsync();
        Console.WriteLine("Devices in Redmond43: {0}", 
          string.Join(", ", twinsInRedmond43.Select(t => t.DeviceId)));
    
        query = registryManager.CreateQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
        var twinsInRedmond43UsingCellular = await query.GetNextAsTwinAsync();
        Console.WriteLine("Devices in Redmond43 using cellular network: {0}", 
          string.Join(", ", twinsInRedmond43UsingCellular.Select(t => t.DeviceId)));
    }
    

    RegistryManager 클래스는 서비스의 디바이스 쌍을 조작하는 데 필요한 모든 메서드를 표시합니다. 이전 코드에서는 registryManager 개체를 초기화한 다음, myDeviceId에 대한 디바이스 쌍을 검색하고, 마지막으로 원하는 위치 정보로 태그를 업데이트합니다.

    업데이트한 후 두 개의 쿼리를 실행합니다. 첫 번째는 Redmond43 공장에 위치한 디바이스의 디바이스 쌍만을 선택하고, 두 번째는 또한 셀룰러 네트워크를 통해서 연결된 디바이스만을 선택하기 위해 쿼리를 구체화합니다.

    이전 코드는 쿼리 개체를 만들 때 반환되는 최대 문서 수를 지정합니다. query 개체에는 모든 결과를 검색하기 위해 여러 번 GetNextAsTwinAsync 메서드를 호출하는 데 사용할 수 있는 HasMoreResults 부울 속성이 들어 있습니다. GetNextAsJson이라는 메서드는 디바이스 쌍이 아닌 결과(예: 집계 쿼리의 결과)에 대해 사용할 수 있습니다.

  9. 마지막으로 Main 메서드에 다음 줄을 추가합니다.

    registryManager = RegistryManager.CreateFromConnectionString(connectionString);
    AddTagsAndQuery().Wait();
    Console.WriteLine("Press Enter to exit.");
    Console.ReadLine();
    
  10. AddTagsAndQuery 프로젝트를 마우스 오른쪽 단추로 클릭하고 디버그를 선택한 후 새 인스턴스 시작을 선택하여 이 애플리케이션을 실행합니다. Redmond43에 위치한 모든 디바이스를 요청하는 쿼리에 대한 결과로는 하나의 디바이스를 보고 셀룰러 네트워크를 사용하는 디바이스에 대해서는 결과를 제한하는 쿼리에 대한 결과로는 아무 디바이스도 볼 수 없어야 합니다.

    Query results in window

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

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

다음 단계

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