작업을 예약하고 브로드캐스트하는 방법

• Visual Studio 필요

개요

이 문서에서는 .NET용 Azure IoT SDK를 사용하여 예약 작업에 대한 백 엔드 서비스 애플리케이션 코드를 만들어 직접 메서드를 호출하거나 하나 이상의 디바이스에서 디바이스 쌍 업데이트를 수행하는 방법을 설명합니다.

서비스 NuGet 패키지 추가

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

문 사용

다음 using 명령문을 추가합니다.

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

using System.Threading;
using System.Threading.Tasks;

IoT Hub에 연결

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

• 공유 액세스 정책
• Microsoft Entra

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

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

이 문서에서는 직접 메서드를 호출하도록 작업을 예약하고, 디바이스 쌍을 업데이트하는 작업을 예약하고, 하나 이상의 디바이스에 대한 작업의 진행률을 모니터링할 수 있는 백 엔드 코드를 설명합니다. 이러한 작업을 수행하려면 서비스에 레지스트리 읽기 및 레지스트리 쓰기 권한이 있어야 합니다. 기본적으로 모든 IoT Hub는 이 사용 권한을 부여하는 registryReadWrite라는 공유 액세스 정책을 사용하여 만듭니다.

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

static JobClient jobClient;
static string connectionString = "{Shared access policy connection string}";
jobClient = JobClient.CreateFromConnectionString(connString);

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 연결 메서드에 전달될 수 있습니다.

• JobClient
• RegistryManager
• DigitalTwinClient
• ServiceClient

이 예제에서는 TokenCredential를 ServiceClient.Create에 전달하여 ServiceClient 연결 개체를 생성합니다.

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

이 예제에서는 TokenCredential가 RegistryManager.Create에 전달되어 RegistryManager 객체를 생성합니다.

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

코드 샘플

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

직접 메서드 작업 예약

ScheduleDeviceMethodAsync를 사용하여 하나 또는 여러 디바이스에서 직접 메서드를 실행하는 작업을 예약합니다.

CloudToDeviceMethod 개체를 사용하여 직접 메서드 이름 및 디바이스 연결 제한 시간 값을 지정합니다.

예시:

// The CloudToDeviceMethod record specifies the direct method name and device connection time-out
CloudToDeviceMethod directMethod = 
new CloudToDeviceMethod("LockDoor", TimeSpan.FromSeconds(5), 
TimeSpan.FromSeconds(5));

이 예제에서는 "Device-1"이라는 하나의 디바이스에서 "LockDoor"라는 직접 메서드에 대한 작업을 예약합니다. 예약된 작업에 포함된 디바이스는 두 번째 매개 변수를 쿼리 조건으로 포함합니다. 쿼리 조건에 대한 자세한 내용은 디바이스 및 모듈 쌍, 작업 및 메시지 라우팅에 대한 IoT Hub 쿼리 언어를 참조 하세요.

string methodJobId = Guid.NewGuid().ToString();  // a unique job ID
static string deviceId = "Device-1";             // In this example, there is only one device affected
JobResponse result = await jobClient.ScheduleDeviceMethodAsync(methodJobId,
   $"DeviceId IN ['{deviceId}']",
   directMethod,
   DateTime.UtcNow,
   (long)TimeSpan.FromMinutes(2).TotalSeconds);

디바이스 쌍 업데이트 작업 예약

ScheduleTwinUpdateAsync를 사용하여 하나 이상의 디바이스에서 실행할 새 디바이스 쌍의 원하는 속성과 태그 업데이트 작업을 예약합니다.

먼저 업데이트를 위해 디바이스 쌍 개체를 만들고 채웁니다. 예시:

static string deviceId = "Device-1";

Twin twin = new Twin(deviceId);
twin.Tags = new TwinCollection();
twin.Tags["Building"] = "43";
twin.Tags["Floor"] = "3";
twin.ETag = "*";
twin.Properties.Desired["LocationUpdate"] = DateTime.UtcNow;

다음으로 ScheduleTwinUpdateAsync를 호출합니다. 두 번째 매개 변수에서 쿼리로 업데이트할 디바이스를 지정합니다. 쿼리 조건에 대한 자세한 내용은 디바이스 및 모듈 쌍, 작업 및 메시지 라우팅에 대한 IoT Hub 쿼리 언어를 참조 하세요.

string twinJobId = Guid.NewGuid().ToString();

JobResponse createJobResponse = jobClient.ScheduleTwinUpdateAsync(
   twinJobId,
   $"DeviceId IN ['{deviceId}']", 
   twin, 
   DateTime.UtcNow, 
   (long)TimeSpan.FromMinutes(2).TotalSeconds).Result;

작업 모니터링

GetJobAsync를 사용하여 특정 작업 ID에 대한 작업 상태를 모니터링합니다.

다음은 작업 상태가 완료되거나 실패할 때까지 작업 ID의 작업 상태를 주기적으로 확인하는 예제입니다. 예시:

JobResponse result;
do
{
   result = await jobClient.GetJobAsync(jobId);
   Console.WriteLine("Job Status : " + result.Status.ToString());
   Thread.Sleep(2000);
} while ((result.Status != JobStatus.Completed) && (result.Status != JobStatus.Failed));

SDK 일정 작업 예제

.NET용 Azure IoT SDK는 작업 예약 작업을 처리하는 서비스 앱의 작업 샘플을 제공합니다. 자세한 내용은 다음을 참조하세요.

• 트윈 업데이트 예약 샘플
• ESG 업데이트 예약 샘플

• Java SE 개발 키트 8이 필요합니다. JDK 8용 다운로드로 이동하려면 장기 지원에서 Java 8을 선택해야 합니다.

개요

이 문서에서는 Java용 Azure IoT SDK를 사용하여 백 엔드 서비스 애플리케이션 코드를 만들어 작업을 예약하여 직접 메서드를 호출하거나 하나 이상의 디바이스에서 디바이스 쌍 업데이트를 수행하는 방법을 설명합니다.

서비스 Import 문

JobClient 클래스에는 서비스에서 작업을 예약하는 데 사용할 수 있는 메서드가 포함되어 있습니다.

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

import com.microsoft.azure.sdk.iot.service.devicetwin.DeviceTwinDevice;
import com.microsoft.azure.sdk.iot.service.devicetwin.Pair;
import com.microsoft.azure.sdk.iot.service.devicetwin.Query;
import com.microsoft.azure.sdk.iot.service.devicetwin.SqlQuery;
import com.microsoft.azure.sdk.iot.service.jobs.JobClient;
import com.microsoft.azure.sdk.iot.service.jobs.JobResult;
import com.microsoft.azure.sdk.iot.service.jobs.JobStatus;

import java.util.Date;
import java.time.Instant;
import java.util.HashSet;
import java.util.Set;
import java.util.UUID;

IoT Hub에 연결

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

• 공유 액세스 정책
• Microsoft Entra

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

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

이 문서에서는 직접 메서드를 호출하도록 작업을 예약하고, 디바이스 쌍을 업데이트하는 작업을 예약하고, 하나 이상의 디바이스에 대한 작업의 진행률을 모니터링할 수 있는 백 엔드 코드를 설명합니다. 이러한 작업을 수행하려면 서비스에 레지스트리 읽기 및 레지스트리 쓰기 권한이 있어야 합니다. 기본적으로 모든 IoT Hub는 이 사용 권한을 부여하는 registryReadWrite라는 공유 액세스 정책을 사용하여 만듭니다.

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

예시:

public static final String iotHubConnectionString = "{Shared access policy connection string}";
JobClient jobClient = new JobClient(iotHubConnectionString);

Microsoft Entra를 사용하여 연결

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

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

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

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의 장단점에 대한 자세한 내용은 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를 사용하여 백 엔드 앱을 인증하는 다음 클래스도 포함되어 있습니다.

• AuthorizationCodeCredential
• AzureCliCredential
• AzureDeveloperCliCredential
• AzurePipelinesCredential
• ChainedTokenCredential
• ClientAssertionCredential
• ClientCertificateCredential
• DeviceCodeCredential
• EnvironmentCredential
• InteractiveBrowserCredential
• ManagedIdentityCredential
• OnBehalfOfCredential

코드 샘플

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

직접 메서드 업데이트 작업 예약

scheduleDeviceMethod를 사용하여 하나 이상의 디바이스에서 직접 메서드를 실행합니다.

이 예제 메서드는 "Device-1"이라는 디바이스에서 "lockDoor"라는 직접 메서드에 대한 작업을 예약합니다.

// Schedule a job now to call the lockDoor direct method
// against a single device. Response and connection
// timeouts are set to 5 seconds.
String deviceId = "Device-1";
String jobId = "DMCMD" + UUID.randomUUID();  //Job ID must be unique

// How long the job is permitted to run without
// completing its work on the set of devices
private static final long maxExecutionTimeInSeconds = 30;

System.out.println("Schedule job " + jobId + " for device " + deviceId);
try {
  JobResult jobResult = jobClient.scheduleDeviceMethod(jobId,
    "deviceId='" + deviceId + "'",
    "lockDoor",
    5L, 5L, null,
    new Date(),
    maxExecutionTimeInSeconds);
} catch (Exception e) {
  System.out.println("Exception scheduling direct method job: " + jobId);
  System.out.println(e.getMessage());
}

디바이스 쌍 업데이트 작업 예약

scheduleUpdateTwin을 사용하여 하나 또는 여러 디바이스에서 디바이스 쌍 업데이트를 실행하는 작업을 예약합니다.

먼저, 디바이스 쌍 업데이트를 위해 DeviceTwinDevice 레코드를 준비합니다. 예시:

String deviceId = "Device-1";

//Create a device twin desired properties update object
DeviceTwinDevice twin = new DeviceTwinDevice(deviceId);
Set<Pair> desiredProperties = new HashSet<Pair>();
desiredProperties.add(new Pair("Building", 43));
desiredProperties.add(new Pair("Floor", 3));
twin.setDesiredProperties(desiredProperties);
// Optimistic concurrency control
twin.setETag("*");

그런 다음, 호출 scheduleUpdateTwin 하여 업데이트 작업을 예약합니다. 예시:

String jobId = "DPCMD" + UUID.randomUUID();  //Unique job ID

// How long the job is permitted to run without
// completing its work on the set of devices
private static final long maxExecutionTimeInSeconds = 30;

// Schedule the update twin job to run now for a single device
System.out.println("Schedule job " + jobId + " for device " + deviceId);
try {
  JobResult jobResult = jobClient.scheduleUpdateTwin(jobId, 
    "deviceId='" + deviceId + "'",
    twin,
    new Date(),
    maxExecutionTimeInSeconds);
} catch (Exception e) {
  System.out.println("Exception scheduling desired properties job: " + jobId);
  System.out.println(e.getMessage());
}

작업 모니터링

getJob을 사용하여 특정 작업 ID에 따라 작업 정보를 가져옵니다. getJob 는 실행 상태를 포함하여 작업 정보를 확인하는 데 사용할 수 있는 메서드와 속성을 포함하는 JobResult 개체를 반환합니다.

예시:

try {
  JobResult jobResult = jobClient.getJob(jobId);
  if(jobResult == null)
  {
    System.out.println("No JobResult for: " + jobId);
    return;
  }
  // Check the job result until it's completed
  while(jobResult.getJobStatus() != JobStatus.completed)
  {
    Thread.sleep(100);
    jobResult = jobClient.getJob(jobId);
    System.out.println("Status " + jobResult.getJobStatus() + " for job " + jobId);
  }
  System.out.println("Final status " + jobResult.getJobStatus() + " for job " + jobId);
} catch (Exception e) {
  System.out.println("Exception monitoring job: " + jobId);
  System.out.println(e.getMessage());
  return;
}

작업 상태 쿼리

queryDeviceJob을 사용하여 하나 이상의 작업에 대한 작업 상태를 쿼리합니다.

예시:

private static void queryDeviceJobs(JobClient jobClient, String start) throws Exception {
  System.out.println("\nQuery device jobs since " + start);

  // Create a jobs query using the time the jobs started
  Query deviceJobQuery = jobClient
      .queryDeviceJob(SqlQuery.createSqlQuery("*", SqlQuery.FromType.JOBS, "devices.jobs.startTimeUtc > '" + start + "'", null).getQuery());

  // Iterate over the list of jobs and print the details
  while (jobClient.hasNextJob(deviceJobQuery)) {
    System.out.println(jobClient.getNextJob(deviceJobQuery));
  }
}

SDK 일정 작업 예제

Java용 Azure IoT SDK는 작업 예약 작업을 처리하는 서비스 앱의 작업 샘플을 제공합니다. 자세한 내용은 작업 클라이언트 샘플을 참조 하세요.

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

개요

이 문서에서는 Python용 Azure IoT SDK를 사용하여 백엔드 서비스 애플리케이션 코드를 생성하고, 작업을 예약하여 직접 메서드를 호출하거나 하나 이상의 디바이스에서 디바이스 쌍의 원하는 속성을 업데이트하는 방법을 설명합니다.

패키지 설치

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

pip install azure-iot-hub

Import 문

IoTHubJobManager 클래스는 서비스에서 작업을 예약하는 백 엔드 애플리케이션을 만드는 데 필요한 모든 메서드를 노출합니다.

다음 import 문을 추가합니다.

import os
import sys
import datetime
import time
import threading
import uuid
import msrest

from azure.iot.hub import IoTHubJobManager
from azure.iot.hub.models import JobProperties, JobRequest, Twin, TwinProperties, CloudToDeviceMethod

IoT Hub에 연결

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

• 공유 액세스 정책
• Microsoft Entra

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

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

이 문서에서는 직접 메서드를 호출하도록 작업을 예약하고, 디바이스 쌍을 업데이트하는 작업을 예약하고, 하나 이상의 디바이스에 대한 작업의 진행률을 모니터링할 수 있는 백 엔드 코드를 설명합니다. 이러한 작업을 수행하려면 서비스에 레지스트리 읽기 및 레지스트리 쓰기 권한이 있어야 합니다. 기본적으로 모든 IoT Hub는 이 사용 권한을 부여하는 registryReadWrite라는 공유 액세스 정책을 사용하여 만듭니다.

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

예시:

IoTHubConnectionString = "{Shared access policy connection string}"
iothub_job_manager = IoTHubJobManager.from_connection_string(IoTHubConnectionString)

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 메서드에 대한 연결에 전달할 수 있습니다.

• JobClient
• RegistryManager
• DigitalTwinClient
• ServiceClient

이 예제에서는 TokenCredential가 ServiceClient.Create에 전달되어 ServiceClient 연결 객체를 생성합니다.

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

이 예제에서는 TokenCredential가 RegistryManager.Create에게 전달되어 RegistryManager 개체를 생성합니다.

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

코드 샘플

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

직접 메서드 작업 예약

create_scheduled_job 사용하여 하나 이상의 디바이스에서 직접 메서드를 실행하도록 새 직접 메서드를 예약합니다.

create_scheduled_job 매개 변수 참고 사항:

• job_id 고유해야 합니다.
• type을(를) scheduleDeviceMethod(으)로 설정
• 직접 메서드 이름 및 페이로드를 설정하는 데 사용 cloud_to_device_method
• 실행 시간(초)을 지정하는 데 사용 max_execution_time_in_seconds
• 직접 메서드 호출에 포함할 디바이스를 지정하는 데 사용합니다 query_condition . 쿼리 조건에 대한 자세한 내용은 디바이스 및 모듈 쌍, 작업 및 메시지 라우팅에 대한 IoT Hub 쿼리 언어를 참조 하세요.

예시:

METHOD_NAME = "lockDoor"
METHOD_PAYLOAD = "{\"lockTime\":\"10m\"}"
job_id = uuid.uuid4()
DEVICE_ID = "Device-1"
TIMEOUT = 60

job_request = JobRequest()
job_request.job_id = job_id
job_request.type = "scheduleDeviceMethod"
job_request.start_time = datetime.datetime.utcnow().isoformat()
job_request.cloud_to_device_method = CloudToDeviceMethod(method_name=METHOD_NAME, payload=METHOD_PAYLOAD)
job_request.max_execution_time_in_seconds = TIMEOUT
job_request.query_condition = "DeviceId in ['{}']".format(device_id)

new_job_response = iothub_job_manager.create_scheduled_job(job_id, job_request)

디바이스 쌍 업데이트 작업 예약

create_scheduled_job을 사용하여 하나 또는 여러 디바이스에서 장치 쌍의 원하는 속성 업데이트를 실행할 새 작업을 만듭니다.

create_scheduled_job 매개 변수 참고 사항:

• job_id 고유해야 합니다.
• type을(를) scheduleUpdateTwin(으)로 설정
• 직접 메서드 이름 및 페이로드를 설정하는 데 사용 update_twin
• 실행 시간(초)을 지정하는 데 사용 max_execution_time_in_seconds
• 직접 메서드 호출이 있는 하나 이상의 디바이스에 대한 조건을 지정하는 데 사용합니다 query_condition . 쿼리 조건에 대한 자세한 내용은 디바이스 및 모듈 쌍, 작업 및 메시지 라우팅에 대한 IoT Hub 쿼리 언어를 참조 하세요.

예시:

UPDATE_PATCH = {"building":43,"floor":3}
job_id = uuid.uuid4()
TIMEOUT = 60

job_request = JobRequest()
job_request.job_id = job_id
job_request.type = "scheduleUpdateTwin"
job_request.start_time = datetime.datetime.utcnow().isoformat()
job_request.update_twin = Twin(etag="*", properties=TwinProperties(desired=UPDATE_PATCH))
job_request.max_execution_time_in_seconds = TIMEOUT
job_request.query_condition = "DeviceId in ['{}']".format(device_id)

new_job_response = iothub_job_manager.create_scheduled_job(job_id, job_request)

작업 모니터링

get_scheduled_job 사용하여 IoT Hub에서 특정 작업의 세부 정보를 검색합니다.

다음은 작업이 완료될 때까지 5초마다 특정 작업 ID의 작업 상태를 확인하는 예제입니다.

while True:
    get_job_response = iothub_job_manager.get_scheduled_job(job_request.job_id)
    print_job_response("Get job response: ", get_job_response)
    if get_job_response.status == "completed":
      print ( "Job is completed." )
    time.sleep(5)

SDK 일정 작업 예제

Python용 Azure IoT SDK는 작업 예약 작업을 처리하는 서비스 앱의 작업 샘플을 제공합니다. 자세한 내용은 다음을 참조하세요.

• 직접 메서드 작업 예약
• 디바이스 쌍 업데이트를 예약합니다.

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

개요

이 문서에서는 Node.js Azure IoT SDK를 사용하여 백 엔드 서비스 애플리케이션 코드를 만들어 작업을 예약하여 직접 메서드를 호출하거나 하나 이상의 디바이스에서 디바이스 쌍 업데이트를 수행하는 방법을 설명합니다.

서비스 SDK 패키지 설치

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

npm install azure-iothub --save

JobClient 클래스는 백 엔드 애플리케이션에서 작업 예약과 상호 작용하는 데 필요한 모든 메서드를 노출합니다.

IoT Hub에 연결

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

• 공유 액세스 정책
• Microsoft Entra

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

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

이 문서에서는 직접 메서드를 호출하도록 작업을 예약하고, 디바이스 쌍을 업데이트하는 작업을 예약하고, 하나 이상의 디바이스에 대한 작업의 진행률을 모니터링할 수 있는 백 엔드 코드를 설명합니다. 이러한 작업을 수행하려면 서비스에 레지스트리 읽기 및 레지스트리 쓰기 권한이 있어야 합니다. 기본적으로 모든 IoT Hub는 이 사용 권한을 부여하는 registryReadWrite라는 공유 액세스 정책을 사용하여 만듭니다.

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

예시:

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

Microsoft Entra를 사용하여 연결

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

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

• Azure에서 사용자 인증 시작
• JavaScript용 Azure ID 클라이언트 라이브러리

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

• 레지스트리
• 클라이언트
• JobClient

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

• Azure 서비스 URL - Azure 서비스 URL은 {Your Entra ___domain URL}.azure-devices.net 형식이며 https:// 접두사 없이 이어야 합니다. 예들 들어 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 예제를 참조 하세요.

직접 메서드 작업 만들기

scheduleDeviceMethod를 사용하여 하나 또는 여러 디바이스에서 직접 메서드를 실행하는 작업을 예약합니다.

먼저 메서드 이름, 페이로드 및 응답 시간 제한 정보를 사용하여 직접 메서드 업데이트 변수를 만듭니다. 예시:

var methodParams = {
    methodName: 'lockDoor',
    payload: null,
    responseTimeoutInSeconds: 15 // Time-out after 15 seconds if device is unable to process method
};

그런 다음, 직접 메서드 호출 작업을 예약하기 위해 호출 scheduleDeviceMethod 합니다.

• 각 작업에는 고유한 작업 ID가 있어야 합니다. 이 작업 ID를 사용하여 이 문서의 작업 모니터링 섹션에 설명된 대로 작업을 모니터링할 수 있습니다.
• queryCondition 작업을 실행할 디바이스를 평가할 매개 변수를 지정합니다. 쿼리 조건에 대한 자세한 내용은 디바이스 및 모듈 쌍, 작업 및 메시지 라우팅에 대한 IoT Hub 쿼리 언어를 참조 하세요.
• jobResult 작업 일정 결과에 대한 콜백을 확인합니다. 작업이 성공적으로 예약된 경우 이 문서의 작업 모니터링 섹션에 표시된 대로 작업 상태를 모니터링할 수 있습니다.

예시:

var methodJobId = uuid.v4();
var queryCondition = "deviceId IN ['myDeviceId']";
var startTime = new Date();
var maxExecutionTimeInSeconds =  300;

jobClient.scheduleDeviceMethod(methodJobId,
                            queryCondition,
                            methodParams,
                            startTime,
                            maxExecutionTimeInSeconds,
                            function(err) {
    if (err) {
        console.error('Could not schedule direct method job: ' + err.message);
    } else {
        monitorJob(methodJobId, function(err, result) {
            if (err) {
                console.error('Could not monitor direct method job: ' + err.message);
            } else {
                console.log(JSON.stringify(result, null, 2));
            }
        });
    }
});

디바이스 쌍 업데이트 작업 예약

scheduleTwinUpdate를 사용하여 하나 또는 여러 디바이스에서 디바이스 쌍 업데이트를 실행하는 새 작업을 만듭니다.

먼저, 디바이스 쌍의 원하는 속성 업데이트 변수를 만듭니다.

var twinPatch = {
   etag: '*',
   properties: {
       desired: {
           building: '43',
           floor: 3
       }
   }
};

그런 다음 scheduleTwinUpdate에 전화를 걸어 디바이스 쌍의 필요한 속성 업데이트 작업을 예약합니다.

• 각 작업에는 고유한 작업 ID가 있어야 합니다. 이 작업 ID를 사용하여 이 문서의 작업 모니터링 섹션에 설명된 대로 작업을 모니터링할 수 있습니다.
• queryCondition 작업을 실행할 디바이스를 평가할 매개 변수를 지정합니다. 쿼리 조건에 대한 자세한 내용은 디바이스 및 모듈 쌍, 작업 및 메시지 라우팅에 대한 IoT Hub 쿼리 언어를 참조 하세요.
• jobResult 작업 일정 결과에 대한 콜백을 확인합니다. 작업이 성공적으로 예약된 경우 이 문서의 작업 모니터링 섹션에 표시된 대로 작업 상태를 모니터링할 수 있습니다.

예시:

var twinJobId = uuid.v4();
var queryCondition = "deviceId IN ['myDeviceId']";
var startTime = new Date();
var maxExecutionTimeInSeconds =  300;

console.log('scheduling Twin Update job with id: ' + twinJobId);
jobClient.scheduleTwinUpdate(twinJobId,
                            queryCondition,
                            twinPatch,
                            startTime,
                            maxExecutionTimeInSeconds,
                            function(err) {
    if (err) {
        console.error('Could not schedule twin update job: ' + err.message);
    } else {
        monitorJob(twinJobId, function(err, result) {
            if (err) {
                console.error('Could not monitor twin update job: ' + err.message);
            } else {
                console.log(JSON.stringify(result, null, 2));
            }
        });
    }
});

작업 모니터링

getJob을 사용하여 특정 작업 ID에 대한 작업 상태를 모니터링합니다.

이 예제 함수는 작업이 완료되거나 실패할 때까지 특정 작업 ID에 대한 작업 상태를 주기적으로 확인합니다.

function monitorJob (jobId, callback) {
    var jobMonitorInterval = setInterval(function() {
        jobClient.getJob(jobId, function(err, result) {
        if (err) {
            console.error('Could not get job status: ' + err.message);
        } else {
            console.log('Job: ' + jobId + ' - status: ' + result.status);
            if (result.status === 'completed' || result.status === 'failed' || result.status === 'cancelled') {
            clearInterval(jobMonitorInterval);
            callback(null, result);
            }
        }
        });
    }, 5000);
}

SDK 일정 작업 예제

Node.js용 Azure IoT SDK는 작업 예약 작업을 처리하는 서비스 앱의 작업 샘플을 제공합니다. 자세한 내용은 작업 클라이언트 E2E 테스트를 참조하세요.