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

IoT Hub, cihaz ikizleri, modül ikizleri, işler ve ileti yönlendirme ile ilgili bilgileri almak için güçlü bir SQL benzeri dil sağlar. Bu makale şunları sunar:

• IoT Hub sorgu dilinin temel özelliklerine giriş ve
• Dilin ayrıntılı açıklaması. İleti yönlendirme için sorgu dili hakkında ayrıntılı bilgi için bkz . İleti yönlendirmedeki sorgular.

Belirli örnekler için bkz . Cihaz ve modül ikizleri için sorgular veya İşler için sorgular.

IoT Hub sorguları çalıştırma

IoT hub'ınıza yönelik sorguları doğrudan Azure portalında çalıştırabilirsiniz.

1. Azure portalında oturum açın ve IoT hub'ınıza gidin.
2. Gezinti menüsünün Cihaz yönetimi bölümünden Sorgular'ı seçin.
3. Metin kutusuna sorgunuzu girin ve Sorguyu çalıştır'ı seçin.

Azure IoT hizmet SDK'larını ve hizmet API'lerini kullanarak uygulamalarınız içinde de sorgu çalıştırabilirsiniz.

Örneğin IoT Hub sorgularını uygulayan kod için Hizmet SDK'ları ile sorgu örnekleri bölümüne bakın.

SDK başvuru sayfalarının ve örneklerinin bağlantıları için bkz . Azure IoT SDK'ları.

IoT Hub sorgusunun temelleri

Her IoT Hub sorgusu, isteğe bağlı WHERE ve GROUP BY yan tümceleriyle SELECT ve FROM yan tümcelerinden oluşur.

Sorgular bir JSON belgeleri koleksiyonu üzerinde çalıştırılır, örneğin cihaz ikizleri. FROM yan tümcesi, üzerinde yinelenecek belge koleksiyonunu gösterir ( cihazlar, devices.modules veya devices.jobs).

Ardından WHERE yan tümcesindeki filtre uygulanır. Toplamalarda, bu adımın sonuçları GROUP BY yan tümcesinde belirtilen şekilde gruplandırılır. Her grup için SELECT yan tümcesinde belirtildiği gibi bir satır oluşturulur.

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

SELECT yan tümcesi

SELECT <select_list> yan tümcesi her IoT Hub sorgusunda gereklidir. Sorgudan alınan değerleri belirtir. Yeni JSON nesneleri oluşturmak için kullanılacak JSON değerlerini belirtir. FROM koleksiyonunun filtrelenmiş (ve isteğe bağlı olarak gruplandırılmış) 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.

Örneğin:

• Tüm değerleri döndür

  SELECT *
  

• Belirli özellikleri döndürme

  SELECT DeviceID, LastActivityTime
  

• Sayı döndürmek için sorgunun sonuçlarını toplama

  SELECT COUNT() as TotalNumber
  

Şu anda SELECT'ten farklı seçim yan tümceleri yalnızca cihaz ikizlerindeki toplama sorgularında desteklenmektedir.

Aşağıdaki söz dizimi, SELECT yan tümcesinin dil bilgisidir:

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.

FROM yan tümcesi

FROM <from_specification> yan tümcesi her ioT Hub sorgusunda gereklidir. Üç değerden biri olmalıdır:

• cihaz ikizlerini sorgulamak için cihazlar
• devices.modules to query module twins
• Cihaz başına iş ayrıntılarını sorgulamaya devices.jobs

Örneğin:

• Tüm cihaz ikizlerini alma

  SELECT * FROM devices
  

WHERE yan tümcesi

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

Örneğin:

• Belirli bir cihazı hedefleyen tüm işleri alma

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

İzin verilen koşullar ifadeler ve koşullar bölümünde açıklanmıştır.

GROUP BY yan tümcesi

GROUP BY <group_specification> yan tümcesi isteğe bağlıdır. Bu yan tümce WHERE yan tümcesinde belirtilen filtreden sonra ve SELECT'de belirtilen projeksiyondan önce yürütülür. Belgeleri bir özniteliğin değerine göre gruplandırıyor. Bu gruplar, SELECT yan tümcesinde belirtildiği gibi toplanmış değerler oluşturmak için kullanılır.

Örneğin:

• Her telemetri yapılandırma durumunu bildiren cihazların sayısını döndürme

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

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

GROUP BY için resmi söz dizimi şö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.

Sorgu sonuçları sayfalaması

Sorgu nesnesi, 100 kayıttan küçük veya buna eşit maksimum sayfa boyutuyla oluşturulur. Birden çok sayfa elde etmek için Node.js SDK'da nextAsTwin veya .Net SDK'da GetNextAsTwinAsync yöntemini birden çok kez çağırın. Sorgu nesnesi, sorgunun gerektirdiği seri durumdan çıkarma seçeneğine bağlı olarak birden çok Sonraki değeri kullanıma açabilir. Örneğin, bir sorgu nesnesi projeksiyonları kullanırken cihaz ikizi veya iş nesneleri ya da düz JSON döndürebilir.

İfadeler ve koşullar

Yüksek düzeyde bir ifade:

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

Koşullar , Boole değeri veren ifadelerdir. Boolean true değerinden 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 şöyledir:

<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 dizimindeki her simgenin ne anlama gelir anlamak için aşağıdaki tabloya bakın:

İşleçler

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

İşlevler

İkizleri ve işleri sorgularken desteklenen tek işlev:

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

Rota koşullarında aşağıdaki tür denetimi ve atama işlevleri desteklenir:

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

Hizmet SDK'ları ile sorgu örnekleri

C# örneği

Sorgu işlevi, RegistryManager sınıfında C# hizmet SDK'sı tarafından kullanıma sunulur.

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

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, sorgu sonuçları sayfalandırma bölümünde belirtilen parametrelerle oluşturulur. GetNextAsTwinAsync yöntemleri birden çok kez çağrılarak birden çok sayfa alınır.

Node.js örnek

Sorgu işlevi, Kayıt Defteri nesnesindeki Node.js için Azure IoT hizmet SDK'sı tarafından kullanıma sunulur.

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

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, sorgu sonuçları sayfalandırma bölümünde belirtilen parametrelerle oluşturulur. nextAsTwin yöntemi birden çok kez çağrılarak birden çok sayfa alınır.

Sonraki adımlar

• IoT Hub ileti yönlendirme sorgusu söz dizimi ile ileti özelliklerine veya ileti gövdesine göre iletileri yönlendirme hakkında bilgi edinin.
• Cihaz ve modül ikizleri için sorgular veya İşler için sorgular ile ilgili belirli örnekleri alın.