IoT Hub cihaz ve modül ikizleri için sorgular

Cihaz ikizleri ve modül ikizleri hem etiketler hem de özellikler olarak rastgele JSON nesneleri içerebilir. IoT Hub, cihaz ikizlerini ve modül ikizlerini tüm ikiz bilgilerini içeren tek bir JSON belgesi olarak sorgulamanızı sağlar.

Aşağıda örnek bir IoT hub cihaz ikizi verilmiştir (modül ikizi yalnızca moduleId parametresiyle benzer olacaktır):

{
    "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
        }
    }
}

Cihaz ikizi sorguları

IoT Hub cihaz ikizlerini cihazlar adlı bir belge koleksiyonu olarak kullanıma sunar. Örneğin, en temel sorgu cihaz ikizleri kümesinin tamamını alır:

SELECT * FROM devices

SELECT yan tümcesini kullanarak bir sorgunun sonuçlarını toplayabilirsiniz. Örneğin, aşağıdaki sorgu ioT hub'ında toplam cihaz sayısını alır:

SELECT COUNT() as totalNumberOfDevices FROM devices

WHERE yan tümcesini kullanarak sorgu sonuçlarını filtreleyin. Örneğin, location.region etiketinin ABD olarak ayarlandığı cihaz ikizlerini almak için aşağıdaki sorguyu kullanın:

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

Boole işleçlerini ve aritmetik karşılaştırmaları kullanarak karmaşık WHERE yan tümceleri oluşturun. Örneğin, aşağıdaki sorgu ABD'de bulunan ve her dakikadan daha az telemetri gönderecek şekilde yapılandırılmış cihaz ikizlerini alır:

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

Dizi sabitlerini IN ve NIN (in değil) işleçleriyle de kullanabilirsiniz. Örneğin, aşağıdaki sorgu WiFi veya kablolu bağlantıyı bildiren cihaz ikizlerini alır:

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

Genellikle belirli bir özelliği içeren tüm cihaz ikizlerini tanımlamak gerekir. IoT Hub bu amaçla işlevi is_defined() destekler. Örneğin, aşağıdaki sorgu özelliğini tanımlayan connectivity cihaz ikizlerini alır:

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

Filtreleme özelliklerinin tam başvurusu için WHERE yan tümcesi bölümüne bakın.

Gruplandırma da desteklenir. Örneğin, aşağıdaki sorgu her telemetri yapılandırması durumundaki cihazların sayısını döndürür:

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

Bu gruplandırma sorgusu aşağıdaki örneğe benzer bir sonuç döndürür:

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

Bu örnekte üç cihaz yapılandırmanın başarılı olduğunu bildirdi, ikisi yapılandırmayı uygulamaya devam ediyor ve biri hata bildirdi.

Projeksiyon sorguları, geliştiricilerin yalnızca önem verdikleri özellikleri döndürmesine olanak sağlar. Örneğin, bağlantısı kesilmiş tüm etkin cihazların cihaz kimliğiyle birlikte son etkinlik zamanını almak için aşağıdaki sorguyu kullanın:

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

Bu sorgunun sonucu aşağıdaki örneğe benzer olacaktır:

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

Modül ikizi sorguları

Modül ikizlerinde sorgulama, cihaz ikizlerinde sorgulamaya benzer, ancak farklı bir koleksiyon/ad alanı kullanılır; cihazlar yerine devices.modules'den sorgularsınız:

SELECT * FROM devices.modules

cihazlar ve devices.modules koleksiyonları arasında birleştirmeye izin vermiyoruz. Modül ikizlerini cihazlar arasında sorgulamak istiyorsanız, bunu etiketlere göre yaparsınız. Aşağıdaki sorgu, tarama durumuna sahip tüm cihazlardaki tüm modül ikizlerini döndürür:

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

Aşağıdaki sorgu, tarama durumuna sahip tüm modül ikizlerini ancak yalnızca belirtilen cihaz alt kümesinde döndürür:

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

İkiz sorgu sınırlamaları

İkiz sorguların alternatif bir seçeneği, get twin REST API'sini kullanarak tek tek cihaz ikizlerini kimliklerine göre sorgulamaktır. Bu API her zaman en son değerleri döndürür ve azaltma sınırları daha yüksektir. REST API'yi doğrudan verebilir veya Azure IoT Hub Hizmet SDK'larından birinde eşdeğer işlevselliği kullanabilirsiniz.

Sorgu ifadelerinin uzunluğu en fazla 8192 karakter olabilir.

Şu anda karşılaştırmalar yalnızca ilkel türler (nesne olmadan) arasında desteklenir; örneğin ... WHERE properties.desired.config = properties.reported.config , yalnızca bu özelliklerin temel değerleri varsa desteklenir.

Herhangi bir senaryo için İkiz Sorguları için Cihaz Kimliği Özellikleri'nde bulunan lastActivityTime bağımlılığını almamanızı öneririz. Bu alan, cihaz durumunun doğru bir göstergesini garanti etmez. Bunun yerine lütfen cihaz durumunu ve etkinliklerini yönetmek için IoT Cihaz Yaşam Döngüsü olaylarını kullanın. Çözümünüzde IoT Hub Yaşam Döngüsü olaylarını kullanma hakkında daha fazla bilgi için lütfen event grid kullanarak eylemleri tetikleyerek olayları IoT Hub için React adresini ziyaret edin.

Sonraki adımlar

• IoT Hub sorgu dilinin temellerini anlama