IoT Hub ileti yönlendirme sorgusu söz dizimi

Makale
03/18/2023

İ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, sizin için ö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ı seçme.

İleti yönlendirme, ileti özelliklerini ve ileti gövdesini, cihaz ikizi etiketlerini ve cihaz ikizi özelliklerini sorgulamanızı sağlar. İleti gövdesi JSON biçiminde değilse, ileti yönlendirme yine de iletiyi yönlendirebilir, 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 false değeri olarak değerlendirilir ve IoT Hub yol kaynak günlüklerinde bir hata oluşturur. Yolun kaydedilip değerlendirilebilmesi için sorgu söz diziminin doğru olması gerekir.

İleti özelliklerine göre sorgu

IoT Hub, protokoller arasında birlikte çalışabilirlik için tüm cihazdan 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ı 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; bazıları aşağıdaki tabloda açıklanmıştır:

Özellik	Tür	Description
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 `application/JSON`ayarlanırsa, izin verilen değerler , `UTF-16`ve `UTF-32`olur`UTF-8`.
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 iletiyi UTC olarak sıralamanın gerçek zamanını 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`.

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.

İleti özellikleri sorgu ifadeleri

İleti sistemi özelliklerindeki bir sorgunun $ önüne simgesi eklenmelidir. Uygulama özelliklerindeki sorgulara adlarıyla erişilir ve ön ekinde $simgesi olmamalıdır. Bir uygulama özelliği adı ile $başlıyorsa, IoT Hub önce sistem özelliklerinde arar ve bulunamazsa uygulama özelliklerinde arar. Aşağıdaki örneklerde, sistem özellikleri ve uygulama özellikleri üzerinde nasıl sorgu yapılacağı gösterilir.

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 ifade ve koşullar bölümünde desteklenen işleçlerin ve işlevlerin tam listesi sağlanır.

İleti gövdesini temel alan sorgu

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

Aşağıdaki JavaScript örneğinde 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);
});

C# dilinde ileti kodlama örneği için bkz. .NET için Microsoft Azure IoT SDK'sında sağlanan HubRoutingSample . Bu örnek, İleti Yönlendirme öğreticisinde 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.

İleti gövdesi sorgu ifadeleri

İleti gövdesindeki bir sorguya önek eklenmelidir $body. Sorgu ifadesinde gövde başvurusu, gövde dizisi başvurusu veya birden çok gövde başvurusu kullanabilirsiniz. Sorgu ifadeniz, 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'

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'

Değişen değişikliklere bağlı olarak ikizi bildirim yükünü filtrelemek için sorgunuzu ileti gövdesinde çalıştırın. Örneğin, istenen ö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)

Cihaz veya modül ikizlerine göre sorgulama

İleti yönlendirme, JSON nesneleri olan cihaz ikizi veya modül ikizi etiketlerini ve özelliklerini sorgulamanızı sağlar. Aşağıdaki örnekte etiketler ve özelliklere sahip bir cihaz ikizi 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 kaynaklanan iletiler için ikiz sorguları (örneğin, IoT Edge modüllerden) ilgili cihaz ikizini değil modül ikizini sorgular.

İkiz sorgu ifadeleri

Cihaz ikizi veya modül ikizinde bir sorguya ön ek $twineklenmelidir. Sorgu ifadeniz bir ikiz etiketi 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.