Cara menggunakan IoT Central REST API untuk mengelola templat perangkat
Artikel
IoT Central REST API memungkinkan Anda mengembangkan aplikasi klien yang terintegrasi dengan aplikasi IoT Central. Anda dapat menggunakan REST API untuk mengelola templat perangkat di aplikasi IoT Central Anda.
Templat perangkat berisi model perangkat dan definisi tampilan. REST API memungkinkan Anda mengelola model perangkat termasuk definisi properti cloud. Anda harus menggunakan UI untuk membuat dan mengelola tampilan.
Bagian model perangkat dari templat perangkat menentukan kapabilitas perangkat yang ingin Anda sambungkan ke aplikasi Anda. Kemampuan mencakup telemetri, properti, dan perintah. Model didefinisikan menggunakan DTDL v2.
Catatan
IoT Central mendefinisikan beberapa ekstensi ke bahasa DTDL. Untuk mempelajari lebih lanjut, lihat Ekstensi IoT Central.
Templat perangkat REST API
IoT Central REST API memungkinkan Anda:
Menambahkan templat perangkat ke aplikasi Anda
Memperbarui templat perangkat di aplikasi Anda
Dapatkan daftar templat perangkat dalam aplikasi
Mendapatkan templat perangkat menurut ID
Menghapus templat perangkat di aplikasi Anda
Memfilter daftar templat perangkat dalam aplikasi
Menambahkan templat perangkat
Gunakan permintaan berikut untuk membuat dan menerbitkan templat perangkat baru. Tampilan default secara otomatis dihasilkan untuk templat perangkat yang dibuat dengan cara ini.
HTTP
PUT https://{your app subdomain}/api/deviceTemplates/{deviceTemplateId}?api-version=2022-07-31
Catatan
ID templat perangkat mengikuti konvensi penamaan DTDL, misalnya: dtmi:contoso:mythermostattemplate;1
Contoh berikut menunjukkan isi permintaan yang menambahkan templat perangkat untuk perangkat termostat. Ini capabilityModel mencakup telemetri suhu, dua sifat, dan perintah. Templat perangkat mendefinisikan CustomerName properti cloud dan menyesuaikan targetTemperature properti dengan decimalPlaces, displayUnit, maxValue, dan minValue. Nilai templat perangkat @id harus sesuai dengan deviceTemplateId nilai dalam URL. Nilai templat @id perangkat tidak sama dengan nilai capabilityModel@id nilai.
JSON
{
"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"
}
}
Isi permintaan memiliki beberapa bidang yang diperlukan:
@id: ID unik dalam bentuk Nama Sumber Daya Seragam sederhana.
@type: menyatakan bahwa objek tingkat atas adalah "ModelDefinition","DeviceModel".
@context: menentukan versi DTDL yang digunakan untuk antarmuka.
contents: mencantumkan properti, telemetri, dan perintah yang membentuk perangkat Anda. Kemampuan dapat didefinisikan dalam beberapa antarmuka.
capabilityModel : Setiap templat perangkat memiliki model kemampuan. Hubungan terjalin antara setiap model kemampuan modul dan model perangkat. Model kemampuan modul mengimplementasikan satu atau lebih antarmuka modul.
Tip
JSON templat perangkat bukan dokumen DTDL standar. JSON templat perangkat menyertakan data khusus IoT Central seperti definisi properti cloud dan unit tampilan. Anda dapat menggunakan format JSON templat perangkat untuk mengimpor dan mengekspor templat perangkat di IoT Central dengan menggunakan REST API, CLI, dan UI.
Ada beberapa bidang opsional yang bisa Anda gunakan untuk menambahkan detail lebih lanjut ke model kapabilitas, seperti nama tampilan dan deskripsi.
Setiap entri dalam daftar antarmuka di bagian penerapan memiliki:
name: nama pemrograman antarmuka.
schema: antarmuka yang diterapkan model kemampuan.
Respons terhadap permintaan ini akan terlihat seperti contoh berikut:
JSON
{
"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"
]
}
Dapatkan templat perangkat
Gunakan permintaan berikut untuk mengambil detail templat perangkat dari aplikasi Anda:
HTTP
GET https://{your app subdomain}/api/deviceTemplates/{deviceTemplateId}?api-version=2022-07-31
Catatan
Anda bisa mendapatkan deviceTemplateId dari IoT Central Application UI dengan mengarahkan mouse ke perangkat.
Respons terhadap permintaan ini akan terlihat seperti contoh berikut:
JSON
{
"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"
]
}
Gunakan permintaan berikut untuk mengambil daftar templat perangkat dari aplikasi Anda:
HTTP
GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-07-31
Respons terhadap permintaan ini akan terlihat seperti contoh berikut:
JSON
{
"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"
]
}
]
}
Menggunakan filter ODATA
Dalam versi pratinjau API (api-version=2022-10-31-preview), Anda dapat menggunakan filter ODATA untuk memfilter dan mengurutkan hasil yang dikembalikan oleh API templat perangkat daftar.
maxpagesize
Gunakan filter maxpagesize untuk mengatur ukuran hasil. Ukuran hasil maksimum yang dikembalikan adalah 100, dan ukuran defaultnya adalah 25.
Gunakan permintaan berikut untuk mengambil 10 templat perangkat teratas dari aplikasi Anda:
HTTP
GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&maxpagesize=10
Respons terhadap permintaan ini akan terlihat seperti contoh berikut:
Respons menyertakan nilai nextLink yang dapat Anda gunakan untuk mengambil halaman hasil berikutnya.
filter
Gunakan filter untuk membuat ekspresi yang memfilter daftar templat perangkat. Tabel berikut ini memperlihatkan operator perbandingan yang bisa Anda gunakan:
Operator Perbandingan
Simbol
Contoh
Sama dengan
eq
'@id' eq 'dtmi:example:test;1'
Tidak Sama
ne
displayName ne 'template 1'
Kurang dari atau sama dengan
le
displayName le 'template A'
Kurang dari
lt
displayName lt 'template B'
Lebih besar atau sama dengan
ge
displayName ge 'template A'
Lebih besar dari
gt
displayName gt 'template B'
Tabel berikut ini memperlihatkan operator logika yang bisa Anda gunakan dalam ekspresi filter :
Operator Logika
Simbol
Contoh
AND
dan
'@id' eq 'dtmi:example:test;1' and capabilityModelId eq 'dtmi:example:test:model1;1'
ATAU
or
'@id' eq 'dtmi:example:test;1' or displayName ge 'template'
Saat ini, filter berfungsi dengan bidang templat perangkat berikut:
FieldName
Tipe
Deskripsi
@id
string
ID templat perangkat
displayName
string
Nama tampilan templat perangkat
capabilityModelId
string
ID model kemampuan templat perangkat
filter fungsi yang didukung:
Saat ini, satu-satunya fungsi filter yang didukung untuk daftar templat perangkat adalah contains fungsi :
txt
filter=contains(displayName, 'template1')
Contoh berikut menunjukkan cara mengambil semua templat perangkat di mana nama tampilan berisi string thermostat:
HTTP
GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&filter=contains(displayName, 'thermostat')
Respons terhadap permintaan ini akan terlihat seperti contoh berikut:
Gunakan orderby untuk mengurutkan hasilnya. Saat ini, orderby hanya memungkinkan Anda mengurutkan pada displayName. Secara default, orderby mengurutkan dalam urutan naik. Gunakan turunan untuk mengurutkan dalam urutan turun, misalnya:
txt
orderby=displayName
orderby=displayName desc
Contoh berikut menunjukkan cara mengambil semua templat perangkat tempat hasilnya diurutkan menurut displayName:
HTTP
GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&orderby=displayName
Respons terhadap permintaan ini akan terlihat seperti contoh berikut:
Pelajari cara menggunakan properti baca-saja dan bisa-tulis dalam solusi Azure IoT Central. Tentukan properti di IoT Central dan gunakan properti secara terprogram.