Como utilizar a API REST do IoT Central para gerir modelos de dispositivos
A API REST do IoT Central permite-lhe desenvolver aplicações cliente que se integram com aplicações do IoT Central. Pode utilizar a API REST para gerir modelos de dispositivos na sua aplicação do IoT Central.
Cada chamada à API REST do IoT Central requer um cabeçalho de autorização. Para saber mais, veja Como autenticar e autorizar chamadas à API REST do IoT Central.
Para obter a documentação de referência da API REST do IoT Central, veja Referência da API REST do Azure IoT Central.
Dica
Pode utilizar o Postman para experimentar as chamadas à API REST descritas neste artigo. Transfira a coleção do Postman do IoT Central e importe-a para o Postman. Na coleção, terá de definir variáveis como o subdomínio da aplicação e o token de administrador.
Para saber como gerir modelos de dispositivos com a IU do IoT Central, veja Como configurar modelos de dispositivos e Como editar modelos de dispositivos
Modelos de dispositivo
Um modelo de dispositivo contém um modelo de dispositivo e definições de visualização. A API REST permite-lhe gerir o modelo de dispositivo, incluindo definições de propriedades na cloud. Tem de utilizar a IU para criar e gerir vistas.
A secção modelo de dispositivo de um modelo de dispositivo especifica as capacidades de um dispositivo que pretende ligar à sua aplicação. As capacidades incluem telemetria, propriedades e comandos. O modelo é definido com DTDL V2.
Nota
O IoT Central define algumas extensões para a linguagem DTDL. Para saber mais, veja Extensão do IoT Central.
API REST de modelos de dispositivos
A API REST do IoT Central permite:
- Adicionar um modelo de dispositivo à sua aplicação
- Atualizar um modelo de dispositivo na sua aplicação
- Obter uma lista dos modelos de dispositivo na aplicação
- Obter um modelo de dispositivo por ID
- Eliminar um modelo de dispositivo na sua aplicação
- Filtrar a lista de modelos de dispositivos na aplicação
Adicionar um modelo de dispositivo
Utilize o seguinte pedido para criar e publicar um novo modelo de dispositivo. As vistas predefinidas são geradas automaticamente para modelos de dispositivo criados desta forma.
PUT https://{your app subdomain}/api/deviceTemplates/{deviceTemplateId}?api-version=2022-07-31
Nota
Os IDs do modelo de dispositivo seguem a convenção de nomenclatura DTDL , por exemplo: dtmi:contoso:mythermostattemplate;1
O exemplo seguinte mostra um corpo do pedido que adiciona um modelo de dispositivo para um dispositivo termóstato. Inclui capabilityModel telemetria de temperatura, duas propriedades e um comando. O modelo de dispositivo define a propriedade cloud CustomerName e personaliza a targetTemperature propriedade com decimalPlaces, displayUnit, maxValuee minValue. O valor do modelo @id de dispositivo tem de corresponder ao deviceTemplateId valor no URL. O valor do modelo @id de dispositivo não é o mesmo que o valor do capabilityModel@id valor.
{
"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"
}
}
O corpo do pedido tem alguns campos necessários:
@id: um ID exclusivo na forma de um Nome de Recurso Uniforme simples.@type: declara que o objeto de nível superior é um"ModelDefinition","DeviceModel".@context: especifica a versão DTDL utilizada para a interface.contents: lista as propriedades, a telemetria e os comandos que compõem o seu dispositivo. As capacidades podem ser definidas em várias interfaces.capabilityModel: cada modelo de dispositivo tem um modelo de capacidade. É estabelecida uma relação entre cada modelo de capacidade de módulo e um modelo de dispositivo. Um modelo de capacidade implementa uma ou mais interfaces de módulo.
Dica
O JSON do modelo de dispositivo não é um documento DTDL padrão. O modelo de dispositivo JSON inclui dados específicos do IoT Central, tais como definições de propriedades na cloud e unidades de apresentação. Pode utilizar o formato JSON do modelo de dispositivo para importar e exportar modelos de dispositivos no IoT Central com a API REST, a CLI e a IU.
Existem alguns campos opcionais que pode utilizar para adicionar mais detalhes ao modelo de capacidade, como o nome a apresentar e a descrição.
Cada entrada na lista de interfaces na secção implementa tem:
name: o nome da programação da interface.schema: a interface que o modelo de capacidade implementa.
A resposta a este pedido tem o seguinte exemplo:
{
"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"
]
}
Obter um modelo de dispositivo
Utilize o seguinte pedido para obter detalhes de um modelo de dispositivo da sua aplicação:
GET https://{your app subdomain}/api/deviceTemplates/{deviceTemplateId}?api-version=2022-07-31
Nota
Pode obter a deviceTemplateId IU da Aplicação Do IoT Central ao pairar o rato sobre um dispositivo.
A resposta a este pedido tem o seguinte exemplo:
{
"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"
]
}
Atualizar um modelo de dispositivo
PATCH https://{your app subdomain}/api/deviceTemplates/{deviceTemplateId}?api-version=2022-07-31
O corpo do pedido de exemplo é semelhante ao seguinte exemplo que adiciona uma LastMaintenanceDate propriedade da capabilityModel cloud ao no modelo de dispositivo:
{
"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"
}
}
A resposta a este pedido tem o seguinte exemplo:
{
"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"
]
}
Eliminar um modelo de dispositivo
Utilize o seguinte pedido para eliminar um modelo de dispositivo:
DELETE https://{your app subdomain}/api/deviceTemplates/{deviceTemplateId}?api-version=2022-07-31
Listar modelos de dispositivos
Utilize o seguinte pedido para obter uma lista de modelos de dispositivos da sua aplicação:
GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-07-31
A resposta a este pedido tem o seguinte exemplo:
{
"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"
]
}
]
}
Utilizar filtros ODATA
Na versão de pré-visualização da API (api-version=2022-10-31-preview), pode utilizar filtros ODATA para filtrar e ordenar os resultados devolvidos pela API de modelos de dispositivos de lista.
maxpagesize
Utilize o filtro maxpagesize para definir o tamanho do resultado. O tamanho máximo dos resultados devolvidos é 100 e o tamanho predefinido é 25.
Utilize o seguinte pedido para obter os 10 principais modelos de dispositivo da sua aplicação:
GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&maxpagesize=10
A resposta a este pedido tem o seguinte exemplo:
{
"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"
}
A resposta inclui um valor nextLink que pode utilizar para obter a página seguinte dos resultados.
filter
Utilize o filtro para criar expressões que filtram a lista de modelos de dispositivos. A tabela seguinte mostra os operadores de comparação que pode utilizar:
| Operador de Comparação | Símbolo | Exemplo |
|---|---|---|
| Igual a | eq | '@id' eq 'dtmi:example:test;1' |
| Não É Igual a | ne | displayName ne 'template 1' |
| Menor ou igual a | le | displayName le 'template A' |
| Menor que | lt | displayName lt 'template B' |
| Maior ou igual a | ge | displayName ge 'template A' |
| Maior que | gt | displayName gt 'template B' |
A tabela seguinte mostra os operadores lógicos que pode utilizar em expressões de filtro :
| Operador Lógico | Símbolo | Exemplo |
|---|---|---|
| AND | e | '@id' eq 'dtmi:example:test;1' and capabilityModelId eq 'dtmi:example:test:model1;1' |
| OU | ou | '@id' eq 'dtmi:example:test;1' or displayName ge 'template' |
Atualmente, o filtro funciona com os seguintes campos de modelo de dispositivo:
| FieldName | Tipo | Description |
|---|---|---|
@id |
cadeia (de carateres) | ID do modelo de dispositivo |
displayName |
string | Nome a apresentar do modelo de dispositivo |
capabilityModelId |
string | ID do modelo de capacidade do modelo de dispositivo |
funções suportadas por filtro:
Atualmente, a única função de filtro suportada para listas de modelos de dispositivos é a contains função:
filter=contains(displayName, 'template1')
O exemplo seguinte mostra como obter todos os modelos de dispositivo onde o nome a apresentar contém a cadeia thermostat:
GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&filter=contains(displayName, 'thermostat')
A resposta a este pedido tem o seguinte exemplo:
{
"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
Utilize orderby para ordenar os resultados. Atualmente, orderby só lhe permite ordenar em displayName. Por predefinição, orderby ordena por ordem ascendente. Utilize desc para ordenar por ordem descendente, por exemplo:
orderby=displayName
orderby=displayName desc
O exemplo seguinte mostra como obter todos os modelos de dispositivo onde o resultado é ordenado por displayName:
GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&orderby=displayName
A resposta a este pedido tem o seguinte exemplo:
{
"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"
]
}
]
}
Também pode combinar dois ou mais filtros.
O exemplo seguinte mostra como obter os dois principais modelos de dispositivo onde o nome a apresentar contém a cadeia thermostat.
GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&filter=contains(displayName, 'thermostat')&maxpagesize=2
A resposta a este pedido tem o seguinte exemplo:
{
"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"
]
}
]
}
Passos seguintes
Agora que aprendeu a gerir modelos de dispositivos com a API REST, um passo seguinte sugerido é Como criar modelos de dispositivos a partir da GUI do IoT Central.