원격 분석, 속성 및 명령 페이로드
디바이스 모델은 다음을 정의합니다.
- 디바이스가 서비스에 보내는 원격 분석입니다.
- 디바이스가 서비스와 동기화하는 속성입니다.
- 서비스가 디바이스에서 호출하는 명령입니다.
팁
Azure IoT Central은 플러그 앤 플레이 규칙을 따르는 서비스입니다. IoT Central에서 디바이스 모델은 디바이스 템플릿의 일부입니다. IoT Central은 현재 IoT Central 확장을 통해 DTDL v2를 지원합니다. IoT Central 애플리케이션은 UTF-8로 인코딩된 JSON 데이터를 수신해야 합니다.
이 문서에서는 DTDL 디바이스 모델에서 정의된 원격 분석, 속성 및 명령에 대해 디바이스에서 보내고 받는 JSON 페이로드를 설명합니다.
이 문서에서는 가능한 모든 유형의 원격 분석, 속성 및 명령 페이로드를 설명하지는 않지만, 예제에서는 주요 유형을 설명합니다.
각 예에서는 디바이스가 IoT Central과 같은 플러그 앤 플레이 인식 서비스와 상호 작용하는 방법을 설명하기 위해 형식 및 예 JSON 페이로드를 정의하는 디바이스 모델의 코드 조각을 보여 줍니다.
이 문서의 예제 JSON 코드 조각은 DTDL(Digital Twin Definition Language) v2를 사용합니다. 또한 몇 가지 IoT Central이 사용하는 DTDL 확장이 있습니다.
사용 중인 페이로드 중 일부를 보여 주는 샘플 디바이스 코드는 Linux 또는 Windows에서 실행되는 샘플 IoT 플러그 앤 플레이 디바이스 애플리케이션을 IoT Hub에 연결 자습서 또는 클라이언트 애플리케이션을 만들고 Azure IoT Central 애플리케이션에 연결 자습서를 참조하세요.
원시 데이터 보기
IoT Central을 사용하는 경우 디바이스가 애플리케이션에 보내는 원시 데이터를 볼 수 있습니다. 이 보기는 디바이스에서 전송된 페이로드의 문제를 해결하는 데 유용합니다. 디바이스가 전송하는 원시 데이터를 보려면 다음을 수행합니다.
디바이스 페이지에서 디바이스로 이동합니다.
원시 데이터 탭을 선택합니다.
이 보기에서 표시할 열을 선택하고 표시할 시간 범위를 설정할 수 있습니다. 모델링되지 않은 데이터 열에는 디바이스 템플릿의 속성 또는 원격 분석 정의와 일치하지 않는 디바이스 데이터가 표시됩니다.
자세한 문제 해결 팁은 디바이스의 데이터가 Azure IoT Central에 표시되지 않는 문제 해결을 참조하세요.
원격
DTDL 원격 분석 명명 규칙에 대한 자세한 내용은 DTDL > 원격 분석을 참조하세요. _ 문자를 사용하여 원격 분석 이름을 시작할 수 없습니다.
다음 이름을 사용하여 원격 분석 형식을 만들지 마세요. IoT Central은 이러한 예약된 이름을 내부적으로 사용합니다. 이러한 이름을 사용하려고 하면 IoT Central에서 데이터를 무시합니다.
EventEnqueuedUtcTimeEventProcessedUtcTimePartitionIdEventHubUser$metadata$version
구성 요소의 원격 분석
원격 분석이 구성 요소에 정의된 경우 디바이스 모델에 정의된 대로 구성 요소 이름과 함께 $.sub라는 사용자 지정 메시지 속성을 추가합니다. 자세히 알아보려면 자습서: IoT 플러그 앤 플레이 여러 구성 요소 디바이스 애플리케이션 연결을 참조하세요. 이 자습서에서는 다양한 프로그래밍 언어를 사용하여 구성 요소에서 원격 분석을 보내는 방법을 보여 줍니다.
Important
IoT Edge 모듈에서 호스트되는 구성 요소의 원격 분석을 올바르게 표시하려면 IoT Edge 버전 1.2.4 이상을 사용합니다. 이전 버전을 사용하는 경우 IoT Edge 모듈의 구성 요소에서 원격 분석이 _unmodeleddata로 표시됩니다.
상속된 인터페이스의 원격 분석
원격 분석이 상속된 인터페이스에 정의된 경우 디바이스는 마치 루트 인터페이스에 정의된 것처럼 원격 분석을 보냅니다. 다음 디바이스 모델이 제공된 경우:
[
{
"@id": "dtmi:contoso:device;1",
"@type": "Interface",
"contents": [
{
"@type": [
"Property",
"Cloud",
"StringValue"
],
"displayName": {
"en": "Device Name"
},
"name": "DeviceName",
"schema": "string"
}
],
"displayName": {
"en": "Contoso Device"
},
"extends": [
"dtmi:contoso:sensor;1"
],
"@context": [
"dtmi:iotcentral:context;2",
"dtmi:dtdl:context;2"
]
},
{
"@context": [
"dtmi:iotcentral:context;2",
"dtmi:dtdl:context;2"
],
"@id": "dtmi:contoso:sensor;1",
"@type": [
"Interface",
"NamedInterface"
],
"contents": [
{
"@type": [
"Telemetry",
"NumberValue"
],
"displayName": {
"en": "Meter Voltage"
},
"name": "MeterVoltage",
"schema": "double"
}
],
"displayName": {
"en": "Contoso Sensor"
},
"name": "ContosoSensor"
}
]
디바이스는 다음 페이로드를 사용하여 미터 전압 원격 분석을 보냅니다. 디바이스의 페이로드에 인터페이스 이름이 포함되지 않습니다.
{
"MeterVoltage": 5.07
}
기본 형식
이 섹션에서는 디바이스가 스트리밍할 수 있는 기본 원격 분석 유형의 예를 보여 줍니다.
디바이스 모델의 다음 코드 조각은 boolean 원격 분석 유형에 대한 정의를 보여 줍니다.
{
"@type": "Telemetry",
"displayName": {
"en": "BooleanTelemetry"
},
"name": "BooleanTelemetry",
"schema": "boolean"
}
디바이스 클라이언트는 다음 예제와 같이 JSON으로 원격 분석을 전송해야 합니다.
{ "BooleanTelemetry": true }
디바이스 모델의 다음 코드 조각은 string 원격 분석 유형에 대한 정의를 보여 줍니다.
{
"@type": "Telemetry",
"displayName": {
"en": "StringTelemetry"
},
"name": "StringTelemetry",
"schema": "string"
}
디바이스 클라이언트는 다음 예제와 같이 JSON으로 원격 분석을 전송해야 합니다.
{ "StringTelemetry": "A string value - could be a URL" }
디바이스 모델의 다음 코드 조각은 integer 원격 분석 유형에 대한 정의를 보여 줍니다.
{
"@type": "Telemetry",
"displayName": {
"en": "IntegerTelemetry"
},
"name": "IntegerTelemetry",
"schema": "integer"
}
디바이스 클라이언트는 다음 예제와 같이 JSON으로 원격 분석을 전송해야 합니다.
{ "IntegerTelemetry": 23 }
디바이스 모델의 다음 코드 조각은 double 원격 분석 유형에 대한 정의를 보여 줍니다.
{
"@type": "Telemetry",
"displayName": {
"en": "DoubleTelemetry"
},
"name": "DoubleTelemetry",
"schema": "double"
}
디바이스 클라이언트는 다음 예제와 같이 JSON으로 원격 분석을 전송해야 합니다.
{ "DoubleTelemetry": 56.78 }
디바이스 모델의 다음 코드 조각은 dateTime 원격 분석 유형에 대한 정의를 보여 줍니다.
{
"@type": "Telemetry",
"displayName": {
"en": "DateTimeTelemetry"
},
"name": "DateTimeTelemetry",
"schema": "dateTime"
}
디바이스 클라이언트는 다음 예제와 같이 JSON으로 원격 분석을 전송해야 합니다. DateTime 유형은 ISO 8061 형식이어야 합니다.
{ "DateTimeTelemetry": "2020-08-30T19:16:13.853Z" }
디바이스 모델의 다음 코드 조각은 duration 원격 분석 유형에 대한 정의를 보여 줍니다.
{
"@type": "Telemetry",
"displayName": {
"en": "DurationTelemetry"
},
"name": "DurationTelemetry",
"schema": "duration"
}
디바이스 클라이언트는 다음 예제와 같이 JSON으로 원격 분석을 전송해야 합니다. 기간은 ISO 8601 형식이어야 합니다.
{ "DurationTelemetry": "PT10H24M6.169083011336625S" }
복합 형식
이 섹션에서는 디바이스가 스트리밍할 수 있는 복잡한 원격 분석 유형의 예를 보여 줍니다.
디바이스 모델의 다음 코드 조각은 Enum 원격 분석 유형에 대한 정의를 보여 줍니다.
{
"@type": "Telemetry",
"displayName": {
"en": "EnumTelemetry"
},
"name": "EnumTelemetry",
"schema": {
"@type": "Enum",
"displayName": {
"en": "Enum"
},
"valueSchema": "integer",
"enumValues": [
{
"displayName": {
"en": "Item1"
},
"enumValue": 0,
"name": "Item1"
},
{
"displayName": {
"en": "Item2"
},
"enumValue": 1,
"name": "Item2"
},
{
"displayName": {
"en": "Item3"
},
"enumValue": 2,
"name": "Item3"
}
]
}
}
디바이스 클라이언트는 다음 예제와 같이 JSON으로 원격 분석을 전송해야 합니다. 가능한 값은 0, 1 및 2이며 IoT Central에서 Item1, Item2 및 Item3으로 표시됩니다.
{ "EnumTelemetry": 1 }
디바이스 모델의 다음 코드 조각은 Object 원격 분석 유형에 대한 정의를 보여 줍니다. 이 개체에는 dateTime, integer 및 Enum 형식의 세 필드가 있습니다.
{
"@type": "Telemetry",
"displayName": {
"en": "ObjectTelemetry"
},
"name": "ObjectTelemetry",
"schema": {
"@type": "Object",
"displayName": {
"en": "Object"
},
"fields": [
{
"displayName": {
"en": "Property1"
},
"name": "Property1",
"schema": "dateTime"
},
{
"displayName": {
"en": "Property2"
},
"name": "Property2",
"schema": "integer"
},
{
"displayName": {
"en": "Property3"
},
"name": "Property3",
"schema": {
"@type": "Enum",
"displayName": {
"en": "Enum"
},
"valueSchema": "integer",
"enumValues": [
{
"displayName": {
"en": "Item1"
},
"enumValue": 0,
"name": "Item1"
},
{
"displayName": {
"en": "Item2"
},
"enumValue": 1,
"name": "Item2"
},
{
"displayName": {
"en": "Item3"
},
"enumValue": 2,
"name": "Item3"
}
]
}
}
]
}
}
디바이스 클라이언트는 다음 예제와 같이 JSON으로 원격 분석을 전송해야 합니다. DateTime 형식은 ISO 8061 규격이어야 합니다. Property3에 사용할 수 있는 값은 0, 1이며 IoT Central에 Item1, Item2 및 Item3으로 표시됩니다.
{
"ObjectTelemetry": {
"Property1": "2020-09-09T03:36:46.195Z",
"Property2": 37,
"Property3": 2
}
}
디바이스 모델의 다음 코드 조각은 vector 원격 분석 유형에 대한 정의를 보여 줍니다.
{
"@type": "Telemetry",
"displayName": {
"en": "VectorTelemetry"
},
"name": "VectorTelemetry",
"schema": "vector"
}
디바이스 클라이언트는 다음 예제와 같이 JSON으로 원격 분석을 전송해야 합니다.
{
"VectorTelemetry": {
"x": 74.72395045538597,
"y": 74.72395045538597,
"z": 74.72395045538597
}
}
디바이스 모델의 다음 코드 조각은 geopoint 원격 분석 유형에 대한 정의를 보여 줍니다.
{
"@type": "Telemetry",
"displayName": {
"en": "GeopointTelemetry"
},
"name": "GeopointTelemetry",
"schema": "geopoint"
}
참고 항목
geopoint 스키마 형식은 DTDL에 대한 IoT Central 확장의 일부입니다. 현재 IoT Central은 이전 버전과의 호환성을 위해 geopoint 스키마 형식 및 location 의미 체계 형식을 지원합니다.
디바이스 클라이언트는 다음 예제와 같이 JSON으로 원격 분석을 전송해야 합니다. IoT Central은 맵에 값을 pin으로 표시합니다.
{
"GeopointTelemetry": {
"lat": 47.64263,
"lon": -122.13035,
"alt": 0
}
}
이벤트 및 상태 유형
이 섹션에서는 디바이스가 IoT Central 애플리케이션으로 보내는 원격 분석 이벤트 및 상태의 예제를 보여 줍니다.
참고 항목
이벤트 및 상태 스키마 형식은 DTDL에 대한 IoT Central 확장의 일부입니다.
디바이스 모델의 다음 코드 조각은 integer 이벤트 유형에 대한 정의를 보여 줍니다.
{
"@type": [
"Telemetry",
"Event"
],
"displayName": {
"en": "IntegerEvent"
},
"name": "IntegerEvent",
"schema": "integer"
}
디바이스 클라이언트는 다음 예제와 같이 JSON으로 이벤트 데이터를 전송해야 합니다.
{ "IntegerEvent": 74 }
디바이스 모델의 다음 코드 조각은 integer 상태 유형에 대한 정의를 보여 줍니다.
{
"@type": [
"Telemetry",
"State"
],
"displayName": {
"en": "IntegerState"
},
"name": "IntegerState",
"schema": {
"@type": "Enum",
"valueSchema": "integer",
"enumValues": [
{
"displayName": {
"en": "Level1"
},
"enumValue": 1,
"name": "Level1"
},
{
"displayName": {
"en": "Level2"
},
"enumValue": 2,
"name": "Level2"
},
{
"displayName": {
"en": "Level3"
},
"enumValue": 3,
"name": "Level3"
}
]
}
}
디바이스 클라이언트는 다음 예제와 같이 JSON으로 상태를 전송해야 합니다. 가능한 정수 상태 값은 1, 2 또는 3입니다.
{ "IntegerState": 2 }
속성
DTDL 속성 명명 규칙에 대한 자세한 내용은 DTDL > 속성을 참조하세요. _ 문자를 사용하여 속성 이름을 시작할 수 없습니다.
구성 요소의 속성
속성이 구성 요소에 정의되어 있는 경우 구성 요소 이름에 속성을 래핑합니다. 다음 예제에서는 thermostat2 구성 요소에 maxTempSinceLastReboot를 설정합니다. 마커 __t는 이 섹션이 구성 요소를 정의함을 나타냅니다.
{
"thermostat2" : {
"__t" : "c",
"maxTempSinceLastReboot" : 38.7
}
}
자세히 알아보려면 자습서: 클라이언트 애플리케이션 만들기 및 Azure IoT Central 애플리케이션에 연결을 참조하세요.
기본 형식
이 섹션에서는 디바이스가 서비스에 보내는 기본 속성 형식의 예를 보여 줍니다.
디바이스 모델의 다음 코드 조각은 boolean 속성 유형에 대한 정의를 보여 줍니다.
{
"@type": "Property",
"displayName": {
"en": "BooleanProperty"
},
"name": "BooleanProperty",
"schema": "boolean",
"writable": false
}
디바이스 클라이언트는 다음 예제와 같은 JSON 페이로드를 디바이스 쌍의 보고된 속성으로 전송해야 합니다.
{ "BooleanProperty": false }
디바이스 모델의 다음 코드 조각은 long 속성 유형에 대한 정의를 보여 줍니다.
{
"@type": "Property",
"displayName": {
"en": "LongProperty"
},
"name": "LongProperty",
"schema": "long",
"writable": false
}
디바이스 클라이언트는 다음 예제와 같은 JSON 페이로드를 디바이스 쌍의 보고된 속성으로 전송해야 합니다.
{ "LongProperty": 439 }
디바이스 모델의 다음 코드 조각은 date 속성 유형에 대한 정의를 보여 줍니다.
{
"@type": "Property",
"displayName": {
"en": "DateProperty"
},
"name": "DateProperty",
"schema": "date",
"writable": false
}
디바이스 클라이언트는 다음 예제와 같은 JSON 페이로드를 디바이스 쌍의 보고된 속성으로 전송해야 합니다. Date 형식은 ISO 8061 규격이어야 합니다.
{ "DateProperty": "2020-05-17" }
디바이스 모델의 다음 코드 조각은 duration 속성 유형에 대한 정의를 보여 줍니다.
{
"@type": "Property",
"displayName": {
"en": "DurationProperty"
},
"name": "DurationProperty",
"schema": "duration",
"writable": false
}
디바이스 클라이언트는 다음 예제와 같은 JSON 페이로드를 디바이스 쌍의 보고된 속성으로 전송해야 합니다. 기간은 ISO 8601 기간 규격이어야 합니다.
{ "DurationProperty": "PT10H24M6.169083011336625S" }
디바이스 모델의 다음 코드 조각은 float 속성 유형에 대한 정의를 보여 줍니다.
{
"@type": "Property",
"displayName": {
"en": "FloatProperty"
},
"name": "FloatProperty",
"schema": "float",
"writable": false
}
디바이스 클라이언트는 다음 예제와 같은 JSON 페이로드를 디바이스 쌍의 보고된 속성으로 전송해야 합니다.
{ "FloatProperty": 1.9 }
디바이스 모델의 다음 코드 조각은 string 속성 유형에 대한 정의를 보여 줍니다.
{
"@type": "Property",
"displayName": {
"en": "StringProperty"
},
"name": "StringProperty",
"schema": "string",
"writable": false
}
디바이스 클라이언트는 다음 예제와 같은 JSON 페이로드를 디바이스 쌍의 보고된 속성으로 전송해야 합니다.
{ "StringProperty": "A string value - could be a URL" }
복합 형식
이 섹션에서는 디바이스가 서비스에 보내는 복합 속성 형식의 예를 보여 줍니다.
디바이스 모델의 다음 코드 조각은 Enum 속성 유형에 대한 정의를 보여 줍니다.
{
"@type": "Property",
"displayName": {
"en": "EnumProperty"
},
"name": "EnumProperty",
"writable": false,
"schema": {
"@type": "Enum",
"displayName": {
"en": "Enum"
},
"valueSchema": "integer",
"enumValues": [
{
"displayName": {
"en": "Item1"
},
"enumValue": 0,
"name": "Item1"
},
{
"displayName": {
"en": "Item2"
},
"enumValue": 1,
"name": "Item2"
},
{
"displayName": {
"en": "Item3"
},
"enumValue": 2,
"name": "Item3"
}
]
}
}
디바이스 클라이언트는 다음 예제와 같은 JSON 페이로드를 디바이스 쌍의 보고된 속성으로 전송해야 합니다. 가능한 값은 0, 1이며 IoT Central에서 Item1, Item2 및 Item3으로 표시됩니다.
{ "EnumProperty": 1 }
디바이스 모델의 다음 코드 조각은 Object 속성 유형에 대한 정의를 보여 줍니다. 이 개체에는 string 및 integer 형식의 두 필드가 있습니다.
{
"@type": "Property",
"displayName": {
"en": "ObjectProperty"
},
"name": "ObjectProperty",
"writable": false,
"schema": {
"@type": "Object",
"displayName": {
"en": "Object"
},
"fields": [
{
"displayName": {
"en": "Field1"
},
"name": "Field1",
"schema": "integer"
},
{
"displayName": {
"en": "Field2"
},
"name": "Field2",
"schema": "string"
}
]
}
}
디바이스 클라이언트는 다음 예제와 같은 JSON 페이로드를 디바이스 쌍의 보고된 속성으로 전송해야 합니다.
{
"ObjectProperty": {
"Field1": 37,
"Field2": "A string value"
}
}
디바이스 모델의 다음 코드 조각은 vector 속성 유형에 대한 정의를 보여 줍니다.
{
"@type": "Property",
"displayName": {
"en": "VectorProperty"
},
"name": "VectorProperty",
"schema": "vector",
"writable": false
}
디바이스 클라이언트는 다음 예제와 같은 JSON 페이로드를 디바이스 쌍의 보고된 속성으로 전송해야 합니다.
{
"VectorProperty": {
"x": 74.72395045538597,
"y": 74.72395045538597,
"z": 74.72395045538597
}
}
디바이스 모델의 다음 코드 조각은 geopoint 속성 유형에 대한 정의를 보여 줍니다.
{
"@type": "Property",
"displayName": {
"en": "GeopointProperty"
},
"name": "GeopointProperty",
"schema": "geopoint",
"writable": false
}
참고 항목
geopoint 스키마 형식은 DTDL에 대한 IoT Central 확장의 일부입니다. 현재 IoT Central은 이전 버전과의 호환성을 위해 geopoint 스키마 형식 및 location 의미 체계 형식을 지원합니다.
디바이스 클라이언트는 다음 예제와 같은 JSON 페이로드를 디바이스 쌍의 보고된 속성으로 전송해야 합니다.
{
"GeopointProperty": {
"lat": 47.64263,
"lon": -122.13035,
"alt": 0
}
}
쓰기 가능한 속성 유형
이 섹션에서는 디바이스가 서비스에서 받는 쓰기 가능한 속성 형식의 예를 보여 줍니다.
쓰기 가능한 속성이 구성 요소에 정의되어 있으면 원하는 속성 메시지에 구성 요소 이름이 포함됩니다. 다음 예제에서는 thermostat2 구성 요소의 targetTemperature를 업데이트하기 위해 디바이스를 요청하는 메시지를 보여 줍니다. 마커 __t는 이 섹션이 구성 요소를 정의함을 나타냅니다.
{
"thermostat2": {
"targetTemperature": {
"value": 57
},
"__t": "c"
},
"$version": 3
}
자세히 알아보려면 IoT 플러그 앤 플레이 여러 구성 요소 디바이스 애플리케이션 연결을 참조하세요.
디바이스 또는 모듈은 reported 속성을 전송하여 속성을 받았는지 확인해야 합니다. reported 속성에는 다음이 포함되어야 합니다.
value- 속성의 실제 값(일반적으로 수신된 값이지만 디바이스가 다른 값을 보고하도록 결정할 수 있음).ac- HTTP 상태 코드를 사용하는 승인 코드입니다.av- desired 속성의$version을 참조하는 승인 버전입니다. 이 값은 desired 속성 JSON 페이로드에서 찾을 수 있습니다.ad- 선택적 승인 설명입니다.
이러한 필드에 대해 자세히 알아보려면 IoT 플러그 앤 플레이 규칙 > 확인 응답을 참조하세요.
디바이스 모델의 다음 코드 조각은 쓰기 가능한 string 속성 유형에 대한 정의를 보여 줍니다.
{
"@type": "Property",
"displayName": {
"en": "StringPropertyWritable"
},
"name": "StringPropertyWritable",
"writable": true,
"schema": "string"
}
디바이스는 서비스로부터 다음 페이로드를 수신합니다.
{
"StringPropertyWritable": "A string from IoT Central", "$version": 7
}
디바이스는 업데이트를 처리한 후 다음 JSON 페이로드를 서비스에 보내야 합니다. 이 메시지에는 서비스에서 받은 원본 업데이트의 버전 번호가 포함되어 있습니다.
팁
서비스가 IoT Central인 경우 다음 메시지를 받으면 UI에서 해당 속성을 동기화됨으로 표시합니다.
{
"StringPropertyWritable": {
"value": "A string from IoT Central",
"ac": 200,
"ad": "completed",
"av": 7
}
}
디바이스 모델의 다음 코드 조각은 쓰기 가능한 Enum 속성 유형에 대한 정의를 보여 줍니다.
{
"@type": "Property",
"displayName": {
"en": "EnumPropertyWritable"
},
"name": "EnumPropertyWritable",
"writable": true,
"schema": {
"@type": "Enum",
"displayName": {
"en": "Enum"
},
"valueSchema": "integer",
"enumValues": [
{
"displayName": {
"en": "Item1"
},
"enumValue": 0,
"name": "Item1"
},
{
"displayName": {
"en": "Item2"
},
"enumValue": 1,
"name": "Item2"
},
{
"displayName": {
"en": "Item3"
},
"enumValue": 2,
"name": "Item3"
}
]
}
}
디바이스는 서비스로부터 다음 페이로드를 수신합니다.
{
"EnumPropertyWritable": 1 , "$version": 10
}
디바이스는 업데이트를 처리한 후 다음 JSON 페이로드를 서비스에 보내야 합니다. 이 메시지에는 서비스에서 받은 원본 업데이트의 버전 번호가 포함되어 있습니다.
팁
서비스가 IoT Central인 경우 다음 메시지를 받으면 UI에서 해당 속성을 동기화됨으로 표시합니다.
{
"EnumPropertyWritable": {
"value": 1,
"ac": 200,
"ad": "completed",
"av": 10
}
}
명령
DTDL 명령 명명 규칙에 대한 자세한 내용은 DTDL > 명령을 참조하세요. _ 문자를 사용하여 명령 이름을 시작할 수 없습니다.
명령이 구성 요소에 정의되어 있으면 디바이스에서 수신하는 명령 이름에 구성 요소 이름이 포함됩니다. 예를 들어 명령이 getMaxMinReport이고, 구성 요소가 thermostat2이면 디바이스에서 thermostat2*getMaxMinReport라는 명령을 실행하라는 요청을 받습니다.
디바이스 모델의 다음 코드 조각은 매개 변수가 없고 디바이스에서 아무것도 반환하지 않는 명령의 정의를 보여 줍니다.
{
"@type": "Command",
"displayName": {
"en": "CommandBasic"
},
"name": "CommandBasic"
}
디바이스는 요청에서 빈 페이로드를 받고 성공 여부를 나타내는 200 HTTP 응답 코드와 함께 응답에 빈 페이로드를 반환해야 합니다.
디바이스 모델의 다음 코드 조각은 정수 매개 변수가 있고 디바이스에서 정수 값을 반환하는 명령의 정의를 보여 줍니다.
{
"@type": "Command",
"request": {
"@type": "CommandPayload",
"displayName": {
"en": "RequestParam"
},
"name": "RequestParam",
"schema": "integer"
},
"response": {
"@type": "CommandPayload",
"displayName": {
"en": "ResponseParam"
},
"name": "ResponseParam",
"schema": "integer"
},
"displayName": {
"en": "CommandSimple"
},
"name": "CommandSimple"
}
디바이스는 요청 페이로드로 정수 값을 받습니다. 디바이스는 성공 여부를 나타내는 200 HTTP 응답 코드를 사용하여 응답 페이로드로 정수 값을 반환해야 합니다.
디바이스 모델의 다음 코드 조각은 개체 매개 변수가 있고 디바이스에서 개체를 반환하는 명령의 정의를 보여 줍니다. 이 예제에서는 두 개체 모두에 정수 및 문자열 필드가 있습니다.
{
"@type": "Command",
"request": {
"@type": "CommandPayload",
"displayName": {
"en": "RequestParam"
},
"name": "RequestParam",
"schema": {
"@type": "Object",
"displayName": {
"en": "Object"
},
"fields": [
{
"displayName": {
"en": "Field1"
},
"name": "Field1",
"schema": "integer"
},
{
"displayName": {
"en": "Field2"
},
"name": "Field2",
"schema": "string"
}
]
}
},
"response": {
"@type": "CommandPayload",
"displayName": {
"en": "ResponseParam"
},
"name": "ResponseParam",
"schema": {
"@type": "Object",
"displayName": {
"en": "Object"
},
"fields": [
{
"displayName": {
"en": "Field1"
},
"name": "Field1",
"schema": "integer"
},
{
"displayName": {
"en": "Field2"
},
"name": "Field2",
"schema": "string"
}
]
}
},
"displayName": {
"en": "CommandComplex"
},
"name": "CommandComplex"
}
다음 코드 조각은 디바이스에 전송된 예제 요청 페이로드를 보여 줍니다.
{ "Field1": 56, "Field2": "A string value" }
다음 코드 조각은 디바이스로부터 전송된 예제 응답 페이로드를 보여 줍니다. 200 HTTP 응답 코드를 사용하여 성공 여부를 표시합니다.
{ "Field1": 87, "Field2": "Another string value" }
다음 단계
이제 디바이스 페이로드에 대해 배웠으므로 다음 단계로 디바이스 개발자 가이드를 참조하세요.