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.
Not
Bu makalede bahsedilen buluttan cihaza mesajlaşma, cihaz ikizleri ve cihaz yönetimi gibi bazı özellikler yalnızca standart IoT Hub katmanında kullanılabilir. Temel ve standart/ücretsiz IoT Hub katmanları hakkında daha fazla bilgi için bkz. Çözümünüz için doğru IoT Hub katmanı seçme.
IoT Hub sorguları çalıştırma
IoT hub'ınıza yönelik sorguları doğrudan Azure portal çalıştırabilirsiniz.
- Azure portal oturum açın ve IoT hub'ınıza gidin.
- Gezinti menüsünün Cihaz yönetimibölümünden Sorgular'ı seçin.
- Metin kutusuna sorgunuzu girin ve Sorguyu çalıştır'ı seçin.
Ayrıca Azure IoT hizmeti SDK'larını ve hizmet API'lerini kullanarak uygulamalarınızda sorgu çalıştırabilirsiniz.
Örneğin IoT Hub sorguları uygulayan kodlar 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, cihaz ikizleri gibi bir JSON belgeleri koleksiyonu üzerinde çalıştırılır. FROM yan tümcesi, belge koleksiyonunun üzerinde yinelenecek olduğunu 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 belirtildiği gibi 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.
Örnek:
Tüm değerleri döndür
SELECT *
Belirli özellikleri döndürme
SELECT DeviceID, LastActivityTime
Sayıyı 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
- modül ikizlerini sorgulamak için devices.modules
- Cihaz başına iş ayrıntılarını sorgulamaya devices.jobs
Örnek:
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 dahil edilmesi için karşılaması gereken bir veya daha fazla koşulu belirtir. Herhangi bir JSON belgesinin sonuçta dahil edilmesi için belirtilen koşulları "true" olarak değerlendirmesi gerekir.
Örnek:
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 içinde 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 toplu değerler oluşturmak için kullanılır.
Örnek:
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 değerlendirilir. Özellik adınız olarak kullanırsanızgroup
, hataları önlemek için bunu çift köşeli ayraçla çevreleyin, örneğin. SELECT * FROM devices WHERE tags.[[group]].name = 'some_value'
GROUP BY için resmi söz dizimi:
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ı sayfalandırması
Sorgu nesnesinin örneği, 100 kayıttan küçük veya buna eşit maksimum sayfa boyutuyla oluşturulur. Birden çok sayfa edinmek 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
Üst düzeyde bir ifade:
- Bir JSON türünün örneğini (Boole, sayı, dize, dizi veya nesne gibi) değerlendirir.
- Yerleşik işleçler ve işlevler kullanılarak cihaz JSON belgesinden ve sabitlerinden gelen veriler işlenerek tanımlanır.
Koşullar , Boole değerini veren ifadelerdir. Boolean true değerinden farklı herhangi bir sabit false olarak kabul edilir. Bu kural null, tanımsız, herhangi bir nesne veya dizi örneği, herhangi bir dize ve Boolean 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>]+ ']'
İfadeler söz dizimindeki sembollerin ne anlama gelir anlamak için aşağıdaki tabloya bakın:
Sembol | Tanım |
---|---|
Öznitelik_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 | Ondalık gösterimiyle ifade edilen bir float. |
hexadecimal_literal | '0x' dizesiyle ifade edilen bir sayı ve ardından onaltılık basamak dizesi. |
string_literal | Sıfır veya daha fazla Unicode karakter veya kaçış dizisi dizisiyle temsil edilen Unicode dizeleri. Dize değişmez değerleri tek tırnak veya çift tırnak içine alınır. İzin verilen çıkışlar: \' , \" , \\ , \uXXXX Dört onaltılık basamakla tanımlanan Unicode karakterleri 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
İkizleri ve işleri sorgularken desteklenen tek işlev:
İşlev | Açıklama |
---|---|
IS_DEFINED(özellik) | Özelliğine bir değer atanıp atanmadığını belirten bir Boole değeri döndürür (dahil).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 kuvvete (x^y) döndürür. |
KARE(x) | Belirtilen sayısal değerin karesini döndürür. |
TAVANAYUVARLA(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. |
KAREKÖK(x) | Belirtilen sayısal değerin karekökünü döndürür. |
Yol koşullarında aşağıdaki tür denetimi ve atama işlevleri desteklenir:
İş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 ifade türünün bir dizi olup olmadığını belirten bir Boole değeri döndürür. |
IS_BOOL | Belirtilen ifade türünün Boole değeri olup olmadığını belirten bir Boole değeri döndürür. |
IS_DEFINED | Özelliğe bir değer atanıp atanmadığını belirten bir Boole değeri döndürür. Bu işlev yalnızca değer ilkel bir tür olduğunda desteklenir. Temel türler dize, Boole, sayısal veya null 'dır. DateTime, nesne türleri ve diziler desteklenmez. |
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 ifade 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 ifade 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 |
---|---|
ARALIKBİRLEŞTRİ(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. |
ALT(x) | Büyük harf karakter verilerini küçük harfe dönüştürdükten sonra bir dize ifadesi döndürür. |
BÜYÜKHARF(x) | Küçük harf 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 dize ifadesinin bir bölümünü döndürür ve belirtilen uzunlukta veya dizenin sonuna kadar devam eder. |
INDEX_OF(dize, parça) | belirtilen ilk dize ifadesi içinde ikinci dize ifadesinin ilk oluşumunun başlangıç konumunu veya dize bulunamazsa -1 döndürür. |
STARTSWITH(x, y) | İlk dize ifadesinin ikincisiyle başlayıp başlamadığını belirten bir Boole değeri döndürür. |
ENDSWITH(x, y) | İlk dize ifadesinin ikincisiyle bitip bitmediğini belirten bir Boole değeri döndürür. |
CONTAINS(x,y) | İlk dize ifadesinin ikincisini içerip içermediğini belirten bir Boole değeri döndürür. |
Hizmet SDK'larıyla sorgu örnekleri
C# örneği
Sorgu işlevi, RegistryManager sınıfında C# hizmet SDK'sı tarafından kullanıma sunulur.
Aşağıda basit bir sorgu örneği 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.jsiçin Azure IoT hizmeti SDK'sı tarafından kullanıma sunulur.
Aşağıda basit bir sorgu örneği 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 veyaişler için sorgular gibi belirli örnekleri alın.