بناء جملة استعلام توجيه رسالة IoT Hub

مقالة
04/21/2022
قراءة خلال 6 دقائق

يمكّن توجيه الرسائل المستخدمين من توجيه أنواع بيانات مختلفة، وهي رسائل بيانات تتبع الاستخدام للجهاز وأحداث دورة حياة الجهاز وأحداث تغيير في مستند معلومات حالة الجهاز إلى نقاط نهاية مختلفة. يمكنك أيضًا تطبيق استعلامات منسقة على هذه البيانات قبل توجيهها لتلقي البيانات التي تهمك. توضح هذه المقالة لغة استعلام توجيه رسالة IoT Hub وتوفر بعض أنماط الاستعلام الشائعة.

ملاحظة

تتوفر بعض الميزات المذكورة في هذه المقالة، مثل المراسلة من السحابة إلى الجهاز، وتوائم الأجهزة، وإدارة الأجهزة، فقط في المستوى القياسي من IoT Hub. لمزيد من المعلومات حول مستويات مركز IoT الأساسية والمعيارية، راجع كيفية اختيار مستوى مركز IoT الصحيح.

يسمح لك توجيه الرسائل بالاستعلام عن خصائص الرسالة ونص الرسالة بالإضافة إلى علامات مستند معلومات حالة الجهاز وخصائص مستند معلومات حالة الجهاز. إذا لم يكن نص الرسالة هو JSON، فلا يزال بإمكان توجيه الرسائل توجيه الرسالة، ولكن لا يمكن تطبيق الاستعلامات على نص الرسالة. توصف الاستعلامات على أنها تعبيرات منطقية حيث يؤدي العبير المنطقي (صواب) إلى نجاح الاستعلام الذي يوجه جميع البيانات الواردة، ويؤدي التعبير المنطقي (خطأ) إلى فشل الاستعلام ولا يتم توجيه أي بيانات. إذا تم تقييم التعبير إلى فارغ أو غير محدد ، التعامل معه على أنه خاطئ وسيتم إنشاء خطأ في سجلات سجلات موارد مسارات IoT Hub في حالة حدوث فشل. يجب أن يكون بناء جملة الاستعلام صحيحًا للتوجيه الذي سيتم حفظه وتقييمه.

استعلام توجيه الرسائل استنادًا إلى خصائص الرسالة

يحدد IoT Hub تنسيقا مشتركا لجميع الرسائل من الجهاز إلى السحابة لقابلية التشغيل البيني عبر البروتوكولات. تفترض رسالة IoT Hub تمثيل JSON التالي للرسالة. يتم إضافة خصائص النظام لكافة المستخدمين وتعريف محتوى الرسالة. يمكن للمستخدمين إضافة خصائص التطبيق بشكل انتقائي إلى الرسالة. نوصي باستخدام أسماء خصائص فريدة حيث أن المراسلة من جهاز إلى سحابة من IoT Hub ليست حساسة لحالة الأحرف. على سبيل المثال، إذا كان لديك خصائص متعددة بنفس الاسم، سوف يرسل IoT Hub أحد الخصائص فقط.

{ 
  "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}}" 
  } 
}

خصائص النظام

تساعد خصائص النظام في تحديد محتويات الرسائل ومصدرها.

الخاصية	النوع	الوصف
نوع المحتوى	سلسلة	يحدد المستخدم نوع محتوى الرسالة. للسماح بالاستعلام على نص الرسالة، يجب تعيين هذه القيمة application/JSON.
المحتوىترميز	سلسلة	يحدد المستخدم نوع ترميز الرسالة. القيم المسموح بها هي UTF-8 و UTF-16 و UTF-32 إذا تم تعيين contentType إلى التطبيق / JSON.
iothub-connection-device-id	سلسلة	يتم تعيين هذه القيمة بواسطة IoT Hub وتحدد معرف الجهاز. للاستعلام، استخدم `$connectionDeviceId`.
iothub-connection-module-id	سلسلة	يتم تعيين هذه القيمة بواسطة IoT Hub وتحدد معرف الوحدة النمطية الطرفية. للاستعلام، استخدم `$connectionModuleId`.
iothub-enqueuedtime	سلسلة	يتم تعيين هذه القيمة بواسطة IoT Hub وتمثل الوقت الفعلي لانتظار الرسالة في UTC. للاستعلام، استخدم `enqueuedTime`.
dt-dataschema	سلسلة	يتم تعيين هذه القيمة بواسطة IoT hub على الرسائل من جهاز إلى سحابة. تحتوي على معرّف طراز الجهاز الذي تم تعيينه في اتصال الجهاز. للاستعلام، استخدم `$dt-dataschema`.
dt-الموضوع	سلسلة	اسم المكوّن الذي يقوم بإرسال رسائل من جهاز إلى سحابة. للاستعلام، استخدم `$dt-subject`.

كما هو موضح في رسائل IoT Hub، توجد خصائص نظام إضافية في الرسالة. بالإضافة إلى الخصائص المذكورة أعلاه في الجدول السابق ، يمكنك أيضا الاستعلام عن connectionDeviceID و connectionModuleId.

خصائص التطبيق

خصائص التطبيق هي سلاسل معرفة من قبل المستخدم يمكن إضافتها إلى الرسالة. هذه الحقول اختيارية.

تعبيرات الاستعلام

يحتاج الاستعلام على خصائص نظام رسالة إلى أن يكون مسبوق بالرمز $. يتم الوصول إلى الاستعلامات حول خصائص التطبيق باسمها ويجب ألا تكون مسبوقة بالرمز $. إذا بدأ اسم خاصية تطبيق بـ $، فسيبحث IoT Hub عنه في خصائص النظام، وإذا لم يتم العثور عليه، فإنه سيبحث في خصائص التطبيق. على سبيل المثال:

للاستعلام عن خاصية النظام contentEncoding

$contentEncoding = 'UTF-8'

للاستعلام عن خاصية التطبيق processingPath:

processingPath = 'hot'

لدمج هذه الاستعلامات، يمكنك استخدام التعبيرات المنطقية والوظائف:

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

يتم عرض قائمة كاملة بعوامل التشغيل والوظائف المدعومة في التعبير والشروط.

استعلام توجيه الرسائل استنادًا إلى نص الرسالة

لتمكين الاستعلام عن نص الرسالة، يجب أن تكون الرسالة مرمزة في JSON إما UTF-8 أو UTF-16 أو UTF-32. contentType يجب تعيين إلى application/JSON وإلى contentEncoding أحد ترميزات UTF المدعومة في خاصية النظام. إذا لم يتم تحديد هذه الخصائص، لن يقوم IoT Hub بتقييم تعبير الاستعلام على نص الرسالة.

يوضح المثال التالي كيفية إنشاء رسالة مع نص JSON تم تشكيله وترميزه بشكل صحيح:

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#، فقم بتنزيل عينات Azure IoT C#‎. قم بفك ضغط ملف master.zip. يعرض ملف Visual Studio الحل .cs برنامج SimulatedDevice كيفية ترميز الرسائل وإرسالها إلى مركز إنترنت الأشياء. هذا هو نفس العينة المستخدمة لاختبار توجيه الرسالة، كما هو موضح في البرنامج التعليمي لتوجيه الرسائل. في الجزء السفلي من البرنامج .cs ، يحتوي أيضا على طريقة للقراءة في أحد الملفات المشفرة ، وفك تشفيرها ، وكتابتها مرة أخرى باسم ASCII حتى تتمكن من قراءتها.

تعبيرات الاستعلام

يجب أن يكون الاستعلام على نص الرسالة مسبوقا ب $body. يمكنك استخدام مرجع نص أو مرجع صفيف نص أو مراجع نص متعددة في تعبير الاستعلام. يمكن لتعبير الاستعلام أيضًا دمج مرجع نص مع خصائص نظام رسالة ومرجع خصائص تطبيق رسالة. على سبيل المثال، فيما يلي كافة تعبيرات الاستعلام الصالحة:

$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'

ملاحظة

لتصفية حمولة إعلام مزدوجة استنادا إلى ما تغير، قم بتشغيل الاستعلام على نص الرسالة. على سبيل المثال، للتصفية عندما يكون هناك تغيير sendFrequency خاصية الرغبة والقيمة أكبر من 10:

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

لتصفية الرسائل التي تحتوي على تغيير خاصية، بغض النظر عن قيمة الخاصية، يمكنك استخدام الدالة (عندما تكون القيمة من النوع البدائي is_defined() ):

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

ملاحظة

يمكنك تشغيل الاستعلامات والدالات فقط على الخصائص الموجودة في مرجع النص الأساسي. لا يمكنك تشغيل الاستعلامات أو الوظائف على مرجع النص الأساسي بأكمله. على سبيل المثال، الاستعلام التالي غير معتمد وسيتم إرجاعه undefined:

$body[0] = 'Feb'

استعلام توجيه الرسائل استنادًا إلى مستند معلومات حالة جهاز

يتيح لك توجيه الرسائل الاستعلام عن علامات وخصائص Device Twin ، وهي كائنات JSON. يتم دعم الاستعلام عن الوحدة النمطية التوأم أيضا. يتم عرض عينة من علامات وخصائص مستند معلومات حالة الجهاز أدناه.

{
    "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 
        } 
    } 
}

ملاحظة

لا ترث الوحدات النمطية علامات مزدوجة من أجهزتها المقابلة. الاستعلامات المزدوجة للرسائل الناشئة من وحدات الجهاز (على سبيل المثال من وحدات IoT Edge) الاستعلام مقابل توأم الوحدة وليس توأم الجهاز المقابل.

تعبيرات الاستعلام

يجب أن يكون الاستعلام على جهاز أو وحدة نمطية مزدوجة مسبوقا ب $twin. يمكن لتعبير الاستعلام أيضا دمج علامة مزدوجة أو مرجع خاصية مع مرجع نص و/أو مرجع خصائص نظام الرسائل و/أو مرجع خصائص تطبيق الرسالة. نوصي باستخدام أسماء فريدة في العلامات والخصائص لأن الاستعلام غير حساس لحالة الأحرف. ينطبق هذا على كل من توائم الجهاز وتوائم الوحدة. امتنع أيضا عن استخدام twin، ، أو ، أو ، $twinbody$bodyكأسماء عقارات. على سبيل المثال، فيما يلي كافة تعبيرات الاستعلام الصالحة:

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

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

$twin.tags.deploymentLocation.floor = 1

استعلام التوجيه على الجسم أو الجهاز التوأم مع وجود نقطة في اسم الحمولة أو الخاصية غير مدعوم.

الخطوات التالية

تعرف على توجيه الرسائل.
جرب البرنامج التعليمي لتوجيه الرسائل.

بناء جملة استعلام توجيه رسالة IoT Hub

هل هذه الصفحة مفيدة؟

استعلام توجيه الرسائل استنادًا إلى خصائص الرسالة

خصائص النظام

خصائص التطبيق

تعبيرات الاستعلام

استعلام توجيه الرسائل استنادًا إلى نص الرسالة

تعبيرات الاستعلام

استعلام توجيه الرسائل استنادًا إلى مستند معلومات حالة جهاز

تعبيرات الاستعلام

الخطوات التالية