IoT Hub ileti yönlendirme sorgusu söz dizimi

Makale
06/13/2024

İ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

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ü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ızı sağlar. İleti gövdesi JSON biçiminde değilse, ileti yönlendirme iletiyi yine de 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 yanlış değeri olarak kabul edilir ve IoT Hub yönlendirmeleri 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. IoT Hub cihazdan buluta mesajlaşma 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; bazıları aşağıdaki tabloda açıklanmıştır:

Özellik	Türü	Açıklama
contentType	Dize	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	Dize	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`.
ıothub-bağlantı-cihaz kimliği	Dize	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	Dize	Bu değer IoT Hub tarafından ayarlanır ve uç modülünün kimliğini tanımlar. Sorgulamak için kullanın `$connectionModuleId`.
iothub-enqueuedtime	Dize	Bu değer IoT Hub tarafından ayarlanır ve utc cinsinden iletinin gerçek sıralanma zamanını temsil eder. Sorgulamak için kullanın `$enqueuedTime`.
dt-dataschema	Dize	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	Dize	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 eki simgesi olmalıdır $ . 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 özelliklerini ve uygulama özelliklerini sorgulama gösterilmektedir.

Sistem özelliği içeriğini sorgulamak içinEncoding:

$contentEncoding = 'UTF-8'

Uygulama özelliği processingPath'i 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 olması ve UTF-8, UTF-16 veya UTF-32 ile kodlanmış olması gerekir. contentType Sistem özelliği olmalıdırapplication/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ış 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, kodunu çözen ve okuyabilmeniz için ASCII olarak geri yazan adlı ReadOneRowFromFilebir yöntemi de vardır.

İleti gövdesi 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'

Sorguları ve işlevleri yalnızca gövde başvurusundaki özelliklerde çalıştırabilirsiniz. Gövde başvurusunun tamamında sorgular veya işlevler ç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 göre bir ikiz bildirimi 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 ikizlerini temel alan sorgu

İ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 (örneğin IoT Edge modüllerinden) kaynaklanan iletiler için ikiz sorguları, ilgili cihaz ikizini değil modül ikizini sorgular.

İkiz sorgu ifadeleri

Cihaz ikizinde 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.

Aracılığıyla paylaş