Cara menggunakan IoT Central REST API untuk mengkueri perangkat

IoT Central REST API memungkinkan Anda mengembangkan aplikasi klien yang terintegrasi dengan aplikasi IoT Central. Anda dapat menggunakan REST API untuk meng-kueri perangkat di aplikasi IoT Central Anda. Berikut ini adalah contoh bagaimana Anda dapat menggunakan REST API kueri:

• Dapatkan 10 nilai telemetri terakhir yang dilaporkan oleh perangkat.
• Temukan semua perangkat yang berada dalam keadaan kesalahan dan memiliki firmware yang sudah usang.
• Tren telemetri dari perangkat, rata-rata dalam jendela 10 menit.
• Dapatkan versi firmware saat ini dari semua perangkat termostat Anda.

Artikel ini menjelaskan cara menggunakan API /query untuk meng-kueri perangkat.

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 mengkueri perangkat dengan menggunakan UI IoT Central, lihat Cara menggunakan penjelajah data untuk menganalisis data perangkat.

Menjalankan kueri

Gunakan permintaan berikut untuk menjalankan kueri:

POST https://{your app subdomain}.azureiotcentral.com/api/query?api-version=2022-10-31-preview

Kueri ada di isi permintaan dan terlihat seperti contoh berikut:

{
  "query": "SELECT $id, $ts, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D)"
}

Nilai dtmi:eclipsethreadx:devkit:hlby5jgib2o dalam klausul FROM adalah ID templat perangkat. Untuk menemukan ID templat perangkat, navigasikan ke halaman Perangkat di aplikasi IoT Central Anda dan arahkan kursor ke perangkat yang menggunakan templat. Kartu termasuk ID templat perangkat:

Respons mencakup telemetri dari beberapa perangkat yang berbagi templat perangkat yang sama. Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
  "results": [
    {
      "$id": "sample-003",
      "$ts": "2021-09-10T12:59:52.015Z",
      "temperature": 47.632160152311016,
      "humidity": 49.726422005390816
    },
    {
      "$id": "sample-001",
      "$ts": "2021-09-10T13:01:34.286Z",
      "temperature": 58.898120617808495,
      "humidity": 44.66125772328022
    },
    {
      "$id": "sample-001",
      "$ts": "2021-09-10T13:04:04.96Z",
      "temperature": 52.79601469228174,
      "humidity": 71.5067230188416
    },
    {
      "$id": "sample-002",
      "$ts": "2021-09-10T13:04:36.877Z",
      "temperature": 49.610062789623264,
      "humidity": 52.78538601804491
    }
  ]
}

Sintaks

Sintaks kueri mirip dengan sintaks SQL dan terdiri atas klausul berikut:

• SELECT diperlukan dan mendefinisikan data yang ingin Anda ambil, seperti nilai telemetri perangkat.
• FROM diperlukan dan mengidentifikasi jenis perangkat yang Anda minta. Klausul ini menentukan ID templat perangkat.
• WHERE bersifat opsional dan memungkinkan Anda memfilter hasilnya.
• ORDER BY bersifat opsional dan memungkinkan Anda mengurutkan hasilnya.
• GROUP BY bersifat opsional dan memungkinkan Anda mengumpulkan hasil.

Bagian berikut menjelaskan klausul ini secara lebih terperinci.

Klausul SELECT

Klausul SELECT mencantumkan nilai data untuk disertakan dalam output kueri dan dapat menyertakan item berikut:

• Telemetri. Gunakan nama telemetri dari templat perangkat.
• $id. ID perangkat.
• $provisioned. Nilai boolean yang menunjukkan apakah perangkat belum tersedia.
• $simulated. Nilai boolean yang menunjukkan apakah perangkat adalah perangkat simulasi.
• $ts. Tanda waktu terkait dengan nilai telemetri.

Jika templat perangkat Anda menggunakan komponen, maka Anda mereferensikan telemetri yang ditentukan dalam komponen sebagai berikut:

{
  "query": "SELECT ComponentName.TelemetryName FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o"
}

Anda dapat menemukan nama komponen di templat perangkat:

Batasan berikut berlaku untuk klausul SELECT:

• Tidak ada operator kartubebas.
• Anda tidak dapat memiliki lebih dari 15 item dalam daftar pilih.
• Kueri mengembalikan maksimum 10.000 rekaman.

Alias

Gunakan kata kunci AS untuk menentukan alias untuk item dalam klausul SELECT. Alias digunakan dalam output kueri. Anda juga dapat menggunakannya di tempat lain dalam kueri. Contohnya:

{
  "query": "SELECT $id as ID, $ts as timestamp, temperature as t, pressure as p FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D) AND t > 0 AND p > 50"
}

Output yang dihasilkan terlihat seperti output berikut:

{
  "results": [
    {
      "ID": "sample-002",
      "timestamp": "2021-09-10T11:40:29.188Z",
      "t": 40.20355053736378,
      "p": 79.26806508746755
    },
    {
      "ID": "sample-001",
      "timestamp": "2021-09-10T11:43:42.61Z",
      "t": 68.03536237975348,
      "p": 58.33517075380311
    }
  ]
}

TOP

Gunakan TOP untuk membatasi jumlah hasil pengembalian kueri. Misalnya, kueri berikut mengembalikan 10 hasil pertama:

{
    "query": "SELECT TOP 10 $id as ID, $ts as timestamp, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o"
}

Jika Anda tidak menggunakan TOP, kueri mengembalikan hasil maksimal 10.000 hasil.

Untuk mengurutkan hasil sebelum TOP membatasi jumlah hasil, gunakan ORDER BY.

Klausul FROM

Klausul FROM harus berisi ID templat perangkat. Klausul FROM menentukan jenis perangkat yang Anda kueri.

Untuk menemukan ID templat perangkat, navigasikan ke halaman Perangkat di aplikasi IoT Central Anda dan arahkan kursor ke perangkat yang menggunakan templat. Kartu termasuk ID templat perangkat:

Anda juga dapat menggunakan panggilan REST API Perangkat - Dapatkan untuk mendapatkan ID templat perangkat untuk perangkat.

Klausul WHERE

Klausul WHERE memungkinkan Anda menggunakan nilai dan jendela waktu untuk memfilter hasil:

Jendela waktu

Untuk mendapatkan telemetri yang diterima oleh aplikasi Anda dalam jendela waktu tertentu, gunakan WITHIN_WINDOW sebagai bagian dari klausul WHERE. Misalnya, untuk mengambil telemetri suhu dan kelembapan selama hari terakhir, gunakan kueri berikut:

{
  "query": "SELECT $id, $ts, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D)"
}

Nilai jendela waktu menggunakan format durasi ISO 8601. Tabel berikut ini mencakup beberapa contoh:

Perbandingan nilai

Anda bisa mendapatkan telemetri berdasarkan nilai tertentu. Misalnya, kueri berikut mengembalikan semua pesan di mana suhu lebih besar dari nol, tekanannya lebih besar dari 50, dan ID perangkat adalah salah satu dari sample-002 dan sample-003:

{
  "query": "SELECT $id, $ts, temperature AS t, pressure AS p FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D) AND t > 0 AND p > 50 AND $id IN ['sample-002', 'sample-003']"
}

Operator berikut didukung:

• Operator logis AND dan OR.
• Operator perbandingan =, !=, >, <, >=, <=, <>, dan IN.

Batasan berikut berlaku untuk klausul WHERE:

• Anda dapat menggunakan maksimal 10 operator dalam satu kueri.
• Dalam kueri, WHERE klausa hanya dapat berisi filter metadata telemetri dan perangkat.
• Dalam kueri, Anda bisa mengambil hingga 10.000 rekaman.

Agregasi dan GRUP BERDASARKAN klausul

Fungsi agregasi memungkinkan Anda menghitung nilai seperti rata-rata, maksimum, dan minimum pada data telemetri dalam jendela waktu. Misalnya, kueri berikut menghitung suhu dan kelembapan rata-rata dari perangkat sample-001 dalam jendela 10 menit:

{
  "query": "SELECT AVG(temperature), AVG(pressure) FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D) AND $id='{{DEVICE_ID}}' GROUP BY WINDOW(PT10M)"
}

Hasilnya terlihat seperti output berikut:

{
    "results": [
        {
            "$ts": "2021-09-14T11:40:00Z",
            "avg_temperature": 49.212146114456104,
            "avg_pressure": 48.590304135023764
        },
        {
            "$ts": "2021-09-14T11:30:00Z",
            "avg_temperature": 52.44844454703927,
            "avg_pressure": 52.25973211022142
        },
        {
            "$ts": "2021-09-14T11:20:00Z",
            "avg_temperature": 50.14626272506926,
            "avg_pressure": 48.98400386898757
        }
    ]
}

Fungsi agregasi berikut didukung: SUM, MAX, MIN, COUNT, AVG, FIRST, dan LAST.

Gunakan GROUP BY WINDOW untuk menentukan ukuran jendela. Jika Anda tidak menggunakan GROUP BY WINDOW, kueri mengagregasi telemetri selama 30 hari terakhir.

Klausul ORDER BY

Klausul ORDER BY memungkinkan Anda mengurutkan hasil kueri dengan nilai telemetri, tanda waktu, atau ID perangkat. Anda dapat mengurutkan dalam urutan naik atau turun. Misalnya, kueri berikut mengembalikan hasil terbaru terlebih dahulu:

{
  "query": "SELECT $id as ID, $ts as timestamp, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o ORDER BY timestamp DESC"
}

Batas

Batas saat ini untuk kueri adalah:

• Tidak lebih dari 15 item dalam daftar klausul SELECT.
• Tidak lebih dari 10 operasi logis dalam klausul WHERE tersebut.
• Panjang maksimum string kueri adalah 350 karakter.
• Anda tidak dapat menggunakan kartubebas (*) dalam daftar klausul SELECT.
• Kueri dapat mengambil hingga 10.000 rekaman.

Langkah berikutnya

Sekarang setelah Anda mempelajari cara meng-kueri perangkat dengan REST API, langkah berikutnya yang disarankan adalah Cara menggunakan REST API IoT Central untuk mengelola pengguna dan peran.