IoT Hub ileti yönlendirme sorgusu söz dizimi

İ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.

İ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:

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 özelliği adı ile $başlıyorsa, IoT Hub önce sistem özelliklerinde bu adı 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 
        } 
    } 
} 

İ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.