쌍 디바이스 시작

개요

이 문서에서는 .NET용 Azure IoT SDK를 사용하여 디바이스 쌍에 대한 디바이스 및 백 엔드 서비스 애플리케이션 코드를 만드는 방법을 설명합니다.

디바이스 애플리케이션 만들기

디바이스 애플리케이션은 reported 쌍 속성을 읽고 쓸 수 있으며, 백 엔드 애플리케이션 또는 IoT Hub에서 설정한 원하는 쌍 속성 변경 내용을 알 수 있습니다.

이 섹션에서는 디바이스 애플리케이션 코드를 사용하여 다음을 수행하도록 하는 방법을 설명합니다.

• 디바이스 쌍 검색 및 reported 속성 검사
• reported 디바이스 쌍 속성 업데이트
• 원하는 속성 업데이트 콜백 처리기 만들기

디바이스 NuGet 패키지 추가

C#으로 작성된 디바이스 클라이언트 애플리케이션에는 Microsoft.Azure.Devices.Client NuGet 패키지가 필요합니다.

디바이스에 연결

DeviceClient 클래스는 서비스의 디바이스 쌍을 조작하는 데 필요한 모든 메서드를 표시합니다.

디바이스 연결 문자열 및 연결 전송 프로토콜과 함께 CreateFromConnectionString 메서드를 사용하여 디바이스에 연결합니다.

CreateFromConnectionString TransportType 전송 프로토콜 매개 변수는 다음 전송 프로토콜을 지원합니다.

• Mqtt
• Mqtt_WebSocket_Only
• Mqtt_Tcp_Only
• Amqp
• Amqp_WebSocket_Only
• Amqp_Tcp_Only

Http1 프로토콜은 디바이스 쌍 업데이트에 대해 지원되지 않습니다.

이 예제에서는 Mqtt 전송 프로토콜을 사용하여 디바이스에 연결합니다.

using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;
using Newtonsoft.Json;

static string DeviceConnectionString = "{IoT hub device connection string}";
static _deviceClient = null;
_deviceClient = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
   TransportType.Mqtt);

디바이스 쌍 검색 및 속성 검사

GetTwinAsync를 호출하여 현재 디바이스 쌍 속성을 검색합니다. Properties, Status, Tags 및 Version을 포함하여 Twin JSON 데이터의 특정 영역에 액세스하는 데 사용할 수 있는 많은 Twin 개체 속성이 있습니다.

이 예제에서는 디바이스 쌍 속성을 검색하고 쌍 값을 JSON 형식으로 출력합니다.

Console.WriteLine("Retrieving twin...");
Twin twin = await _deviceClient.GetTwinAsync();
Console.WriteLine("\tInitial twin value received:");
Console.WriteLine($"\t{twin.ToJson()}");

reported 디바이스 쌍 속성 업데이트

reported 쌍 속성을 업데이트하려면 다음을 수행합니다.

1. reported 속성 업데이트에 대한 TwinCollection 개체 만들기
2. TwinCollection 개체 내에서 하나 이상의 reported 속성 업데이트
3. UpdateReportedPropertiesAsync를 사용하여 reported 속성 변경 내용을 IoT Hub 서비스에 푸시

예시:

try
{
Console.WriteLine("Sending sample start time as reported property");
TwinCollection reportedProperties = new TwinCollection();
reportedProperties["DateTimeLastAppLaunch"] = DateTime.UtcNow;
await _deviceClient.UpdateReportedPropertiesAsync(reportedProperties);
}
catch (Exception ex)
{
   Console.WriteLine();
   Console.WriteLine("Error in sample: {0}", ex.Message);
}

원하는 속성 업데이트 콜백 처리기 만들기

콜백 처리기 메서드 이름을 SetDesiredPropertyUpdateCallbackAsync에 전달하여 디바이스 쌍에서 desired 속성이 변경될 때 실행되는 desired 속성 업데이트 콜백 처리기를 만듭니다.

예를 들어 이 호출은 desired 속성이 변경될 때마다 OnDesiredPropertyChangedAsync 메서드에 알리도록 시스템을 설정합니다.

await _deviceClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

쌍 속성은 TwinCollection 콜백 메서드에 전달되며 KeyValuePair 구조체로 검사할 수 있습니다.

이 예제에서는 desired 속성 업데이트를 TwinCollection으로 수신한 다음, KeyValuePair 컬렉션 업데이트를 반복하고 출력합니다. KeyValuePair 컬렉션을 반복한 후 코드는 UpdateReportedPropertiesAsync를 호출하여 마지막으로 업데이트된 시간을 최신 상태로 유지하도록 DateTimeLastDesiredPropertyChangeReceived reported 속성을 업데이트합니다.

private async Task OnDesiredPropertyChangedAsync(TwinCollection desiredProperties, object userContext)
{
   var reportedProperties = new TwinCollection();

   Console.WriteLine("\tDesired properties requested:");
   Console.WriteLine($"\t{desiredProperties.ToJson()}");

   // For the purpose of this sample, we'll blindly accept all twin property write requests.
   foreach (KeyValuePair<string, object> desiredProperty in desiredProperties)
   {
         Console.WriteLine($"Setting {desiredProperty.Key} to {desiredProperty.Value}.");
         reportedProperties[desiredProperty.Key] = desiredProperty.Value;
   }

   Console.WriteLine("\tAlso setting current time as reported property");
   reportedProperties["DateTimeLastDesiredPropertyChangeReceived"] = DateTime.UtcNow;

   await _deviceClient.UpdateReportedPropertiesAsync(reportedProperties);
}

SDK 디바이스 샘플

.NET용 Azure IoT SDK는 디바이스 쌍 작업을 처리하는 디바이스 앱의 작업 샘플을 제공합니다. 자세한 내용은 TwinSample을 참조하세요.

백 엔드 애플리케이션 만들기

백 엔드 애플리케이션은 다음을 수행합니다.

• IoT Hub를 통해 디바이스에 연결합니다.
• reported 및 desired 속성을 읽고, 디바이스 desired 속성을 작성하고, 디바이스 쿼리를 실행할 수 있습니다.

RegistryManager 클래스는 서비스의 디바이스 쌍과 상호 작용하는 백 엔드 애플리케이션을 만드는 데 필요한 모든 메서드를 표시합니다.

이 섹션에서는 다음을 수행하는 백 엔드 애플리케이션 코드를 만드는 방법을 설명합니다.

• 디바이스 쌍 필드 읽기 및 업데이트
• 디바이스 쌍 쿼리 만들기

서비스 NuGet 패키지 추가

백 엔드 서비스 애플리케이션에는 Microsoft.Azure.Devices NuGet 패키지가 필요합니다.

IoT Hub에 연결

CreateFromConnectionString을 사용하여 백 엔드 애플리케이션을 디바이스에 연결합니다. 필수 구성 요소 섹션에서 만든 IoT Hub 서비스 연결 문자열을 매개 변수로 제공합니다.

using Microsoft.Azure.Devices;
static RegistryManager registryManager;
static string connectionString = "{IoT hub service connection string}";
registryManager = RegistryManager.CreateFromConnectionString(connectionString);

디바이스 쌍 필드 읽기 및 업데이트

GetTwinAsync를 호출하여 Twin 개체로 현재 디바이스 쌍 필드를 가져올 수 있습니다.

Twin 클래스에는 디바이스 쌍의 각 섹션에 해당하는 속성이 포함됩니다. Twin 클래스 속성을 사용하여 디바이스 쌍 필드를 보고 업데이트합니다. UpdateTwinAsync를 사용하여 디바이스에 업데이트를 쓰기 전에 Twin 개체 속성을 사용하여 여러 쌍 필드를 업데이트할 수 있습니다.

쌍 필드 업데이트를 수행한 후 UpdateTwinAsync를 호출하여 Twin 개체 필드 업데이트를 디바이스에 다시 씁니다. 오류 처리기와 함께 try 및 catch 논리를 사용하여 UpdateTwinAsync에서 잘못된 형식의 패치 오류를 catch합니다.

디바이스 쌍 태그 읽기 및 업데이트

디바이스 쌍 Tags 속성을 사용하여 디바이스 태그 정보를 읽고 씁니다.

쌍 개체를 사용하여 태그 업데이트

이 예제는 location 태그 패치를 만들고 Tags 속성을 사용하여 Twin 개체에 할당한 다음, UpdateTwinAsync를 사용하여 패치를 적용합니다.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

// Create the tag patch
var tagspatch =
   @"{
   tags: {
         location: {
            region: 'US',
            plant: 'Redmond43'
         }
   }
}";

// Assign the patch to the Twin object
twin.Tags["location"] = tagspatch;

// Apply the patch to update the device twin tags section
try
{
   await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);
}
catch (Exception e)
{
   console.WriteLine("Twin update failed.", e.Message);
}

JSON 문자열을 사용하여 태그 업데이트

JSON 형식 디바이스 쌍 정보 업데이트 패치를 만들고 적용할 수 있습니다. IoT Hub는 올바르게 형식이 지정된 경우 패치를 구문 분석하고 적용합니다.

이 예제에서는 GetTwinAsync를 호출하여 현재 디바이스 쌍 필드를 Twin 개체로 가져오고, 지역 및 공장 위치 정보를 사용하여 JSON 형식의 tag 패치를 만든 다음, UpdateTwinAsync를 호출하여 디바이스 쌍을 업데이트하는 패치를 적용합니다. UpdateTwinAsync가 실패하면 오류 메시지가 표시됩니다.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

// Create the JSON tags patch
var patch =
   @"{
      tags: {
            location: {
               region: 'US',
               plant: 'Redmond43'
            }
      }
   }";
// Apply the patch to update the device twin tags
try
{
   await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);
}
catch (Exception e)
{
   console.WriteLine("Twin update failed.", e.Message);
}

쌍 desired 속성 보기 및 업데이트

디바이스 쌍 TwinProperties.Desired 속성을 사용하여 디바이스 desired 속성 정보를 읽고 씁니다. JSON 형식 패치를 사용하여 쌍 Desired 속성을 업데이트합니다.

이 예제에서는 GetTwinAsync를 호출하여 현재 디바이스 쌍 필드를 Twin 개체로 검색하고, 쌍 speed desired 속성을 업데이트한 다음, UpdateTwinAsync를 호출하여 디바이스 쌍을 업데이트하는 Twin 개체를 적용합니다.

// Retrieve the device twin
var twin = await registryManager.GetTwinAsync("myDeviceId");

twin.Properties.Desired["speed"] = "type: '5G'";
await registryManager.UpdateTwinAsync(twin.DeviceId, twin, twin.ETag);

기타 쌍 업데이트 방법

다음 SDK 메서드를 사용하여 쌍 업데이트를 적용할 수도 있습니다.

• ReplaceTwinAsync를 호출하여 전체 디바이스 쌍을 바꿉니다.
• UpdateTwins2Async를 호출하여 이전에 시스템 내에서 만든 쌍 목록을 업데이트합니다.

디바이스 쌍 쿼리 만들기

이 섹션에서는 두 개의 디바이스 쌍 쿼리를 보여 줍니다. 디바이스 쌍 쿼리는 디바이스 쌍의 결과 집합을 반환하는 SQL과 유사한 쿼리입니다.

디바이스 쌍 쿼리를 만들려면 CreateQuery를 호출하여 쌍 SQL 쿼리를 제출하고 IQuery 인터페이스를 가져옵니다. 필요에 따라 두 번째 매개 변수를 사용하여 CreateQuery를 호출하여 페이지당 최대 항목 수를 지정할 수 있습니다.

다음으로 모든 쌍 결과를 검색하는 데 필요한 횟수만큼 GetNextAsTwinAsync 또는 GetNextAsJsonAsync 메서드를 호출합니다.

• GetNextAsTwinAsync: 다음 페이징된 결과를 Twin 개체로 가져옵니다.
• GetNextAsTwinAsync: 다음 페이징된 결과를 JSON 문자열로 가져옵니다.

IQuery 인터페이스에는 가져올 쌍 결과가 더 있는지 확인하는 데 사용할 수 있는 HasMoreResults 부울 속성이 포함되어 있습니다.

이 예제 쿼리는 Redmond43 공장에 있는 디바이스 쌍만 선택합니다.

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

SDK 서비스 샘플

.NET용 Azure IoT SDK는 디바이스 쌍 작업을 처리하는 디바이스 앱의 작업 샘플을 제공합니다. 자세한 내용은 Registry Manager 샘플을 참조하세요.

개요

이 문서에서는 Java용 Azure IoT SDK를 사용하여 디바이스 쌍에 대한 디바이스 및 백 엔드 서비스 애플리케이션 코드를 만드는 방법을 설명합니다.

디바이스 애플리케이션 만들기

디바이스 애플리케이션은 reported 쌍 속성을 읽고 쓸 수 있으며, 백 엔드 애플리케이션 또는 IoT Hub에서 설정한 원하는 쌍 속성 변경 내용을 알 수 있습니다.

이 섹션에서는 다음을 수행하는 디바이스 애플리케이션 코드를 만드는 방법을 설명합니다.

• 디바이스 쌍 검색 및 보기
• reported 디바이스 쌍 속성 업데이트
• desiered 속성 변경 내용 구독

DeviceClient 클래스는 디바이스의 디바이스 쌍과 상호 작용하는 데 필요한 모든 메서드를 표시합니다.

디바이스 Import 문

다음 디바이스 import 문을 사용하여 Java용 Azure IoT SDK에 액세스합니다.

import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.DeviceTwin.*;

디바이스에 연결

디바이스에 연결하려면 다음을 수행합니다.

1. IotHubClientProtocol을 사용하여 전송 프로토콜을 선택합니다. 예시:

   IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
   

2. DeviceClient 생성자를 사용하여 디바이스 기본 연결 문자열 및 프로토콜을 추가합니다.

   String connString = "{IoT hub device connection string}";
   DeviceClient client = new DeviceClient(connString, protocol);
   

3. open을 사용하여 디바이스를 IoT Hub에 연결합니다. 클라이언트가 이미 열려 있으면 메서드는 아무 작업도 수행하지 않습니다.

   client.open(true);
   

디바이스 쌍 검색 및 보기

클라이언트 연결을 연 후 getTwin을 호출하여 현재 쌍 속성을 Twin 개체로 가져옵니다.

예시:

private static Twin twin;
System.out.println("Getting current twin");
twin = client.getTwin();
System.out.println("Received current twin:");
System.out.println(twin);

디바이스 쌍 reported 속성 업데이트

현재 쌍을 검색한 후 reported 속성 업데이트를 시작할 수 있습니다. 올바른 reported 속성 버전이 있기만 하면 현재 쌍을 가져오지 않고도 reported 속성 업데이트를 수행할 수 있습니다. reported 속성을 보낸 후에 "사전 조건 실패" 오류가 수신되면 reported 속성 버전이 만료된 것입니다. 이 경우 getTwin을 다시 호출하여 최신 버전을 가져옵니다.

reported 속성을 업데이트하려면 다음을 수행합니다.

1. getReportedProperties를 호출하여 쌍 reported 속성을 TwinCollection 개체로 가져옵니다.

2. put을 사용하여 TwinCollection 개체 내에서 reported 속성을 업데이트합니다. 각 reported 속성 업데이트에 대해 put을 호출합니다.

3. updateReportedProperties를 사용하여 put 메서드를 통해 업데이트된 reported 속성 그룹을 적용합니다.

예시:

TwinCollection reportedProperties = twin.getReportedProperties();

int newTemperature = new Random().nextInt(80);
reportedProperties.put("HomeTemp(F)", newTemperature);
System.out.println("Updating reported property \"HomeTemp(F)\" to value " + newTemperature);

ReportedPropertiesUpdateResponse response = client.updateReportedProperties(reportedProperties);
System.out.println("Successfully set property \"HomeTemp(F)\" to value " + newTemperature);

desiered 속성 변경 내용 구독

subscribeToDesiredProperties를 호출하여 desired 속성 변경 내용을 구독합니다. 이 클라이언트는 desiered 속성이 업데이트될 때마다 Twin 개체를 사용하여 콜백을 받습니다. 해당 콜백에는 전체 desired 속성 집합이 포함되거나 desired 속성이 변경된 방법에 따라 업데이트된 desired 속성만 포함됩니다.

이 예제에서는 desired 속성 변경 내용을 구독합니다. desired 속성 변경 내용은 DesiredPropertiesUpdatedHandler 처리기에 전달됩니다.

client.subscribeToDesiredProperties(new DesiredPropertiesUpdatedHandler(), null);

이 예제에서 DesiredPropertiesUpdatedHandler desired 속성 변경 콜백 처리기는 getDesiredProperties를 호출하여 속성 변경 내용을 검색한 다음, 업데이트된 쌍 속성을 출력합니다.

  private static class DesiredPropertiesUpdatedHandler implements DesiredPropertiesCallback
  {
      @Override
      public void onDesiredPropertiesUpdated(Twin desiredPropertyUpdateTwin, Object context)
      {
          if (twin == null)
          {
              // No need to care about this update because these properties will be present in the twin retrieved by getTwin.
              System.out.println("Received desired properties update before getting current twin. Ignoring this update.");
              return;
          }

          // desiredPropertyUpdateTwin.getDesiredProperties() contains all the newly updated desired properties as well as the new version of the desired properties
          twin.getDesiredProperties().putAll(desiredPropertyUpdateTwin.getDesiredProperties());
          twin.getDesiredProperties().setVersion(desiredPropertyUpdateTwin.getDesiredProperties().getVersion());
          System.out.println("Received desired property update. Current twin:");
          System.out.println(twin);
      }
  }

SDK 디바이스 샘플

Java용 Azure IoT SDK에는 이 문서에 설명된 디바이스 앱 개념을 테스트하는 작업 샘플이 포함되어 있습니다. 자세한 내용은 디바이스 쌍 샘플을 참조하세요.

백 엔드 애플리케이션 만들기

이 섹션에서는 다음을 수행하는 백 엔드 애플리케이션을 만드는 방법을 설명합니다.

• 디바이스 쌍 태그 업데이트
• 태그 및 속성에 필터를 사용하여 디바이스 쿼리

ServiceClient DeviceTwin 클래스에는 서비스가 디바이스 쌍에 액세스하는 데 사용할 수 있는 메서드가 포함되어 있습니다.

서비스 Import 문

다음 서비스 import 문을 사용하여 Java용 Azure IoT SDK에 액세스합니다.

import com.microsoft.azure.sdk.iot.service.devicetwin.*;
import com.microsoft.azure.sdk.iot.service.exceptions.IotHubException;

IoT Hub 서비스 클라이언트에 연결

IoT Hub에 연결하여 디바이스 쌍 정보를 보고 업데이트하려면 다음을 수행합니다.

1. DeviceTwinClientOptions 개체를 만듭니다. 애플리케이션에 필요한 옵션을 설정합니다. 이러한 옵션은 DeviceTwin 개체에 전달됩니다.
2. DeviceTwin 생성자를 사용하여 IoT Hub에 대한 연결을 만듭니다. DeviceTwin 개체는 IoT 허브와의 통신을 처리합니다. 필수 구성 요소 섹션에서 만든 IoT Hub 서비스 연결 문자열과 DeviceTwinClientOptions 개체를 매개 변수로 제공합니다.
3. DeviceTwinDevice 개체는 해당 속성 및 태그로 디바이스 쌍을 나타냅니다.

예시:

public static final String iotHubConnectionString = "{IoT hub service connection string}";
public static final String deviceId = "myDeviceId";
public static final String region = "US";
public static final String plant = "Redmond43";

// Get the DeviceTwin and DeviceTwinDevice objects
DeviceTwinClientOptions twinOptions = new DeviceTwinClientOptions();
DeviceTwin twinClient = new DeviceTwin(iotHubConnectionString,twinOptions);
DeviceTwinDevice device = new DeviceTwinDevice(deviceId);

디바이스 쌍 필드 업데이트

디바이스 쌍 필드를 업데이트하려면 다음을 수행합니다.

1. getTwin을 사용하여 현재 디바이스 쌍 필드 검색.

   이 예제에서는 디바이스 쌍 필드를 검색하고 출력합니다.

   // Get the device twin from IoT Hub
   System.out.println("Device twin before update:");
   twinClient.getTwin(device);
   System.out.println(device);
   

2. HashSet 개체를 사용하여 쌍 태그 쌍 그룹 add

3. setTags를 사용하여 tags 개체의 태그 쌍 그룹을 DeviceTwinDevice 개체에 추가

4. updateTwin을 사용하여 IoT Hub에서 쌍 업데이트

   이 예제에서는 디바이스 쌍에 대한 지역 및 공장 디바이스 쌍 태그를 업데이트합니다.

   // Update device twin tags if they are different
   // from the existing values
   String currentTags = device.tagsToString();
   if ((!currentTags.contains("region=" + region) && !currentTags.contains("plant=" + plant))) {
   
   // Create the tags and attach them to the DeviceTwinDevice object
   Set<Pair> tags = new HashSet<Pair>();
   tags.add(new Pair("region", region));
   tags.add(new Pair("plant", plant));
   device.setTags(tags);
   
   // Update the device twin in IoT Hub
   System.out.println("Updating device twin");
   twinClient.updateTwin(device);
   }
   
   // Retrieve and display the device twin with the tag values from IoT Hub
   System.out.println("Device twin after update:");
   twinClient.getTwin(device);
   System.out.println(device);
   

디바이스 쌍 쿼리 만들기

이 섹션에서는 두 개의 디바이스 쌍 쿼리를 보여 줍니다. 디바이스 쌍 쿼리는 디바이스 쌍의 결과 집합을 반환하는 SQL과 유사한 쿼리입니다.

Query 클래스에는 쌍, 작업, 디바이스 작업 또는 원시 데이터용 IoT Hub에 대해 SQL 스타일 쿼리를 만드는 데 사용할 수 있는 메서드가 포함되어 있습니다.

디바이스 쿼리를 만들려면 다음을 수행합니다.

1. createSqlQuery를 사용하여 쌍 SQL 쿼리 빌드

2. queryTwin을 사용하여 쿼리 실행

3. hasNextDeviceTwin을 사용하여 결과 집합에 다른 디바이스 쌍이 있는지 확인

4. getNextDeviceTwin을 사용하여 결과 집합에서 다음 디바이스 쌍 검색

다음 예제 쿼리는 최대 100개의 디바이스를 반환합니다.

이 예제 쿼리는 Redmond43 공장에 있는 디바이스 쌍만 선택합니다.

// Query the device twins in IoT Hub
System.out.println("Devices in Redmond:");

// Construct the query
SqlQuery sqlQuery = SqlQuery.createSqlQuery("*", SqlQuery.FromType.DEVICES, "tags.plant='Redmond43'", null);

// Run the query, returning a maximum of 100 devices
Query twinQuery = twinClient.queryTwin(sqlQuery.getQuery(), 100);
while (twinClient.hasNextDeviceTwin(twinQuery)) {
  DeviceTwinDevice d = twinClient.getNextDeviceTwin(twinQuery);
  System.out.println(d.getDeviceId());
}

이 예제 쿼리는 셀룰러 네트워크를 통해 연결된 디바이스만 선택하도록 첫 번째 쿼리를 구체화합니다.

System.out.println("Devices in Redmond using a cellular network:");

// Construct the query
sqlQuery = SqlQuery.createSqlQuery("*", SqlQuery.FromType.DEVICES, "tags.plant='Redmond43' AND properties.reported.connectivityType = 'cellular'", null);

// Run the query, returning a maximum of 100 devices
twinQuery = twinClient.queryTwin(sqlQuery.getQuery(), 3);
while (twinClient.hasNextDeviceTwin(twinQuery)) {
  DeviceTwinDevice d = twinClient.getNextDeviceTwin(twinQuery);
  System.out.println(d.getDeviceId());
}

SDK 서비스 샘플

Java용 Azure IoT SDK는 디바이스 쌍 작업을 처리하는 디바이스 앱의 작업 샘플을 제공합니다. 자세한 내용은 디바이스 쌍 샘플을 참조하세요.

개요

이 문서에서는 Python용 Azure IoT SDK를 사용하여 디바이스 쌍에 대한 디바이스 및 백 엔드 서비스 애플리케이션 코드를 만드는 방법을 설명합니다.

디바이스 애플리케이션 만들기

디바이스 애플리케이션은 reported 쌍 속성을 읽고 쓸 수 있으며, 백 엔드 애플리케이션 또는 IoT Hub에서 설정한 원하는 쌍 속성 변경 내용을 알 수 있습니다.

IoTHubDeviceClient 클래스에는 디바이스 쌍을 사용하는 데 사용할 수 있는 메서드가 포함되어 있습니다.

이 섹션에서는 다음을 수행하는 디바이스 애플리케이션 코드를 만드는 방법을 설명합니다.

• 디바이스 쌍 검색 및 reported 속성 검사
• reported 디바이스 쌍 속성 패치

디바이스에 연결

이 섹션에서는 공유 액세스 키를 포함하는 디바이스 기본 키를 사용하여 디바이스에 애플리케이션을 연결하는 방법을 보여 줍니다.

디바이스에 애플리케이션을 연결하려면 다음을 수행합니다.

1. create_from_connection_string을 호출하여 디바이스 연결 문자열 추가
2. connect를 호출하여 디바이스 클라이언트를 Azure IoT Hub에 연결

# import the device client library
import asyncio
from azure.iot.device.aio import IoTHubDeviceClient

# substitute the device connection string in conn_str
# and add it to the IoTHubDeviceClient object
conn_str = "{IOT hub device connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(conn_str)

# connect the application to the device
await device_client.connect()

디바이스 쌍 검색 및 reported 속성 검사

태그 및 속성을 포함한 디바이스 쌍 정보를 검색하고 검사할 수 있습니다. 검색된 디바이스 쌍 정보는 Azure Portal에서 디바이스에 대해 볼 수 있는 디바이스 쌍 JSON 형식 데이터와 일치합니다.

get_twin을 호출하여 Azure IoT Hub 서비스에서 디바이스 쌍을 가져옵니다. 쌍 정보는 출력하거나 검사할 수 있는 변수에 배치됩니다.

이 예제에서는 디바이스 쌍을 검색하고 print 명령을 사용하여 디바이스 쌍을 JSON 형식으로 봅니다.

# get the twin
twin = await device_client.get_twin()
print("Twin document:")
print("{}".format(twin))

reported 디바이스 쌍 속성 패치

패치를 적용하여 디바이스 reported 속성을 JSON 형식으로 업데이트할 수 있습니다.

reported 속성을 업데이트하는 패치를 적용하려면 다음을 수행합니다.

1. reported 속성 JSON 패치를 변수에 할당합니다.
2. patch_twin_reported_properties를 호출하여 reported 속성에 JSON 패치를 적용합니다. 이것은 동기 호출입니다. 즉, 패치가 서비스로 전송되고 승인될 때까지 이 함수가 결과를 반환하지 않습니다.

patch_twin_reported_properties가 오류를 반환하면 이 함수는 해당 오류를 발생시킵니다.

# create the reported properties patch
reported_properties = {"temperature": random.randint(320, 800) / 10}
print("Setting reported temperature to {}".format(reported_properties["temperature"]))
# update the reported properties and wait for the result
await device_client.patch_twin_reported_properties(reported_properties)

다음 메서드를 호출하여 디바이스 쌍을 업데이트할 수도 있습니다.

• replace_twin을 호출하여 디바이스 쌍 태그 및 desired 속성을 바꿉니다.
• update_twin을 호출하여 디바이스 쌍 태그 및 desired 속성을 업데이트합니다.

들어오는 desired 속성 패치 처리기

on_twin_desired_properties_patch_received를 호출하여 쌍 desired 속성 패치가 수신될 때 호출되는 처리기 함수 또는 코루틴을 만듭니다. 처리기는 JSON 사전 개체의 형태로 쌍 패치에 해당하는 하나의 인수를 사용합니다.

이 예제에서는 twin_patch_handler라는 desired 속성 패치 처리기를 설정합니다.

예시:

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

twin_patch_handler는 JSON desired 속성 업데이트를 수신하고 출력합니다.

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

SDK 디바이스 샘플

Python용 Azure SDK에는 다음 샘플이 포함되어 있습니다.

• get_twin - 디바이스에 연결하고 쌍 정보를 검색합니다.
• update_twin_reported_properties - 쌍 reported 속성을 업데이트합니다.
• receive_twin_desired_properties - desired 속성을 수신하고 업데이트합니다.

백 엔드 애플리케이션 만들기

백 엔드 애플리케이션은 IoT Hub를 통해 디바이스에 연결하고, reported 및 desired 속성을 읽고, 디바이스 desired 속성을 작성하고, 디바이스 쿼리를 실행할 수 있습니다.

이 섹션에서는 다음을 수행하는 백 엔드 애플리케이션을 만드는 방법을 설명합니다.

• 쌍 태그 및 desired 속성 업데이트
• 태그 및 속성에 필터를 사용하여 디바이스 쿼리

IoTHubRegistryManager 클래스는 서비스의 디바이스 쌍과 상호 작용하는 백 엔드 애플리케이션을 만드는 데 필요한 모든 메서드를 표시합니다.

IoT Hub에 연결

from_connection_string을 사용하여 IoT Hub에 연결합니다. 필수 구성 요소 섹션에서 만든 IoT Hub 서비스 연결 문자열을 매개 변수로 제공합니다.

예시:

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

# Connect to IoT hub
IOTHUB_CONNECTION_STRING = "{IoT hub service connection string}"
iothub_registry_manager = IoTHubRegistryManager.from_connection_string(IOTHUB_CONNECTION_STRING)

쌍 태그 및 desired 속성 업데이트

update_twin을 사용하여 백 엔드 애플리케이션에서 디바이스 쌍 태그와 desired 속성을 동시에 업데이트할 수 있습니다.

1. get_twin을 호출하여 디바이스 쌍의 현재 버전을 가져옵니다.
2. Twin 클래스를 사용하여 JSON 형식의 태그 및 속성을 추가합니다.
3. update_twin을 호출하여 디바이스 쌍에 패치를 적용합니다. replace_twin을 사용하여 디바이스 쌍에 대해 desired 속성 및 태그를 바꿀 수도 있습니다.

이 예제에서는 region 및 plant 태그 정보를 업데이트하고, power_level desired 속성을 1로 설정합니다.

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

DEVICE_ID = "[Device Id]"
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)

디바이스 쌍 쿼리 만들기

디바이스 쌍 쿼리를 사용하여 디바이스 쌍 정보를 쿼리할 수 있습니다. 디바이스 쌍 쿼리는 디바이스 쌍의 결과 집합을 반환하는 SQL과 유사한 쿼리입니다.

디바이스 쌍 쿼리를 사용하려면 다음을 수행합니다.

1. QuerySpecification 개체를 사용하여 SQL과 유사한 쿼리 요청을 정의합니다.

2. query_iot_hub를 사용하여 IoTHub를 쿼리하고 SQL과 유사한 쿼리 사양을 사용하여 디바이스 쌍 정보를 검색합니다.

이 예제에서는 두 개의 쿼리를 실행합니다. 첫 번째는 Redmond43 공장에 있는 디바이스의 디바이스 쌍만 선택하고, 두 번째는 셀룰러 네트워크를 통해 연결된 디바이스만 선택하도록 쿼리를 구체화합니다. 결과는 각 쿼리 후에 출력됩니다.

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

print()

SDK 서비스 샘플

Python용 Azure IoT SDK는 디바이스 쌍 작업을 처리하는 디바이스 앱의 작업 샘플을 제공합니다. 자세한 내용은 Registry Manager 쿼리 샘플을 참조하세요.

개요

이 문서에서는 Node.js용 Azure IoT SDK를 사용하여 디바이스 쌍에 대한 디바이스 및 백 엔드 서비스 애플리케이션 코드를 만드는 방법을 설명합니다.

디바이스 애플리케이션 만들기

디바이스 애플리케이션은 reported 쌍 속성을 읽고 쓸 수 있으며, 백 엔드 애플리케이션 또는 IoT Hub에서 설정한 원하는 쌍 속성 변경 내용을 알 수 있습니다.

이 섹션에서는 Node.js용 Azure IoT SDK에서 azure-iot-device 패키지를 사용하여 디바이스 애플리케이션을 만드는 방법을 설명합니다.

• 디바이스 쌍 검색 및 reported 속성 검사
• reported 디바이스 쌍 속성 업데이트
• desired 속성 변경 내용에 대한 알림 받기

SDK 패키지 설치

이 명령을 실행하여 개발 머신에 azure-iot-device 디바이스 SDK를 설치합니다.

npm install azure-iot-device --save

azure-iot-device 패키지에는 IoT 디바이스와 인터페이스하는 개체가 포함되어 있습니다. Twin 클래스에는 쌍별 개체가 포함됩니다. 이 섹션에서는 디바이스 쌍 데이터를 읽고 쓰는 데 사용되는 Client 클래스 코드에 대해 설명합니다.

전송 프로토콜 선택

Client 개체는 다음 프로토콜을 지원합니다.

• Amqp
• Http - Http를 사용할 때 Client 인스턴스는 IoT Hub의 메시지를 자주(최소 25분마다) 확인합니다.
• Mqtt
• MqttWs
• AmqpWs

개발 머신에 필요한 전송 프로토콜을 설치합니다.

예를 들어 이 명령은 Mqtt 프로토콜을 설치합니다.

npm install azure-iot-device-mqtt --save

MQTT, AMQP, HTTPS 지원 간 차이점에 대한 자세한 내용은 클라우드-디바이스 통신 지침 및 통신 프로토콜 선택을 참조하세요.

클라이언트 모듈 만들기

설치된 패키지를 사용하여 Client 모듈을 만듭니다.

예시:

const Client = require('azure-iot-device').Client;

프로토콜 모듈 만들기

설치된 전송 패키지를 사용하여 Protocol 모듈을 만듭니다.

이 예제에서는 MQTT 프로토콜을 할당합니다.

const Protocol = require('azure-iot-device-mqtt').Mqtt;

디바이스 연결 문자열 및 전송 프로토콜 추가

ConnectionString을 호출하여 디바이스 연결 매개 변수를 제공합니다.

• connStr - IoT 허브에 대한 "디바이스 연결" 권한을 캡슐화하는 연결 문자열입니다. 연결 문자열에는 "HostName=<iothub_host_name>;DeviceId=<device_id>;SharedAccessKey=<device_key>" 형식의 호스트 이름, 디바이스 ID 및 공유 액세스 키가 포함됩니다.
• transportCtor - 전송 프로토콜입니다.

이 예제에서는 Mqtt 전송 프로토콜을 사용합니다.

const deviceConnectionString = "{IoT hub device connection string}"
const Protocol = require('azure-iot-device-mqtt').Mqtt;
let client = Client.fromConnectionString(deviceConnectionString, Protocol);

IoT Hub에 대한 연결 열기

IoT 디바이스와 IoT Hub 간의 연결을 열려면 open 메서드를 사용합니다. .catch(err)을 사용하여 오류를 catch하고 처리기 코드를 호출합니다.

예시:

client.open()  //open the connection
.catch((err) => {
  console.error('Could not connect: ' + err.message);
});

디바이스 쌍 검색 및 reported 속성 검사

getTwin을 호출하여 현재 디바이스 쌍 정보를 Twin 개체로 가져옵니다.

예시:

client.getTwin(function(err, twin))
if (err)
    console.error('could not get twin');

reported 디바이스 쌍 속성 업데이트

update를 사용하여 디바이스 reported 속성을 업데이트합니다. JSON 형식 패치를 첫 번째 매개 변수로 포함하고 함수 실행 상태 콜백 메서드를 메서드의 두 번째 매개 변수로 포함합니다.

이 예제에서는 JSON 형식 디바이스 쌍 패치가 patch 변수에 저장됩니다. 패치에는 디바이스 쌍 connectivity 업데이트 값 cellular가 포함되어 있습니다. 패치 및 오류 처리기는 update 메서드에 전달됩니다. 오류가 발생하면 콘솔 오류 메시지가 표시됩니다.

var patch = {
    connectivity: {
        type: 'cellular'
    }
}
twin.properties.reported.update(patch, function(err)
  {
    if (err)
      {
        console.error('could not update twin');
      } 
    else
      {
        console.log('twin state reported');
        process.exit();
      }
  });

desired 속성 변경 내용에 대한 알림 받기

콜백 처리기 메서드 이름을 twin.on에 전달하여 디바이스에서 desired 속성이 변경될 때 실행되는 desired 속성 업데이트 이벤트 수신기를 만듭니다.

desired 속성 이벤트 수신기는 다음 형식 중 하나를 사용할 수 있습니다.

• 단일 이벤트 처리기를 사용하여 모든 패치 수신
• 속성 그룹화에서 변경된 내용이 있으면 이벤트 수신
• 단일 속성 변경에 대한 이벤트 수신

단일 이벤트 처리기를 사용하여 모든 패치 수신

desired 속성 변경 내용을 수신하는 수신기를 만들 수 있습니다.

이 예제 코드는 서비스에서 수신되는 모든 속성을 출력합니다.

twin.on('properties.desired', function (delta) {
    console.log('new desired properties received:');
    console.log(JSON.stringify(delta));
});

속성 그룹화에서 변경된 내용이 있으면 이벤트 수신

속성 그룹화에서 변경된 내용이 있으면 수신기를 만들어 이벤트를 수신할 수 있습니다.

예시:

1. minTemperature 및 maxTemperature 속성은 properties.desired.climate changes 속성 그룹 아래에 있습니다.

2. 백 엔드 서비스 애플리케이션은 이 패치를 적용하여 minTemperature 및 maxTemperature desired 속성을 업데이트합니다.

   const twinPatch1 = {
   properties: {
      desired: {
       climate: { minTemperature: 68, maxTemperature: 76, },
       },
     },
    };
   

3. 이 코드는 properties.desired.climate 속성 그룹화 내에서 변경 내용을 트리거하는 desired 속성 변경 이벤트 수신기를 설정합니다. 이 그룹 내에서 desired 속성 변경 내용이 있는 경우 콘솔에 표시되는 최소 및 최대 온도 변경 메시지는 다음과 같습니다.

   twin.on('properties.desired.climate', function (delta) {
       if (delta.minTemperature || delta.maxTemperature) {
           console.log('updating desired temp:');
           console.log('min temp = ' + twin.properties.desired.climate.minTemperature);
           console.log('max temp = ' + twin.properties.desired.climate.maxTemperature);
       }
   });
   

단일 속성 변경에 대한 이벤트 수신

단일 속성 변경에 대한 수신기를 설정할 수 있습니다. 이 예제에서는 fanOn 부울 값이 패치의 일부인 경우에만 이 이벤트에 대한 코드가 실행됩니다. 이 코드는 서비스에서 업데이트할 때마다 새 desired fanOn 상태를 출력합니다.

1. 백 엔드 애플리케이션은 다음 desired 속성 패치를 적용합니다.

    const twinPatch2 = {
     properties: {
       desired: {
         climate: {
           hvac: {
             systemControl: { fanOn: true, },
           },
         },
       },
     },
   };
   

2. 수신기는 fanOn 속성이 변경되는 경우에만 트리거됩니다.

    twin.on('properties.desired.climate.hvac.systemControl', function (fanOn) {
        console.log('setting fan state to ' + fanOn);
     });
   

디바이스 SDK 샘플

Node.js용 Azure IoT SDK에는 두 개의 디바이스 쌍 샘플이 포함되어 있습니다.

• 간단한 샘플 디바이스 쌍

• SAS를 사용하는 간단한 샘플 디바이스 쌍

백 엔드 애플리케이션 만들기

백 엔드 애플리케이션은 IoT Hub를 통해 디바이스에 연결하고, reported 및 desired 속성을 읽고, 디바이스 desired 속성을 작성하고, 디바이스 쿼리를 실행할 수 있습니다.

이 섹션에서는 다음을 수행하는 백 엔드 애플리케이션을 만드는 방법을 설명합니다.

• 디바이스 쌍 검색 및 업데이트
• 디바이스 쌍 쿼리 만들기

서비스 SDK 패키지 설치

이 명령을 실행하여 개발 머신에 azure-iothub를 설치합니다.

npm install azure-iothub --save

Registry 클래스는 백 엔드 애플리케이션에서 디바이스 쌍과 상호 작용하는 데 필요한 모든 메서드를 표시합니다.

IoT Hub에 연결

fromConnectionString을 사용하여 IoT Hub에 연결합니다. 필수 구성 요소 섹션에서 만든 IoT Hub 서비스 연결 문자열을 매개 변수로 제공합니다.

'use strict';
var iothub = require('azure-iothub');
var connectionString = '{Iot Hub service connection string}';
var registry = iothub.Registry.fromConnectionString(connectionString);

디바이스 쌍 검색 및 업데이트

디바이스 쌍에 대한 태그 및 desired 속성 업데이트가 포함된 패치를 만들 수 있습니다.

디바이스 쌍을 업데이트하려면 다음을 수행합니다.

1. getTwin을 호출하여 디바이스 쌍 개체를 검색합니다.

• 디바이스 쌍 업데이트를 포함하는 패치의 형식을 지정합니다. 패치는 Twin 클래스에 설명된 대로 JSON으로 형식이 지정됩니다. 백 엔드 서비스 패치에는 태그 및 desired 속성 업데이트가 포함될 수 있습니다. 패치 형식에 대한 자세한 내용은 태그 및 속성 형식을 참조하세요.

1. update를 호출하여 디바이스 쌍을 패치로 업데이트합니다.

이 예제에서는 디바이스 쌍이 myDeviceId에 대해 검색된 다음, region: 'US', plant: 'Redmond43'의 location 태그 업데이트를 포함하는 쌍에 패치가 적용됩니다.

     registry.getTwin('myDeviceId', function(err, twin){
         if (err) {
             console.error(err.constructor.name + ': ' + err.message);
         } else {
             var patch = {
                 tags: {
                     location: {
                         region: 'US',
                         plant: 'Redmond43'
                   }
                 }
             };

             twin.update(patch, function(err) {
               if (err) {
                 console.error('Could not update twin: ' + err.constructor.name + ': ' + err.message);
               } else {
                 console.log(twin.deviceId + ' twin updated successfully');
                 queryTwins();
               }
             });
         }
     });

디바이스 쌍 쿼리 만들기

SQL과 유사한 디바이스 쿼리를 만들어 디바이스 쌍에서 정보를 수집할 수 있습니다.

createQuery를 사용하여 디바이스 또는 작업에 대한 정보를 찾기 위해 IoT Hub 인스턴스에서 실행할 수 있는 쿼리를 만듭니다.

createQuery에는 다음 두 매개 변수가 포함됩니다.

• sqlQuery - SQL 문자열로 작성된 쿼리입니다.
• pageSize - 페이지당 원하는 결과 수입니다(선택 사항. 기본값: 1000, 최대: 10000).

pageSize 매개 변수가 지정된 경우 쿼리 개체에는 nextAsTwin 메서드를 확인하고 사용하여 모든 결과를 검색하는 데 필요한 횟수만큼 다음 쌍 결과 페이지를 가져올 수 있는 hasMoreResults 부울 속성이 포함됩니다. next라는 메서드는 디바이스 쌍이 아닌 결과(예: 집계 쿼리의 결과)에 대해 사용할 수 있습니다.

이 예제 쿼리는 Redmond43 공장에 있는 디바이스 쌍만 선택합니다.

var queryTwins = function() {
var query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
query.nextAsTwin(function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        console.log("Devices in Redmond43: " + results.map(function(twin) {return twin.deviceId}).join(','));
    }
});

이 예제 쿼리는 셀룰러 네트워크를 통해 연결된 디바이스만 선택하도록 첫 번째 쿼리를 구체화합니다.

query = registry.createQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
query.nextAsTwin(function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        console.log("Devices in Redmond43 using cellular network: " + results.map(function(twin) {return twin.deviceId}).join(','));
    }
});
};

서비스 SDK 샘플

Node.js용 Azure IoT SDK는 디바이스 쌍 작업을 처리하는 디바이스 앱의 작업 샘플을 제공합니다. 자세한 내용은 디바이스 쌍 백 엔드 서비스를 참조하세요. 이 프로젝트는 특정 디바이스에 대한 디바이스 쌍 패치 업데이트를 보내는 데 사용됩니다.