Aracılığıyla paylaş

IoT Hub query language for device and module twins, jobs, and message routing

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ı. For more information about query language for message routing, see IoT Hub message routing query syntax.

For specific examples, see Queries for IoT Hub device and module twins or Queries for IoT Hub jobs.

Note

Buluttan cihaza mesajlaşma, cihaz ikizleri ve cihaz yönetimi gibi bu makalede bahsedilen özelliklerden bazıları yalnızca IoT Hub'ın standart katmanında kullanılabilir. Temel ve standart/ücretsiz IoT Hub katmanları hakkında daha fazla bilgi için bkz. çözüm için doğru IoT Hub katmanını ve boyutunu seçme.

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.

For links to SDK reference pages and samples, see Azure IoT Hub SDKs.

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. The FROM clause indicates the document collection to be iterated on (either devices, devices.modules, or 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 ifadesi

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 clause

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

  • devices to query device twins
  • devices.modules to query module twins
  • devices.jobs'u cihaz başına iş ayrıntılarını sorgulamak için kullanın.

Örneğin:

  • Tüm cihaz ikizlerini alma

    SELECT * FROM devices

WHERE clause

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'

The allowed conditions are described in the Expressions and conditions section.

GROUP BY clause

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.

Dikkat

Terim group şu anda sorgularda özel bir anahtar sözcük olarak ele alınmakta. In case, you use group as your property name, consider surrounding it with double brackets to avoid errors, as shown in this example: SELECT * FROM devices WHERE tags.[[group]].name = 'some_value'.

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. To obtain multiple pages, call the nextAsTwin on Node.js SDK or GetNextAsTwinAsync on .NET SDK method multiple times. 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 nesneleri, görev nesneleri veya 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.
  • Is defined by manipulating data coming from the device JSON document and constants using built-in operators and functions.

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:

Symbol Tanım
özellik_adı FROM koleksiyonundaki 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 A float expressed in decimal notation.
hexadecimal_literal '0x' dizesiyle ve ardından onaltılık basamak dizesiyle ifade edilen bir sayı.
string_literal Sıfır veya daha fazla Unicode karakteri veya kaçış dizisiyle temsil edilen Unicode dizeleri. String literals are enclosed in single quotes or double quotes. Allowed escapes: \', \", \\, \uXXXX for Unicode characters defined by four hexadecimal digits.

Operatörler

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

Aile Operatörler
Aritmetik +, -, *, /, %
Mantıksal VE VEYA DEĞİl
Karşılaştırma =, !=, <, >, <=, >=, <>

İşlevler

When querying twins and jobs the only supported function is:

İşlev Açıklama
IS_DEFINED(property) Returns a Boolean indicating if the property is assigned a value (including null).

Rota 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 (e^x) üstel değerini döndürür.
POWER(x,y) Belirtilen ifadenin değerini belirtilen güce (x^y) döndürür.
SQUARE(x) Belirtilen sayısal değerin karesini döndürür.
CEILING(x) Belirtilen sayısal ifadeden büyük veya buna eşit en küçük tamsayı değerini döndürür.
FLOOR(x) Belirtilen sayısal ifadeden küçük veya buna eşit 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şaretini döndürür.
SQRT(x) Belirtilen sayısal değerin karekökünü döndürür.

In routes conditions, the following type checking and casting functions are supported:

İşlev Açıklama
AS_NUMBER Giriş dizesini sayıya dönüştürür. noop giriş bir sayıysa; Undefined dize bir sayıyı 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 değeri olup olmadığını belirten bir Boole değeri döndürür.
IS_DEFINED Returns a Boolean indicating if the property is a value. Bu işlev yalnızca değer ilkel bir tür olduğunda desteklenir. İlkel türler dize, Boole, sayısal veya null'dır. DateTime, object types, and arrays aren't supported.
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 ilkel (dize, Boole, sayısal veya null) olup olmadığını belirten bir Boole değeri döndürür.
IS_STRING Belirtilen ifadenin türünün bir dize olup olmadığını belirten bir Boole değeri döndürür.

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

İşlev Açıklama
CONCAT(x, y, …) İki veya daha fazla dize değerini birleştirmenin sonucu olan bir dize döndürür.
UZUNLUK(x) Belirtilen dize ifadesinin karakter sayısını döndürür.
LOWER(x) Büyük harf karakter verilerini küçük harfe dönüştürdükten sonra bir dize ifadesi döndürür.
UPPER(x) Küçük harf karakter verilerini büyük harfe dönüştürdükten sonra bir dize ifadesi döndürür.
SUBSTRING(string, start [, length]) Belirtilen karakter sıfır tabanlı konumdan başlayarak dize ifadesinin bir bölümünü döndürür ve belirtilen uzunluğa veya dizenin sonuna kadar devam eder.
INDEX_OF(string, fragment) belirtilen ilk dize ifadesinde ikinci dize ifadesinin ilk oluşumunun başlangıç konumunu veya dize bulunamazsa -1 döndürür.
STARTS_WITH(x, y) İlk dize ifadesinin ikincisiyle başlayıp başlamadığını gösteren bir Boole döndürür.
ENDS_WITH(x, y) İlk dize ifadesinin ikincisiyle bitip bitmediğini belirten bir Boole döndürür.
CONTAINS(x,y) İlk dize ifadesinin ikincisini içerip içermediğini belirten bir Boole döndürür.

Hizmet SDK'ları ile sorgu örnekleri

C# örneği

The query functionality is exposed by the Azure IoT Hub service SDK for .NET in the RegistryManager class.

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

The query object is instantiated with the parameters mentioned in the Query results pagination section. Multiple pages are retrieved by calling the GetNextAsTwinAsync methods multiple times.

Node.js örnek

The query functionality is exposed by the Azure IoT Hub service SDK for Node.js in the Registry object.

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);

The query object is instantiated with the parameters mentioned in the Query results pagination section. nextAsTwin yöntemi birden çok kez çağrılarak birden çok sayfa elde edilir.

Sonraki adımlar