Azure IoT Central 솔루션에서 명령을 사용하는 방법

이 방법 가이드에서는 디바이스 템플릿에 정의된 명령을 사용하는 방법을 보여 줍니다.

운영자는 IoT Central UI를 사용하여 디바이스에서 명령을 호출할 수 있습니다. 명령은 디바이스의 동작을 제어합니다. 예를 들어 운영자는 명령을 호출하여 디바이스를 다시 부팅하거나 진단 데이터를 수집할 수 있습니다.

디바이스는 다음을 수행할 수 있습니다.

명령에 즉시 응답합니다.
명령을 받으면 IoT Central에 응답한 다음 장기 실행 명령이 완료되었을 때 IoT Central에 알립니다.

기본적으로 명령은 장치가 연결되어 있기를 기대하며, 장치에 연결할 수 없는 경우 실패합니다. 디바이스 템플릿 UI에서 오프라인일 경우 큐 옵션을 선택하면, 디바이스가 온라인 상태가 될 때까지 명령을 큐에 대기시킬 수 있습니다. 이러한 오프라인 명령은 이 문서의 뒷부분에 있는 별도의 섹션에서 설명합니다.

IoT Pug 및 Play 명령 규칙에 대한 자세한 내용은 IoT 플러그 앤 플레이 규칙을 참조하세요.

디바이스가 IoT Central과 교환하는 명령 데이터에 대한 자세한 내용은 원격 분석, 속성 및 명령 페이로드를 참조하세요.

IoT Central REST API를 사용하여 명령을 관리하는 방법을 알아보려면 IoT Central REST API를 사용하여 디바이스를 제어하는 방법을 참조하세요.

디바이스 SDK를 사용하지 않고 디바이스에서 명령을 구현하는 방법을 알아보려면 MQTT 프로토콜을 사용하여 IoT Hub와 통신을 참조하세요.

명령어를 정의하세요

표준 명령은 디바이스에 전송되어 디바이스에 작업을 수행하도록 지시합니다. 명령에는 추가 정보가 포함된 매개 변수가 포함될 수 있습니다. 예를 들어 디바이스에서 밸브를 여는 명령에는 밸브를 여는 정도를 지정하는 매개 변수가 있을 수 있습니다. 디바이스에서 명령을 완료할 때 명령이 반환 값을 받을 수도 있습니다. 예를 들어 디바이스에 일부 진단을 실행하도록 요청하는 명령은 진단 보고서를 반환 값으로 받을 수 있습니다.

명령은 디바이스 템플릿의 일부로 정의됩니다. 다음 스크린샷은 자동 온도 조절기 디바이스 템플릿의 Max-Min 보고서 가져오기 명령 정의를 보여줍니다. 이 명령에는 요청 및 응답 매개 변수가 모두 있습니다.

다음 표에서는 명령 기능에 대한 구성 설정을 보여줍니다.

분야	Description
표시 이름	대시보드 타일 및 디바이스 양식에 사용되는 명령 값입니다.
이름	명령 이름입니다. IoT Central은 표시 이름에서 이 필드에 대한 값을 생성하지만 필요한 경우 고유한 값을 선택할 수 있습니다. 이 필드는 영숫자여야 합니다. 디바이스 코드는 이 이름 값을 사용합니다.
기능 유형	명령.
오프라인일 경우 큐에 넣기	이 명령을 오프라인 명령으로 만들지 여부입니다.
Description	명령 기능에 대한 설명입니다.
주석	명령 기능에 대한 모든 설명입니다.
요청	디바이스 명령에 대한 페이로드입니다.
응답	디바이스 명령 응답의 페이로드입니다.

Azure IoT Central에서 디바이스 템플릿에서 명령을 정의하는 데 사용하는 DTDL(디지털 트윈 정의 언어)에 대해 알아보려면 IoT 플러그 앤 플레이 규칙 > 명령을 참조하세요.

표시 이름 및 설명과 같은 선택적 필드를 사용하면 인터페이스 및 기능에 더 많은 세부 정보를 추가할 수 있습니다.

표준 명령

표준 명령을 처리하기 위해 디바이스는 IoT Central에서 명령을 받는 즉시 응답 값을 보냅니다. Azure IoT 디바이스 SDK를 사용하여 IoT Central 애플리케이션에서 호출한 표준 명령을 처리할 수 있습니다.

여러 언어로 구현되는 예제는 자습서: 클라이언트 애플리케이션 만들기 및 Azure IoT Central 애플리케이션에 연결

다음 스크린샷은 성공적인 명령 응답이 IoT Central UI에 표시되는 방법을 보여 줍니다.

비고

표준 명령의 경우 시간 제한은 30초입니다. 디바이스가 30초 이내에 응답하지 않으면 IoT Central은 명령이 실패했다고 가정합니다. 이 시간 제한 기간은 구성할 수 없습니다.

오래 실행되는 명령

장기 실행 명령에서 디바이스는 명령을 즉시 완료하지 않습니다. 대신 디바이스는 명령 수신을 확인한 다음 나중에 명령이 완료되었는지 확인합니다. 이 방법을 사용하면 디바이스가 IoT Central에 대한 연결을 열어 두지 않고 장기 실행 작업을 완료할 수 있습니다.

비고

장기 실행 명령은 IoT 플러그 앤 플레이 규칙의 일부가 아닙니다. IoT Central에는 장기 실행 명령을 구현하는 자체 규칙이 있습니다.

이 섹션에서는 명령이 완료되었다는 확인 전송을 디바이스에서 지연시키는 방법을 보여 있습니다.

다음 코드 조각은 디바이스가 장기 실행 명령을 구현하는 방법을 보여줍니다.

비고

이 문서에서는 단순성을 위해 Node.js 사용합니다.

client.onDeviceMethod('rundiagnostics', commandHandler);

// ...

const commandHandler = async (request, response) => {
  switch (request.methodName) {
  case 'rundiagnostics': {
    console.log('Starting long-running diagnostics run ' + request.payload);
    await sendCommandResponse(request, response, 202, 'Diagnostics run started');

    // Long-running operation here
    // ...

    const patch = {
      rundiagnostics: {
        value: 'Diagnostics run complete at ' + new Date().toLocaleString()
      }
    };

    deviceTwin.properties.reported.update(patch, function (err) {
      if (err) throw err;
      console.log('Properties have been reported for component');
    });
    break;
  }
  default:
    await sendCommandResponse(request, response, 404, 'unknown method');
    break;
  }
};

onDeviceMethod 메서드를 설정하는 commandHandler 호출입니다. 이 명령 처리기:

명령의 이름을 확인합니다.
응답을 IoT Central로 다시 보내기 위한 호출 sendCommandResponse 입니다. 이 응답에는 보류 중인 결과를 나타내는 응답 코드가 포함됩니다 202 .
장기 실행 작업을 완료합니다.
명령과 이름이 같은 reported 속성을 사용하여 명령이 완료되었다고 IoT Central에 알릴 수 있습니다.

다음 스크린샷은 명령이 완료되었음을 나타내는 속성 업데이트를 받을 때 IoT Central UI를 보여 줍니다.

오프라인 명령

이 섹션에서는 디바이스가 오프라인 명령을 처리하는 방법을 보여 줍니다. 디바이스가 온라인 상태이면 수신되는 즉시 오프라인 명령을 처리할 수 있습니다. 디바이스가 오프라인인 경우 다음에 IoT Central에 연결할 때 오프라인 명령을 처리합니다. 디바이스는 오프라인 명령에 대한 응답으로 반환 값을 보낼 수 없습니다.

비고

오프라인 명령은 IoT 플러그 앤 플레이 규칙의 일부가 아닙니다. IoT Central에는 오프라인 명령을 구현하는 자체 규칙이 있습니다.

비고

이 문서에서는 단순성을 위해 Node.js 사용합니다.

다음 스크린샷은 GenerateDiagnostics라는 오프라인 명령을 보여 줍니다. 요청 매개 변수는 StartTime 이라는 datetime 속성과 Bank라는 정수 열거형 속성이 있는 개체입니다.

다음 코드 조각은 클라이언트가 오프라인 명령을 수신 대기하고 메시지 내용을 표시하는 방법을 보여 줍니다.

client.on('message', function (msg) {
  console.log('Body: ' + msg.data);
  console.log('Properties: ' + JSON.stringify(msg.properties));
  client.complete(msg, function (err) {
    if (err) {
      console.error('complete error: ' + err.toString());
    } else {
      console.log('complete sent');
    }
  });
});

이전 코드 조각의 출력은 StartTime 및 Bank 값을 사용하여 페이로드를 표시합니다. 속성 목록에는 메서드 이름 목록 항목에 명령 이름이 포함됩니다.

Body: {"StartTime":"2021-01-06T06:00:00.000Z","Bank":2}
Properties: {"propertyList":[{"key":"iothub-ack","value":"none"},{"key":"method-name","value":"GenerateDiagnostics"}]}

비고

오프라인 명령에 대한 기본 TTL(Time to Live)은 24시간이며, 그 후에는 메시지가 만료됩니다.

할당되지 않은 디바이스의 명령

디바이스 템플릿에 할당되지 않은 디바이스에서 명령을 호출할 수 있습니다. 할당되지 않은 디바이스에서 명령을 호출하려면 디바이스 섹션에서 디바이스로 이동한 다음, 디바이스 관리를 선택한 다음 명령을 선택합니다. 메서드 이름, 페이로드 및 기타 필요한 값을 입력합니다. 다음 스크린샷은 명령을 호출하는 데 사용하는 UI를 보여줍니다.

다음 단계

이제 Azure IoT Central 애플리케이션에서 명령을 사용하는 방법을 알아보려면 원격 분석, 속성 및 명령 페이로드 를 참조하여 명령 매개 변수에 대해 자세히 알아보고 클라이언트 애플리케이션을 만들고 Azure IoT Central 애플리케이션에 연결 하여 다양한 언어로 전체 코드 샘플을 확인합니다.

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-09-29