Cara menggunakan IoT Central REST API untuk mengontrol perangkat
IoT Central REST API memungkinkan Anda mengembangkan aplikasi klien yang terintegrasi dengan aplikasi IoT Central. Anda dapat menggunakan REST API untuk mengontrol perangkat di aplikasi IoT Central Anda. REST API memungkinkan Anda:
- Baca nilai telemetri terakhir yang diketahui dari perangkat.
- Membaca nilai properti dari perangkat.
- Setel properti bisa-tulis pada perangkat.
- Perintah panggilan di perangkat.
Artikel ini menjelaskan cara menggunakan /devices/{device_id}
API untuk mengontrol masing-masing perangkat. Anda juga dapat menggunakan pekerjaan untuk mengontrol perangkat secara massal.
Perangkat dapat mengelompokkan properti, telemetri, dan perintah yang didukungnya ke dalam komponen dan modul.
Setiap panggilan IoT Central REST API memerlukan header otorisasi. Untuk mempelajari selengkapnya, lihat Cara mengautentikasi dan mengotorisasi panggilan IoT Central REST API.
Untuk dokumentasi referensi untuk IoT Central REST API, lihat Referensi IoT Central REST API.
Untuk mempelajari cara mengontrol perangkat dengan menggunakan UI IoT Central, lihat
- Gunakan properti dalam solusi Azure IoT Central.
- Cara menggunakan perintah dalam solusi Azure IoT Central().
Komponen dan modul
Komponen memungkinkan Anda mengelompokkan dan menggunakan kembali kemampuan perangkat. Untuk mempelajari selengkapnya tentang komponen dan model perangkat, lihat panduan pemodelan IoT Plug and Play.
Tidak semua templat perangkat menggunakan komponen. Cuplikan layar berikut menunjukkan templat perangkat untuk termostat sederhana, tempat semua kemampuan didefinisikan dalam satu antarmuka yang disebut Komponen Akar:
Cuplikan layar berikut menunjukkan templat perangkat pengontrol suhu yang menggunakan komponen. Pengontrol suhu memiliki dua komponen termostat dan komponen informasi perangkat:
Di IoT Central, modul mengacu pada modul IoT Edge yang berjalan pada perangkat IoT Edge yang terhubung. Modul dapat memiliki model sederhana seperti termostat yang tidak menggunakan komponen. Modul juga dapat menggunakan komponen untuk mengatur serangkaian kemampuan yang lebih kompleks. Cuplikan layar berikut menunjukkan contoh templat perangkat yang menggunakan modul. Perangkat sensor lingkungan memiliki modul yang disebut SimulatedTemperatureSensor
dan antarmuka yang diwariskan yang disebut management
:
Dapatkan komponen perangkat
Gunakan permintaan berikut untuk mengambil komponen dari perangkat yang disebut temperature-controller-01
:
GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components?api-version=2022-07-31
Respons terhadap permintaan ini akan terlihat seperti contoh berikut. value
Array berisi detail setiap komponen perangkat:
{
"value": [
{
"@type": "Component",
"name": "thermostat1",
"displayName": "Thermostat One",
"description": "Thermostat One of Two."
},
{
"@type": "Component",
"name": "thermostat2",
"displayName": "Thermostat Two",
"description": "Thermostat Two of Two."
},
{
"@type": "Component",
"name": "deviceInformation",
"displayName": "Device Information interface",
"description": "Optional interface with basic device hardware information."
}
]
}
Dapatkan modul perangkat
Gunakan permintaan berikut untuk mengambil daftar modul yang berjalan pada perangkat IoT Edge yang terhubung yang disebut environmental-sensor-01
:
GET https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules?api-version=2022-07-31
Respons terhadap permintaan ini akan terlihat seperti contoh berikut. Array modul hanya mencakup modul kustom yang berjalan pada perangkat IoT Edge, bukan bawaan modul $edgeAgent
dan $edgeHub
:
{
"value": [
{
"@type": [
"Relationship",
"EdgeModule"
],
"name": "SimulatedTemperatureSensor",
"displayName": "SimulatedTemperatureSensor"
}
]
}
Gunakan permintaan berikut untuk mengambil daftar komponen dalam modul yang disebut SimulatedTemperatureSensor
:
GET https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules?api-version=2022-07-31
Baca telemetri
Gunakan permintaan berikut untuk mengambil nilai telemetri terakhir yang diketahui dari perangkat yang tidak menggunakan komponen. Dalam contoh ini, perangkat dipanggil thermostat-01
dan telemetri disebut temperature
:
GET https://{your app subdomain}.azureiotcentral.com/api/devices/thermostat-01/telemetry/temperature?api-version=2022-07-31
Respons terhadap permintaan ini akan terlihat seperti contoh berikut:
{
"timestamp": "2021-03-24T12:33:15.223Z",
"value": 40.10993804456927
}
Gunakan permintaan berikut untuk mengambil nilai telemetri terakhir yang diketahui dari perangkat yang menggunakan komponen. Dalam contoh ini, perangkat disebut temperature-controller-01
, komponen disebut, dan thermostat2
telemetri disebut temperature
:
GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/telemetry/temperature?api-version=2022-07-31
Respons terhadap permintaan ini akan terlihat seperti contoh berikut:
{
"timestamp": "2021-03-24T12:43:44.968Z",
"value": 70.29168040339141
}
Jika perangkat adalah perangkat IoT Edge, gunakan permintaan berikut untuk mengambil nilai telemetri terakhir yang diketahui dari modul. Contoh ini menggunakan perangkat yang disebut dengan environmental-sensor-01
modul yang disebut dan SimulatedTemperatureSensor
telemetri yang disebut ambient
. ambient
Jenis telemetri memiliki nilai suhu dan kelembaban:
GET https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules/SimulatedTemperatureSensor/telemetry/ambient?api-version=2022-07-31
Respons terhadap permintaan ini akan terlihat seperti contoh berikut:
{
"timestamp": "2021-03-25T15:44:34.955Z",
"value": {
"temperature": 21.18032378129676,
"humidity": 25
}
}
Tip
Untuk mengakses telemetri dari komponen dalam modul, gunakan /api/devices/{deviceId}/modules/{moduleName}/components/{componentName}/telemetry/{telemetryName}
.
Membaca properti
Gunakan permintaan berikut untuk mengambil nilai properti dari perangkat yang tidak menggunakan komponen. Dalam contoh ini, perangkat disebut thermostat-01
:
GET https://{your app subdomain}.azureiotcentral.com/api/devices/thermostat-01/properties?api-version=2022-07-31
Respons terhadap permintaan ini akan terlihat seperti contoh berikut. Ini menunjukkan perangkat melaporkan satu nilai properti:
{
"maxTempSinceLastReboot": 93.95907131817654,
"$metadata": {
"maxTempSinceLastReboot": {
"lastUpdateTime": "2021-03-24T12:47:46.7571438Z"
}
}
}
Gunakan permintaan berikut untuk mengambil nilai properti dari semua komponen. Dalam contoh ini, perangkat disebut temperature-controller-01
:
GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/properties?api-version=2022-07-31
Respons terhadap permintaan ini akan terlihat seperti contoh berikut:
{
"serialNumber": "Explicabo animi nihil qui facere sit explicabo nisi.",
"$metadata": {
"serialNumber": {
"lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
}
},
"thermostat1": {
"maxTempSinceLastReboot": 79.7290121339184,
"$metadata": {
"maxTempSinceLastReboot": {
"lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
}
}
},
"thermostat2": {
"maxTempSinceLastReboot": 54.214860556320424,
"$metadata": {
"maxTempSinceLastReboot": {
"lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
}
}
},
"deviceInformation": {
"manufacturer": "Eveniet culpa sed sit omnis.",
"$metadata": {
"manufacturer": {
"lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
},
"model": {
"lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
},
"swVersion": {
"lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
},
"osName": {
"lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
},
"processorArchitecture": {
"lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
},
"processorManufacturer": {
"lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
},
"totalStorage": {
"lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
},
"totalMemory": {
"lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
}
},
"model": "Necessitatibus id ab dolores vel eligendi fuga.",
"swVersion": "Ut minus ipsum ut omnis est asperiores harum.",
"osName": "Atque sit omnis eum sapiente eum tenetur est dolor.",
"processorArchitecture": "Ratione enim dolor iste iure.",
"processorManufacturer": "Aliquam eligendi sit ipsa.",
"totalStorage": 36.02825898541592,
"totalMemory": 55.442695395750505
}
}
Gunakan permintaan berikut untuk mengambil nilai properti dari komponen individual. Dalam contoh ini, perangkat dipanggil temperature-controller-01
dan komponen disebut thermostat2
:
GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/properties?api-version=2022-07-31
Respons terhadap permintaan ini akan terlihat seperti contoh berikut:
{
"maxTempSinceLastReboot": 24.445128131004935,
"$metadata": {
"maxTempSinceLastReboot": {
"lastUpdateTime": "2021-03-24T14:03:53.787491Z"
}
}
}
Jika perangkat adalah perangkat IoT Edge, gunakan permintaan berikut untuk mengambil nilai properti dari modul. Contoh ini menggunakan perangkat yang disebut environmental-sensor-01
dengan modul yang disebut SimulatedTemperatureSensor
:
GET https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules/SimulatedTemperatureSensor/properties?api-version=2022-07-31
Respons terhadap permintaan ini akan terlihat seperti contoh berikut:
{
"$metadata": {
"SendData": {
"desiredValue": true,
"desiredVersion": 1
},
"SendInterval": {
"desiredValue": 10,
"desiredVersion": 1
}
}
}
Tip
Untuk mengakses properti dari komponen dalam modul, gunakan /devices/{deviceId}/modules/{moduleName}/components/{componentName}/properties
.
Properti tulis
Beberapa properti dapat ditulis. Dalam contoh model termostat, targetTemperature
properti adalah properti bisa-tulis.
Gunakan permintaan berikut untuk menulis nilai properti individual ke perangkat yang tidak menggunakan komponen. Dalam contoh ini, perangkat disebut thermostat-01
:
PATCH https://{your app subdomain}.azureiotcentral.com/api/devices/thermostat-01/properties?api-version=2022-07-31
Isi permintaan terlihat seperti contoh berikut:
{
"targetTemperature": 65.5
}
Respons terhadap permintaan ini akan terlihat seperti contoh berikut:
{
"$metadata": {
"targetTemperature": {
"desiredValue": 65.5
}
}
}
Tip
Untuk memperbarui semua properti pada perangkat, gunakan PUT
sebagai gantinya PATCH
.
Gunakan permintaan berikut untuk menulis nilai properti individual ke perangkat yang menggunakan komponen. Dalam contoh ini, perangkat dipanggil temperature-controller-01
dan komponen disebut thermostat2
:
PATCH https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/properties?api-version=2022-07-31
Isi permintaan terlihat seperti contoh berikut:
{
"targetTemperature": 65.5
}
Respons terhadap permintaan ini akan terlihat seperti contoh berikut:
{
"$metadata": {
"targetTemperature": {
"desiredValue": 65.5
}
}
}
Tip
Untuk memperbarui semua properti pada komponen, gunakan PUT
sebagai gantinya PATCH
.
Jika perangkat adalah perangkat IoT Edge, gunakan permintaan berikut untuk menulis nilai properti individual ke modul. Contoh ini menggunakan perangkat yang disebut environmental-sensor-01
, modul yang disebut SimulatedTemperatureSensor
, dan properti yang disebut SendInterval
:
PUT https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules/SimulatedTemperatureSensor/properties?api-version=2022-07-31
Isi permintaan terlihat seperti contoh berikut:
{
"SendInterval": 20
}
Respons terhadap permintaan ini akan terlihat seperti contoh berikut:
{
"$metadata": {
"SendInterval": {
"desiredValue": 20
}
}
}
Tip
Untuk memperbarui semua properti pada modul, gunakan PUT
alih-alih PATCH
.
Perbarui properti modul
Jika Anda menggunakan perangkat IoT Edge, gunakan permintaan berikut untuk mengambil nilai properti dari modul:
GET https://{your app subdomain}.azureiotcentral.com/api/devices/{deviceId}/modules/{moduleName}/properties?api-version=2022-07-31
Jika Anda menggunakan perangkat IoT Edge, gunakan permintaan berikut untuk mengambil nilai properti dari komponen dalam modul:
GET https://{your app subdomain}.azureiotcentral.com/api/devices/{deviceId}/modules/{moduleName}/components/{componentName}/properties?api-version=2022-07-31
Perintah panggilan
Anda dapat menggunakan REST API untuk memanggil perintah perangkat dan mengambil riwayat perintah.
Gunakan permintaan berikut untuk memanggil perintah pada perangkat yang tidak menggunakan komponen. Dalam contoh ini, perangkat dipanggil thermostat-01
dan perintah disebut getMaxMinReport
:
POST https://{your app subdomain}.azureiotcentral.com/api/devices/thermostat-01/commands/getMaxMinReport?api-version=2022-07-31
Isi permintaan terlihat seperti contoh berikut:
{
"request": "2021-03-24T12:55:20.789Z"
}
Respons terhadap permintaan ini akan terlihat seperti contoh berikut:
{
"response": {
"maxTemp": 21.002000799562367,
"minTemp": 73.09674605264892,
"avgTemp": 59.54553991653756,
"startTime": "2022-02-28T15:02:56.789Z",
"endTime": "2021-05-05T03:50:56.412Z"
},
"responseCode": 200
}
Untuk melihat riwayat untuk perintah ini, gunakan permintaan berikut:
GET https://{your app subdomain}.azureiotcentral.com/api/devices/thermostat-01/commands/getMaxMinReport?api-version=2022-07-31
Respons terhadap permintaan ini akan terlihat seperti contoh berikut:
{
"value": [
{
"response": {
"maxTemp": 71.43744908819954,
"minTemp": 51.29986610160005,
"avgTemp": 39.577384387771744,
"startTime": "2021-06-20T00:38:17.620Z",
"endTime": "2022-01-07T22:30:41.104Z"
},
"responseCode": 200
}
]
}
Gunakan permintaan berikut untuk memanggil perintah pada perangkat yang menggunakan komponen. Dalam contoh ini, perangkat disebut temperature-controller-01
, komponen disebut, dan perintah disebut thermostat2
getMaxMinReport
:
POST https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/commands/getMaxMinReport?api-version=2022-07-31
Format payload permintaan dan respons sama dengan perangkat yang tidak menggunakan komponen.
Untuk melihat riwayat untuk perintah ini, gunakan permintaan berikut:
GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/commands/getMaxMinReport?api-version=2022-07-31
Tip
Untuk memanggil perintah dalam komponen dalam modul, gunakan /devices/{deviceId}/modules/{moduleName}/components/{componentName}/commands/{commandName}
.
Langkah berikutnya
Setelah Anda mempelajari cara mengontrol perangkat dengan REST API, langkah berikutnya yang disarankan adalah Cara menggunakan REST API Azure IoT Central untuk mengontrol dan mengelola pekerjaan.