영어로 읽기

다음을 통해 공유


IoT Hub 모듈 ID 및 모듈 ID 쌍 시작

프로그래밍 언어 선택

모듈 ID 및 모듈 ID 쌍은 Azure IoT Hub 디바이스 ID 및 디바이스 쌍과 유사하지만 보다 세분성을 제공합니다. Azure IoT Hub 디바이스 ID 및 디바이스 쌍을 사용하면 백 엔드 애플리케이션이 디바이스를 구성하고 디바이스의 조건에 대한 가시성을 제공할 수 있지만 모듈 ID 및 모듈 ID 쌍은 디바이스의 개별 구성 요소에 대해 이러한 기능을 제공합니다. 운영 체제 디바이스 또는 펌웨어 디바이스와 같은 여러 구성 요소가 있는 지원 디바이스에서 모듈 ID 및 모듈 ID 쌍은 각 구성 요소에 대해 격리된 구성 및 조건을 허용합니다. 자세한 내용은 Azure IoT Hub 모듈 쌍 이해를 참조 하세요.

참고

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

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

  • 모듈 ID 쌍 reported 속성을 보고 업데이트하고 원하는 속성을 업데이트하기 위한 요청을 처리하는 디바이스 앱입니다.
  • 모듈 ID 원하는 속성을 읽고 설정할 수 있는 서비스 앱입니다.

참고

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

필수 조건

  • IoT 허브

  • IoT Hub 디바이스

  • IoT Hub 디바이스 모듈 ID

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

  • Visual Studio 필요

개요

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

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

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

  • 모듈 ID 쌍 검색 및 reported 속성 검사
  • 보고된 모듈 ID 쌍 속성 업데이트
  • 모듈 원하는 속성 업데이트 콜백 처리기 만들기

중요

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

필수 디바이스 NuGet 패키지

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

using 이러한 문을 추가하여 디바이스 라이브러리를 사용합니다.

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

디바이스에 연결

ModuleClient 클래스는 디바이스에서 모듈 ID 쌍과 상호 작용하는 데 필요한 모든 메서드를 노출합니다.

모듈 ID 연결 문자열 CreateFromConnectionString 메서드를 사용하여 디바이스에 연결합니다.

전송 매개 변수 없이 호출 CreateFromConnectionString 하면 기본 AMQP 전송을 사용하여 연결됩니다.

이 예제에서는 기본 AMQP 전송을 사용하여 디바이스에 연결합니다.

static string ModuleConnectionString = "{Device module identity connection string}";
private static ModuleClient _moduleClient = null;

_moduleClient = ModuleClient.CreateFromConnectionString(ModuleConnectionString, null);

모듈 ID 쌍 검색 및 속성 검사

GetTwinAsync를 호출하여 현재 모듈 ID 쌍 속성을 Twin 개체로 검색합니다.

이 예제에서는 JSON 형식으로 모듈 ID 쌍 속성을 검색하고 표시합니다.

Console.WriteLine("Retrieving twin...");
Twin twin = await _moduleClient.GetTwinAsync();
Console.WriteLine("\tModule identity twin value received:");
Console.WriteLine(JsonConvert.SerializeObject(twin.Properties));

모듈 ID 쌍 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 _moduleClient.UpdateReportedPropertiesAsync(reportedProperties);
}
catch (Exception ex)
{
   Console.WriteLine();
   Console.WriteLine("Error in sample: {0}", ex.Message);
}

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

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

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

await _moduleClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

모듈 ID 쌍 속성은 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 _moduleClient.UpdateReportedPropertiesAsync(reportedProperties);
}

SDK 모듈 샘플

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

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

이 섹션에서는 모듈 ID 필드를 읽고 업데이트하는 방법을 설명합니다.

RegistryManager 클래스는 서비스에서 모듈 ID 쌍과 상호 작용하는 백 엔드 애플리케이션을 만드는 데 필요한 모든 메서드를 노출합니다.

필수 서비스 NuGet 패키지

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

using 이러한 문을 추가하여 서비스 라이브러리를 사용합니다.

using Microsoft.Azure.Devices;
using Microsoft.Azure.Devices.Shared;

IoT Hub에 연결

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

  • 공유 액세스 정책
  • Microsoft Entra

중요

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

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

CreateFromConnectionString을 사용하여 백 엔드 애플리케이션을 IoT Hub에 연결합니다.

이 섹션에서 사용되는 메서드는 UpdateModuleAsync 원하는 속성을 모듈에 추가하려면 Service Connect 공유 액세스 정책 권한이 필요합니다. 매개 변수CreateFromConnectionString로서 Service Connect 권한을 포함하는 공유 액세스 정책 연결 문자열 제공합니다. 공유 액세스 정책에 대한 자세한 내용은 공유 액세스 서명을 사용하여 IoT Hub에 대한 액세스 제어를 참조 하세요.

예시:

static RegistryManager registryManager;
static string connectionString = "{IoT hub 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 서비스 인증의 작업 샘플은 역할 기반 인증 샘플을 참조 하세요.

모듈 ID 필드 읽기 및 업데이트

GetModuleAsync를 호출하여 현재 모듈 ID 쌍 필드를 Module 개체로 검색 합니다.

클래스에는 Module 모듈 ID 쌍의 섹션에 해당하는 클래스가 포함됩니다 properties . 모듈 클래스 속성을 사용하여 모듈 ID 쌍 필드를 보고 업데이트합니다. 를 사용하여 디바이스에 Module 업데이트를 작성하기 전에 개체 속성을 사용하여 여러 필드를 업데이트할 수 있습니다 UpdateModuleAsync.

모듈 ID 쌍 필드 업데이트를 수행한 후 UpdateModuleAsync를 호출하여 개체 필드 업데이트를 디바이스에 다시 작성 Module 합니다. 오류 처리기와 함께 trycatch 논리를 사용하여 UpdateModuleAsync에서 잘못된 형식의 패치 오류를 catch합니다.

이 예제에서는 개체로 모듈을 Module 검색하고, 속성을 업데이트 module LastActivityTime 한 다음, IoT Hub에서 다음을 사용하여 UpdateModuleAsync모듈을 업데이트합니다.

// Retrieve the module
var module = await registryManager.GetModuleAsync("myDeviceId","myModuleId");

// Update the module object
module.LastActivityTime = DateTime.Now;

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

기타 모듈 API

SDK 서비스 샘플

.NET용 Azure IoT SDK는 모듈 ID 쌍 작업을 처리하는 서비스 앱의 작업 샘플을 제공합니다. 자세한 내용은 레지스트리 관리자 E2E 테스트를 참조 하세요.

  • Python 버전 3.7 이상을 사용하는 것이 좋습니다. 설치 프로그램의 요구 사항에 따라 32비트 또는 64비트 설치를 사용해야 합니다. 설치하는 동안 메시지가 나타나면 플랫폼별 환경 변수에 Python을 추가해야 합니다.

개요

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

패키지 설치

디바이스 애플리케이션을 만들려면 azure-iot-device 라이브러리를 설치해야 합니다.

pip install azure-iot-device

백 엔드 서비스 애플리케이션을 만들려면 azure-iot-hub 라이브러리를 설치해야 합니다.

pip install azure-iot-hub

msrest 라이브러리는 HTTPOperationError 예외를 catch하는 데 사용됩니다.

pip install msrest

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

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

  • 모듈 ID 쌍 검색 및 reported 속성 검사
  • 모듈 ID 쌍 reported 속성 업데이트
  • 모듈 ID 쌍 desired 속성 업데이트 콜백 처리기 만들기

중요

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

Import 문

디바이스 라이브러리를 사용하려면 이 import 문을 추가합니다.

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

디바이스에 연결

IoTHubModuleClient 클래스에는 모듈 ID 쌍을 사용하는 데 사용할 수 있는 메서드가 포함되어 있습니다.

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

  1. create_from_connection_string 호출하여 모듈 ID 연결 문자열 추가
  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 = "{Device module identity connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(conn_str)

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

모듈 ID 쌍 검색 및 속성 검사

get_twin 호출하여 Azure IoT Hub 서비스에서 모듈 ID 쌍을 검색합니다. 트윈 정보는 검사할 수 있는 변수에 배치됩니다.

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

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

모듈 ID 쌍 reported 속성 업데이트

패치를 적용하여 JSON 형식으로 모듈 ID 쌍 reported 속성을 업데이트할 수 있습니다.

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

  1. reported 속성 JSON 패치를 변수에 할당합니다.
  2. patch_twin_reported_properties를 호출하여 reported 속성에 JSON 패치를 적용합니다.

예시:

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

모듈 ID 쌍 desired 속성 업데이트 콜백 처리기 만들기

on_twin_desired_properties_patch_received 호출하여 모듈 ID 쌍 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 IoT SDK는 모듈 ID 쌍 작업을 처리하는 디바이스 앱의 작업 샘플을 제공합니다.

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

이 섹션에서는 모듈 ID 쌍 desired 속성을 검색하고 업데이트하는 백 엔드 애플리케이션을 만드는 방법을 설명합니다.

IoTHubRegistryManager 클래스는 서비스에서 모듈 ID 쌍과 상호 작용하는 백 엔드 애플리케이션을 만드는 데 필요한 모든 메서드를 노출합니다.

서비스 Import 문

서비스 라이브러리를 사용하려면 이 import 문을 추가합니다.

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

IoT Hub에 연결

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

  • 공유 액세스 정책
  • Microsoft Entra

중요

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

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

from_connection_string을 사용하여 IoT Hub에 연결합니다.

이 섹션에서 사용되는 메서드는 update_module_twin 원하는 속성을 모듈에 추가하려면 Service Connect 공유 액세스 정책 권한이 필요합니다. 매개 변수from_connection_string로서 Service Connect 권한을 포함하는 공유 액세스 정책 연결 문자열 제공합니다. 공유 액세스 정책에 대한 자세한 내용은 공유 액세스 서명을 사용하여 IoT Hub에 대한 액세스 제어를 참조 하세요.

예시:

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

Microsoft Entra를 사용하여 연결

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

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

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의 장단점에 대한 자세한 내용은 Python용 Azure ID 클라이언트 라이브러리의 자격 증명 체인을 참조하세요.

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

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

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 인증 라이브러리)을 참조 하세요.

모듈 ID 쌍 desired 속성 검색 및 업데이트

update_module_twin 사용하여 백 엔드 애플리케이션에서 원하는 속성을 업데이트할 수 있습니다.

모듈 ID 쌍 desired 속성을 검색하고 업데이트하려면 다음을 수행합니다.

  1. get_module_twin 호출하여 모듈 ID 쌍의 현재 버전을 가져옵니다.
  2. Twin 클래스를 사용하여 원하는 속성을 JSON 형식으로 추가합니다.
  3. update_module_twin을 호출하여 디바이스 쌍에 패치를 적용합니다. replace_module_twin 사용하여 모듈 ID 쌍에 대해 원하는 속성과 태그를 바꿀 수도 있습니다.

다음은 원하는 속성을 .로 업데이트하는 telemetryInterval 122예제입니다.

try:
    module_twin = iothub_registry_manager.get_module_twin(DEVICE_ID, MODULE_ID)
    print ( "" )
    print ( "Module identity twin properties before update:" )
    print ( "{0}".format(module_twin.properties) )

    # Update twin
    twin_patch = Twin()
    twin_patch.properties = TwinProperties(desired={"telemetryInterval": 122})
    updated_module_twin = iothub_registry_manager.update_module_twin(
        DEVICE_ID, MODULE_ID, twin_patch, module_twin.etag
    )
    print ( "" )
    print ( "Module identity twin properties after update     :" )
    print ( "{0}".format(updated_module_twin.properties) )

except Exception as ex:
    print ( "Unexpected error {0}".format(ex) )
except KeyboardInterrupt:
    print ( "IoTHubRegistryManager sample stopped" )

SDK 서비스 샘플

Python용 Azure IoT SDK는 디바이스 ID 모듈 쌍 작업을 처리하는 서비스 앱의 작업 샘플을 제공합니다. 자세한 내용은 테스트 IoTHub 레지스트리 관리자를 참조 하세요.

  • Node.js 버전 10.0.x 이상이 필요합니다.

개요

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

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

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

  • 모듈 ID 쌍 검색 및 reported 속성 검사
  • 모듈 ID 보고 쌍 속성 업데이트
  • 모듈 ID 쌍 desired 속성 변경에 대한 알림 받기

중요

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

SDK 패키지 설치

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

npm install azure-iot-device --save

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

전송 프로토콜 선택

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

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

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

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

npm install azure-iot-device-amqp --save

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

클라이언트 개체 만들기

Client 설치된 패키지를 사용하여 개체를 만듭니다.

예시:

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

프로토콜 개체 만들기

Protocol 설치된 전송 패키지를 사용하여 개체를 만듭니다.

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

const Protocol = require('azure-iot-device-amqp').Amqp;

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

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

  • connStr - IoT Hub ID 모듈 연결 문자열.
  • transportCtor - 전송 프로토콜입니다.

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

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

IoT Hub에 대한 연결 열기

IoT 디바이스와 IoT Hub 간의 연결을 열려면 open 메서드를 사용합니다.

예시:

client.open(function(err) {
  if (err) {
    console.error('error connecting to hub: ' + err);
    process.exit(1);
  }
})

모듈 ID 쌍 검색 및 reported 속성 검사

getTwin을 호출하여 현재 모듈 ID 쌍 정보를 Twin 개체로 검색합니다.

그런 다음 디바이스 코드는 모듈 ID 쌍 속성에 액세스할 수 있습니다.

예시:

// Retrieve the current module identity twin
client.getTwin(function(err, twin))
if (err)
    console.error('could not get twin');

// Display the current properties
console.log('twin contents:');
console.log(twin.properties);

모듈 ID 쌍 reported 속성 업데이트

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

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

// Create a patch to send to IoT Hub
var patch = {
  updateTime: new Date().toString(),
  firmwareVersion:'1.2.1',
  weather:{
    temperature: 72,
    humidity: 17
  }
};

// Apply the patch
twin.properties.reported.update(patch, function(err)
  {
    if (err)
      {
        console.error('could not update twin');
      } 
    else
      {
        console.log('twin state reported');
        process.exit();
      }
  });

모듈 ID 쌍 desired 속성 변경에 대한 알림 받기

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

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

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

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

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

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

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

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

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

예시:

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

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

    const twinPatch1 = {
    properties: {
       desired: {
        climate: { minTemperature: 68, maxTemperature: 76, },
        },
      },
     };
    
  3. 이 코드는 속성 그룹화 내의 변경 내용을 트리거하는 원하는 속성 변경 이벤트 수신기를 properties.desired.climate 설정합니다. 이 그룹 내에서 원하는 속성 변경이 있는 경우 최소 및 최대 온도 변경 메시지가 콘솔에 표시됩니다.

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

전체 예제

이 예제에서는 다중 수준 콜백 함수 중첩을 포함하여 이 섹션의 원칙을 캡슐화합니다.

var Client = require('azure-iot-device').Client;
var Protocol = require('azure-iot-device-amqp').Amqp;
// Copy/paste your module connection string here.
var connectionString = 'HostName=xxx.azure-devices.net;DeviceId=myFirstDevice2;ModuleId=myFirstModule2;SharedAccessKey=xxxxxxxxxxxxxxxxxx';
// Create a client using the Amqp protocol.
var client = Client.fromConnectionString(connectionString, Protocol);
client.on('error', function (err) {
  console.error(err.message);
});
// connect to the hub
client.open(function(err) {
  if (err) {
    console.error('error connecting to hub: ' + err);
    process.exit(1);
  }
  console.log('client opened');
// Create device Twin
  client.getTwin(function(err, twin) {
    if (err) {
      console.error('error getting twin: ' + err);
      process.exit(1);
    }
    // Output the current properties
    console.log('twin contents:');
    console.log(twin.properties);
    // Add a handler for desired property changes
    twin.on('properties.desired', function(delta) {
        console.log('new desired properties received:');
        console.log(JSON.stringify(delta));
    });
    // create a patch to send to the hub
    var patch = {
      updateTime: new Date().toString(),
      firmwareVersion:'1.2.1',
      weather:{
        temperature: 75,
        humidity: 20
      }
    };
    // send the patch
    twin.properties.reported.update(patch, function(err) {
      if (err) throw err;
      console.log('twin state reported');
    });

  });
});

디바이스 SDK 샘플

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

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

이 섹션에서는 모듈 ID 쌍을 검색하고 원하는 속성을 업데이트하는 백 엔드 애플리케이션을 만드는 방법을 설명합니다.

서비스 SDK 패키지 설치

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

npm install azure-iothub --save

레지스트리 개체 만들기

레지스트리 클래스는 백 엔드 애플리케이션에서 모듈 ID 쌍과 상호 작용하는 데 필요한 모든 메서드를 노출합니다.

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

IoT Hub에 연결

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

  • 공유 액세스 정책
  • Microsoft Entra

중요

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

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

fromConnectionString을 사용하여 IoT Hub에 연결합니다.

이 섹션에서 사용되는 메서드는 update 원하는 속성을 모듈에 추가하려면 Service Connect 공유 액세스 정책 권한이 필요합니다. 매개 변수fromConnectionString로서 Service Connect 권한을 포함하는 공유 액세스 정책 연결 문자열 제공합니다. 공유 액세스 정책에 대한 자세한 내용은 공유 액세스 서명을 사용하여 IoT Hub에 대한 액세스 제어를 참조 하세요.

let connectionString = '{IoT hub shared access policy connection string}';
let registry = Registry.fromConnectionString(serviceConnectionString);

Microsoft Entra를 사용하여 연결

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

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

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의 장단점에 대한 자세한 내용은 JavaScript용 Azure ID 클라이언트 라이브러리의 자격 증명 체인을 참조 하세요.

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

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

npm install --save @azure/identity

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

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 예제를 참조 하세요.

모듈 ID 쌍 검색 및 원하는 속성 업데이트

모듈 ID 쌍에 대해 원하는 속성 업데이트를 포함하는 패치를 만들 수 있습니다.

모듈 ID 쌍을 업데이트하려면 다음을 수행합니다.

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

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

  3. 업데이트를 호출하여 모듈 ID 쌍을 패치로 업데이트합니다.

이 예제에서는 모듈 ID 쌍을 검색 myDeviceId 하고 myModuleId. 그런 다음 정보가 포함된 트윈에 패치가 적용됩니다 climate .

// Insert your device ID and moduleId here.
var deviceId = 'myFirstDevice2';
var moduleId = 'myFirstModule2';

// Retrieve the current module identity twin
registry.getModuleTwin(deviceId, moduleId, function (err, twin) {
  console.log('getModuleTwin returned ' + (err ? err : 'success'));
  if (err) {
    console.log(err);
  } else {
    console.log('success');
    console.log('Current twin:' + JSON.stringify(twin))

    // Format a desired property patch
    const twinPatch1 = {
      properties: {
        desired: {
          climate: { minTemperature: 69, maxTemperature: 77, },
        },
      },
    };

    // Send the desired property patch to IoT Hub
    twin.update(twinPatch1, function(err) {
    if (err) throw err;
    console.log('twin state reported');
    });
  }
});

서비스 SDK 샘플

Node.js용 Azure IoT SDK는 모듈 ID 쌍 작업을 처리하는 서비스 앱의 작업 샘플을 제공합니다. 자세한 내용은 다음을 참조하세요.