Cihaz ve modül ikizleri, işler ve mesaj yönlendirmesi için IoT Hub sorgu dili

IoT Hub, cihaz TWINS, Modül TWINS, işlerve ileti yönlendirmeile ilgili bilgileri almak için güçlü bir SQL benzeri dil sağlar. Bu makalede şunları sunulmaktadır:

  • IoT Hub sorgu dilinin ana özelliklerine giriş ve
  • Dilin ayrıntılı açıklaması. İleti yönlendirme için sorgu dili hakkındaki ayrıntılar için bkz. ileti yönlendirmesinde sorgular.

Not

Bu makalede bahsedilen, buluttan cihaza mesajlaşma, cihaz iksi ve cihaz yönetimi gibi özelliklerden bazıları yalnızca standart IoT Hub standart katmanında kullanılabilir. Temel ve standart IoT Hub katmanları hakkında daha fazla bilgi için bkz. Doğru IoT Hub katmanını seçme.

Cihaz ve modül ikizi sorguları

Cihaz TWINS ve Modül TWINS , hem Etiketler hem de özellikler olarak rastgele JSON nesneleri içerebilir. IoT Hub, tüm ikizi bilgilerini içeren tek bir JSON belgesi olarak Device TWINS ve modül TWINS 'i sorgulamanızı sağlar.

Örneğin, IoT Hub cihazlarınızın aşağıdaki yapıya sahip olduğunu varsayın (modül ikizi, yalnızca ek bir ModuleID ile benzerdir):

{
    "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 TWINS 'i cihazlar adlı bir belge koleksiyonu olarak kullanıma sunar. Örneğin, aşağıdaki sorgu tüm cihaz TWINS kümesini alır:

SELECT * FROM devices

Not

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

IoT Hub, rastgele koşullara göre cihaz ikizlerini filtrelemesini almanızı sağlar. Örneğin, Location. Region etiketinin US olarak ayarlandığı cihaz TWINS 'i almak için aşağıdaki sorguyu kullanın:

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

Boole işleçleri ve aritmetik karşılaştırmalar de desteklenir. Örneğin, ABD 'de bulunan ve her dakikadan daha az telemetri gönderecek şekilde yapılandırılmış cihaz ikizlerini almak için aşağıdaki sorguyu kullanın:

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

Bir kolaylık olması halinde, dizi sabitlerini de ın ve ın (Not ın) işleçleriyle kullanmak da mümkündür. Örneğin, WiFi veya kablolu bağlantı rapor eden cihaz ikizlerini almak için aşağıdaki sorguyu kullanın:

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 işlevi bu is_defined() amaçla destekler. Örneğin, özelliğini tanımlayan cihaz ikizlerini connectivity almak için aşağıdaki sorguyu kullanın:

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

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

Gruplama ve toplamalar da de destekler. Örneğin, her telemetri yapılandırma durumundaki cihaz sayısını bulmak için aşağıdaki sorguyu kullanın:

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

Bu gruplama sorgusu, aşağıdaki örnektekine benzer bir sonuç elde etmek için:

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

Bu örnekte, üç cihaz başarılı yapılandırma bildirdi, ikisi hala yapılandırmayı uyguluyor ve biri hata bildirdi.

Projeksiyon sorguları, geliştiricilerin yalnızca önemle önemleri olan özellikleri geri vermesine olanak sağlar. Örneğin, bağlantısı kesilmiş tüm etkinleştirilmiş cihazların cihaz kimliğiyle birlikte son etkinlik zamanı almak için aşağıdaki sorguyu kullanın:

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

Sorgu Gezgini'nde bir sorgu için bu sorgunun örnek bir sorgu sonucu IoT Hub:

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

Modül ikizi sorguları

Modül ikizlerini sorgulamak, cihaz ikizlerini sorgulamaya benzer ancak farklı bir koleksiyon/ad alanı kullanır; yerine cihazlarından, devices.modules'dan sorgularsiniz:

SELECT * FROM devices.modules

Cihazlar ve devices.modules koleksiyonları arasında birleştirmeye izin vermiyoruz. Modül ikizlerini cihazlar arasında sorgulamak için etiketlere göre sorgularsiniz. Bu sorgu, tarama durumuna sahip tüm cihazlardaki tüm modül ikizlerini iade eder:

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

Bu sorgu tarama durumuna sahip tüm modül ikizlerini ancak yalnızca belirtilen cihaz alt kümesinde geri döner:

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

C# örneği

Sorgu işlevi RegistryManager sınıfındaki C# hizmeti SDK'sı tarafından ortaya çıkar.

Basit bir sorgu örneği aşağıda verilmiştir:

var query = registryManager.CreateQuery("SELECT * FROM devices", 100);
while (query.HasMoreResults)
{
    var page = await query.GetNextAsTwinAsync();
    foreach (var twin in page)
    {
        // do work on twin object
    }
}

Sorgu nesnesi, bir sayfa boyutu (100 'e kadar) ile oluşturulur. Daha sonra, Getnextastwınasync yöntemleri birden çok kez çağırarak birden çok sayfa alınır.

Sorgu nesnesi, sorgu için gereken seri kaldırma seçeneğine bağlı olarak birden çok sonraki değeri kullanıma sunar. Örneğin, cihaz ikizi veya iş nesneleri ya da projeksiyonlar kullanılırken düz JSON.

Node.js örneği

Sorgu işlevselliği, kayıt defteri nesnesindeki Node.jsiçin Azure IoT hizmeti SDK 'sı tarafından sunulur.

Basit bir sorgu örneği aşağıda verilmiştir:

var query = registry.createQuery('SELECT * FROM devices', 100);
var onResults = function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        // Do something with the results
        results.forEach(function(twin) {
            console.log(twin.deviceId);
        });

        if (query.hasMoreResults) {
            query.nextAsTwin(onResults);
        }
    }
};
query.nextAsTwin(onResults);

Sorgu nesnesi, bir sayfa boyutu (100 'e kadar) ile oluşturulur. Ardından, Nextastwin yöntemi birden çok kez çağırarak birden çok sayfa alınır.

Sorgu nesnesi, sorgu için gereken seri kaldırma seçeneğine bağlı olarak birden çok sonraki değeri kullanıma sunar. Örneğin, cihaz ikizi veya iş nesneleri ya da projeksiyonlar kullanılırken düz JSON.

Sınırlamalar

Önemli

Sorgu sonuçları, cihaz iksındaki en son değerlere göre birkaç dakikalık gecikmeye neden olabilir. Bağımsız cihaz TWINS 'i KIMLIĞE göre sorgularken Get ikizi REST APIkullanın. Bu API her zaman en son değerleri döndürür ve daha yüksek azaltma sınırlarına sahiptir. REST API doğrudan verebilir veya Azure IoT Hub hizmeti SDK'larından birindeki denk işlevselliği kullanabilirsiniz.

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

İşleri sorgular ile çalışmaya başlama

İşler , cihaz kümelerinde işlemleri yürütmek için bir yol sağlar. Her cihaz ikizi, işler adlı bir koleksiyonda yer aldığı işlerin bilgilerini içerir.

{
    "deviceId": "myDeviceId",
    "etag": "AAAAAAAAAAc=",
    "tags": {
        ...
    },
    "properties": {
        ...
    },
    "jobs": [
        {
            "deviceId": "myDeviceId",
            "jobId": "myJobId",
            "jobType": "scheduleTwinUpdate",
            "status": "completed",
            "startTimeUtc": "2016-09-29T18:18:52.7418462",
            "endTimeUtc": "2016-09-29T18:20:52.7418462",
            "createdDateTimeUtc": "2016-09-29T18:18:56.7787107Z",
            "lastUpdatedDateTimeUtc": "2016-09-29T18:18:56.8894408Z",
            "outcome": {
                "deviceMethodResponse": null
            }
        },
        ...
    ]
}

Şu anda bu koleksiyon, devices.jobs dilindeki IoT Hub sorgulanabilir.

Önemli

Şu anda, cihaz ikizleri sorgu edilirken jobs özelliği hiçbir zaman döndürülz. Başka bir ifadeyle , 'FROM devices' içeren sorgular. jobs özelliğine yalnızca kullanılarak sorgularla doğrudan FROM devices.jobs erişilebilir.

Örneğin, tek bir cihazı etkileyen tüm işleri (geçmiş ve zamanlanmış) almak için aşağıdaki sorguyu kullanabilirsiniz:

SELECT * FROM devices.jobs
  WHERE devices.jobs.deviceId = 'myDeviceId'

Bu sorgunun döndürülen her işin cihaza özgü durumunu (ve muhtemelen doğrudan yöntem yanıtını) sağladığına dikkat edin.

Bu koleksiyonda tüm nesne özelliklerinde rastgele Boole koşullarıyla filtrelemek de devices.jobs mümkündür.

Örneğin, Belirli bir cihaz için Eylül 2016'dan sonra oluşturulan tüm tamamlanmış cihaz ikizi güncelleştirme işlerini almak için aşağıdaki sorguyu kullanın:

SELECT * FROM devices.jobs
  WHERE devices.jobs.deviceId = 'myDeviceId'
    AND devices.jobs.jobType = 'scheduleTwinUpdate'
    AND devices.jobs.status = 'completed'
    AND devices.jobs.createdTimeUtc > '2016-09-01'

Ayrıca tek bir işin cihaz başına sonuçlarını da elde edebilirsiniz.

SELECT * FROM devices.jobs
  WHERE devices.jobs.jobId = 'myJobId'

Sınırlamalar

Şu anda, devices.jobs sorgular şunları desteklemez:

  • Bu nedenle projeksiyonlar SELECT * yalnızca mümkündür.
  • İş özelliklerine ek olarak cihaz ikizi ile ilgili koşullar (önceki bölüme bakın).
  • Sayı, ort, group by gibi toplamalar gerçekleştirme.

IoT Hub sorgusunun temelleri

Her IoT Hub, isteğe bağlı WHERE ve GROUP BY yan tümceleri ile SELECT ve FROM yan tümcelerinden oluşur. Her sorgu, cihaz ikizleri gibi bir JSON belgeleri koleksiyonunda çalıştır. FROM yan tümcesi üzerinde (cihazlar, devices.modules veya devices.jobs ). Ardından WHERE yan tümcesinde yer alan filtre uygulanır. Toplamalarla, bu adımın sonuçları GROUP BY yan tümcesinde belirtilen şekilde gruplandı. Her grup için SELECT yan tümcesinde belirtilen şekilde bir satır oluşturulur.

SELECT <select_list>
  FROM <from_specification>
  [WHERE <filter_condition>]
  [GROUP BY <group_specification>]

FROM yan tümcesi

FROM <from_specification> yan tümcesi yalnızca üç değeri kabul edebilir: cihazlardan cihaz ikizlerini sorgular . modüller, modülleri sorgulamak için veya Devices.Jobs 'den sorgu işi-cihaz başına ayrıntılar.

WHERE yan tümcesi

Where <filter_condition> yan tümcesi isteğe bağlıdır. Bu, FROM koleksiyonundaki JSON belgelerinin sonucun bir parçası olarak dahil edilmesini sağlamak için karşılaması gereken bir veya daha fazla koşulu belirtir. Herhangi bir JSON belgesi, sonuca eklenmek için belirtilen koşulları "true" olarak değerlendirmelidir.

İzin verilen koşullar, bölüm ifadelerinde ve koşullarındaaçıklanmıştır.

SELECT yan tümcesi

SELECT <select_list> zorunludur ve sorgudan alınan değerleri belirtir. Yeni JSON nesneleri oluşturmak için kullanılacak JSON değerlerini belirtir. IÇINDEKI koleksiyonun filtrelenmiş (ve isteğe bağlı olarak gruplanmış) alt kümesinin her öğesi için, projeksiyon aşaması yeni bir JSON nesnesi oluşturur. Bu nesne SELECT yan tümcesinde belirtilen değerlerle oluşturulur.

SELECT yan tümcesinin dilbilgisini aşağıda verilmiştir:

SELECT [TOP <max number>] <projection list>

<projection_list> ::=
    '*'
    | <projection_element> AS alias [, <projection_element> AS alias]+

<projection_element> :==
    attribute_name
    | <projection_element> '.' attribute_name
    | <aggregate>

<aggregate> :==
    count()
    | avg(<projection_element>)
    | sum(<projection_element>)
    | min(<projection_element>)
    | max(<projection_element>)

Attribute_name , from koleksiyonundaki JSON belgesinin herhangi bir özelliğine başvurur. SELECT yan tümcelerinin bazı örnekleri, Device ikizi sorguları ile çalışmaya başlama bölümünde bulunabilir.

Şu anda, Select* öğesinden farklı seçim yan tümceleri yalnızca cihaz ikslarındaki toplu sorgularda desteklenir.

GROUP BY yan tümcesi

GROUP BY <group_specification> yan tümcesi WHERE yan tümcesinde belirtilen filtreden sonra ve Select içinde belirtilen projeksiyon öncesinde yürütülen isteğe bağlı bir adımdır. Bir özniteliğin değerine göre belgeleri gruplandırır. Bu gruplar, SELECT yan tümcesinde belirtilen şekilde toplanmış değerler oluşturmak için kullanılır.

GROUP BY kullanan bir sorgu örneği:

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

GROUP BY için biçimsel sözdizimi şöyledir:

GROUP BY <group_by_element>
<group_by_element> :==
    attribute_name
    | < group_by_element > '.' attribute_name

Attribute_name , from koleksiyonundaki JSON belgesinin herhangi bir özelliğine başvurur.

Şu anda GROUP BY yan tümcesi yalnızca cihaz ikizleri sorgulanırken desteklenir.

Önemli

Bu terim group şu anda sorgularda özel anahtar sözcük olarak kabul edilir. Özellik adınız olarak kullanıyorsanız, hatalardan kaçınmak için köşeli ayraçla çevrelenin, group örneğin, SELECT * FROM devices WHERE tags.[[group]].name = 'some_value' .

İfadeler ve koşullar

Yüksek düzeyde bir ifade:

  • Bir JSON türünün (Boole, sayı, dize, dizi veya nesne gibi) bir örneğini değerlendirir.
  • Yerleşik işleçler ve işlevler kullanılarak cihaz JSON belgelerinden gelen veriler ve sabitler kullanılarak tanımlanır.

Koşullar, Boole olarak değerlendirilen ifadelerdir. Boole true'dan farklı sabitler false olarak kabul edilir. Bu kural null, tanımsız, herhangi bir nesne veya dizi örneği, herhangi bir dize ve Boole false içerir.

İfadelerin söz dizimi şu şekildedir:

<expression> ::=
    <constant> |
    attribute_name |
    <function_call> |
    <expression> binary_operator <expression> |
    <create_array_expression> |
    '(' <expression> ')'

<function_call> ::=
    <function_name> '(' expression ')'

<constant> ::=
    <undefined_constant>
    | <null_constant>
    | <number_constant>
    | <string_constant>
    | <array_constant>

<undefined_constant> ::= undefined
<null_constant> ::= null
<number_constant> ::= decimal_literal | hexadecimal_literal
<string_constant> ::= string_literal
<array_constant> ::= '[' <constant> [, <constant>]+ ']'

İfade söz dizimlerinde her sembolün ne anlama olduğunu anlamak için aşağıdaki tabloya bakın:

Sembol Tanım
Öznitelik_adý FROM koleksiyonunda JSON belgesinin herhangi bir özelliği.
binary_operator İşleçler bölümünde listelenen herhangi bir ikili işleç.
function_name İşlevler bölümünde listelenen herhangi bir işlev.
decimal_literal Ondalık değerle ifade edildi bir float.
hexadecimal_literal ' 0x ' dizesinin ardından onaltılık basamak dizesi tarafından ifade edilen bir sayı.
string_literal Dize sabit değerleri, sıfır veya daha fazla Unicode karakter ya da kaçış dizileri tarafından temsil edilen Unicode dizeleridir. Dize sabit değerleri tek tırnak veya çift tırnak içine alınır. İzin verilen kaçış:,,, \' \" \\ \uXXXX 4 onaltılık basamakla tanımlanan Unicode karakterler için.

İşleçler

Aşağıdaki işleçler desteklenir:

Family (Aile) İşleçler
Aritmetik +, -, *, /, %
Mantıksal VE, VEYA DEĞIL
Karşılaştırma =, !=, <, >, <=, >=, <>

İşlevler

TWINS ve işleri sorgularken yalnızca desteklenen işlev şunlardır:

İşlev Açıklama
IS_DEFINED (özellik) Özelliğin bir değer atandığını (dahil) belirten bir Boole değeri döndürür null .

Rotalar koşullarında aşağıdaki matematik işlevleri desteklenir:

İşlev Açıklama
ABS (x) Belirtilen sayısal ifadenin mutlak (pozitif) değerini döndürür.
EXP (x) Belirtilen sayısal ifadenin üstel değerini döndürür (e ^ x).
Güç (x, y) Belirtilen bir ifadenin belirtilen kuvvetinin değerini döndürür (x ^ y).
KARE (x) Belirtilen sayısal değerin karesini döndürür.
TAVAN (x) Belirtilen sayısal ifadeden büyük veya eşittir olan en küçük tamsayı değerini döndürür.
FLOOR(x) Belirtilen sayısal ifadeye eşit veya daha küçük olan en büyük tamsayıyı döndürür.
SIGN(x) Belirtilen sayısal ifadenin pozitif (+1), sıfır (0) veya negatif (-1) işaretlerini döndürür.
SQRT(x) Belirtilen sayısal değerin karekökünü döndürür.

Yol koşullarında, aşağıdaki tür denetimi ve tür atama işlevleri de desteklemektedir:

İşlev Açıklama
AS_NUMBER Giriş dizesini bir sayıya dönüştürür. noop giriş bir sayı ise; Undefined dize bir s sayı temsil etmiyorsa.
IS_ARRAY Belirtilen ifadenin türünün bir dizi olup olmadığını belirten bir Boole değeri döndürür.
IS_BOOL Belirtilen ifadenin türünün Boole olup olmadığını belirten bir Boole değeri döndürür.
IS_DEFINED Özelliğin bir değer atanarak atanmamış olduğunu belirten bir Boole döndürür. Bu yalnızca değer ilkel bir tür olduğunda de destekler. İlkel türler dize, Boole, sayısal veya null içerir. DateTime, nesne türleri ve diziler desteklenmiyor.
IS_NULL Belirtilen ifadenin türünün null olup olmadığını belirten bir Boole değeri döndürür.
IS_NUMBER Belirtilen ifadenin türünün bir sayı olup olmadığını belirten bir Boole değeri döndürür.
IS_OBJECT Belirtilen ifadenin türünün bir JSON nesnesi olup olmadığını belirten bir Boole değeri döndürür.
IS_PRIMITIVE Belirtilen ifadenin türünün bir ilkel öğe (dize, Boolean, sayısal veya) olduğunu gösteren bir Boole değeri döndürür null .
IS_STRING Belirtilen ifadenin türünün bir dize olup olmadığını gösteren bir Boole değeri döndürür.

Yollar koşullarında aşağıdaki dize işlevleri desteklenir:

İşlev Açıklama
CONCAT (x, y,...) İki veya daha fazla dize değerinin bitişinin sonucu olan bir dize döndürür.
Uzunluk (x) Belirtilen dize ifadesinin karakter sayısını döndürür.
DAHA düşük (x) Büyük harfli karakter verilerini küçük harfe dönüştürdükten sonra bir dize ifadesi döndürür.
UPPER (x) Küçük harfli karakter verilerini büyük harfe dönüştürdükten sonra bir dize ifadesi döndürür.
Alt DIZE (dize, başlangıç [, uzunluk]) Belirtilen karakter sıfır tabanlı konumdan başlayarak bir dize ifadesinin parçasını döndürür ve belirtilen uzunluğa veya dizenin sonuna kadar devam eder.
INDEX_OF (dize, parça) İlk belirtilen dize ifadesinde ikinci dize ifadesinin ilk örneğinin başlangıç konumunu döndürür veya dize bulunamazsa-1.
STARTS_WITH (x, y) İlk dize ifadesinin ikinciyle başlatılıp başlatılmayacağını gösteren bir Boole değeri döndürür.
ENDS_WITH (x, y) İlk dize ifadesinin ikinciyle sonlanıp bitmediğini gösteren bir Boole değeri döndürür.
IÇERIR (x, y) İlk dize ifadesinin ikincisini içerdiğini belirten bir Boole döndürür.

Sonraki adımlar

Azure IoT SDK'larını kullanarak uygulamalarınıza sorgu yürütmeyi öğrenin.