Kueri untuk perangkat IoT Hub dan modul kembar

Artikel
03/18/2023

Device twins dan module twins dapat mengandung objek JSON arbitrer sebagai tag dan properti. IoT Hub memungkinkan Anda untuk meminta device twins dan module twins sebagai satu dokumen JSON yang berisi semua informasi kembar.

Berikut adalah contoh kembar perangkat hub IoT (modul kembar akan mirip hanya dengan parameter untuk moduleId):

{
    "deviceId": "myDeviceId",
    "etag": "AAAAAAAAAAc=",
    "status": "enabled",
    "statusUpdateTime": "0001-01-01T00:00:00",
    "connectionState": "Disconnected",
    "lastActivityTime": "0001-01-01T00:00:00",
    "cloudToDeviceMessageCount": 0,
    "authenticationType": "sas",
    "x509Thumbprint": {
        "primaryThumbprint": null,
        "secondaryThumbprint": null
    },
    "version": 2,
    "tags": {
        "location": {
            "region": "US",
            "plant": "Redmond43"
        }
    },
    "properties": {
        "desired": {
            "telemetryConfig": {
                "configId": "db00ebf5-eeeb-42be-86a1-458cccb69e57",
                "sendFrequencyInSecs": 300
            },
            "$metadata": {
            ...
            },
            "$version": 4
        },
        "reported": {
            "connectivity": {
                "type": "cellular"
            },
            "telemetryConfig": {
                "configId": "db00ebf5-eeeb-42be-86a1-458cccb69e57",
                "sendFrequencyInSecs": 300,
                "status": "Success"
            },
            "$metadata": {
            ...
            },
            "$version": 7
        }
    }
}

Kueri kembar perangkat

IoT Hub mengekspos perangkat kembar sebagai koleksi dokumen yang disebut perangkat. Misalnya, kueri yang paling mendasar mengambil seluruh set perangkat kembar:

SELECT * FROM devices

Catatan

Azure IoT SDKs mendukung hasil penomoran yang besar.

Anda bisa mengagregasi hasil kueri menggunakan klausa SELECT. Misalnya, kueri berikut mendapatkan hitungan jumlah total perangkat di hub IoT:

SELECT COUNT() as totalNumberOfDevices FROM devices

Memfilter hasil kueri menggunakan klausa WHERE. Misalnya, untuk menerima kembar perangkat di mana tag location.region diatur ke AS , gunakan kueri berikut:

SELECT * FROM devices
WHERE tags.location.region = 'US'

Buat klausa WHERE yang kompleks dengan menggunakan operator Boolean dan perbandingan aritmatika. Misalnya, kueri berikut mengambil kembar perangkat yang terletak di AS dan dikonfigurasi untuk mengirim telemetri kurang dari setiap menit:

SELECT * FROM devices
  WHERE tags.location.region = 'US'
    AND properties.reported.telemetryConfig.sendFrequencyInSecs >= 60

Anda juga dapat menggunakan konstanta array dengan operator IN dan NIN (tidak in). Misalnya, kueri berikut mengambil perangkat kembar yang melaporkan WiFi atau konektivitas kabel:

SELECT * FROM devices
  WHERE properties.reported.connectivity IN ['wired', 'wifi']

Seringkali perlu untuk mengidentifikasi semua kembar perangkat yang berisi properti tertentu. IoT Hub mendukung fungsi untuk is_defined() tujuan ini. Misalnya, kueri berikut mengambil kembar perangkat yang menentukan connectivity properti :

SELECT * FROM devices
  WHERE is_defined(properties.reported.connectivity)

Lihat bagian klausa WHERE untuk referensi lengkap kemampuan pemfilteran.

Pengelompokan juga didukung. Misalnya, kueri berikut mengembalikan jumlah perangkat dalam setiap status konfigurasi telemetri:

SELECT properties.reported.telemetryConfig.status AS status,
    COUNT() AS numberOfDevices
  FROM devices
  GROUP BY properties.reported.telemetryConfig.status

Kueri pengelompokan ini akan menjalankan hasil yang mirip dengan contoh berikut:

[
    {
        "numberOfDevices": 3,
        "status": "Success"
    },
    {
        "numberOfDevices": 2,
        "status": "Pending"
    },
    {
        "numberOfDevices": 1,
        "status": "Error"
    }
]

Dalam contoh ini, tiga perangkat melaporkan konfigurasi yang berhasil, dua masih menerapkan konfigurasi, dan satu melaporkan kesalahan.

Kueri proyeksi memungkinkan pengembang untuk menjalankan hanya properti yang mereka pedulikan. Misalnya, untuk mengambil waktu aktivitas terakhir bersama dengan ID perangkat dari semua perangkat yang diaktifkan yang terputus, gunakan kueri berikut:

SELECT DeviceId, LastActivityTime FROM devices WHERE status = 'enabled' AND connectionState = 'Disconnected'

Hasil kueri tersebut akan terlihat seperti contoh berikut:

[
  {
    "deviceId": "AZ3166Device",
    "lastActivityTime": "2021-05-07T00:50:38.0543092Z"
  }
]

Modul kueri kembar

Kueri pada modul kembar mirip dengan kueri pada perangkat kembar, tetapi menggunakan koleksi / namespace yang berbeda; alih-alih dari perangkat, Anda meminta dari devices.modules:

SELECT * FROM devices.modules

Kami tidak mengizinkan bergabung antara koleksi perangkat dan devices.modules. Jika Anda ingin mengkueri modul kembar di seluruh perangkat, Anda melakukannya berdasarkan tag. Kueri berikut mengembalikan semua modul kembar di semua perangkat dengan status pemindaian:

SELECT * FROM devices.modules WHERE properties.reported.status = 'scanning'

Kueri berikut mengembalikan semua modul kembar dengan status pemindaian, tetapi hanya pada subset perangkat yang ditentukan:

SELECT * FROM devices.modules
  WHERE properties.reported.status = 'scanning'
  AND deviceId IN ['device1', 'device2']

Batasan kueri kembar

Penting

Hasil kueri pada akhirnya adalah operasi yang konsisten dan penundaan hingga 30 menit harus ditoleransi. Dalam kebanyakan kasus, kueri kembar mengembalikan hasil dalam urutan beberapa detik. IoT Hub berusaha untuk memberikan latensi rendah untuk semua operasi. Namun, dikarenakan kondisi jaringan dan faktor lain yang tidak dapat diprediksi hal itu tidak dapat menjamin latensi tertentu.

Opsi alternatif untuk kueri kembar adalah mengkueri kembar perangkat individual berdasarkan ID dengan menggunakan REST API get twin. API ini selalu menjalankan nilai terbaru dan memiliki batas throttling yang lebih tinggi. Anda dapat mengeluarkan REST API secara langsung atau menggunakan fungsionalitas yang setara di salah satu SDK Layanan Azure IoT Hub.

Ekspresi kueri bisa memiliki panjang maksimum 8192 karakter.

Saat ini, perbandingan hanya didukung antara jenis primitif (tanpa objek), misalnya ... WHERE properties.desired.config = properties.reported.config hanya didukung jika properti tersebut memiliki nilai primitif.

Sebaiknya jangan mengambil dependensi pada lastActivityTime yang ditemukan di Properti Identitas Perangkat untuk Kueri Kembar untuk skenario apa pun. Bidang ini tidak menjamin pengukur status perangkat yang akurat. Sebagai gantinya, gunakan peristiwa Siklus Hidup Perangkat IoT untuk mengelola status dan aktivitas perangkat. Informasi selengkapnya tentang cara menggunakan peristiwa siklus hidup IoT Hub dalam solusi Anda, kunjungi React untuk IoT Hub peristiwa dengan menggunakan Event Grid untuk memicu tindakan.

Catatan

Hindari membuat asumsi tentang latensi maksimum operasi ini. Silakan lihat Solusi Latensi untuk informasi lebih lanjut tentang cara membangun solusi Anda dengan mempertimbangkan latensi.

Langkah berikutnya

Memahami dasar-dasar bahasa kueri IoT Hub

Bagikan melalui