쌍 디바이스 시작

아티클
12/04/2024

Azure IoT Hub 디바이스 SDK 및 서비스 SDK를 사용하여 일반적인 디바이스 쌍 작업을 처리하는 애플리케이션을 개발합니다. 디바이스 쌍은 메타데이터, 상태 및 조건을 포함하는 디바이스의 상태 정보를 저장하는 JSON 문서입니다. IoT Hub는 여기에 연결하는 각 디바이스에 대해 하나의 디바이스 쌍을 유지합니다.

디바이스 쌍은 다음 작업에 사용할 수 있습니다.

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

디바이스 쌍을 사용하는 경우를 포함한 디바이스 쌍에 대한 자세한 내용은 IoT Hub에서 디바이스 쌍 이해 및 사용을 참조하세요.

참고 항목

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

이 문서에서는 두 가지 유형의 애플리케이션을 개발하는 방법을 보여 줍니다.

디바이스 앱은 원하는 속성을 업데이트하고 reported 속성에 대한 변경 내용으로 응답하라는 요청을 처리할 수 있습니다.
서비스 앱은 디바이스 쌍 태그를 업데이트하고, 원하는 새 속성을 설정하고, 디바이스 쌍 값을 기준으로 디바이스를 쿼리할 수 있습니다.

참고 항목

이 문서는 이 문서 내에서 참조되는 Azure IoT SDK를 보완하기 위한 것입니다. SDK 도구를 사용하여 디바이스 및 백 엔드 애플리케이션을 모두 빌드할 수 있습니다.

필수 조건

IoT Hub. 일부 SDK 호출에는 IoT Hub 기본 연결 문자열이 필요하므로 연결 문자열을 기록해 둡니다.
등록된 디바이스. 일부 SDK 호출에는 디바이스 기본 연결 문자열이 필요하므로 연결 문자열을 기록해 둡니다.
애플리케이션이 MQTT 프로토콜을 사용하는 경우 포트 8883이 방화벽에서 열려 있는지 확인합니다. MQTT 프로토콜은 포트 8883을 통해 통신합니다. 이 포트는 일부 회사 및 교육용 네트워크 환경에서 차단될 수 있습니다. 이 문제를 해결하는 자세한 내용과 방법은 IoT Hub에 연결(MQTT)을 참조하세요.
언어 SDK 요구 사항:
- .NET SDK - Visual Studio가 필요합니다.
- Python SDK - Python 버전 3.7 이상이 권장됩니다. 설치 프로그램의 요구 사항에 따라 32비트 또는 64비트 설치를 사용해야 합니다. 설치하는 동안 메시지가 나타나면 플랫폼별 환경 변수에 Python을 추가해야 합니다.
- Java - Java SE Development Kit 8가 필요합니다. JDK 8용 다운로드로 이동하려면 장기 지원에서 Java 8을 선택해야 합니다.
- Node.js - Node.js 버전 10.0.x 이상이 필요합니다.

개요

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

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

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

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

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

Important

이 문서에서는 공유 액세스 서명(대칭 키 인증이라고도 함)을 사용하여 디바이스를 연결하는 단계를 설명합니다. 이 인증 방법은 테스트와 평가에 편리하지만, X.509 인증서를 사용하여 디바이스를 인증하는 것이 더 안전한 방식입니다. 자세한 내용은 보안 모범 사례 > 연결 보안을 참조하세요.

디바이스 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 쌍 속성을 업데이트하려면 다음을 수행합니다.

reported 속성 업데이트에 대한 TwinCollection 개체 만들기
TwinCollection 개체 내에서 하나 이상의 reported 속성 업데이트
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에 연결

다음 방법을 사용하여 백 엔드 서비스를 IoT Hub에 연결할 수 있습니다.

공유 액세스 정책
Microsoft Entra

Important

이 문서에서는 공유 액세스 서명을 사용하여 서비스에 연결하는 단계를 설명합니다. 이 인증 방법은 테스트와 평가에 편리하지만, Microsoft Entra ID나 관리 ID를 사용하여 서비스를 인증하는 것이 더 안전한 방식입니다. 자세한 내용은 보안 모범 사례 > 클라우드 보안을 참조하세요.

공유 액세스 정책을 사용하여 연결

CreateFromConnectionString을 사용하여 백 엔드 애플리케이션을 디바이스에 연결합니다. 애플리케이션은 디바이스 쌍의 원하는 속성을 수정하기 위해 서비스 연결 권한이 필요하며, ID 레지스트리를 쿼리하려면 레지스트리 읽기 권한이 필요합니다. 이러한 두 권한만 포함하는 기본 공유 액세스 정책이 없으므로 권한이 없는 경우 만들어야 합니다. 이 공유 액세스 정책 연결 문자열 매개 변수fromConnectionString로 제공합니다. 공유 액세스 정책에 대한 자세한 내용은 공유 액세스 서명을 사용하여 IoT Hub에 대한 액세스 제어를 참조 하세요.

using Microsoft.Azure.Devices;
static RegistryManager registryManager;
static string connectionString = "{Shared access policy connection string}";
registryManager = RegistryManager.CreateFromConnectionString(connectionString);

Microsoft Entra를 사용하여 연결

Microsoft Entra를 사용하는 백 엔드 앱은 IoT Hub에 연결하기 전에 보안 토큰 자격 증명을 성공적으로 인증하고 가져와야 합니다. 이 토큰은 IoT Hub 연결 메서드에 전달됩니다. IoT Hub용 Microsoft Entra를 설정하고 사용하는 방법에 대한 일반적인 내용은 Microsoft Entra ID를 사용하여 IoT Hub에 대한 액세스 제어를 참조하세요.

Microsoft Entra 앱 구성

기본 인증 자격 증명에 대해 구성된 Microsoft Entra 앱을 설정해야 합니다. 앱에는 백 엔드 애플리케이션에서 인증하는 데 사용되는 클라이언트 암호와 같은 매개 변수가 포함되어 있습니다. 사용 가능한 앱 인증 구성은 다음과 같습니다.

클라이언트 암호
인증서
페더레이션 ID 자격 증명

Microsoft Entra 앱은 수행 중인 작업에 따라 특정 역할 권한이 필요할 수 있습니다. 예를 들어 IoT Hub 디바이스 및 모듈 쌍에 대한 읽기 및 쓰기 액세스를 사용하려면 IoT Hub 쌍 기여자가 필요합니다. 자세한 내용은 Azure RBAC 역할 할당을 사용하여 IoT Hub에 대한 액세스 관리를 참조하세요.

Microsoft Entra 앱 설정에 대한 자세한 내용은 빠른 시작: Microsoft ID 플랫폼 애플리케이션 등록을 참조하세요.

DefaultAzureCredential을 사용하여 인증

Microsoft Entra를 사용하여 백 엔드 애플리케이션을 인증하는 가장 쉬운 방법은 DefaultAzureCredential을 사용하는 것이지만 특정 TokenCredential 또는 구문 분석ChainedTokenCredential된 방법을 포함하여 프로덕션 환경에서 다른 방법을 사용하는 것이 좋습니다. 편의상 이 섹션에서는 인증 사용 DefaultAzureCredential 및 클라이언트 비밀에 대해 설명합니다. 사용 DefaultAzureCredential의 장단점에 대한 자세한 내용은 DefaultAzureCredential에 대한 사용 지침을 참조 하세요.

DefaultAzureCredential 는 다양한 인증 메커니즘을 지원하고 실행 중인 환경에 따라 적절한 자격 증명 유형을 결정합니다. 작업 자격 증명을 찾을 때까지 여러 자격 증명 형식을 순서대로 사용하려고 시도합니다.

Microsoft Entra에는 다음 NuGet 패키지 및 해당 using 문이 필요합니다.

Azure.Core
Azure.Identity

using Azure.Core;
using Azure.Identity;

이 예제에서는 Microsoft Entra 앱 등록 클라이언트 암호, 클라이언트 ID 및 테넌트 ID가 환경 변수에 추가됩니다. 이러한 환경 변수는 애플리케이션을 인증하는 데 사용됩니다 DefaultAzureCredential . 성공적인 Microsoft Entra 인증의 결과는 IoT Hub 연결 방법으로 전달되는 보안 토큰 자격 증명입니다.

string clientSecretValue = "xxxxxxxxxxxxxxx";
string clientID = "xxxxxxxxxxxxxx";
string tenantID = "xxxxxxxxxxxxx";

Environment.SetEnvironmentVariable("AZURE_CLIENT_SECRET", clientSecretValue);
Environment.SetEnvironmentVariable("AZURE_CLIENT_ID", clientID);
Environment.SetEnvironmentVariable("AZURE_TENANT_ID", tenantID);

TokenCredential tokenCredential = new DefaultAzureCredential();

그러면 결과 TokenCredential 을 Microsoft Entra 자격 증명을 수락하는 모든 SDK 클라이언트에 대한 IoT Hub 메서드에 대한 연결에 전달할 수 있습니다.

이 예제에서는 TokenCredential ServiceClient 연결 개체를 만들기 위해 전달 ServiceClient.Create 됩니다.

string hostname = "xxxxxxxxxx.azure-devices.net";
using var serviceClient = ServiceClient.Create(hostname, tokenCredential, TransportType.Amqp);

이 예제에서는 TokenCredential RegistryManager 개체를 만들기 위해 전달 RegistryManager.Create 됩니다.

string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);

코드 샘플

Microsoft Entra 서비스 인증의 작업 샘플은 역할 기반 인증 샘플을 참조 하세요.

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

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 디바이스 쌍 속성 업데이트
desiered 속성 변경 내용 구독

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

Important

디바이스 Import 문

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

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

디바이스에 연결

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

IotHubClientProtocol을 사용하여 전송 프로토콜을 선택합니다. 예시:
```
IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
```

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

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

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 속성을 업데이트하려면 다음을 수행합니다.

getReportedProperties를 호출하여 쌍 reported 속성을 TwinCollection 개체로 가져옵니다.
put을 사용하여 TwinCollection 개체 내에서 reported 속성을 업데이트합니다. 각 reported 속성 업데이트에 대해 put을 호출합니다.
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);

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에 연결할 수 있습니다.

공유 액세스 정책
Microsoft Entra

Important

공유 액세스 정책을 사용하여 연결

DeviceTwin 생성자를 사용하여 IoT Hub에 대한 연결을 만듭니다. DeviceTwin 개체는 IoT 허브와의 통신을 처리합니다.

애플리케이션은 디바이스 쌍의 원하는 속성을 수정하기 위해 서비스 연결 권한이 필요하며, ID 레지스트리를 쿼리하려면 레지스트리 읽기 권한이 필요합니다. 이러한 두 권한만 포함하는 기본 공유 액세스 정책이 없으므로 권한이 없는 경우 만들어야 합니다. 이 공유 액세스 정책 연결 문자열 매개 변수fromConnectionString로 제공합니다. 공유 액세스 정책에 대한 자세한 내용은 공유 액세스 서명을 사용하여 IoT Hub에 대한 액세스 제어를 참조 하세요.

DeviceTwinDevice 개체는 해당 속성 및 태그로 디바이스 쌍을 나타냅니다.

예시:

public static final String iotHubConnectionString = "{Shared access policy 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
DeviceTwin twinClient = new DeviceTwin(iotHubConnectionString);
DeviceTwinDevice device = new DeviceTwinDevice(deviceId);

Microsoft Entra를 사용하여 연결

Java SDK 인증에 대한 개요는 Java 및 Azure ID를 사용한 Azure 인증을 참조 하세요.

간단히 하기 위해 이 섹션에서는 클라이언트 암호를 사용하는 인증을 설명하는 데 중점을 둡니다.

Microsoft Entra 앱 구성

클라이언트 암호
인증서
페더레이션 ID 자격 증명

Microsoft Entra 앱 설정에 대한 자세한 내용은 빠른 시작: Microsoft ID 플랫폼 애플리케이션 등록을 참조하세요.

DefaultAzureCredential을 사용하여 인증

Microsoft Entra를 사용하여 백 엔드 애플리케이션을 인증하는 가장 쉬운 방법은 DefaultAzureCredential을 사용하는 것이지만 특정 TokenCredential 또는 구문 분석ChainedTokenCredential된 방법을 포함하여 프로덕션 환경에서 다른 방법을 사용하는 것이 좋습니다. 사용DefaultAzureCredential의 장단점에 대한 자세한 내용은 Java용 Azure ID 클라이언트 라이브러리의 자격 증명 체인을 참조하세요.

DefaultAzureCredential 은 다양한 인증 메커니즘을 지원하고 실행 중인 환경에 따라 적절한 자격 증명 유형을 결정합니다. 작업 자격 증명을 찾을 때까지 여러 자격 증명 형식을 순서대로 사용하려고 시도합니다.

DefaultAzureCredentialBuilder를 사용하여 Microsoft Entra 앱 자격 증명을 인증할 수 있습니다. 클라이언트 비밀 tenantID, clientID 및 클라이언트 비밀 값과 같은 연결 매개 변수를 환경 변수로 저장합니다. TokenCredential 만들어지면 ServiceClient 또는 다른 작성기에서 '자격 증명' 매개 변수로 전달합니다.

이 예제에서는 DefaultAzureCredentialBuilder DefaultAzureCredential에 설명된 목록에서 연결을 인증하려고 시도합니다. 성공적인 Microsoft Entra 인증의 결과는 ServiceClient와 같은 생성자에 전달되는 보안 토큰 자격 증명입니다.

TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build();

ClientSecretCredentialBuilder를 사용하여 인증

ClientSecretCredentialBuilder를 사용하여 클라이언트 비밀 정보를 사용하여 자격 증명을 만들 수 있습니다. 성공하면 이 메서드는 ServiceClient 또는 다른 작성기에서 '자격 증명' 매개 변수로 전달할 수 있는 TokenCredential을 반환합니다.

이 예제에서는 Microsoft Entra 앱 등록 클라이언트 암호, 클라이언트 ID 및 테넌트 ID 값이 환경 변수에 추가되었습니다. 이러한 환경 변수는 자격 증명을 빌드하는 데 사용됩니다 ClientSecretCredentialBuilder .

string clientSecretValue = System.getenv("AZURE_CLIENT_SECRET");
string clientID = System.getenv("AZURE_CLIENT_ID");
string tenantID = System.getenv("AZURE_TENANT_ID");

TokenCredential credential =
     new ClientSecretCredentialBuilder()
          .tenantId(tenantID)
          .clientId(clientID)
          .clientSecret(clientSecretValue)
          .build();

기타 인증 클래스

Java SDK에는 Microsoft Entra를 사용하여 백 엔드 앱을 인증하는 다음 클래스도 포함되어 있습니다.

코드 샘플

Microsoft Entra 서비스 인증의 작업 샘플은 역할 기반 인증 샘플을 참조 하세요.

디바이스 쌍 필드 업데이트

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

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

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

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

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

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 스타일 쿼리를 만드는 데 사용할 수 있는 메서드가 포함되어 있습니다.

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

createSqlQuery를 사용하여 쌍 SQL 쿼리 빌드
queryTwin을 사용하여 쿼리 실행
hasNextDeviceTwin을 사용하여 결과 집합에 다른 디바이스 쌍이 있는지 확인
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를 사용하여 디바이스 쌍에 대한 디바이스 및 백 엔드 서비스 애플리케이션 코드를 만드는 방법을 설명합니다.

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

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

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

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

Important

디바이스에 연결

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

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

create_from_connection_string을 호출하여 디바이스 연결 문자열 추가
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 속성을 업데이트하는 패치를 적용하려면 다음을 수행합니다.

reported 속성 JSON 패치를 변수에 할당합니다.
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 속성을 수신하고 업데이트합니다.

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

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

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

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

IoT Hub에 연결

다음 방법을 사용하여 백 엔드 서비스를 IoT Hub에 연결할 수 있습니다.

공유 액세스 정책
Microsoft Entra

Important

공유 액세스 정책을 사용하여 연결

from_connection_string을 사용하여 IoT Hub에 연결합니다. 애플리케이션은 디바이스 쌍의 원하는 속성을 수정하기 위해 서비스 연결 권한이 필요하며, ID 레지스트리를 쿼리하려면 레지스트리 읽기 권한이 필요합니다. 이러한 두 권한만 포함하는 기본 공유 액세스 정책이 없으므로 권한이 없는 경우 만들어야 합니다. 이 공유 액세스 정책 연결 문자열 매개 변수fromConnectionString로 제공합니다. 공유 액세스 정책에 대한 자세한 내용은 공유 액세스 서명을 사용하여 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)

Microsoft Entra를 사용하여 연결

Python SDK 인증에 대한 개요는 Python용 Azure SDK를 사용하여 Azure 서비스에 Python 앱 인증을 참조 하세요.

Microsoft Entra 앱 구성

클라이언트 암호
인증서
페더레이션 ID 자격 증명

Microsoft Entra 앱 설정에 대한 자세한 내용은 빠른 시작: Microsoft ID 플랫폼 애플리케이션 등록을 참조하세요.

DefaultAzureCredential을 사용하여 인증

Microsoft Entra를 사용하여 백 엔드 애플리케이션을 인증하는 가장 쉬운 방법은 DefaultAzureCredential을 사용하는 것이지만 특정 TokenCredential 또는 구문 분석ChainedTokenCredential된 방법을 포함하여 프로덕션 환경에서 다른 방법을 사용하는 것이 좋습니다. 편의상 이 섹션에서는 인증 사용 DefaultAzureCredential 및 클라이언트 비밀에 대해 설명합니다. 사용DefaultAzureCredential의 장단점에 대한 자세한 내용은 Python용 Azure ID 클라이언트 라이브러리의 자격 증명 체인을 참조하세요.

Microsoft Entra에는 이 가져오기 패키지 및 해당 import 문이 필요합니다.

pip install azure-identity

from azure.identity import DefaultAzureCredential

이 예제에서는 Microsoft Entra 앱 등록 클라이언트 암호, 클라이언트 ID 및 테넌트 ID가 환경 변수에 추가되었습니다. 이러한 환경 변수는 애플리케이션을 인증하는 데 사용됩니다 DefaultAzureCredential . 성공적인 Microsoft Entra 인증의 결과는 IoT Hub 연결 방법으로 전달되는 보안 토큰 자격 증명입니다.

from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()

그러면 결과 AccessToken을 전달하여 from_token_credential Microsoft Entra 자격 증명을 수락하는 모든 SDK 클라이언트의 IoT Hub에 연결할 수 있습니다.

IoTHubRegistryManager 를 사용하여 Entra 토큰 자격 증명을 사용하여 IoT Hub에 대한 서비스 연결을 만듭니다.
IoTHubJobManager
DigitalTwinClient
IoTHubHttpRuntimeManager
IoTHubConfigurationManager

from_token_credential 에는 다음 두 개의 매개 변수가 필요합니다.

Azure 서비스 URL - Azure 서비스 URL은 접두사 없이 https:// 형식 {Your Entra domain URL}.azure-devices.net 이어야 합니다. 예들 들어 MyAzureDomain.azure-devices.net입니다.
Azure 자격 증명 토큰

이 예제에서는 .를 사용하여 DefaultAzureCredentialAzure 자격 증명을 가져옵니다. 그런 다음 Azure 서비스 URL 및 자격 증명을 제공하여 IoTHubRegistryManager.from_token_credential IoT Hub에 대한 연결을 만듭니다.

import sys
import os

from azure.identity import DefaultAzureCredential
from azure.iot.hub import IoTHubRegistryManager

# Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

# Set environment variables
os.environ['AZURE_CLIENT_SECRET'] = clientSecretValue
os.environ['AZURE_CLIENT_ID'] = clientID
os.environ['AZURE_TENANT_ID'] = tenantID

# Acquire a credential object
credential = DefaultAzureCredential()

# Use Entra to authorize IoT Hub service
print("Connecting to IoTHubRegistryManager...")
iothub_registry_manager = IoTHubRegistryManager.from_token_credential(
url="MyAzureDomain.azure-devices.net",
token_credential=credential)

코드 샘플

Microsoft Entra 서비스 인증의 작업 샘플은 Python용 MSAL(Microsoft 인증 라이브러리)을 참조 하세요.

쌍 태그 및 desired 속성 업데이트

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

get_twin을 호출하여 디바이스 쌍의 현재 버전을 가져옵니다.
Twin 클래스를 사용하여 JSON 형식의 태그 및 속성을 추가합니다.
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과 유사한 쿼리입니다.

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

QuerySpecification 개체를 사용하여 SQL과 유사한 쿼리 요청을 정의합니다.
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를 사용하여 디바이스 쌍에 대한 디바이스 및 백 엔드 서비스 애플리케이션 코드를 만드는 방법을 설명합니다.

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

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

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

Important

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

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

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

예시:

minTemperature 및 maxTemperature 속성은 properties.desired.climate changes 속성 그룹 아래에 있습니다.
백 엔드 서비스 애플리케이션은 이 패치를 적용하여 minTemperature 및 maxTemperature desired 속성을 업데이트합니다.
```
const twinPatch1 = {
properties: {
   desired: {
    climate: { minTemperature: 68, maxTemperature: 76, },
    },
  },
 };
```

이 코드는 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 상태를 출력합니다.

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

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

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

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

디바이스 SDK 샘플

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

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

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

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

서비스 SDK 패키지 설치

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

npm install azure-iothub --save

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

IoT Hub에 연결

다음 방법을 사용하여 백 엔드 서비스를 IoT Hub에 연결할 수 있습니다.

공유 액세스 정책
Microsoft Entra

Important

공유 액세스 정책을 사용하여 연결

fromConnectionString을 사용하여 IoT Hub에 연결합니다. 애플리케이션은 디바이스 쌍의 원하는 속성을 수정하기 위해 서비스 연결 권한이 필요하며, ID 레지스트리를 쿼리하려면 레지스트리 읽기 권한이 필요합니다. 이러한 두 권한만 포함하는 기본 공유 액세스 정책이 없으므로 권한이 없는 경우 만들어야 합니다. 이 공유 액세스 정책 연결 문자열 매개 변수fromConnectionString로 제공합니다. 공유 액세스 정책에 대한 자세한 내용은 공유 액세스 서명을 사용하여 IoT Hub에 대한 액세스 제어를 참조 하세요.

'use strict';
var iothub = require('azure-iothub');
var connectionString = '{Shared access policy connection string}';
var registry = iothub.Registry.fromConnectionString(connectionString);

Microsoft Entra를 사용하여 연결

Node.js SDK 인증에 대한 개요는 다음을 참조하세요.

Microsoft Entra 앱 구성

클라이언트 암호
인증서
페더레이션 ID 자격 증명

Microsoft Entra 앱 설정에 대한 자세한 내용은 빠른 시작: Microsoft ID 플랫폼 애플리케이션 등록을 참조하세요.

DefaultAzureCredential을 사용하여 인증

Microsoft Entra를 사용하여 백 엔드 애플리케이션을 인증하는 가장 쉬운 방법은 DefaultAzureCredential을 사용하는 것이지만 특정 TokenCredential 또는 구문 분석ChainedTokenCredential된 방법을 포함하여 프로덕션 환경에서 다른 방법을 사용하는 것이 좋습니다. 편의상 이 섹션에서는 인증 사용 DefaultAzureCredential 및 클라이언트 비밀에 대해 설명합니다. 사용 DefaultAzureCredential의 장단점에 대한 자세한 내용은 JavaScript용 Azure ID 클라이언트 라이브러리의 자격 증명 체인을 참조 하세요.

Microsoft Entra에는 다음 패키지가 필요합니다.

npm install --save @azure/identity

import { DefaultAzureCredential } from "@azure/identity";

// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();

그러면 결과 자격 증명 토큰을 fromTokenCredential로 전달하여 Microsoft Entra 자격 증명을 수락하는 모든 SDK 클라이언트에 대해 IoT Hub에 연결할 수 있습니다.

fromTokenCredential 에는 다음 두 개의 매개 변수가 필요합니다.

Azure 서비스 URL - Azure 서비스 URL은 접두사 없이 https:// 형식 {Your Entra domain URL}.azure-devices.net 이어야 합니다. 예들 들어 MyAzureDomain.azure-devices.net입니다.
Azure 자격 증명 토큰

이 예제에서는 .를 사용하여 DefaultAzureCredentialAzure 자격 증명을 가져옵니다. 그런 다음 Azure 도메인 URL 및 자격 증명을 제공하여 Registry.fromTokenCredential IoT Hub에 대한 연결을 만듭니다.

const { DefaultAzureCredential } = require("@azure/identity");

let Registry = require('azure-iothub').Registry;

// Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

// Set environment variables
process.env['AZURE_CLIENT_SECRET'] = clientSecretValue;
process.env['AZURE_CLIENT_ID'] = clientID;
process.env['AZURE_TENANT_ID'] = tenantID;

// Acquire a credential object
const credential = new DefaultAzureCredential()

// Create an instance of the IoTHub registry
hostName = 'MyAzureDomain.azure-devices.net';
let registry = Registry.fromTokenCredential(hostName,credential);

코드 샘플

Microsoft Entra 서비스 인증의 작업 샘플은 Azure ID 예제를 참조 하세요.

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

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

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

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

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

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는 디바이스 쌍 작업을 처리하는 디바이스 앱의 작업 샘플을 제공합니다. 자세한 내용은 디바이스 쌍 백 엔드 서비스를 참조하세요. 이 프로젝트는 특정 디바이스에 대한 디바이스 쌍 패치 업데이트를 보내는 데 사용됩니다.

다음을 통해 공유

쌍 디바이스 시작

필수 조건

개요

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

디바이스 NuGet 패키지 추가

디바이스에 연결

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

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

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

SDK 디바이스 샘플

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

서비스 NuGet 패키지 추가

IoT Hub에 연결

공유 액세스 정책을 사용하여 연결

Microsoft Entra를 사용하여 연결

Microsoft Entra 앱 구성

DefaultAzureCredential을 사용하여 인증

코드 샘플

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

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

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

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

쌍 desired 속성 보기 및 업데이트

기타 쌍 업데이트 방법

디바이스 쌍 쿼리 만들기

SDK 서비스 샘플

개요

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

디바이스 Import 문

디바이스에 연결

디바이스 쌍 검색 및 보기

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

desiered 속성 변경 내용 구독

SDK 디바이스 샘플

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

서비스 Import 문

IoT Hub에 연결

공유 액세스 정책을 사용하여 연결

Microsoft Entra를 사용하여 연결

Microsoft Entra 앱 구성

DefaultAzureCredential을 사용하여 인증

ClientSecretCredentialBuilder를 사용하여 인증

기타 인증 클래스

코드 샘플

디바이스 쌍 필드 업데이트

디바이스 쌍 쿼리 만들기

SDK 서비스 샘플

개요

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

디바이스에 연결

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

reported 디바이스 쌍 속성 패치

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

SDK 디바이스 샘플

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

IoT Hub에 연결

공유 액세스 정책을 사용하여 연결

Microsoft Entra를 사용하여 연결

Microsoft Entra 앱 구성

DefaultAzureCredential을 사용하여 인증

코드 샘플

쌍 태그 및 desired 속성 업데이트

디바이스 쌍 쿼리 만들기

SDK 서비스 샘플

개요

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

SDK 패키지 설치

전송 프로토콜 선택

클라이언트 모듈 만들기

프로토콜 모듈 만들기

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

IoT Hub에 대한 연결 열기

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

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

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

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

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

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

디바이스 SDK 샘플