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

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

ملاحظة

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

يسمح لك توجيه الرسائل بالاستعلام عن خصائص الرسالة ونص الرسالة بالإضافة إلى علامات مستند معلومات حالة الجهاز وخصائص مستند معلومات حالة الجهاز. إذا لم يكن نص الرسالة بتنسيق 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.
contentEncoding	سلسلة	يحدد المستخدم نوع ترميز الرسالة. إذا تم تعيين الخاصية contentType إلى application/JSON، فإن القيم المسموح بها هي UTF-8و UTF-16و.UTF-32
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-subject	سلسلة	اسم المكوّن الذي يقوم بإرسال رسائل من جهاز إلى سحابة. للاستعلام، استخدم $dt-subject.

لمزيد من المعلومات حول خصائص النظام الأخرى المتوفرة، راجع إنشاء رسائل IoT Hub وقراءتها.

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

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

تعبيرات استعلام خصائص الرسالة

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

للاستعلام عن محتوى خاصية النظام ترميز:

$contentEncoding = 'UTF-8'

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

processingPath = 'hot'

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

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

يتم توفير قائمة كاملة بعوامل التشغيل والوظائف المدعومة في قسم التعبير والشروط في لغة استعلام IoT Hub لتوائم الجهاز والوحدة النمطية والمهام وتوجيه الرسائل.

الاستعلام استنادا إلى نص الرسالة

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

يوضح مثال JavaScript التالي كيفية إنشاء رسالة مع نص 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#، راجع HubRoutingSample المتوفر في Microsoft Azure IoT SDK ل .NET. هذه العينة هي نفس العينة المستخدمة في البرنامج التعليمي لتوجيه الرسائل. يحتوي ملف Program.cs أيضا على أسلوب يسمى ReadOneRowFromFile، والذي يقرأ أحد الملفات المشفرة، ويفك ترميزه، ويكتبه مرة أخرى ك 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'

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

$body[0] = 'Feb'

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

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

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

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

الاستعلام استنادا إلى الجهاز أو الوحدة النمطية المزدوجة

يمكنك توجيه الرسائل من الاستعلام عن العلامات والخصائص المزدوجة للجهاز أو الوحدة النمطية المزدوجة ، وهي كائنات 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 

التقييدات

لا تدعم استعلامات التوجيه استخدام المسافة البيضاء أو أي من الأحرف التالية في أسماء الخصائص أو مسار نص الرسالة أو المسار المزدوج للجهاز/الوحدة: ()<>@,;:\"/?={}.

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

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