Как использовать REST API в IoT Central для управления шаблонами устройств
REST API IoT Central позволяет разрабатывать клиентские приложения, которые интегрируются с приложениями IoT Central. Rest API можно использовать для управления шаблонами устройств в приложении IoT Central.
Каждому вызову REST API IoT Central требуется заголовок авторизации. Дополнительные сведения см. в разделе Аутентификация и авторизация вызовов REST API IoT Central.
Справочную документацию по REST API IoT Central см. в справочнике по REST API Azure IoT Central.
Сведения об управлении шаблонами устройств с помощью пользовательского интерфейса IoT Central см. в статье "Настройка шаблонов устройств" и "Изменение шаблонов устройств"
Шаблоны устройств
Шаблон устройства содержит определения модели устройства и представления. REST API позволяет управлять моделью устройства, включая определения облачных свойств. Для создания представлений и управления ими необходимо использовать пользовательский интерфейс.
Раздел модели устройства в шаблоне устройства определяет возможности устройства, которое вы хотите подключить к своему приложению. К ним относятся данные телеметрии, свойства и команды. Модель определяется с помощью DTDL версии 2.
Примечание.
IoT Central определяет некоторые расширения на языке DTDL. Дополнительные сведения см . в расширении IoT Central.
REST API шаблонов устройств
С помощью REST API IoT Central вы можете:
- добавить шаблон устройства в приложение;
- обновить шаблон устройства в приложении;
- получить список шаблонов устройств в приложении;
- получить шаблон устройства по идентификатору;
- удалить шаблон устройства в приложении.
- Фильтрация списка шаблонов устройств в приложении
Добавление шаблона устройства
Используйте следующий запрос, чтобы создать и опубликовать новый шаблон устройства. Представления по умолчанию создаются автоматически для шаблонов устройств, созданных таким образом.
PUT https://{your app subdomain}/api/deviceTemplates/{deviceTemplateId}?api-version=2022-07-31
Примечание.
Идентификаторы шаблонов устройств соответствуют соглашению об именовании DTDL , например: dtmi:contoso:mythermostattemplate;1
В следующем примере показан текст запроса, который добавляет шаблон устройства для термостата. Включает capabilityModel данные телеметрии температуры, два свойства и команду. Шаблон устройства определяет облачное CustomerName свойство и настраивает targetTemperature свойство с помощью decimalPlaces, displayUnitи maxValue.minValue Значение шаблона @id устройства должно соответствовать deviceTemplateId значению в URL-адресе. Значение шаблона @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: уникальный идентификатор в виде простого универсального имени ресурса.@type: объявляет, что объект верхнего уровня является"ModelDefinition","DeviceModel"объектом.@context: указывает версию DTDL, используемую для интерфейса.contents: перечисляет свойства, данные телеметрии и команды, составляющие устройство. Возможности можно определить в нескольких интерфейсах.capabilityModel: каждый шаблон устройства имеет модель возможностей. Между каждой моделью возможностей модуля и моделью возможностей устройства устанавливается связь. Модель возможностей реализует один или несколько интерфейсов модуля.
Совет
Json шаблона устройства не является стандартным документом DTDL. Json шаблона устройства включает в себя определенные данные IoT Central, такие как определения облачных свойств и единицы отображения. Формат JSON шаблона устройства можно использовать для импорта и экспорта шаблонов устройств в IoT Central с помощью REST API, интерфейса командной строки и пользовательского интерфейса.
Есть некоторые необязательные поля, которые можно использовать для добавления дополнительных деталей к модели возможностей, например отображаемое имя и описание.
Каждая запись в списке интерфейсов в разделе Implements определяет следующее.
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 можно получить 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
Текст запроса образца выглядит следующим образом, который добавляет LastMaintenanceDate облачное свойство в capabilityModel шаблон устройства:
{
"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 , которое можно использовать для получения следующей страницы результатов.
Фильтр
Используйте фильтр для создания выражений, которые фильтруют список шаблонов устройств. В следующей таблице показаны операторы сравнения, которые можно использовать:
| Оператор сравнения | Символ | Пример |
|---|---|---|
| Равно | 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' |
В следующей таблице показаны операторы логики, которые можно использовать в выражениях фильтра :
| Оператор логики | Символ | Пример |
|---|---|---|
| И | и | '@id' eq 'dtmi:example:test;1' and capabilityModelId eq 'dtmi:example:test:model1;1' |
| ИЛИ | or | '@id' eq 'dtmi:example:test;1' or displayName ge 'template' |
В настоящее время фильтр работает со следующими полями шаблона устройства:
| FieldName | Тип | Описание: |
|---|---|---|
@id |
строка | Идентификатор шаблона устройства |
displayName |
строка | Отображаемое имя шаблона устройства |
capabilityModelId |
строка | Идентификатор модели возможностей шаблона устройства |
Фильтрация поддерживаемых функций:
В настоящее время единственной поддерживаемой функцией фильтра для списков шаблонов устройств является 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. По умолчанию порядок сортировки выполняется по возрастанию. Используйте 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.
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"
]
}
]
}