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

  • Makale

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

Not

Azure IoT SDK'ları büyük sonuçların sayfalamasını destekler.

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ı

Önemli

Sorgu sonuçları nihai tutarlı işlemlerdir ve 30 dakikaya kadar olan gecikmelere tolerans gösterilmelidir. Çoğu durumda, ikiz sorgusu sonuçları birkaç saniyelik sırayla döndürür. IoT Hub tüm işlemler için düşük gecikme süresi sağlamaya çalışır. Ancak, ağ koşulları ve diğer öngörülemeyen faktörler nedeniyle belirli bir gecikme süresini garanti edemez.

İ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.

Not

Bu işlemin en uzun gecikme süresiyle ilgili varsayımlarda bulunmaktan kaçının. Gecikme süresini dikkate alarak çözümünüzü oluşturma hakkında daha fazla bilgi için lütfen Gecikme Çözümleri'ne bakın.

Sonraki adımlar