다음을 통해 공유

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

  • 아티클

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

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

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

  • 명령에 즉시 응답합니다.
  • 명령을 받으면 IoT Central에 응답하고 장기 실행 명령이 완료되면 IoT Central에 나중에 알립니다.

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

IoT 플러그 앤 플레이 명령 규칙에 대해 알아보려면 IoT 플러그 앤 플레이 규칙을 참조하세요.

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

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

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

명령 정의

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

명령은 디바이스 템플릿의 일부로 정의됩니다. 다음 스크린샷은 Thermostat 디바이스 템플릿의 Get Max-Min report 명령 정의를 보여줍니다. 이 명령에는 요청 및 응답 매개 변수가 모두 있습니다.

Screenshot showing Get Max Min Report command in Thermostat device template.

다음 표에는 명령 기능의 구성 설정이 나와 있습니다.

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

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

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

표준 명령

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

여러 언어로 구현된 예는 클라이언트 애플리케이션을 만들고 Azure IoT Central 애플리케이션에 연결을 참조하세요.

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

Screenshot showing how to view command payload for a standard command.

참고 항목

표준 명령의 경우 시간 제한은 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 메서드를 설정합니다. 이 명령 처리기는 다음을 수행합니다.

  1. 명령의 이름을 확인합니다.
  2. sendCommandResponse를 호출하여 응답을 IoT Central에 다시 보냅니다. 이 응답에는 보류 중인 결과를 나타내는 202 응답 코드가 포함됩니다.
  3. 장기 실행 작업을 완료합니다.
  4. 명령과 이름이 같은 reported 속성을 사용하여 명령이 완료되었음을 IoT Central에 알립니다.

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

Screenshot that shows long-running command finished.

오프라인 명령

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

참고 항목

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

참고 항목

이 문서에서는 편의를 위해 Node.js를 사용합니다.

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

Screenshot that shows the UI for an offline command.

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

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 값이 있는 페이로드가 표시됩니다. 속성 목록에는 method-name 목록 항목에 명령 이름이 포함됩니다.

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를 보여 줍니다.

Screenshot that shows an example of calling a command on an unassigned device.

다음 단계

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