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.

Bilgi Notu

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 için doğru IoT Hub katmanını ve boyutunu 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ımlanmamış bir değer olarak değerlendirilirse, Boole yanlış değeri olarak kabul edilir ve IoT Hub yönlendirme 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.

Bilgi Notu

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:

Mülk	Türü	Açıklama
içerikTürü	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.
içerik kodlaması	Dize	Kullanıcı iletinin kodlama türünü belirtir. contentType özelliği olarak `application/JSON`ayarlanırsa, izin verilen değerler , `UTF-8`ve `UTF-16`olur`UTF-32`.
ıothub-bağlantı-cihaz kimliği	Dize	IoT Hub, cihazın kimliğini tanımlayan bu değeri ayarlar. Sorgulamak için kullanın `$connectionDeviceId`.
iothub-bağlantı-modül-kimliği	Dize	IoT Hub, uç modülünün kimliğini tanımlayan bu değeri ayarlar. Sorgulamak için kullanın `$connectionModuleId`.
iothub-enqueuedtime	Dize	IoT Hub, mesajın UTC cinsinden fiili sıralanma zamanını temsil eden bu değeri ayarlar. Sorgulamak için kullanın `$enqueuedTime`.
dt-veri şeması	Dize	IoT Hub, cihazdan buluta iletilerde bu değeri ayarlar. 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 IoT Hub iletileri oluşturma ve okuma'ya bakın.

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 sorgu, $ simgesiyle önceden belirtilmelidir. 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 İfadeler 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, ileti 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 ifadesi içinde gövde başvurusu, gövde dizisi başvurusu veya çeşitli gövde başvuruları 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 referansındaki özelliklerde çalıştırabilirsiniz. Tüm gövde üzerinde 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 
        } 
    } 
}

Bilgi Notu

Modüller, karşılık gelen cihazlarından ikiz etiketlerini devralamaz. 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 ikizi veya modül ikizi üzerinde bir sorguya $twin ön eki eklenmelidir. 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. Ö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

Bilgi Notu

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 twinda kaçınmanız gerekir.

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.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-08-13

Aracılığıyla paylaş

IoT Hub ileti yönlendirme sorgusu söz dizimi

İleti özelliklerine göre sorgu

Sistem özellikleri

Uygulama özellikleri

İleti özellikleri sorgu ifadeleri

İleti gövdesini temel alan sorgu

İleti gövdesi sorgu ifadeleri

Cihaz veya modül ikizlerini temel alan sorgu

İkiz sorgu ifadeleri

Sınırlamalar

Sonraki adımlar

Geri Bildirim

Ek kaynaklar