Aracılığıyla paylaş

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 ikiz 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

Uyarı

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 bir dakikadan daha sık aralıklarla telemetri gönderecek şekilde yapılandırılmış cihaz ikizlerini getirir.

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

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

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 is_defined() işlevini destekler. Örneğin, aşağıdaki sorgu connectivity özelliğini içeren cihaz ikizlerini getirir.

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

Filtreleme özelliklerinin tam referansı için WHERE koşulu 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 yerinedevices.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ın alternatif bir seçeneği, get twin REST API'sini kullanarak tek tek cihaz ikizlerini kimlikle sorgulamaktır. Bu API her zaman en son değerleri döndürür ve hız sınırlamaları daha yüksektir. REST API'yi doğrudan verebilir veya Azure IoT Hub Hizmeti 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 bir bağımlılığı lastActivityTime 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 IoT Hub olaylarına tepki verme bölümünü ziyaret edin.

Uyarı

Bu işlemin en yüksek 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

  • Last updated on