IoT Central REST API를 사용하여 디바이스 템플릿을 관리하는 방법
IoT Central REST API를 사용하면 IoT Central 애플리케이션과 통합되는 클라이언트 애플리케이션을 개발할 수 있습니다. REST API를 사용하여 IoT Central 애플리케이션에서 디바이스 템플릿을 관리할 수 있습니다.
모든 IoT Central REST API 호출에는 권한 부여 헤더가 필요합니다. 자세히 알아보려면 IoT Central REST API 호출을 인증하고 권한을 부여하는 방법을 참조하세요.
IoT Central REST API에 대한 참조 설명서는 Azure IoT Central REST API 참조를 참조하세요.
팁
Postman을 사용하여 이 문서에 설명된 REST API 호출을 사용해 볼 수 있습니다. IoT Central Postman 컬렉션을 다운로드하고 Postman으로 가져옵니다. 컬렉션에서 앱 하위 도메인 및 관리자 토큰과 같은 변수를 설정해야 합니다.
IoT Central UI를 사용하여 디바이스 템플릿을 관리하는 방법을 알아보려면 디바이스 템플릿 설정 방법 및 디바이스 템플릿 편집 방법을 참조하세요.
디바이스 템플릿
디바이스 템플릿에는 디바이스 모델 및 보기 정의가 포함됩니다. REST API를 사용하면 클라우드 속성 정의를 포함한 디바이스 모델을 관리할 수 있습니다. UI를 사용하여 보기를 만들고 관리해야 합니다.
디바이스 템플릿의 디바이스 모델 섹션은 애플리케이션에 연결하려는 디바이스의 기능을 지정합니다. 기능에는 원격 분석, 속성 및 명령이 포함됩니다. 모델은 DTDL V2를 사용하여 정의됩니다.
참고 항목
IoT Central은 DTDL 언어에 대한 일부 확장을 정의합니다. 자세한 내용은 IoT Central 확장을 참조하세요.
디바이스 템플릿 REST API
IoT Central REST API를 통해 다음을 수행할 수 있습니다.
- 애플리케이션에 디바이스 템플릿 추가
- 애플리케이션에서 디바이스 템플릿 업데이트
- 애플리케이션에서 디바이스 템플릿 목록 가져오기
- ID별 디바이스 템플릿 가져오기
- 애플리케이션에서 디바이스 템플릿 삭제
- 애플리케이션의 디바이스 템플릿 목록 필터링
디바이스 템플릿 추가하기
다음 요청을 사용하여 새 디바이스 템플릿을 만들고 게시합니다. 이러한 방식으로 만들어진 디바이스 템플릿에 대해 기본 보기가 자동으로 생성됩니다.
PUT https://{your app subdomain}/api/deviceTemplates/{deviceTemplateId}?api-version=2022-07-31
참고 항목
디바이스 템플릿 ID는 예를 들어 dtmi:contoso:mythermostattemplate;1과 같이 DTDL 명명 규칙을 따릅니다.
다음 예제에서는 자동 온도 조절기 디바이스를 위한 디바이스 템플릿을 추가하는 요청 본문을 보여 줍니다. capabilityModel에는 온도 원격 분석, 두 가지 속성 및 명령이 포함됩니다. 디바이스 템플릿은 CustomerName 클라우드 속성을 정의하고, decimalPlaces, displayUnit, maxValue 및 minValue를 사용하여 targetTemperature 속성을 사용자 지정합니다. 디바이스 템플릿 @id의 값은 URL의 deviceTemplateId 값과 일치해야 합니다. 디바이스 템플릿 @id의 값은 capabilityModel@id 값과 일치하지 않습니다.
{
"displayName": "Thermostat",
"@id": "dtmi:contoso:mythermostattemplate;1",
"@type": [
"ModelDefinition",
"DeviceModel"
],
"@context": [
"dtmi:iotcentral:context;2",
"dtmi:dtdl:context;2"
],
"capabilityModel": {
"@id": "dtmi:contoso:Thermostat;1",
"@type": "Interface",
"contents": [
{
"@type": [
"Telemetry",
"Temperature"
],
"description": "Temperature in degrees Celsius.",
"displayName": "Temperature",
"name": "temperature",
"schema": "double",
"unit": "degreeCelsius"
},
{
"@type": [
"Property",
"Temperature"
],
"description": "Allows to remotely specify the desired target temperature.",
"displayName": "Target Temperature",
"name": "targetTemperature",
"schema": "double",
"unit": "degreeCelsius",
"writable": true,
"decimalPlaces": 1,
"displayUnit": "C",
"maxValue": 80,
"minValue": 50
},
{
"@type": [
"Property",
"Temperature"
],
"description": "Returns the max temperature since last device reboot.",
"displayName": "Max temperature since last reboot.",
"name": "maxTempSinceLastReboot",
"schema": "double",
"unit": "degreeCelsius"
},
{
"@type": "Command",
"description": "This command returns the max, min and average temperature from the specified time to the current time.",
"displayName": "Get report",
"name": "getMaxMinReport",
"request": {
"@type": "CommandPayload",
"description": "Period to return the max-min report.",
"displayName": "Since",
"name": "since",
"schema": "dateTime"
},
"response": {
"@type": "CommandPayload",
"displayName": "Temperature Report",
"name": "tempReport",
"schema": {
"@type": "Object",
"fields": [
{
"displayName": "Max temperature",
"name": "maxTemp",
"schema": "double"
},
{
"displayName": "Min temperature",
"name": "minTemp",
"schema": "double"
},
{
"displayName": "Average Temperature",
"name": "avgTemp",
"schema": "double"
},
{
"displayName": "Start Time",
"name": "startTime",
"schema": "dateTime"
},
{
"displayName": "End Time",
"name": "endTime",
"schema": "dateTime"
}
]
}
}
},
{
"@type": [
"Property",
"Cloud",
"StringValue"
],
"displayName": "Customer Name",
"name": "CustomerName",
"schema": "string"
}
],
"description": "Reports current temperature and provides desired temperature control.",
"displayName": "Thermostat"
}
}
요청 본문에는 다음과 같은 몇 가지 필수 필드가 있습니다.
@id: 단순 URN(Uniform Resource Name) 형식의 고유한 ID입니다.@type: 최상위 개체가"ModelDefinition","DeviceModel"임을 선언합니다.@context: 인터페이스에 사용되는 DTDL 버전을 지정합니다.contents: 디바이스를 구성하는 속성, 원격 분석 및 명령을 나열합니다. 이 기능은 여러 인터페이스에서 정의될 수 있습니다.capabilityModel: 모든 디바이스 템플릿에는 기능 모델이 있습니다. 각 모듈 기능 모델과 디바이스 모델 간의 관계가 설정됩니다. 기능 모델은 하나 이상의 모듈 인터페이스를 구현합니다.
팁
디바이스 템플릿 JSON은 표준 DTDL 문서가 아닙니다. 디바이스 템플릿 JSON에는 클라우드 속성 정의 및 표시 단위와 같은 IoT Central 특정 데이터가 포함됩니다. 디바이스 템플릿 JSON 형식을 사용하여 REST API, CLI 및 UI를 사용하여 IoT Central에서 디바이스 템플릿을 가져오고 내보낼 수 있습니다.
표시 이름 및 설명과 같은 추가 정보를 기능 모델에 추가하는 데 사용할 수 있는 몇 가지 선택적 필드가 있습니다.
구현 섹션에서 인터페이스 목록의 각 항목에는 다음이 포함됩니다.
name: 인터페이스의 프로그래밍 이름입니다.schema: 기능 모델이 구현하는 인터페이스입니다.
이 요청에 대한 응답은 다음 예제와 같습니다.
{
"etag": "\"~F27cqSo0ON3bfOzwgZxAl89/JVvM80+dds6y8+mZh5M=\"",
"displayName": "Thermostat",
"capabilityModel": {
"@id": "dtmi:contoso:Thermostat;1",
"@type": "Interface",
"contents": [
{
"@type": [
"Telemetry",
"Temperature"
],
"description": "Temperature in degrees Celsius.",
"displayName": "Temperature",
"name": "temperature",
"schema": "double",
"unit": "degreeCelsius"
},
{
"@type": [
"Property",
"Temperature",
"NumberValue"
],
"description": "Allows to remotely specify the desired target temperature.",
"displayName": "Target Temperature",
"name": "targetTemperature",
"schema": "double",
"unit": "degreeCelsius",
"writable": true,
"decimalPlaces": 1,
"displayUnit": "C",
"maxValue": 80,
"minValue": 50
},
{
"@type": [
"Property",
"Temperature"
],
"description": "Returns the max temperature since last device reboot.",
"displayName": "Max temperature since last reboot.",
"name": "maxTempSinceLastReboot",
"schema": "double",
"unit": "degreeCelsius"
},
{
"@type": "Command",
"description": "This command returns the max, min and average temperature from the specified time to the current time.",
"displayName": "Get report",
"name": "getMaxMinReport",
"request": {
"@type": "CommandPayload",
"description": "Period to return the max-min report.",
"displayName": "Since",
"name": "since",
"schema": "dateTime"
},
"response": {
"@type": "CommandPayload",
"displayName": "Temperature Report",
"name": "tempReport",
"schema": {
"@type": "Object",
"fields": [
{
"displayName": "Max temperature",
"name": "maxTemp",
"schema": "double"
},
{
"displayName": "Min temperature",
"name": "minTemp",
"schema": "double"
},
{
"displayName": "Average Temperature",
"name": "avgTemp",
"schema": "double"
},
{
"displayName": "Start Time",
"name": "startTime",
"schema": "dateTime"
},
{
"displayName": "End Time",
"name": "endTime",
"schema": "dateTime"
}
]
}
}
},
{
"@type": [
"Property",
"Cloud",
"StringValue"
],
"displayName": "Customer Name",
"name": "CustomerName",
"schema": "string"
}
],
"description": "Reports current temperature and provides desired temperature control.",
"displayName": "Thermostat"
},
"@id": "dtmi:modelDefinition:spzeut3n:n2lteu39u6",
"@type": [
"ModelDefinition",
"DeviceModel"
],
"@context": [
"dtmi:iotcentral:context;2",
"dtmi:dtdl:context;2"
]
}
디바이스 템플릿 가져오기
다음 요청을 사용하여 애플리케이션에서 디바이스 템플릿의 세부 정보를 검색합니다.
GET https://{your app subdomain}/api/deviceTemplates/{deviceTemplateId}?api-version=2022-07-31
참고 항목
디바이스 위로 마우스를 가져가면 IoT Central 애플리케이션 UI에서 deviceTemplateId를 가져올 수 있습니다.
이 요청에 대한 응답은 다음 예제와 같습니다.
{
"etag": "\"~F27cqSo0ON3bfOzwgZxAl89/JVvM80+dds6y8+mZh5M=\"",
"displayName": "Thermostat",
"capabilityModel": {
"@id": "dtmi:contoso:Thermostat;1",
"@type": "Interface",
"contents": [
{
"@type": [
"Telemetry",
"Temperature"
],
"description": "Temperature in degrees Celsius.",
"displayName": "Temperature",
"name": "temperature",
"schema": "double",
"unit": "degreeCelsius"
},
{
"@type": [
"Property",
"Temperature",
"NumberValue"
],
"description": "Allows to remotely specify the desired target temperature.",
"displayName": "Target Temperature",
"name": "targetTemperature",
"schema": "double",
"unit": "degreeCelsius",
"writable": true,
"decimalPlaces": 1,
"displayUnit": "C",
"maxValue": 80,
"minValue": 50
},
{
"@type": [
"Property",
"Temperature"
],
"description": "Returns the max temperature since last device reboot.",
"displayName": "Max temperature since last reboot.",
"name": "maxTempSinceLastReboot",
"schema": "double",
"unit": "degreeCelsius"
},
{
"@type": "Command",
"description": "This command returns the max, min and average temperature from the specified time to the current time.",
"displayName": "Get report",
"name": "getMaxMinReport",
"request": {
"@type": "CommandPayload",
"description": "Period to return the max-min report.",
"displayName": "Since",
"name": "since",
"schema": "dateTime"
},
"response": {
"@type": "CommandPayload",
"displayName": "Temperature Report",
"name": "tempReport",
"schema": {
"@type": "Object",
"fields": [
{
"displayName": "Max temperature",
"name": "maxTemp",
"schema": "double"
},
{
"displayName": "Min temperature",
"name": "minTemp",
"schema": "double"
},
{
"displayName": "Average Temperature",
"name": "avgTemp",
"schema": "double"
},
{
"displayName": "Start Time",
"name": "startTime",
"schema": "dateTime"
},
{
"displayName": "End Time",
"name": "endTime",
"schema": "dateTime"
}
]
}
}
},
{
"@type": [
"Property",
"Cloud",
"StringValue"
],
"displayName": "Customer Name",
"name": "CustomerName",
"schema": "string"
}
],
"description": "Reports current temperature and provides desired temperature control.",
"displayName": "Thermostat"
},
"@id": "dtmi:modelDefinition:spzeut3n:n2lteu39u6",
"@type": [
"ModelDefinition",
"DeviceModel"
],
"@context": [
"dtmi:iotcentral:context;2",
"dtmi:dtdl:context;2"
]
}
디바이스 템플릿 업데이트
PATCH https://{your app subdomain}/api/deviceTemplates/{deviceTemplateId}?api-version=2022-07-31
샘플 요청 본문은 디바이스 템플릿의 capabilityModel에 LastMaintenanceDate 클라우드 속성을 추가하는 다음 예제와 같습니다.
{
"capabilityModel": {
"contents": [
{
"@type": [
"Telemetry",
"Temperature"
],
"description": "Temperature in degrees Celsius.",
"displayName": "Temperature",
"name": "temperature",
"schema": "double",
"unit": "degreeCelsius"
},
{
"@type": [
"Property",
"Temperature"
],
"description": "Allows to remotely specify the desired target temperature.",
"displayName": "Target Temperature",
"name": "targetTemperature",
"schema": "double",
"unit": "degreeCelsius",
"writable": true,
"decimalPlaces": 1,
"displayUnit": "C",
"maxValue": 80.0,
"minValue": 50.0
},
{
"@type": [
"Property",
"Temperature"
],
"description": "Returns the max temperature since last device reboot.",
"displayName": "Max temperature since last reboot.",
"name": "maxTempSinceLastReboot",
"schema": "double",
"unit": "degreeCelsius"
},
{
"@type": "Command",
"description": "This command returns the max, min and average temperature from the specified time to the current time.",
"displayName": "Get report",
"name": "getMaxMinReport",
"request": {
"@type": "CommandPayload",
"description": "Period to return the max-min report.",
"displayName": "Since",
"name": "since",
"schema": "dateTime"
},
"response": {
"@type": "CommandPayload",
"displayName": "Temperature Report",
"name": "tempReport",
"schema": {
"@type": "Object",
"fields": [
{
"displayName": "Max temperature",
"name": "maxTemp",
"schema": "double"
},
{
"displayName": "Min temperature",
"name": "minTemp",
"schema": "double"
},
{
"displayName": "Average Temperature",
"name": "avgTemp",
"schema": "double"
},
{
"displayName": "Start Time",
"name": "startTime",
"schema": "dateTime"
},
{
"displayName": "End Time",
"name": "endTime",
"schema": "dateTime"
}
]
}
}
},
{
"@type": [
"Property",
"Cloud",
"StringValue"
],
"displayName": "Customer Name",
"name": "CustomerName",
"schema": "string"
},
{
"@type": [
"Property",
"Cloud",
"StringValue"
],
"displayName": "Last Maintenance Date",
"name": "LastMaintenanceDate",
"schema": "dateTime"
}
],
"description": "Reports current temperature and provides desired temperature control.",
"displayName": "Thermostat"
}
}
이 요청에 대한 응답은 다음 예제와 같습니다.
{
"etag": "\"~6Ku691rHAgw/yw8u+ygZJGAKjSN4P4q/KxCU2xskrmk=\"",
"displayName": "Thermostat",
"capabilityModel": {
"@id": "dtmi:contoso:Thermostat;1",
"@type": "Interface",
"contents": [
{
"@type": [
"Telemetry",
"Temperature"
],
"description": "Temperature in degrees Celsius.",
"displayName": "Temperature",
"name": "temperature",
"schema": "double",
"unit": "degreeCelsius"
},
{
"@type": [
"Property",
"Temperature"
],
"description": "Allows to remotely specify the desired target temperature.",
"displayName": "Target Temperature",
"name": "targetTemperature",
"schema": "double",
"unit": "degreeCelsius",
"writable": true,
"decimalPlaces": 1,
"displayUnit": "C",
"maxValue": 80,
"minValue": 50
},
{
"@type": [
"Property",
"Temperature"
],
"description": "Returns the max temperature since last device reboot.",
"displayName": "Max temperature since last reboot.",
"name": "maxTempSinceLastReboot",
"schema": "double",
"unit": "degreeCelsius"
},
{
"@type": "Command",
"description": "This command returns the max, min and average temperature from the specified time to the current time.",
"displayName": "Get report",
"name": "getMaxMinReport",
"request": {
"@type": "CommandPayload",
"description": "Period to return the max-min report.",
"displayName": "Since",
"name": "since",
"schema": "dateTime"
},
"response": {
"@type": "CommandPayload",
"displayName": "Temperature Report",
"name": "tempReport",
"schema": {
"@type": "Object",
"fields": [
{
"displayName": "Max temperature",
"name": "maxTemp",
"schema": "double"
},
{
"displayName": "Min temperature",
"name": "minTemp",
"schema": "double"
},
{
"displayName": "Average Temperature",
"name": "avgTemp",
"schema": "double"
},
{
"displayName": "Start Time",
"name": "startTime",
"schema": "dateTime"
},
{
"displayName": "End Time",
"name": "endTime",
"schema": "dateTime"
}
]
}
}
},
{
"@type": [
"Property",
"Cloud",
"StringValue"
],
"displayName": "Customer Name",
"name": "CustomerName",
"schema": "string"
},
{
"@type": [
"Property",
"Cloud",
"DateTimeValue"
],
"displayName": "Last Maintenance Date",
"name": "LastMaintenanceDate",
"schema": "dateTime"
}
],
"description": "Reports current temperature and provides desired temperature control.",
"displayName": "Thermostat"
},
"@id": "dtmi:modelDefinition:spzeut3n:n2lteu39u6",
"@type": [
"ModelDefinition",
"DeviceModel"
],
"@context": [
"dtmi:iotcentral:context;2",
"dtmi:dtdl:context;2"
]
}
디바이스 템플릿 삭제
다음 요청을 사용하여 디바이스 템플릿을 삭제합니다.
DELETE https://{your app subdomain}/api/deviceTemplates/{deviceTemplateId}?api-version=2022-07-31
디바이스 템플릿 나열
애플리케이션에서 디바이스 템플릿의 목록을 검색하려면 다음 요청을 사용합니다.
GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-07-31
이 요청에 대한 응답은 다음 예제와 같습니다.
{
"value": [
{
"etag": "\"~F27cqSo0ON3bfOzwgZxAl89/JVvM80+dds6y8+mZh5M=\"",
"displayName": "Thermostat",
"capabilityModel": {
"@id": "dtmi:contoso:Thermostat;1",
"@type": "Interface",
"contents": [
{
"@type": [
"Telemetry",
"Temperature"
],
"description": "Temperature in degrees Celsius.",
"displayName": "Temperature",
"name": "temperature",
"schema": "double",
"unit": "degreeCelsius"
},
{
"@type": [
"Property",
"Temperature",
"NumberValue"
],
"description": "Allows to remotely specify the desired target temperature.",
"displayName": "Target Temperature",
"name": "targetTemperature",
"schema": "double",
"unit": "degreeCelsius",
"writable": true,
"decimalPlaces": 1,
"displayUnit": "C",
"maxValue": 80,
"minValue": 50
},
{
"@type": [
"Property",
"Temperature"
],
"description": "Returns the max temperature since last device reboot.",
"displayName": "Max temperature since last reboot.",
"name": "maxTempSinceLastReboot",
"schema": "double",
"unit": "degreeCelsius"
},
{
"@type": "Command",
"description": "This command returns the max, min and average temperature from the specified time to the current time.",
"displayName": "Get report",
"name": "getMaxMinReport",
"request": {
"@type": "CommandPayload",
"description": "Period to return the max-min report.",
"displayName": "Since",
"name": "since",
"schema": "dateTime"
},
"response": {
"@type": "CommandPayload",
"displayName": "Temperature Report",
"name": "tempReport",
"schema": {
"@type": "Object",
"fields": [
{
"displayName": "Max temperature",
"name": "maxTemp",
"schema": "double"
},
{
"displayName": "Min temperature",
"name": "minTemp",
"schema": "double"
},
{
"displayName": "Average Temperature",
"name": "avgTemp",
"schema": "double"
},
{
"displayName": "Start Time",
"name": "startTime",
"schema": "dateTime"
},
{
"displayName": "End Time",
"name": "endTime",
"schema": "dateTime"
}
]
}
}
},
{
"@type": [
"Property",
"Cloud",
"StringValue"
],
"displayName": "Customer Name",
"name": "CustomerName",
"schema": "string"
}
],
"description": "Reports current temperature and provides desired temperature control.",
"displayName": "Thermostat"
},
"@id": "dtmi:modelDefinition:spzeut3n:n2lteu39u6",
"@type": [
"ModelDefinition",
"DeviceModel"
],
"@context": [
"dtmi:iotcentral:context;2",
"dtmi:dtdl:context;2"
]
},
{
"etag": "\"~XS5GovPNzJqFIwkkV/vyWW5U/6if2NwC/NqUlDxExAY=\"",
"displayName": "Thermostat2",
"capabilityModel": {
"@id": "dtmi:contoso:Thermostat2;1",
"@type": "Interface",
"contents": [
{
"@type": [
"Telemetry",
"Temperature"
],
"description": "Temperature in degrees Celsius.",
"displayName": "Temperature",
"name": "temperature",
"schema": "double",
"unit": "degreeCelsius"
},
{
"@type": [
"Property",
"Temperature",
"NumberValue"
],
"description": "Allows to remotely specify the desired target temperature.",
"displayName": "Target Temperature",
"name": "targetTemperature",
"schema": "double",
"unit": "degreeCelsius",
"writable": true,
"decimalPlaces": 1,
"displayUnit": "C",
"maxValue": 80,
"minValue": 50
},
{
"@type": [
"Property",
"Temperature"
],
"description": "Returns the max temperature since last device reboot.",
"displayName": "Max temperature since last reboot.",
"name": "maxTempSinceLastReboot",
"schema": "double",
"unit": "degreeCelsius"
},
{
"@type": "Command",
"description": "This command returns the max, min and average temperature from the specified time to the current time.",
"displayName": "Get report",
"name": "getMaxMinReport",
"request": {
"@type": "CommandPayload",
"description": "Period to return the max-min report.",
"displayName": "Since",
"name": "since",
"schema": "dateTime"
},
"response": {
"@type": "CommandPayload",
"displayName": "Temperature Report",
"name": "tempReport",
"schema": {
"@type": "Object",
"fields": [
{
"displayName": "Max temperature",
"name": "maxTemp",
"schema": "double"
},
{
"displayName": "Min temperature",
"name": "minTemp",
"schema": "double"
},
{
"displayName": "Average Temperature",
"name": "avgTemp",
"schema": "double"
},
{
"displayName": "Start Time",
"name": "startTime",
"schema": "dateTime"
},
{
"displayName": "End Time",
"name": "endTime",
"schema": "dateTime"
}
]
}
}
},
{
"@type": [
"Property",
"Cloud",
"StringValue"
],
"displayName": "Customer Name",
"name": "CustomerName",
"schema": "string"
}
],
"description": "Reports current temperature and provides desired temperature control.",
"displayName": "Thermostat"
},
"@id": "dtmi:modelDefinition:spzeut3n:n2lteu39u67",
"@type": [
"ModelDefinition",
"DeviceModel"
],
"@context": [
"dtmi:iotcentral:context;2",
"dtmi:dtdl:context;2"
]
}
]
}
ODATA 필터 사용
API의 미리 보기 버전(api-version=2022-10-31-preview)에서 ODATA 필터를 사용하여 목록 디바이스 템플릿 API에서 반환된 결과를 필터링하고 정렬할 수 있습니다.
maxpagesize
maxpagesize 필터를 사용하여 결과 크기를 설정합니다. 반환된 최대 결과 크기는 100이고 기본 크기는 25입니다.
애플리케이션에서 상위 10개 디바이스 템플릿을 검색하려면 다음 요청을 사용합니다.
GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&maxpagesize=10
이 요청에 대한 응답은 다음 예제와 같습니다.
{
"value": [
{
"etag": "\"~6Ku691rHAgw/yw8u+ygZJGAKjSN4P4q/KxCU2xskrmk=\"",
"displayName": "Thermostat",
"capabilityModel": {
"@id": "dtmi:contoso:Thermostat;1",
"@type": "Interface",
"contents": [
...
],
"description": "Reports current temperature and provides desired temperature control.",
"displayName": "Thermostat"
},
"@id": "dtmi:modelDefinition:spzeut3n:n2lteu39u6",
"@type": [
"ModelDefinition",
"DeviceModel"
],
"@context": [
"dtmi:iotcentral:context;2",
"dtmi:dtdl:context;2"
]
},
{
"etag": "\"~6Ku691rHAgw/yw8u+ygZJGAKjSN4P4q/KxCU2xskrmk=\"",
"displayName": "Thermostat3",
"capabilityModel": {
"@id": "dtmi:contoso:Thermostat;3",
"@type": "Interface",
"contents": [
...
],
"description": "Reports current temperature and provides desired temperature control.",
"displayName": "Thermostat3"
},
"@id": "dtmi:modelDefinition:spzeut3n:n2lteu39u6",
"@type": [
"ModelDefinition",
"DeviceModel"
],
"@context": [
"dtmi:iotcentral:context;3",
"dtmi:dtdl:context;2"
]
},
// ...
],
"nextLink": "https://{your app subdomain}.azureiotcentral.com/api/deviceTemplates?api-version=2022-07-31&%24top=1&%24skiptoken=%7B%22token%22%3A%22%2BRID%3A%7EJWYqAKZQKp20qCoAAAAACA%3D%3D%23RT%3A1%23TRC%3A1%23ISV%3A2%23IEO%3A65551%23QCF%3A4%22%2C%22range%22%3A%7B%22min%22%3A%2205C1DFFFFFFFFC%22%2C%22max%22%3A%22FF%22%7D%7D"
}
응답에는 결과의 다음 페이지를 검색하는 데 사용할 수 있는 nextLink 값이 포함됩니다.
필터링
디바이스 템플릿의 목록을 필터링하는 식을 만들려면 filter를 사용합니다. 다음 표에는 사용할 수 있는 비교 연산자가 나와 있습니다.
| 비교 연산자 | 기호 | 예시 |
|---|---|---|
| 같음 | eq | '@id' eq 'dtmi:example:test;1' |
| 같지 않음 | ne | displayName ne 'template 1' |
| 작거나 같음 | le | displayName le 'template A' |
| 보다 작음 | lt | displayName lt 'template B' |
| 크거나 같음 | ge | displayName ge 'template A' |
| 보다 큼 | gt | displayName gt 'template B' |
다음 표는 filter 식에서 사용할 수 있는 논리 연산자를 보여 줍니다.
| 논리 연산자 | 기호 | 예시 |
|---|---|---|
| AND | 및 | '@id' eq 'dtmi:example:test;1' and capabilityModelId eq 'dtmi:example:test:model1;1' |
| 또는 | 또는 | '@id' eq 'dtmi:example:test;1' or displayName ge 'template' |
현재 filter는 다음 디바이스 템플릿 필드에서 작동합니다.
| FieldName | Type | Description |
|---|---|---|
@id |
string | 디바이스 템플릿 ID |
displayName |
string | 디바이스 템플릿 표시 이름 |
capabilityModelId |
string | 디바이스 템플릿 기능 모델 ID |
filter 지원 함수:
현재 디바이스 템플릿 목록에 지원되는 유일한 필터 함수는 contains 함수입니다.
filter=contains(displayName, 'template1')
다음 예제에서는 표시 이름에 thermostat 문자열이 포함된 모든 디바이스 템플릿을 검색하는 방법을 보여 줍니다.
GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&filter=contains(displayName, 'thermostat')
이 요청에 대한 응답은 다음 예제와 같습니다.
{
"value": [
{
"etag": "\"~6Ku691rHAgw/yw8u+ygZJGAKjSN4P4q/KxCU2xskrmk=\"",
"displayName": "Thermostat",
"capabilityModel": {
"@id": "dtmi:contoso:Thermostat;1",
"@type": "Interface",
"contents": [
...
],
"description": "Reports current temperature and provides desired temperature control.",
"displayName": "Thermostat"
},
"@id": "dtmi:modelDefinition:spzeut3n:n2lteu39u6",
"@type": [
"ModelDefinition",
"DeviceModel"
],
"@context": [
"dtmi:iotcentral:context;2",
"dtmi:dtdl:context;2"
]
},
{
"etag": "\"~6Ku691rHAgw/yw8u+ygZJGAKjSN4P46/KxCU2xskrmk=\"",
"displayName": "Room Thermostat",
"capabilityModel": {
"@id": "dtmi:contoso:RoomThermostat;1",
"@type": "Interface",
"contents": [
...
],
"description": "Reports current room temperature and provides desired temperature control.",
"displayName": "Room Thermostat"
},
"@id": "dtmi:modelDefinition:spzeut3n:n2lteu39u7",
"@type": [
"ModelDefinition",
"DeviceModel"
],
"@context": [
"dtmi:iotcentral:context;2",
"dtmi:dtdl:context;2"
]
},
{
"etag": "\"~6Ku691rHAgw/yw8u+ygZJGAKjSN4P7q/KxCU2xskrmk=\"",
"displayName": "Vehicle Thermostat",
"capabilityModel": {
"@id": "dtmi:contoso:VehicleThermostat;1",
"@type": "Interface",
"contents": [
...
],
"description": "Reports current vehicle temperature and provides desired temperature control.",
"displayName": "Vehicle Thermostat"
},
"@id": "dtmi:modelDefinition:spzeut3n:n2lt7u39u7",
"@type": [
"ModelDefinition",
"DeviceModel"
],
"@context": [
"dtmi:iotcentral:context;2",
"dtmi:dtdl:context;2"
]
}
]
}
orderby
orderby를 사용하여 결과를 정렬합니다. 현재 orderby는 displayName에서만 정렬할 수 있습니다. 기본적으로 orderby는 오름차순으로 정렬합니다. 내림차순으로 정렬하려면 desc를 사용합니다. 예를 들면 다음과 같습니다.
orderby=displayName
orderby=displayName desc
다음 예에서는 결과가 displayName으로 정렬된 모든 디바이스 템플릿을 검색하는 방법을 보여 줍니다.
GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&orderby=displayName
이 요청에 대한 응답은 다음 예제와 같습니다.
{
"value": [
{
"etag": "\"~6Ku691rHAgw/yw8u+ygZJGAKjSN4P4q/KxCU2xskrmk=\"",
"displayName": "Aircon Thermostat",
"capabilityModel": {
"@id": "dtmi:contoso:AirconThermostat;1",
"@type": "Interface",
"contents": [
...
],
"description": "Reports current temperature and provides desired temperature control.",
"displayName": "Thermostat"
},
"@id": "dtmi:modelDefinition:spzeut3n:n2lteu39u6",
"@type": [
"ModelDefinition",
"DeviceModel"
],
"@context": [
"dtmi:iotcentral:context;2",
"dtmi:dtdl:context;2"
]
},
{
"etag": "\"~6Ku691rHAgw/yw8u+ygZJGAKjSN4P46/KxCU2xskrmk=\"",
"displayName": "Room Thermostat",
"capabilityModel": {
"@id": "dtmi:contoso:RoomThermostat;1",
"@type": "Interface",
"contents": [
...
],
"description": "Reports current room temperature and provides desired temperature control.",
"displayName": "Room Thermostat"
},
"@id": "dtmi:modelDefinition:spzeut3n:n2lteu39u7",
"@type": [
"ModelDefinition",
"DeviceModel"
],
"@context": [
"dtmi:iotcentral:context;2",
"dtmi:dtdl:context;2"
]
},
{
"etag": "\"~6Ku691rHAgw/yw8u+ygZJGAKjSN4P7q/KxCU2xskrmk=\"",
"displayName": "Vehicle Thermostat",
"capabilityModel": {
"@id": "dtmi:contoso:VehicleThermostat;1",
"@type": "Interface",
"contents": [
...
],
"description": "Reports current vehicle temperature and provides desired temperature control.",
"displayName": "Vehicle Thermostat"
},
"@id": "dtmi:modelDefinition:spzeut3n:n2lt7u39u7",
"@type": [
"ModelDefinition",
"DeviceModel"
],
"@context": [
"dtmi:iotcentral:context;2",
"dtmi:dtdl:context;2"
]
}
]
}
두 개 이상의 필터를 결합할 수도 있습니다.
다음 예제에서는 표시 이름에 thermostat 문자열이 포함된 상위 2개 디바이스 템플릿을 검색하는 방법을 보여 줍니다.
GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&filter=contains(displayName, 'thermostat')&maxpagesize=2
이 요청에 대한 응답은 다음 예제와 같습니다.
{
"value": [
{
"etag": "\"~6Ku691rHAgw/yw8u+ygZJGAKjSN4P4q/KxCU2xskrmk=\"",
"displayName": "Aircon Thermostat",
"capabilityModel": {
"@id": "dtmi:contoso:AirconThermostat;1",
"@type": "Interface",
"contents": [
...
],
"description": "Reports current temperature and provides desired temperature control.",
"displayName": "Thermostat"
},
"@id": "dtmi:modelDefinition:spzeut3n:n2lteu39u6",
"@type": [
"ModelDefinition",
"DeviceModel"
],
"@context": [
"dtmi:iotcentral:context;2",
"dtmi:dtdl:context;2"
]
},
{
"etag": "\"~6Ku691rHAgw/yw8u+ygZJGAKjSN4P46/KxCU2xskrmk=\"",
"displayName": "Room Thermostat",
"capabilityModel": {
"@id": "dtmi:contoso:RoomThermostat;1",
"@type": "Interface",
"contents": [
...
],
"description": "Reports current room temperature and provides desired temperature control.",
"displayName": "Room Thermostat"
},
"@id": "dtmi:modelDefinition:spzeut3n:n2lteu39u7",
"@type": [
"ModelDefinition",
"DeviceModel"
],
"@context": [
"dtmi:iotcentral:context;2",
"dtmi:dtdl:context;2"
]
}
]
}
다음 단계
이제 REST API를 사용하여 디바이스 템플릿을 관리하는 방법을 배웠으므로 다음 단계는 IoT Central GUI에서 디바이스 템플릿을 만드는 방법입니다.