IoT Hub ileti yönlendirme sorgusu söz dizimi

Makale
01/27/2023
Okumak için 6 dakika

İleti yönlendirme, kullanıcıların cihaz telemetri iletileri, cihaz yaşam döngüsü olayları ve cihaz ikizi değişiklik olayları gibi farklı veri türlerini çeşitli uç noktalara yönlendirmesine olanak tanır. Ayrıca, önemli olan verileri almak üzere yönlendirmeden önce bu verilere zengin sorgular uygulayabilirsiniz. Bu makalede, IoT Hub ileti yönlendirme sorgu dili açıklanır ve bazı yaygın sorgu desenleri sağlanır.

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ını seçme.

İleti yönlendirme, ileti özellikleri ve ileti gövdesinin yanı sıra cihaz ikizi etiketlerini ve cihaz ikizi özelliklerini sorgulamanıza olanak tanır. İleti gövdesi JavaScript Nesne Gösterimi (JSON) biçiminde değilse, ileti yönlendirme işlemi iletiyi yönlendirmeye devam edebilir, ancak sorgular ileti gövdesine uygulanamaz. Sorgular, doğruysa sorgunun başarılı olduğu ve tüm gelen verileri yönlendirdiği Boole ifadeleri olarak tanımlanır; aksi takdirde sorgu başarısız olur ve gelen veriler yönlendirilmiş olmaz. İfade null veya tanımsız bir değer olarak değerlendirilirse Boole yanlış değeri olarak kabul edilir ve IoT Hub yol kaynak günlüklerinde bir hata oluşturulur. Yolun kaydedilip değerlendirilmesi için sorgu söz dizimi doğru olmalıdır.

İleti özelliklerine göre ileti yönlendirme sorgusu

IoT Hub, protokoller arasında birlikte çalışabilirlik için tüm cihazlardan buluta mesajlaşma için ortak bir biçim tanımlar. IoT Hub iletinin aşağıdaki JSON gösterimini varsayar. Sistem özellikleri tüm kullanıcılar için eklenir ve iletinin içeriğini tanımlar. Kullanıcılar iletiye seçmeli olarak uygulama özellikleri ekleyebilir. Cihazdan buluta mesajlaşma IoT Hub büyük/küçük harfe duyarlı olmadığından benzersiz özellik adlarını kullanmanızı öneririz. Örneğin, aynı ada sahip birden çok özelliğiniz varsa, IoT Hub özelliklerden yalnızca birini gönderir.

{ 
  "message": { 
    "systemProperties": { 
      "contentType": "application/json", 
      "contentEncoding": "UTF-8", 
      "iothub-message-source": "deviceMessages", 
      "iothub-enqueuedtime": "2017-05-08T18:55:31.8514657Z" 
    }, 
    "appProperties": { 
      "processingPath": "{cold | warm | hot}", 
      "verbose": "{true, false}", 
      "severity": 1-5, 
      "testDevice": "{true | false}" 
    }, 
    "body": "{\"Weather\":{\"Temperature\":50}}" 
  } 
}

Sistem özellikleri

Sistem özellikleri, iletilerin içeriğini ve kaynağını belirlemeye yardımcı olur ve bazıları aşağıdaki tabloda açıklanmıştır.

Özellik	Tür	Açıklama
Contenttype	string	Kullanıcı iletinin içerik türünü belirtir. İleti gövdesinde sorgulamaya izin vermek için bu değer olarak `application/JSON`ayarlanmalıdır.
Contentencoding	string	Kullanıcı iletinin kodlama türünü belirtir. contentType özelliği olarak ayarlandıysa`application/JSON`, izin verilen değerler `UTF-8`, `UTF-16`ve `UTF-32` değerleridir.
iothub-connection-device-id	string	Bu değer IoT Hub tarafından ayarlanır ve cihazın kimliğini tanımlar. Sorgulamak için kullanın `$connectionDeviceId`.
iothub-connection-module-id	string	Bu değer IoT Hub tarafından ayarlanır ve kenar modülünün kimliğini tanımlar. Sorgulamak için kullanın `$connectionModuleId`.
iothub-enqueuedtime	string	Bu değer IoT Hub tarafından ayarlanır ve utc cinsinden iletinin gerçek sıralanma saatini temsil eder. Sorgulamak için kullanın `$enqueuedTime`.
dt-dataschema	string	Bu değer, cihazdan buluta iletilerde IoT Hub tarafından ayarlanır. Cihaz bağlantısında ayarlanan cihaz modeli kimliğini içerir. Sorgulamak için kullanın `$dt-dataschema`.
dt-subject	string	Cihazdan buluta iletileri gönderen bileşenin adı. Sorgulamak için kullanın `$dt-subject`.

Önceki tabloda iletide kullanılabilen sistem özelliklerinden yalnızca bazıları açıklanmaktadır. Diğer kullanılabilir sistem özellikleri hakkında daha fazla bilgi için bkz. IoT Hub iletileri oluşturma ve okuma.

Uygulama özellikleri

Uygulama özellikleri, iletiye eklenebilen kullanıcı tanımlı dizelerdir. Bu alanlar isteğe bağlıdır.

Sorgu ifadeleri

İleti sistemi özelliklerindeki bir sorgunun $ önüne simgesi eklenmelidir. Uygulama özelliklerindeki sorgulara adları ile erişilir ve ön ekinde $sembol bulunmamalıdır. Bir uygulama özellik adı ile $başlıyorsa, IoT Hub önce sistem özelliklerinde onu arar ve bulunamazsa uygulama özelliklerinde arar. Aşağıdaki örneklerde sistem özellikleri ve uygulama özelliklerini sorgulama gösterilmektedir.

Sistem özelliği içeriğinde sorgulamak için Kodlama:

$contentEncoding = 'UTF-8'

ProcessingPath uygulama özelliğinde sorgulamak için:

processingPath = 'hot'

Bu sorguları birleştirmek için Boole ifadelerini ve işlevlerini kullanabilirsiniz:

$contentEncoding = 'UTF-8' AND processingPath = 'hot'

Cihaz ve modül ikizleri, işler ve ileti yönlendirme için IoT Hub sorgu dilinin İfade ve koşullar bölümünde desteklenen işleçlerin ve işlevlerin tam listesi sağlanır.

İleti gövdesini temel alan ileti yönlendirme sorgusu

İleti gövdesinde sorgulamayı etkinleştirmek için ileti JSON biçiminde olmalı ve UTF-8, UTF-16 veya UTF-32 ile kodlanmalıdır. Sistem contentType özelliği olarak application/JSONayarlanmalıdır. Sistem özelliği, contentEncoding bu sistem özelliği tarafından desteklenen UTF kodlama değerlerinden birine ayarlanmalıdır. Bu sistem özellikleri belirtilmezse, IoT Hub ileti gövdesindeki sorgu ifadesini değerlendirmez.

Aşağıdaki örnekte düzgün biçimlendirilmiş ve kodlanmış bir JSON gövdesine sahip bir iletinin nasıl oluşturulacağı gösterilmektedir:

var messageBody = JSON.stringify(Object.assign({}, {
    "Weather": {
        "Temperature": 50,
        "Time": "2017-03-09T00:00:00.000Z",
        "PrevTemperatures": [
            20,
            30,
            40
        ],
        "IsEnabled": true,
        "Location": {
            "Street": "One Microsoft Way",
            "City": "Redmond",
            "State": "WA"
        },
        "HistoricalData": [
            {
                "Month": "Feb",
                "Temperature": 40
            },
            {
                "Month": "Jan",
                "Temperature": 30
            }
        ]
    }
}));

// Encode message body using UTF-8  
var messageBytes = Buffer.from(messageBody, "utf8");

var message = new Message(messageBytes);

// Set message body type and content encoding 
message.contentEncoding = "utf-8";
message.contentType = "application/json";

// Add other custom application properties   
message.properties.add("Status", "Active");

deviceClient.sendEvent(message, (err, res) => {
    if (err) console.log('error: ' + err.toString());
    if (res) console.log('status: ' + res.constructor.name);
});

Not

Bu, JavaScript'te ileti gövdesinin kodlamasının nasıl işlendiğini gösterir. C# dilinde bir örnek görmek istiyorsanız . .NET için Microsoft Azure IoT SDK'sını indirin ve sıkıştırılmış klasörü (azure-iot-sdk-csharp-main.zip) genişletin. HubRoutingSample cihaz örneğinin Program.cs dosyası, SDK'nın \iothub\device\samples\how to guides\HubRoutingSample alt klasöründe iletilerin nasıl kodlanıp IoT hub'ına gönderilip gönderilip kodlanacaklarını gösterir. Bu, İleti Yönlendirme öğreticisinde açıklandığı gibi ileti yönlendirmeyi test etmede kullanılan örnekle aynıdır. Program.cs dosyasında ayrıca kodlanmış dosyalardan birini okuyan, kodu çözen ve okuyabilmeniz için ASCII olarak geri yazan adlı ReadOneRowFromFilebir yöntemi vardır.

Sorgu ifadeleri

İleti gövdesindeki bir sorguya ön ek $bodyeklenmelidir. Sorgu ifadesinde gövde başvurusu, gövde dizisi başvurusu veya birden çok gövde başvurusu kullanabilirsiniz. Sorgu ifadeniz bir gövde başvurusunu ileti sistemi özellikleri başvurusu veya ileti uygulaması özellikleri başvurusuyla da birleştirebilir. Örneğin, aşağıdaki örneklerin tümü geçerli sorgu ifadeleridir:

$body.Weather.HistoricalData[0].Month = 'Feb'

$body.Weather.Temperature = 50 AND $body.Weather.IsEnabled

length($body.Weather.Location.State) = 2

$body.Weather.Temperature = 50 AND processingPath = 'hot'

Not

Değişen değişikliklere göre bir ikiz bildirimi yükünü filtrelemek için ileti gövdesinde sorgunuzu çalıştırın. Örneğin, üzerinde istenen bir özellik değişikliği sendFrequency olduğunda ve değer 10'dan büyük olduğunda filtrelemek için:

$body.properties.desired.telemetryConfig.sendFrequency > 10

Özellik değişikliği içeren iletileri filtrelemek için, özelliğin değeri ne olursa olsun işlevini kullanabilirsiniz is_defined() (değer ilkel bir tür olduğunda):

is_defined($body.properties.desired.telemetryConfig.sendFrequency)

Not

Sorguları ve işlevleri yalnızca gövde başvurusundaki özelliklerde çalıştırabilirsiniz. Gövde başvurusunun tamamında sorgu veya işlev çalıştıramazsınız. Örneğin, aşağıdaki sorgu desteklenmez ve döndürür undefined:

$body[0] = 'Feb'

Cihaz ikizi temelinde ileti yönlendirme sorgusu

İleti yönlendirme, JSON nesneleri olan Cihaz İkizi etiketlerini ve özelliklerini sorgulamanızı sağlar. Modül ikizinde sorgulama da desteklenir. Aşağıdaki örnekte cihaz ikizi etiketleri ve özellikleriyle ilgili bir sorgu gösterilmektedir.

{
    "tags": { 
        "deploymentLocation": { 
            "building": "43", 
            "floor": "1" 
        } 
    }, 
    "properties": { 
        "desired": { 
            "telemetryConfig": { 
                "sendFrequency": "5m" 
            }, 
            "$metadata" : {...}, 
            "$version": 1 
        }, 
        "reported": { 
            "telemetryConfig": { 
                "sendFrequency": "5m", 
                "status": "success" 
            },
            "batteryLevel": 55, 
            "$metadata" : {...}, 
            "$version": 4 
        } 
    } 
}

Not

Modüller, karşılık gelen cihazlarından ikiz etiketlerini devralmaz. Cihaz modüllerinden (örneğin, IoT Edge modüllerden) kaynaklanan iletiler için ikiz sorguları, ilgili cihaz ikizini değil modül ikizini sorgular.

Sorgu ifadeleri

Cihaz ikizi veya modül ikizinde bir sorguya ön ek $twineklenmelidir. Sorgu ifadeniz bir ikiz etiketini veya özellik başvurusunu gövde başvurusu, ileti sistemi özellikleri başvurusu veya ileti uygulaması özellikleri başvurusuyla da birleştirebilir. Sorgu büyük/küçük harfe duyarlı olmadığından etiketlerde ve özelliklerde benzersiz adlar kullanmanızı öneririz. Bu öneri hem cihaz ikizleri hem de modül ikizleri için geçerlidir. Ayrıca , $twin, bodyveya $body özelliğini özellik adları olarak kullanmaktan twinkaçınmanızı öneririz. Örneğin, aşağıdaki örneklerin tümü geçerli sorgu ifadeleridir:

$twin.properties.desired.telemetryConfig.sendFrequency = '5m'

$body.Weather.Temperature = 50 AND $twin.properties.desired.telemetryConfig.sendFrequency = '5m'

$twin.tags.deploymentLocation.floor = 1

Sınırlamalar

Yönlendirme sorguları özellik adlarında, ileti gövdesi yolunda veya cihaz/modül ikiz yolunda boşluk veya aşağıdaki karakterlerden herhangi birinin kullanılmasını desteklemez: ()<>@,;:\"/?={}.

Sonraki adımlar

İleti yönlendirme hakkında bilgi edinin.
İleti yönlendirme öğreticisini deneyin.

IoT Hub ileti yönlendirme sorgusu söz dizimi

İleti özelliklerine göre ileti yönlendirme sorgusu

Sistem özellikleri

Uygulama özellikleri

Sorgu ifadeleri

İleti gövdesini temel alan ileti yönlendirme sorgusu

Sorgu ifadeleri

Cihaz ikizi temelinde ileti yönlendirme sorgusu

Sorgu ifadeleri

Sınırlamalar

Sonraki adımlar

Ek kaynaklar

Ek kaynaklar