Jak zarządzać szablonami urządzeń za pomocą interfejsu API REST usługi IoT Central
Interfejs API REST usługi IoT Central umożliwia tworzenie aplikacji klienckich, które integrują się z aplikacjami usługi IoT Central. Interfejs API REST umożliwia zarządzanie szablonami urządzeń w aplikacji usługi IoT Central.
Każde wywołanie interfejsu API REST usługi IoT Central wymaga nagłówka autoryzacji. Aby dowiedzieć się więcej, zobacz Jak uwierzytelniać i autoryzować wywołania interfejsu API REST usługi IoT Central.
Aby uzyskać dokumentację referencyjną interfejsu API REST usługi IoT Central, zobacz Dokumentacja interfejsu API REST usługi Azure IoT Central.
Aby dowiedzieć się, jak zarządzać szablonami urządzeń przy użyciu interfejsu użytkownika usługi IoT Central, zobacz Jak skonfigurować szablony urządzeń i Jak edytować szablony urządzeń
Szablony urządzeń
Szablon urządzenia zawiera model urządzenia i definicje widoku. Interfejs API REST umożliwia zarządzanie modelem urządzenia, w tym definicjami właściwości w chmurze. Aby tworzyć widoki i zarządzać nimi, musisz użyć interfejsu użytkownika.
Sekcja modelu urządzenia szablonu urządzenia określa możliwości urządzenia, które chcesz połączyć z aplikacją. Możliwości obejmują dane telemetryczne, właściwości i polecenia. Model jest definiowany przy użyciu języka DTDL w wersji 2.
Uwaga
Usługa IoT Central definiuje niektóre rozszerzenia języka DTDL. Aby dowiedzieć się więcej, zobacz Rozszerzenie usługi IoT Central.
Interfejs API REST szablonów urządzeń
Interfejs API REST usługi IoT Central umożliwia wykonywanie następujących działań:
- Dodawanie szablonu urządzenia do aplikacji
- Aktualizowanie szablonu urządzenia w aplikacji
- Pobieranie listy szablonów urządzeń w aplikacji
- Pobieranie szablonu urządzenia według identyfikatora
- Usuwanie szablonu urządzenia w aplikacji
- Filtrowanie listy szablonów urządzeń w aplikacji
Dodawanie szablonu urządzenia
Użyj następującego żądania, aby utworzyć i opublikować nowy szablon urządzenia. Widoki domyślne są generowane automatycznie dla szablonów urządzeń utworzonych w ten sposób.
PUT https://{your app subdomain}/api/deviceTemplates/{deviceTemplateId}?api-version=2022-07-31
Uwaga
Identyfikatory szablonów urządzeń są zgodne z konwencją nazewnictwa DTDL , na przykład: dtmi:contoso:mythermostattemplate;1
Poniższy przykład przedstawia treść żądania, która dodaje szablon urządzenia dla urządzenia termostatu. Zawiera capabilityModel dane telemetryczne temperatury, dwie właściwości i polecenie. Szablon urządzenia definiuje CustomerName właściwość chmury i dostosowuje targetTemperature właściwość za pomocą decimalPlacespoleceń , displayUnit, maxValuei minValue. Wartość szablonu @id urządzenia musi być zgodna z wartością deviceTemplateId w adresie URL. Wartość szablonu @id urządzenia nie jest taka sama jak wartość wartości 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"
}
}
Treść żądania zawiera kilka wymaganych pól:
@id: unikatowy identyfikator w postaci prostej ujednoliconej nazwy zasobu.@type: deklaruje, że obiekt najwyższego"ModelDefinition","DeviceModel"poziomu to .@context: określa wersję DTDL używaną dla interfejsu.contents: wyświetla listę właściwości, telemetrii i poleceń tworzących urządzenie. Możliwości można zdefiniować w wielu interfejsach.capabilityModel: każdy szablon urządzenia ma model możliwości. Relacja jest ustanawiana między poszczególnymi modelami możliwości modułu i modelem urządzenia. Model możliwości implementuje co najmniej jeden interfejs modułu.
Napiwek
Kod JSON szablonu urządzenia nie jest standardowym dokumentem DTDL. Kod JSON szablonu urządzenia zawiera dane specyficzne dla usługi IoT Central, takie jak definicje właściwości w chmurze i jednostki wyświetlania. Format JSON szablonu urządzenia umożliwia importowanie i eksportowanie szablonów urządzeń w usłudze IoT Central przy użyciu interfejsu API REST, interfejsu wiersza polecenia i interfejsu użytkownika.
Istnieje kilka opcjonalnych pól, których można użyć, aby dodać więcej szczegółów do modelu możliwości, takie jak nazwa wyświetlana i opis.
Każdy wpis na liście interfejsów w sekcji implementacji ma następujące elementy:
name: nazwa programowania interfejsu.schema: interfejs implementuje model możliwości.
Odpowiedź na to żądanie wygląda następująco:
{
"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"
]
}
Pobieranie szablonu urządzenia
Użyj następującego żądania, aby pobrać szczegóły szablonu urządzenia z aplikacji:
GET https://{your app subdomain}/api/deviceTemplates/{deviceTemplateId}?api-version=2022-07-31
Uwaga
Możesz pobrać element z interfejsu deviceTemplateId użytkownika aplikacji usługi IoT Central, umieszczając wskaźnik myszy na urządzeniu.
Odpowiedź na to żądanie wygląda następująco:
{
"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"
]
}
Aktualizowanie szablonu urządzenia
PATCH https://{your app subdomain}/api/deviceTemplates/{deviceTemplateId}?api-version=2022-07-31
Przykładowa treść żądania wygląda podobnie do poniższego przykładu, który dodaje LastMaintenanceDate właściwość w chmurze do capabilityModel szablonu urządzenia:
{
"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"
}
}
Odpowiedź na to żądanie wygląda następująco:
{
"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"
]
}
Usuwanie szablonu urządzenia
Użyj następującego żądania, aby usunąć szablon urządzenia:
DELETE https://{your app subdomain}/api/deviceTemplates/{deviceTemplateId}?api-version=2022-07-31
Wyświetlanie listy szablonów urządzeń
Użyj następującego żądania, aby pobrać listę szablonów urządzeń z aplikacji:
GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-07-31
Odpowiedź na to żądanie wygląda następująco:
{
"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"
]
}
]
}
Korzystanie z filtrów ODATA
W wersji zapoznawczej interfejsu API (api-version=2022-10-31-preview) można użyć filtrów ODATA do filtrowania i sortowania wyników zwracanych przez interfejs API szablonów urządzeń listy.
maxpagesize
Użyj filtru maxpagesize , aby ustawić rozmiar wyniku. Maksymalny zwracany rozmiar wyniku to 100, a domyślny rozmiar to 25.
Użyj następującego żądania, aby pobrać 10 pierwszych szablonów urządzeń z aplikacji:
GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&maxpagesize=10
Odpowiedź na to żądanie wygląda następująco:
{
"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"
}
Odpowiedź zawiera wartość nextLink , której można użyć do pobrania następnej strony wyników.
filtr
Użyj filtru , aby utworzyć wyrażenia filtrujące listę szablonów urządzeń. W poniższej tabeli przedstawiono operatory porównania, których można użyć:
| Operator porównania | Symbol | Przykład |
|---|---|---|
| Równa się | eq | '@id' eq 'dtmi:example:test;1' |
| Nie równa się | ne | displayName ne 'template 1' |
| Mniejsze niż lub równe | le | displayName le 'template A' |
| Mniejsze niż | lt | displayName lt 'template B' |
| Większe niż lub równe | ge | displayName ge 'template A' |
| Większe niż | gt | displayName gt 'template B' |
W poniższej tabeli przedstawiono operatory logiki, których można używać w wyrażeniach filtru :
| Operator logiki | Symbol | Przykład |
|---|---|---|
| ORAZ | oraz | '@id' eq 'dtmi:example:test;1' and capabilityModelId eq 'dtmi:example:test:model1;1' |
| LUB | lub | '@id' eq 'dtmi:example:test;1' or displayName ge 'template' |
Obecnie filtr działa z następującymi polami szablonu urządzenia:
| Nazwa pola | Type | opis |
|---|---|---|
@id |
string | Identyfikator szablonu urządzenia |
displayName |
string | Nazwa wyświetlana szablonu urządzenia |
capabilityModelId |
string | Identyfikator modelu możliwości szablonu urządzenia |
filtrowanie obsługiwanych funkcji:
Obecnie jedyną obsługiwaną funkcją filtru dla list szablonów urządzeń jest contains funkcja:
filter=contains(displayName, 'template1')
W poniższym przykładzie pokazano, jak pobrać wszystkie szablony urządzeń, w których nazwa wyświetlana zawiera ciąg thermostat:
GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&filter=contains(displayName, 'thermostat')
Odpowiedź na to żądanie wygląda następująco:
{
"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
Użyj polecenia orderby , aby posortować wyniki. Obecnie funkcja orderby umożliwia sortowanie tylko według parametru displayName. Domyślnie kolejność sortuje w kolejności rosnącej. Użyj desc do sortowania w kolejności malejącej, na przykład:
orderby=displayName
orderby=displayName desc
W poniższym przykładzie pokazano, jak pobrać wszystkie szablony urządzeń, w których wynik jest sortowany według displayName:
GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&orderby=displayName
Odpowiedź na to żądanie wygląda następująco:
{
"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"
]
}
]
}
Można również połączyć dwa lub więcej filtrów.
W poniższym przykładzie pokazano, jak pobrać dwa pierwsze szablony urządzeń, w których nazwa wyświetlana zawiera ciąg thermostat.
GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&filter=contains(displayName, 'thermostat')&maxpagesize=2
Odpowiedź na to żądanie wygląda następująco:
{
"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"
]
}
]
}