클라우드-디바이스 메시지 보내기 및 받기

아티클
07/17/2024

Azure IoT Hub는 솔루션 백 엔드에서 수백만 개의 디바이스로의 C2D(클라우드-디바이스) 메시지를 포함하여 양방향 통신을 가능하게 하는 완전 관리형 서비스입니다.

이 문서에서는 Azure IoT SDK를 사용하여 다음 형식의 애플리케이션을 빌드하는 방법을 설명합니다.

IoT Hub 메시징 큐에서 클라우드-디바이스 메시지를 수신하고 처리하는 디바이스 애플리케이션입니다.
IoT Hub 메시징 큐를 통해 단일 디바이스에 클라우드-디바이스 메시지를 보내는 백 엔드 애플리케이션입니다.

이 문서는 이 문서 내에서 참조되는 실행 가능한 SDK 샘플을 보완하기 위한 것입니다.

참고 항목

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

개요

클라우드-디바이스 메시지를 수신하는 디바이스 애플리케이션의 경우 IoT Hub에 연결한 다음, 들어오는 메시지를 처리하도록 메시지 처리기를 설정해야 합니다. Azure IoT Hub 디바이스 SDK는 디바이스가 서비스에서 메시지를 수신하고 처리하는 데 사용할 수 있는 클래스와 메서드를 제공합니다. 이 문서에서는 다음을 포함하여 메시지를 수신하는 디바이스 애플리케이션의 주요 요소에 대해 설명합니다.

디바이스 클라이언트 개체 선언
IoT Hub에 연결
IoT Hub 메시지 큐에서 메시지 검색
메시지를 처리하고 IoT Hub에 다시 승인 보내기
메시지 수신 재시도 정책 구성

백 엔드 애플리케이션이 클라우드-디바이스 메시지를 보내려면 IoT Hub에 연결하고 IoT Hub 메시지 큐를 통해 메시지를 보내야 합니다. Azure IoT Hub 서비스 SDK는 애플리케이션이 디바이스에 메시지를 보내는 데 사용할 수 있는 클래스와 메서드를 제공합니다. 이 문서에서는 다음을 포함하여 디바이스에 메시지를 보내는 모든 애플리케이션의 주요 요소에 대해 설명합니다.

서비스 클라이언트 개체 선언
IoT Hub에 연결
메시지 작성 및 보내기
배달 피드백 받기
메시지 보내기 재시도 정책 구성

메시지 큐 이해

클라우드-디바이스 메시징을 이해하려면 IoT Hub 디바이스 메시지 큐의 작동 방식에 대한 몇 가지 기본 사항을 이해해야 합니다.

솔루션 백 엔드 애플리케이션에서 IoT 디바이스로 전송된 클라우드-디바이스 메시지는 IoT Hub를 통해 라우팅됩니다. 솔루션 백 엔드 애플리케이션과 대상 디바이스 간에는 직접적인 P2P 메시징 통신이 없습니다. IoT Hub는 들어오는 메시지를 메시지 큐에 넣어 대상 IoT 디바이스에서 다운로드할 수 있도록 준비합니다.

메시지 전달을 한 번 이상 보장하기 위해 IoT 허브는 디바이스 별 큐에 클라우드-디바이스 메시지를 유지합니다. 디바이스는 IoT Hub가 큐에서 메시지를 제거하기 전에 메시지 완료를 명시적으로 승인해야 합니다. 이 방법은 연결 및 디바이스 오류로부터 복원력을 보장합니다.

IoT Hub는 디바이스 메시지 큐에 메시지를 넣을 때 메시지 상태를 큐에 넣음으로 설정합니다. 디바이스 스레드가 큐에서 메시지를 가져오면 IoT Hub는 메시지 상태를 숨김으로 설정하여 메시지를 잠급니다. 이 상태는 디바이스의 다른 스레드가 동일한 메시지를 처리하는 것을 방지합니다. 디바이스 스레드가 메시지 처리를 성공적으로 완료하면 IoT Hub에 알리고 IoT Hub는 메시지 상태를 완료됨으로 설정합니다.

메시지를 성공적으로 수신하고 처리하는 디바이스 애플리케이션은 메시지를 완료했다고 합니다. 그러나 필요한 경우 디바이스는 다음을 수행할 수도 있습니다.

메시지 거부. 이 경우 IoT Hub는 메시지를 Dead lettered 상태로 설정합니다. MQTT(메시지 큐 원격 분석 전송) 프로토콜을 통해 연결하는 디바이스는 클라우드-디바이스 메시지를 거부할 수 없습니다.
메시지 중단. 이 경우 IoT Hub는 메시지 상태를 큐에 넣음으로 설정하여 메시지를 큐에 다시 넣습니다. MQTT 프로토콜을 통해 연결하는 디바이스는 클라우드-디바이스 메시지를 중단할 수 없습니다.

클라우드-디바이스 메시지 수명 주기 및 IoT Hub가 클라우드-디바이스 메시지를 처리하는 방법에 대한 자세한 내용은 IoT 허브에서 클라우드-디바이스 메시지 보내기를 참조하세요.

클라우드-디바이스 메시지 받기

이 섹션에서는 .NET용 Azure IoT SDK의 DeviceClient 클래스를 사용하여 클라우드-디바이스 메시지를 수신하는 방법을 설명합니다.

디바이스 클라이언트 애플리케이션이 메시지를 수신하는 데 사용할 수 있는 두 가지 옵션이 있습니다.

폴링: 디바이스 애플리케이션이 코드 루프(예: while 또는 for 루프)를 사용하여 새 IoT Hub 메시지를 확인합니다. 루프가 지속적으로 실행되어 메시지를 확인합니다.
콜백: 디바이스 애플리케이션이 메시지가 도착할 때 즉시 호출되는 비동기 메시지 처리기 메서드를 설정합니다.

DeviceClient 개체 선언

DeviceClient에는 IoT Hub에서 메시지를 수신하는 데 필요한 메서드와 속성이 포함되어 있습니다.

예시:

static DeviceClient deviceClient;

연결 매개 변수 제공

CreateFromConnectionString 메서드를 사용하여 IoT Hub 기본 연결 문자열과 디바이스 ID를 DeviceClient에 제공합니다. 필수 IoT Hub 기본 연결 문자열 외에도 CreateFromConnectionString 메서드를 오버로드하여 다음과 같은 선택적 매개 변수를 포함할 수 있습니다.

transportType - 전송 프로토콜: HTTP 버전 1, AMQP 또는 MQTT의 변형입니다. 기본값은 AMQP입니다. 사용 가능한 모든 값을 보려면 TransportType 열거형을 참조하세요.
transportSettings - DeviceClient 및 ModuleClient에 대한 다양한 전송 관련 설정을 정의하는 데 사용되는 인터페이스입니다. 자세한 내용은 ITransportSettings 인터페이스를 참조하세요.
ClientOptions - 초기화 중에 디바이스 또는 모듈 클라이언트 인스턴스의 구성을 허용하는 옵션입니다.

이 예에서는 CreateFromConnectionString을 호출하여 DeviceClient 연결 IoT 허브 및 디바이스 ID 설정을 정의합니다.

static string connectionString = "{your IoT hub connection string}";
static string deviceID = "{your device ID}";
deviceClient = DeviceClient.CreateFromConnectionString(connectionString,deviceID);

폴링

폴링에서는 ReceiveAsync를 사용하여 메시지를 확인합니다.

ReceiveAsync에 대한 호출은 다음 형식을 취할 수 있습니다.

ReceiveAsync() - 계속하기 전에 메시지의 기본 제한 시간을 기다립니다.
ReceiveAsync (Timespan) - 특정 제한 시간을 사용하여 디바이스 큐에서 메시지를 수신합니다.
ReceiveAsync (CancellationToken) - 취소 토큰을 사용하여 디바이스 큐에서 메시지를 받습니다. 취소 토큰을 사용하는 경우 기본 제한 시간이 사용되지 않습니다.

MQTT 또는 AMQP 대신 HTTP 1의 전송 형식을 사용하는 경우 ReceiveAsync 메서드가 즉시 반환됩니다. HTTP 1에서 클라우드-디바이스 메시지에 대해 지원되는 패턴은 메시지를 가끔씩(최소한 25분에 한 번) 확인하는 디바이스에 간헐적으로 연결됩니다. HTTP 1 수신을 더 많이 실행하면 IoT Hub가 요청을 제한할 수 있습니다. MQTT, AMQP 및 HTTP 1 지원 간의 차이점에 대한 자세한 내용은 클라우드-디바이스 통신 지침 및 통신 프로토콜 선택을 참조하세요.

CompleteAsync 메서드

디바이스가 메시지를 수신한 후 디바이스 애플리케이션은 CompleteAsync 메서드를 호출하여 메시지가 성공적으로 처리되었으며 메시지가 IoT Hub 디바이스 큐에서 안전하게 제거될 수 있음을 IoT Hub에 알립니다. 디바이스는 사용 중인 전송 프로토콜에 관계없이 처리가 성공적으로 완료되면 이 메서드를 호출해야 합니다.

메시지 중단, 거부 또는 시간 제한

AMQP 및 HTTP 버전 1 프로토콜을 사용하지만 MQTT 프로토콜은 아닌 디바이스에서 다음을 수행할 수도 있습니다.

AbandonAsync를 호출하여 메시지를 취소합니다. 이로 인해 IoT Hub는 나중에 사용할 수 있도록 디바이스 큐에 메시지를 보존합니다.
RejectAsync를 호출하여 메시지를 거부합니다. 이렇게 하면 디바이스 큐에서 메시지가 영구적으로 제거됩니다.

디바이스에서 메시지를 완료, 중단 또는 거부할 수 없도록 하는 문제가 발생할 경우 IoT Hub는 정해진 시간 제한 기간이 지나면 메시지를 다시 배달하도록 큐에 넣습니다. 이런 이유로 디바이스 앱의 메시지 처리 논리는 idempotent이므로 같은 메시지를 여러 번 수신해도 동일한 결과가 생성됩니다.

폴링 루프

폴링을 사용하면 애플리케이션은 ReceiveAsync 메서드를 반복적으로 호출하는 코드 루프를 사용하여 중지될 때까지 새 메시지를 확인합니다.

시간 제한 값 또는 기본 시간 제한과 함께 ReceiveAsync를 사용하는 경우 루프에서 ReceiveAsync에 대한 각 호출은 지정된 시간 제한 기간 동안 기다립니다. ReceiveAsync 시간이 초과되면 null 값이 반환되고 루프가 계속됩니다.

메시지가 수신되면 CompleteAsync에 전달되어야 하는 Task 개체가 ReceiveAsync에 의해 반환됩니다. CompleteAsync를 호출하면 IoT Hub에 Task 매개 변수를 기반으로 메시지 큐에서 지정된 메시지를 삭제하라고 알립니다.

이 예에서 루프는 메시지가 수신되거나 폴링 루프가 중지될 때까지 ReceiveAsync를 호출합니다.

static bool stopPolling = false;

while (!stopPolling)
{
   // Check for a message. Wait for the default DeviceClient timeout period.
   using Message receivedMessage = await _deviceClient.ReceiveAsync();

   // Continue if no message was received
   if (receivedMessage == null)
   {
      continue;
   }
   else  // A message was received
   {
      // Print the message received
      Console.WriteLine($"{DateTime.Now}> Polling using ReceiveAsync() - received message with Id={receivedMessage.MessageId}");
      PrintMessage(receivedMessage);

      // Notify IoT Hub that the message was received. IoT Hub will delete the message from the message queue.
      await _deviceClient.CompleteAsync(receivedMessage);
      Console.WriteLine($"{DateTime.Now}> Completed C2D message with Id={receivedMessage.MessageId}.");
   }

   // Check to see if polling loop should end
   stopPolling = ShouldPollingstop ();
}

Callback

디바이스 애플리케이션에서 콜백 클라우드-디바이스 메시지를 수신하려면 애플리케이션이 IoT Hub에 연결하고 들어오는 메시지를 처리하도록 콜백 수신기를 설정해야 합니다. 디바이스로 들어오는 메시지는 IoT Hub 메시지 큐에서 수신됩니다.

콜백을 사용하면 디바이스 애플리케이션이 SetReceiveMessageHandlerAsync를 사용하여 메시지 처리기 메서드를 설정합니다. 메시지 처리기가 호출된 다음 메시지가 수신됩니다. 메시지를 수신하기 위한 콜백 메서드를 만들면 수신된 메시지를 지속적으로 폴링할 필요가 없습니다.

콜백은 다음 프로토콜을 통해서만 사용할 수 있습니다.

Mqtt
Mqtt_WebSocket_Only
Mqtt_Tcp_Only
Amqp
Amqp_WebSocket_Only
Amqp_Tcp_only

SDK 메서드는 수신된 메시지를 폴링해야 하므로 Http1 프로토콜 옵션은 콜백을 지원하지 않으며 이는 콜백 원칙에 위배됩니다.

이 예에서 SetReceiveMessageHandlerAsync는 메시지가 수신될 때마다 호출되는 OnC2dMessageReceivedAsync라는 콜백 처리기 메서드를 설정합니다.

// Subscribe to receive C2D messages through a callback (which isn't supported over HTTP).
await deviceClient.SetReceiveMessageHandlerAsync(OnC2dMessageReceivedAsync, deviceClient);
Console.WriteLine($"\n{DateTime.Now}> Subscribed to receive C2D messages over callback.");

메시지 재시도 정책 수신

디바이스 클라이언트 메시지 재시도 정책은 DeviceClient.SetRetryPolicy를 사용하여 정의할 수 있습니다.

메시지 다시 시도 제한 시간은 DeviceClient.OperationTimeoutInMilliseconds 속성에 저장됩니다.

SDK 수신 메시지 샘플

.NET/C# SDK에는 이 섹션에 설명된 메시지 수신 메서드가 포함된 메시지 수신 샘플이 포함되어 있습니다.

클라우드-디바이스 메시지 보내기

이 섹션에서는 .NET용 Azure IoT SDK의 ServiceClient 클래스를 사용하여 솔루션 백 엔드 애플리케이션에서 IoT 디바이스로 메시지를 보내는 데 필요한 필수 코드를 설명합니다. 앞에서 설명한 대로 솔루션 백 엔드 애플리케이션은 IoT Hub에 연결되고 메시지는 대상 디바이스로 인코딩된 IoT Hub로 전송됩니다. IoT Hub는 들어오는 메시지를 해당 메시지 큐에 저장하고, 메시지는 IoT Hub 메시지 큐에서 대상 디바이스로 배달됩니다.

솔루션 백 엔드 애플리케이션은 메시지 큐를 통해 디바이스 배달을 위해 IoT Hub로 전송된 메시지에 대한 배달 피드백을 요청하고 수신할 수도 있습니다.

ServiceClient 개체 선언

ServiceClient에는 IoT Hub를 통해 애플리케이션에서 디바이스로 메시지를 보내는 데 필요한 메서드와 속성이 포함되어 있습니다.

static ServiceClient serviceClient;

연결 문자열 제공

CreateFromConnectionString 메서드를 사용하여 IoT Hub 기본 연결 문자열을 ServiceClient에 제공합니다. 필수 IoT Hub 기본 연결 문자열 외에도 CreateFromConnectionString 메서드를 오버로드하여 다음과 같은 선택적 매개 변수를 포함할 수 있습니다.

transportType - Amqp 또는 Amqp_WebSocket_Only.
transportSettings - 서비스 클라이언트에 대한 AMQP 및 HTTP 프록시 설정입니다.
ServiceClientOptions - 초기화 중에 서비스 클라이언트 인스턴스 구성을 허용하는 옵션입니다. 자세한 내용은 ServiceClientOptions를 참조하세요.

이 예에서는 IoT Hub 연결 문자열을 사용하여 ServiceClient 개체를 만듭니다.

static string connectionString = "{your iot hub connection string}";
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);

비동기식 클라우드-디바이스 메시지 보내기

클라우드(IoT Hub)를 통해 애플리케이션에서 디바이스로 비동기 메시지를 보내려면 sendAsync를 사용합니다. 호출은 AMQP 프로토콜을 사용하여 이루어집니다.

sendAsync는 다음 매개 변수를 사용합니다.

deviceID - 대상 디바이스의 문자열 식별자입니다.
message - 클라우드-디바이스 메시지입니다. 메시지는 메시지 형식이며 이에 따라 서식을 지정할 수 있습니다.
timeout - 선택적 제한 시간 값입니다. 지정하지 않으면 기본값은 1분입니다.

이 예에서는 10초 제한 시간 값을 사용하여 대상 디바이스에 테스트 메시지를 보냅니다.

string targetDevice = "Device-1";
static readonly TimeSpan operationTimeout = TimeSpan.FromSeconds(10);
var commandMessage = new
Message(Encoding.ASCII.GetBytes("Cloud to device message."));
await serviceClient.SendAsync(targetDevice, commandMessage, operationTimeout);

배달 피드백 받기

전송 프로그램은 각 클라우드-디바이스 메시지에 대해 IoT Hub에서 배달(또는 만료) 승인을 요청할 수 있습니다. 이 옵션을 사용하면 전송 프로그램에서 알림, 다시 시도 또는 보정 논리를 사용할 수 있습니다. 메시지 피드백 작업 및 속성에 대한 전체 설명은 메시지 피드백에 설명되어 있습니다.

메시지 배달 피드백을 받으려면 다음을 수행합니다.

feedbackReceiver 개체 만들기
Ack 매개 변수를 사용하여 메시지 보내기
피드백 수신 대기

FeedbackReceiver 개체 만들기

GetFeedbackReceiver를 호출하여 FeedbackReceiver 개체를 만듭니다. FeedbackReceiver에는 서비스가 피드백 수신 작업을 수행하는 데 사용할 수 있는 메서드가 포함되어 있습니다.

var feedbackReceiver = serviceClient.GetFeedbackReceiver();

Ack 매개 변수를 사용하여 메시지 보내기

배달 피드백을 받으려면 각 메시지에 배달 승인 Ack 속성 값이 포함되어야 합니다. Ack 속성은 다음 값 중 하나일 수 있습니다.

없음(기본값): 피드백 메시지가 생성되지 않습니다.
Positive: 메시지가 완료된 경우 피드백 메시지를 받습니다.
Negative: 디바이스에서 메시지를 완료하지 않고 메시지가 만료된 경우(또는 최대 배달 횟수에 도달한 경우) 피드백 메시지를 받습니다.
Full: Positive 및 Negative 결과 모두에 대한 피드백입니다.

이 예에서는 Ack 속성이 Full로 설정되어 하나의 메시지에 대해 긍정적이거나 부정적인 메시지 배달 피드백을 모두 요청합니다.

var commandMessage = new
Message(Encoding.ASCII.GetBytes("Cloud to device message."));
commandMessage.Ack = DeliveryAcknowledgement.Full;
await serviceClient.SendAsync(targetDevice, commandMessage);

피드백 수신 대기

CancellationToken을 정의합니다. 그런 다음 루프에서 ReceiveAsync를 반복적으로 호출하여 배달 피드백 메시지를 확인합니다. ReceiveAsync에 대한 각 호출은 ServiceClient 개체에 정의된 제한 시간 동안 기다립니다.

수신된 메시지 없이 ReceiveAsync 제한 시간이 만료되면 ReceiveAsync는 null을 반환하고 루프가 계속됩니다.
피드백 메시지가 수신되면 취소 토큰과 함께 CompleteAsync에 전달되어야 하는 Task 개체가 ReceiveAsync에 의해 반환됩니다. CompleteAsync를 호출하면 Task 매개 변수를 기반으로 메시지 큐에서 지정된 전송 메시지가 삭제됩니다.
필요한 경우 수신 코드는 AbandonAsync를 호출하여 전송 메시지를 큐에 다시 넣을 수 있습니다.

var feedbackReceiver = serviceClient.GetFeedbackReceiver();

// Define the cancellation token.
CancellationTokenSource source = new CancellationTokenSource();
CancellationToken token = source.Token;
// Call ReceiveAsync, passing the token. Wait for the timout period.
var feedbackBatch = await feedbackReceiver.ReceiveAsync(token);
if (feedbackBatch == null) continue;

이 예에서는 이러한 단계를 포함하는 방법을 보여 줍니다.

private async static void ReceiveFeedbackAsync()
{
      var feedbackReceiver = serviceClient.GetFeedbackReceiver();

      Console.WriteLine("\nReceiving c2d feedback from service");
      while (true)
      {
         // Check for messages, wait for the timeout period.
         var feedbackBatch = await feedbackReceiver.ReceiveAsync();
         // Continue the loop if null is received after a timeout.
         if (feedbackBatch == null) continue;

         Console.ForegroundColor = ConsoleColor.Yellow;
         Console.WriteLine("Received feedback: {0}",
            string.Join(", ", feedbackBatch.Records.Select(f => f.StatusCode)));
         Console.ResetColor();

         await feedbackReceiver.CompleteAsync(feedbackBatch);
      }
   }

이 피드백 수신 패턴은 디바이스 애플리케이션에서 클라우드-디바이스 메시지를 수신하는 데 사용되는 패턴과 유사합니다.

서비스 클라이언트 다시 연결

예외가 발생하면 서비스 클라이언트는 해당 정보를 호출 애플리케이션에 전달합니다. 이 시점에서는 예외 세부 사항을 확인하고 필요한 조치를 취하는 것이 좋습니다.

예시:

네트워크 예외인 경우 작업을 다시 시도할 수 있습니다.
보안 예외(무단 예외)인 경우 자격 증명을 검사하고 최신 상태인지 확인합니다.
제한/할당량 초과 예외인 경우 요청 전송 빈도를 모니터링 및/또는 수정하거나 허브 인스턴스 배율 단위를 업데이트합니다. 자세한 내용은 IoT Hub 할당량 및 제한을 참조하세요.

메시지 재시도 정책 보내기

ServiceClient 메시지 재시도 정책은 ServiceClient.SetRetryPolicy를 사용하여 정의할 수 있습니다.

SDK 전송 메시지 샘플

.NET/C# SDK에는 이 섹션에 설명된 메시지 보내기 메서드가 포함된 서비스 클라이언트 샘플이 포함되어 있습니다.

클라우드-디바이스 메시지 받기

이 섹션에서는 Java용 Azure IoT SDK의 DeviceClient 클래스를 사용하여 클라우드-디바이스 메시지를 수신하는 방법을 설명합니다.

Java 기반 디바이스 애플리케이션이 클라우드-디바이스 메시지를 수신하려면 IoT Hub에 연결한 다음 IoT Hub에서 들어오는 메시지를 처리하도록 콜백 수신기 및 메시지 처리기를 설정해야 합니다. 또한 디바이스 애플리케이션은 디바이스-IoT Hub 메시지 연결이 끊어진 경우 연결 끊김을 검색하고 처리할 수 있어야 합니다.

Azure IoT Java SDK 라이브러리 가져오기

이 문서에서 참조된 코드는 이러한 SDK 라이브러리를 사용합니다.

import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.exceptions.IotHubClientException;
import com.microsoft.azure.sdk.iot.device.transport.IotHubConnectionStatus;

DeviceClient 개체 선언

DeviceClient 개체 인스턴스화에는 다음 매개 변수가 필요합니다.

connString - IoT 디바이스 연결 문자열입니다. 연결 문자열은 ';'으로 구분된 키-값 쌍의 집합이며, 키와 값은 '='으로 구분됩니다. 여기에는 HostName, DeviceId, and SharedAccessKey 키의 값이 포함되어야 합니다.
전송 프로토콜 - DeviceClient 연결은 다음 IoTHubClientProtocol 전송 프로토콜 중 하나를 사용할 수 있습니다. AMQP는 가장 다재다능하며 메시지를 자주 확인할 수 있고 메시지 거부 및 취소가 가능합니다. MQTT는 메시지 거부 또는 중단 방법을 지원하지 않습니다.
- AMQPS
- AMQPS_WS
- HTTPS
- MQTT
- MQTT_WS

예시:

static string connectionString = "{a device connection string}";
static protocol = IotHubClientProtocol.AMQPS;
DeviceClient client = new DeviceClient(connectionString, protocol);

메시지 콜백 방법 설정

IoT Hub에서 메시지가 수신될 때 알림을 받는 메시지 처리기 메서드를 정의하려면 setMessageCallback 메서드를 사용합니다.

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

callback - 콜백 메서드 이름입니다. null일 수 있습니다.
context - object 형식의 선택적 컨텍스트입니다. 지정되지 않은 경우 null을 사용합니다.

이 예에서는 컨텍스트 매개 변수가 없는 MessageCallback이라는 callback 메서드가 setMessageCallback에 전달됩니다.

client.setMessageCallback(new MessageCallback(), null);

메시지 콜백 처리기 만들기

콜백 메시지 처리기는 IoT Hub 메시지 큐에서 전달되어 들어오는 메시지를 수신하고 처리합니다.

이 예에서 메시지 처리기는 들어오는 메시지를 처리한 다음 IotHubMessageResult.COMPLETE를 반환합니다. IotHubMessageResult.COMPLETE 반환 값은 메시지가 성공적으로 처리되었으며 메시지가 디바이스 큐에서 안전하게 제거될 수 있음을 IoT Hub에 알립니다. 처리가 성공적으로 완료되면 디바이스는 IotHubMessageResult.COMPLETE를 반환하여 사용 중인 프로토콜에 관계없이 메시지 큐에서 메시지를 제거해야 함을 IoT Hub에 알려야 합니다.

  protected static class MessageCallback implements com.microsoft.azure.sdk.iot.device.MessageCallback
  {
      public IotHubMessageResult onCloudToDeviceMessageReceived(Message msg, Object context)
      {
          System.out.println(
                  "Received message with content: " + new String(msg.getBytes(), Message.DEFAULT_IOTHUB_MESSAGE_CHARSET));
          // Notify IoT Hub that the message
          return IotHubMessageResult.COMPLETE;
      }
  }

메시지 중단 및 거부 옵션

디바이스로 들어오는 수많은 메시지가 성공적으로 수신되어 IotHubMessageResult.COMPLETE가 발생하더라도 메시지를 중단하거나 거부해야 할 수도 있습니다.

MQTT가 아닌 AMQP 및 HTTPS를 사용하면 애플리케이션에서 다음을 수행할 수 있습니다.
- IotHubMessageResult.ABANDON 메시지입니다. IoT 허브는 이를 다시 큐에 넣고 나중에 다시 보냅니다.
- IotHubMessageResult.REJECT 메시지입니다. IoT 허브는 메시지를 다시 큐에 넣지 않고 메시지 큐에서 메시지를 영구적으로 제거합니다.
MQTT 또는 MQTT_WS를 사용하는 클라이언트는 ABANDON 또는 REJECT 메시지를 보낼 수 없습니다.

참고 항목

MQTT 또는 AMQP 대신 HTTPS를 전송으로 사용하는 경우 DeviceClient 인스턴스는 IoT Hub의 메시지를 자주(최소 25분 간격) 확인합니다. MQTT, AMQP, HTTPS 지원 간 차이점에 대한 자세한 내용은 클라우드-디바이스 통신 지침 및 통신 프로토콜 선택을 참조하세요.

메시지 상태 콜백 메서드 만들기

애플리케이션은 registerConnectionStatusChangeCallback을 사용하여 디바이스의 연결 상태가 변경될 때 실행될 콜백 메서드를 등록할 수 있습니다. 이런 방식으로 애플리케이션은 다운된 메시지 연결을 검색하고 다시 연결을 시도할 수 있습니다.

이 예에서는 연결 상태 변경 콜백 메서드로 IotHubConnectionStatusChangeCallbackLogger가 등록되어 있습니다.

client.registerConnectionStatusChangeCallback(new IotHubConnectionStatusChangeCallbackLogger(), new Object());

콜백이 실행되고 ConnectionStatusChangeContext 개체를 전달합니다.

현재 연결 상태를 가져오려면 connectionStatusChangeContext.getNewStatus()를 호출합니다.

IotHubConnectionStatus status = connectionStatusChangeContext.getNewStatus();

반환된 연결 상태는 다음 값 중 하나일 수 있습니다.

IotHubConnectionStatus.DISCONNECTED
IotHubConnectionStatus.DISCONNECTED_RETRYING
IotHubConnectionStatus.CONNECTED

연결 상태 변경 이유를 알아보려면 connectionStatusChangeContext.getNewStatusReason()을 호출합니다.

IotHubConnectionStatusChangeReason statusChangeReason = connectionStatusChangeContext.getNewStatusReason();

연결 상태 변경 이유를 찾으려면 connectionStatusChangeContext.getCause()를 호출합니다. 정보가 없으면 getCause()는 null을 반환할 수 있습니다.

Throwable throwable = connectionStatusChangeContext.getCause();
if (throwable != null)
    throwable.printStackTrace();

상태 변경 콜백 메서드 연결 상태 변경 상태를 추출하는 방법, 디바이스 상태가 변경된 이유 및 컨텍스트를 보여 주는 전체 샘플은 이 문서의 SDK 수신 메시지 샘플 섹션에 나열된 HandleMessages 샘플을 참조하세요.

디바이스와 IoT Hub 간의 연결 열기

open을 사용하여 디바이스와 IoT Hub 간의 연결을 만듭니다. 이제 디바이스는 IoT Hub와 비동기식으로 메시지를 보내고 받을 수 있습니다. 클라이언트가 이미 열려 있으면 메서드는 아무 작업도 수행하지 않습니다.

client.open(true);

SDK 수신 메시지 샘플

HandleMessages: IoT Hub에 연결하고 클라우드-디바이스 메시지를 수신하는 Java용 Microsoft Azure IoT SDK에 포함된 샘플 디바이스 앱입니다.

클라우드-디바이스 메시지 보내기

이 섹션에서는 Java용 Azure IoT SDK의 ServiceClient 클래스를 사용하여 클라우드-디바이스 메시지를 보내는 방법을 설명합니다. 솔루션 백 엔드 애플리케이션은 IoT Hub에 연결되고 메시지는 대상 디바이스로 인코딩된 IoT Hub로 전송됩니다. IoT Hub는 들어오는 메시지를 해당 메시지 큐에 저장하고, 메시지는 IoT Hub 메시지 큐에서 대상 디바이스로 배달됩니다.

종속성 문 추가

IoT 허브 서비스와 통신하기 위해 애플리케이션에서 iothub-java-service-client 패키지를 사용하도록 종속성을 추가합니다.

<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-service-client</artifactId>
  <version>1.7.23</version>
</dependency>

Import 문 추가

Azure IoT Java SDK 및 예외 처리기를 사용하려면 다음 import 문을 추가합니다.

import com.microsoft.azure.sdk.iot.service.*;
import java.io.IOException;
import java.net.URISyntaxException;

연결 프로토콜 정의

IotHubServiceClientProtocol을 사용하여 서비스 클라이언트가 IoT Hub와 통신하는 데 사용하는 애플리케이션 계층 프로토콜을 정의합니다.

IotHubServiceClientProtocol은 AMQPS 또는 AMQPS_WS 열거형만 허용합니다.

private static final IotHubServiceClientProtocol protocol =    
    IotHubServiceClientProtocol.AMQPS;

ServiceClient 개체 만들기

IoT 허브 연결 문자열과 프로토콜을 제공하는 ServiceClient 개체를 만듭니다.

private static final String connectionString = "{yourhubconnectionstring}";
private static final ServiceClient serviceClient (connectionString, protocol);

애플리케이션과 IoT Hub 간의 연결 열기

AMQP 보낸 사람 연결을 엽니다. 이 방법은 애플리케이션과 IoT Hub 간의 연결을 만듭니다.

serviceClient.open();

메시지 배달 피드백을 위한 피드백 수신기 열기

FeedbackReceiver를 사용하여 IoT Hub 피드백으로 전송된 메시지를 가져올 수 있습니다. FeedbackReceiver는 Receive 메서드가 Message 대신 FeedbackBatch를 반환하는 특수 수신기입니다.

이 예에서는 FeedbackReceiver 개체가 만들어지고 피드백을 기다리기 위해 open() 문이 호출됩니다.

FeedbackReceiver feedbackReceiver = serviceClient
  .getFeedbackReceiver();
if (feedbackReceiver != null) feedbackReceiver.open();

메시지 속성 추가

선택적으로 setProperties를 사용하여 메시지 속성을 추가할 수 있습니다. 이러한 속성은 디바이스로 전송된 메시지에 포함되며 수신 시 디바이스 애플리케이션에서 추출할 수 있습니다.

Map<String, String> propertiesToSend = new HashMap<String, String>();
propertiesToSend.put(messagePropertyKey,messagePropertyKey);
messageToSend.setProperties(propertiesToSend);

비동기 메시지 만들기 및 보내기

Message 개체는 보낼 메시지를 저장합니다. 이 예에서는 "클라우드-디바이스 메시지"가 배달됩니다.

setDeliveryAcknowledgement를 사용하여 IoT Hub 메시지 큐 승인에 대한 배달 여부를 요청합니다. 이 예에서 요청된 승인은 배달되거나 배달되지 않은 Full입니다.

클라이언트에서 디바이스로 비동기 메시지를 보내려면 SendAsync를 사용합니다. 또는 Send(비동기 아님) 메서드를 사용할 수 있지만 이 함수는 내부적으로 동기화되어 한 번에 하나의 전송 작업만 허용됩니다. 메시지는 애플리케이션에서 IoT Hub로 배달됩니다. IoT Hub는 메시지를 메시지 큐에 넣고 대상 디바이스에 배달할 준비를 합니다.

Message messageToSend = new Message("Cloud to device message.");
messageToSend.setDeliveryAcknowledgementFinal(DeliveryAcknowledgement.Full);
serviceClient.sendAsync(deviceId, messageToSend);

메시지 배달 피드백 받기

애플리케이션에서 메시지가 전송된 후 애플리케이션은 제한 시간 값을 사용하거나 사용하지 않고 receive를 호출할 수 있습니다. 제한 시간 값이 제공되지 않으면 기본 제한 시간이 사용됩니다. 이는 검사할 수 있는 메시지 배달 피드백 속성이 포함된 FeedbackBatch 개체를 다시 배달합니다.

이 예에서는 FeedbackBatch 수신기를 만들고 getEnqueuedTimeUtc를 호출하여 메시지가 큐에 넣은 시간을 인쇄합니다.

FeedbackBatch feedbackBatch = feedbackReceiver.receive(10000);
if (feedbackBatch != null) {
  System.out.println("Message feedback received, feedback time: "
    + feedbackBatch.getEnqueuedTimeUtc().toString());
}

SDK 전송 메시지 샘플

서비스 클라이언트 샘플 - 메시지 보내기 예, #1.
서비스 클라이언트 샘플 - 메시지 보내기 예 #2.

Azure IoT SDK 라이브러리 설치

관련 코드를 호출하기 전에 개발 컴퓨터에 azure-iot-device SDK 라이브러리를 설치합니다.

pip install azure-iot-device

IoT 디바이스와 메시지를 보내는 데 사용되는 두 가지 Python SDK 클래스가 있습니다. 이러한 클래스의 메시지 처리 방법은 이 페이지의 섹션에 설명되어 있습니다.

IoTHubDeviceClient 클래스에는 디바이스에서 Azure IoT Hub로의 동기 연결을 만들고 IoT Hub에서 메시지를 수신하는 메서드가 포함되어 있습니다.
IoTHubRegistryManager 클래스에는 IoT Hub 레지스트리 관리자 작업을 위한 API가 포함되어 있습니다. 이 문서에서 이 클래스의 메서드는 IoT Hub에 연결하고 디바이스에 메시지를 보내는 방법을 보여 줍니다.

클라우드-디바이스 메시지 받기

이 섹션에서는 Python용 Azure IoT SDK의 IoTHubDeviceClient 클래스를 사용하여 클라우드-디바이스 메시지를 수신하는 방법을 설명합니다.

Python 기반 디바이스 애플리케이션이 클라우드-디바이스 메시지를 수신하려면 IoT Hub에 연결한 다음 IoT Hub에서 들어오는 메시지를 처리하도록 콜백 메시지 처리기를 설정해야 합니다.

IoTHubDeviceClient 개체 가져오기

azure.iot.device SDK에서 IoTHubDeviceClient 함수를 가져오는 코드 줄을 추가합니다.

from azure.iot.device import IoTHubDeviceClient

디바이스 클라이언트 연결

IoTHubDeviceClient를 인스턴스화하고 IoT Hub 연결 문자열을 create_from_connection_string에 전달합니다. 그러면 디바이스에서 IoT Hub로의 연결이 만들어집니다.

또는 다음 방법 중 하나를 사용하여 IoTHubDeviceClient디바이스에 연결할 수 있습니다.

deviceConnectionString = "{your IoT hub connection string}";
client = IoTHubDeviceClient.create_from_connection_string ({deviceConnectionString})

다시 연결 처리

IoTHubDeviceClient는 기본적으로 끊어진 연결을 다시 설정하려고 시도합니다. 다시 연결 동작은 IoTHubDeviceClient connection_retry 및 connection_retry_interval 매개 변수에 의해 제어됩니다.

메시지 처리기 만들기

디바이스로 들어오는 메시지를 처리하는 메시지 처리기 함수를 만듭니다.

이 예에서는 메시지가 수신되면 message_handler가 호출됩니다. 메시지 속성(.items)은 루프를 사용하여 콘솔에 인쇄됩니다.

def message_handler(message):
    global RECEIVED_MESSAGES
    RECEIVED_MESSAGES += 1
    print("")
    print("Message received:")

    # print data from both system and application (custom) properties
    for property in vars(message).items():
        print ("    {}".format(property))

    print("Total calls received: {}".format(RECEIVED_MESSAGES))

메시지 처리기 할당

on_message_received 메서드를 사용하여 메시지 처리기 메서드를 IoTHubDeviceClient 개체에 할당합니다.

이 예에서는 message_handler라는 메시지 처리기 메서드가 IoTHubDeviceClient client 개체에 연결됩니다. client 개체는 IoT Hub에서 클라우드-디바이스 메시지를 수신하기를 기다립니다. 이 코드는 메시지를 최대 300초(5분) 동안 기다리거나 키보드 키를 누르면 종료됩니다.

try:
    # Attach the handler to the client
    client.on_message_received = message_handler

    while True:
        time.sleep(300)
except KeyboardInterrupt:
    print("IoT Hub C2D Messaging device sample stopped")
finally:
    # Graceful exit
    print("Shutting down IoT Hub Client")
    client.shutdown()

SDK 수신 메시지 샘플

메시지 수신 - Azure IoT Hub에서 디바이스로 전송된 C2D(클라우드-디바이스) 메시지를 수신합니다.

클라우드-디바이스 메시지 보내기

이 섹션에서는 Python용 Azure IoT SDK의 IoTHubRegistryManager 클래스를 사용하여 클라우드-디바이스 메시지를 보내는 방법을 설명합니다. 솔루션 백 엔드 애플리케이션은 IoT Hub에 연결되고 메시지는 대상 디바이스로 인코딩된 IoT Hub로 전송됩니다. IoT Hub는 들어오는 메시지를 해당 메시지 큐에 저장하고, 메시지는 IoT Hub 메시지 큐에서 대상 디바이스로 배달됩니다.

IoTHubRegistryManager 개체 가져오기

다음 import 문을 추가합니다. IoTHubRegistryManager에는 IoT Hub 레지스트리 관리자 작업을 위한 API가 포함되어 있습니다.

from azure.iot.hub import IoTHubRegistryManager

IoT Hub 레지스트리 관리자 연결

IoT Hub에 연결하는 IoTHubRegistryManager 개체를 인스턴스화하고 IoT Hub 연결 문자열을 from_connection_string에 전달합니다.

IoTHubConnectionString = "{Primary connection string to an IoT hub}"
registry_manager = IoTHubRegistryManager.from_connection_string(IoTHubConnectionString)

메시지 작성 및 보내기

클라우드(IoT Hub)를 통해 디바이스에 메시지를 보내려면 send_c2d_message를 사용합니다.

send_c2d_message는 다음 매개 변수를 사용합니다.

deviceID - 대상 디바이스의 문자열 식별자입니다.
message - 클라우드-디바이스 메시지입니다. 메시지 형식은 str(문자열)입니다.
properties - dict 형식 속성의 선택적 컬렉션입니다. 속성에는 애플리케이션 속성과 시스템 속성이 포함될 수 있습니다. 기본값은 {}입니다.

이 예에서는 대상 디바이스에 테스트 메시지를 보냅니다.

# define the device ID
deviceID = "Device-1"

# define the message
message = "{\"c2d test message\"}"

# include optional properties
props={}
props.update(messageId = "message1")
props.update(prop1 = "test property-1")
props.update(prop1 = "test property-2")
prop_text = "Test message"
props.update(testProperty = prop_text)

# send the message through the cloud (IoT Hub) to the device
registry_manager.send_c2d_message(deviceID, message, properties=props)

SDK 전송 메시지 샘플

send_message.py - 클라우드-디바이스 메시지를 보내는 방법을 보여 줍니다.

Node.js 메시징 패키지 설치

개발 컴퓨터에 azure-iot-device 및 azure-iothub 패키지를 설치하려면 다음 명령을 실행합니다.

npm install azure-iot-device --save
npm install azure-iothub --save

azure-iot-device 패키지에는 IoT 디바이스와 인터페이스하는 개체가 포함되어 있습니다. 이 문서에서는 IoT Hub에서 메시지를 수신하는 Client 클래스 코드를 설명합니다.

azure-iothub 패키지에는 IoT Hub와 상호 작용하는 개체가 포함되어 있습니다. 이 문서에서는 IoT Hub를 통해 애플리케이션에서 디바이스로 메시지를 보내는 Client 클래스 코드에 대해 설명합니다.

디바이스 애플리케이션에서 메시지 수신

이 섹션에서는 Node.js용 Azure IoT SDK의 azure-iot-device 패키지를 사용하여 클라우드-디바이스 메시지를 수신하는 방법을 설명합니다.

Node.js 기반 디바이스 애플리케이션이 클라우드-디바이스 메시지를 수신하려면 IoT Hub에 연결한 다음 IoT Hub에서 들어오는 메시지를 처리하도록 콜백 수신기 및 메시지 처리기를 설정해야 합니다. 또한 디바이스 애플리케이션은 디바이스-IoT Hub 메시지 연결이 끊어진 경우 연결 끊김을 검색하고 처리할 수 있어야 합니다.

클라이언트 모듈 만들기

azure-iot-device 패키지에서 Client 클래스를 사용하여 Client를 만듭니다. Client 클래스에는 디바이스가 IoT Hub에서 수신하고 IoT Hub로 보내는 데 사용할 수 있는 메서드가 포함되어 있습니다.

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

전송 프로토콜 선택

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

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

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

이 예에서는 AMQP 프로토콜을 Protocol 변수에 할당합니다. 이 프로토콜 변수는 이 문서의 연결 문자열 추가 섹션에 있는 Client.fromConnectionString 메서드에 전달됩니다.

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

메시지 완료, 거부, 중단 기능

선택한 프로토콜에 따라 메시지 완료, 거부, 중단 방법을 사용할 수 있습니다.

AMQP 및 HTTP

AMQP 및 HTTP 전송은 메시지를 완료, 거부 또는 중단할 수 있습니다.

완료 - 메시지를 완료하기 위해 클라우드-디바이스 메시지를 보낸 서비스에 메시지가 수신되었다는 알림이 전달됩니다. IoT Hub는 메시지 큐에서 메시지를 제거합니다. 메서드는 client.complete(message, callback function) 형식을 취합니다.
거부 - 메시지를 거부하려면 클라우드-디바이스 메시지를 보낸 서비스에 해당 메시지가 디바이스에서 처리되지 않는다는 알림이 전달됩니다. IoT Hub는 디바이스 큐에서 메시지를 영구적으로 제거합니다. 메서드는 client.reject(message, callback function) 형식을 취합니다.
중단 - 메시지를 중단하기 위해 IoT Hub는 즉시 메시지 재전송을 시도합니다. IoT Hub는 나중에 사용할 수 있도록 디바이스 큐에 메시지를 보존합니다. 메서드는 client.abandon(message, callback function) 형식을 취합니다.

MQTT

MQTT는 메시지 완료, 거부 또는 중단 함수를 지원하지 않습니다. 대신 MQTT는 기본적으로 메시지를 수락하고 해당 메시지는 IoT Hub 메시지 큐에서 제거됩니다.

다시 배달 시도

IoT Hub 문자열 및 전송 프로토콜 추가

다음 매개 변수를 사용하여 디바이스-IoT 허브 연결을 설정하려면 fromConnectionString을 호출합니다.

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

const Protocol = require('azure-iot-device-mqtt').Amqp;
let client = Client.fromConnectionString(deviceConnectionString, Protocol);

들어오는 메시지 처리기 만들기

메시지 처리기는 들어오는 각 메시지에 대해 호출됩니다.

메시지가 성공적으로 수신된 후 AMQP 또는 HTTP 전송을 사용하는 경우 client.complete 메서드를 호출하여 메시지 큐에서 메시지를 제거할 수 있음을 IoT Hub에 알립니다.

예를 들어, 이 메시지 처리기는 메시지 ID와 메시지 본문을 콘솔에 인쇄한 다음 client.complete를 호출하여 메시지를 처리했으며 디바이스 큐에서 안전하게 제거할 수 있음을 IoT Hub에 알립니다. MQTT 전송을 사용하는 경우에는 complete 호출이 필요하지 않으며 생략할 수 있습니다. AMQP 또는 HTTPS 전송을 위해서는 complete에 대한 호출이 필요합니다.

function messageHandler(msg) {
  console.log('Id: ' + msg.messageId + ' Body: ' + msg.data);
  client.complete(msg, printResultFor('completed'));
}

연결 끊기 처리기 만들기

연결이 끊어지면 연결 끊기 처리기가 호출됩니다. 연결 끊기 처리기는 다시 연결 코드를 구현하는 데 유용합니다.

이 예에서는 연결 끊기 오류 메시지를 포착하여 콘솔에 표시합니다.

function disconnectHandler() {
  clearInterval(sendInterval);
  sendInterval = null;
  client.open().catch((err) => {
    console.error(err.message);
  });
}

이벤트 수신기 추가

.on 메서드를 사용하여 이러한 이벤트 수신기를 지정할 수 있습니다.

연결 처리기
오류 처리기
처리기 연결 끊기
메시지 처리기

이 예에는 이전에 정의한 메시지 및 연결 끊기 처리기가 포함되어 있습니다.

client.on('connect', connectHandler);
client.on('error', errorHandler);
client.on('disconnect', disconnectHandler);
client.on('message', messageHandler);

IoT Hub에 대한 연결 열기

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

예시:

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

SDK 수신 메시지 샘플

simple_sample_device - IoT 허브에 연결하고 클라우드-디바이스 메시지를 수신하는 디바이스 앱입니다.

클라우드-디바이스 메시지 보내기

이 섹션에서는 Node.js용 Azure IoT SDK의 azure-iothub 패키지를 사용하여 클라우드-디바이스 메시지를 보내는 방법을 설명합니다. 앞에서 설명한 대로 솔루션 백 엔드 애플리케이션은 IoT Hub에 연결되고 메시지는 대상 디바이스로 인코딩된 IoT Hub로 전송됩니다. IoT Hub는 들어오는 메시지를 해당 메시지 큐에 저장하고, 메시지는 IoT Hub 메시지 큐에서 대상 디바이스로 배달됩니다.

클라이언트 및 메시지 모듈 로드

azure-iothub 패키지의 Client 클래스를 사용하여 Client 개체를 선언합니다.

azure-iot-common 패키지의 Message 클래스를 사용하여 Message 개체를 선언합니다.

'use strict';
var Client = require('azure-iothub').Client;
var Message = require('azure-iot-common').Message;

클라이언트 개체 만들기

다음 매개 변수를 사용하여 fromConnectionString을 사용하여 클라이언트를 만듭니다.

IoT Hub 연결 문자열
전송 방식

이 예에서는 serviceClient 개체가 Amqp 전송 형식으로 만들어집니다.

var connectionString = '{IoT Hub connection string}';
var serviceClient = Client.fromConnectionString(connectionString,`Amqp`);

클라이언트 연결 열기

애플리케이션과 IoT Hub 간의 연결을 열려면 Client open 메서드를 호출합니다.

open은 open 작업이 완료될 때 호출되는 콜백 함수를 지정하거나 지정하지 않고 호출할 수 있습니다.

이 예에서는 open 메서드에 선택적 err 연결 열기 콜백 함수가 포함되어 있습니다. 열기 오류가 발생하면 오류 개체가 반환됩니다. 연결 열기가 성공하면 null 콜백 값이 반환됩니다.

serviceClient.open(function (err)
if (err)
  console.error('Could not connect: ' + err.message);

메시지 작성

message 개체에는 비동기식 클라우드-디바이스 메시지가 포함됩니다. 메시지 기능은 AMQP, MQTT 및 HTTP에서 동일한 방식으로 작동합니다.

메시지 개체는 이러한 속성을 포함하여 여러 속성을 지원합니다. 전체 목록을 보려면 메시지 속성을 참조하세요.

ack - 배달 피드백. 다음 섹션에서 설명합니다.
properties - 사용자 지정 메시지 속성을 저장하기 위한 문자열 키와 값이 포함된 맵입니다.
messageId - 양방향 통신을 연관시키는 데 사용됩니다.

메시지 개체가 인스턴스화될 때 메시지 본문을 추가합니다. 이 예에서는 'Cloud to device message.' 메시지가 추가되었습니다.

var message = new Message('Cloud to device message.');
message.ack = 'full';
message.messageId = "My Message ID";

배달 승인

메시지 피드백을 받을 각 메시지에는 전송 승인 ack 속성 값이 포함되어야 합니다. ack 속성은 다음 값 중 하나일 수 있습니다.

없음(기본값): 피드백 메시지가 생성되지 않습니다.
sent: 메시지가 완료된 경우 피드백 메시지를 받습니다.
: 디바이스에서 메시지를 완료하지 않고 메시지가 만료된 경우(또는 최대 배달 횟수에 도달한 경우) 피드백 메시지를 받습니다.
full: 전송된 결과와 전송되지 않은 결과 모두에 대한 피드백입니다.

이 예에서는 ack 속성이 full로 설정되어 하나의 메시지에 대해 보낸 메시지와 보내지 않은 메시지 배달 피드백을 모두 요청합니다.

message.ack = 'full';

메시지 피드백 수신기 연결

메시지 피드백 수신기 콜백 함수는 getFeedbackReceiver를 사용하여 Client에 연결됩니다.

메시지 피드백 수신기는 두 가지 인수를 받습니다.

오류 개체(null일 수 있음)
AmqpReceiver 개체 - 클라이언트가 새 피드백 메시지를 수신하면 이벤트를 내보냅니다.

이 함수 예는 배달 피드백 메시지를 수신하고 콘솔에 인쇄합니다.

function receiveFeedback(err, receiver){
  receiver.on('message', function (msg) {
    console.log('Feedback message:')
    console.log(msg.getData().toString('utf-8'));
  });
}

이 코드는 getFeedbackReceiver를 사용하여 receiveFeedback 피드백 콜백 함수를 서비스 Client 개체에 연결합니다.

serviceClient.getFeedbackReceiver(receiveFeedback);

메시지 완료 결과 처리기 정의

메시지 전송 완료 콜백 함수는 각 메시지가 전송된 후 호출됩니다.

이 함수 예는 메시지 send 작업 결과를 콘솔에 인쇄합니다. 이 예에서 printResultFor 함수는 다음 섹션에 설명된 send 함수에 대한 매개 변수로 제공됩니다.

function printResultFor(op) {
  return function printResult(err, res) {
    if (err) console.log(op + ' error: ' + err.toString());
    if (res) console.log(op + ' status: ' + res.constructor.name);
  };
}

메시지 보내기

IoT Hub를 통해 디바이스 앱에 비동기 클라우드-디바이스 메시지를 보내려면 send 함수를 사용합니다.

send는 다음 매개 변수를 지원합니다.

deviceID - 대상 디바이스의 디바이스 ID입니다.
message - 디바이스에 보낼 메시지 본문입니다.
done - 작업이 완료되면 호출할 선택적 함수입니다. done은 두 가지 인수로 호출됩니다.
- 오류 개체(null일 수 있음)
- 로깅 또는 디버깅에 유용한 전송 관련 응답 개체입니다.

이 코드는 send를 호출하여 IoT Hub를 통해 디바이스 앱에 클라우드-디바이스 메시지를 보냅니다. 이전 섹션에서 정의한 콜백 함수 printResultFor는 배달 승인 정보를 수신합니다.

var targetDevice = '{device ID}';
serviceClient.send(targetDevice, message, printResultFor('send'));

이 예에서는 디바이스에 메시지를 보내고 디바이스가 클라우드-디바이스 메시지를 확인할 때 피드백 메시지를 처리하는 방법을 보여 줍니다.

serviceClient.open(function (err) {
  if (err) {
    console.error('Could not connect: ' + err.message);
  } else {
    console.log('Service client connected');
    serviceClient.getFeedbackReceiver(receiveFeedback);
    var message = new Message('Cloud to device message.');
    message.ack = 'full';
    message.messageId = "My Message ID";
    console.log('Sending message: ' + message.getData());
    serviceClient.send(targetDevice, message, printResultFor('send'));
  }
});

SDK 전송 메시지 샘플

send_c2d_message.js - IoT Hub를 통해 디바이스에 C2D 메시지를 보냅니다.

연결 다시 연결 정책

이 문서에서는 디바이스와 IoT Hub 연결 또는 외부 애플리케이션과 IoT Hub 연결에 대한 메시지 재시도 정책을 보여 주지 않습니다. 프로덕션 코드에서는 복원력 있는 애플리케이션을 만들기 위한 디바이스 다시 연결 관리에 설명된 대로 연결 다시 시도 정책을 구현해야 합니다.

메시지 보존 시간, 다시 시도 횟수, 최대 전송 횟수

IoT Hub에서 클라우드-디바이스 메시지 보내기에 설명된 대로 포털 IoT Hub 구성 옵션 또는 Azure CLI를 사용하여 다음 메시지 값에 대한 기본값을 보고 구성할 수 있습니다. 이러한 구성 옵션은 메시지 배달 및 피드백에 영향을 미칠 수 있습니다.

기본 TTL(Time to Live) - 메시지가 IoT Hub에 의해 만료되기 전에 디바이스에서 메시지를 사용할 수 있는 시간입니다.
피드백 보존 시간 - IoT Hub가 클라우드-디바이스 메시지 만료 또는 배달에 대한 피드백을 보존하는 시간입니다.
IoT Hub가 클라우드-디바이스 메시지를 디바이스에 배달하려고 시도하는 횟수입니다.

다음을 통해 공유

클라우드-디바이스 메시지 보내기 및 받기

개요

메시지 큐 이해

클라우드-디바이스 메시지 받기

DeviceClient 개체 선언

연결 매개 변수 제공

폴링

CompleteAsync 메서드

메시지 중단, 거부 또는 시간 제한

폴링 루프

Callback

메시지 재시도 정책 수신

SDK 수신 메시지 샘플

클라우드-디바이스 메시지 보내기

ServiceClient 개체 선언

연결 문자열 제공

비동기식 클라우드-디바이스 메시지 보내기

배달 피드백 받기

FeedbackReceiver 개체 만들기

Ack 매개 변수를 사용하여 메시지 보내기

피드백 수신 대기

서비스 클라이언트 다시 연결

메시지 재시도 정책 보내기

SDK 전송 메시지 샘플

클라우드-디바이스 메시지 받기

Azure IoT Java SDK 라이브러리 가져오기

DeviceClient 개체 선언

메시지 콜백 방법 설정

메시지 콜백 처리기 만들기

메시지 중단 및 거부 옵션

메시지 상태 콜백 메서드 만들기

디바이스와 IoT Hub 간의 연결 열기

SDK 수신 메시지 샘플

클라우드-디바이스 메시지 보내기

종속성 문 추가

Import 문 추가

연결 프로토콜 정의

ServiceClient 개체 만들기

애플리케이션과 IoT Hub 간의 연결 열기

메시지 배달 피드백을 위한 피드백 수신기 열기

메시지 속성 추가

비동기 메시지 만들기 및 보내기

메시지 배달 피드백 받기

SDK 전송 메시지 샘플

Azure IoT SDK 라이브러리 설치

클라우드-디바이스 메시지 받기

IoTHubDeviceClient 개체 가져오기

디바이스 클라이언트 연결

다시 연결 처리

메시지 처리기 만들기

메시지 처리기 할당

SDK 수신 메시지 샘플

클라우드-디바이스 메시지 보내기

IoTHubRegistryManager 개체 가져오기

IoT Hub 레지스트리 관리자 연결

메시지 작성 및 보내기

SDK 전송 메시지 샘플

Node.js 메시징 패키지 설치

디바이스 애플리케이션에서 메시지 수신

클라이언트 모듈 만들기

전송 프로토콜 선택

메시지 완료, 거부, 중단 기능

AMQP 및 HTTP

MQTT

다시 배달 시도

IoT Hub 문자열 및 전송 프로토콜 추가

들어오는 메시지 처리기 만들기

연결 끊기 처리기 만들기

이벤트 수신기 추가

IoT Hub에 대한 연결 열기

SDK 수신 메시지 샘플

클라우드-디바이스 메시지 보내기

클라이언트 및 메시지 모듈 로드

클라이언트 개체 만들기

클라이언트 연결 열기

메시지 작성

배달 승인

메시지 피드백 수신기 연결

메시지 완료 결과 처리기 정의