Cara menggunakan IoT Central REST API untuk mengontrol perangkat

  • Artikel

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.

Tip

Anda dapat menggunakan Postman untuk mencoba panggilan REST API yang dijelaskan dalam artikel ini. Unduh koleksi IoT Central Postman dan impor ke Postman. Dalam koleksi, Anda harus mengatur variabel seperti subdomain aplikasi dan token admin.

Untuk mempelajari cara mengontrol perangkat dengan menggunakan UI IoT Central, lihat

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:

Screenshot that shows a simple no component thermostat device.

Cuplikan layar berikut menunjukkan templat perangkat pengontrol suhu yang menggunakan komponen. Pengontrol suhu memiliki dua komponen termostat dan komponen informasi perangkat:

Screenshot that shows a temperature controller device with two thermostat components and a device information component.

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:

Screenshot that shows an environmental sensor device with a module.

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. valueArray 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 thermostat2getMaxMinReport:

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.