لغة استعلام IoT Hub لتوائم الجهاز والوحدة والوظائف وتوجيه الرسائل
توفر IoT Hub لغة قوية تشبه SQL لاسترداد المعلومات المتعلقة بتوائم الجهاز وتوائم الوحدة والوظائف وتوجيه الرسائل. تقدم هذه المقالة:
- مقدمة عن الميزات الرئيسية لغة استعلام IoT Hub
- والوصف التفصيلي المتعلق باللغة. للحصول على تفاصيل حول لغة الاستعلام لتوجيه الرسائل، انظر الاستعلامات في توجيه الرسائل.
للحصول على أمثلة محددة، راجع استعلامات الجهاز والوحدة النمطية المزدوجة أو الاستعلامات عن الوظائف.
إشعار
تتوفر بعض الميزات المذكورة في هذه المقالة، مثل المراسلة من السحابة إلى الجهاز والجهاز المزدوج وإدارة الجهاز، في الطبقة القياسية لـ IoT Hub فقط. لمزيد من المعلومات حول مستويات IoT Hub الأساسية والقياسية/المجانية، راجع اختيار طبقة IoT Hub المناسبة للحل الخاص بك.
تشغيل استعلامات IoT Hub
يمكنك تشغيل الاستعلامات مقابل مركز IoT مباشرة في مدخل Microsoft Azure.
- سجل الدخول إلى مدخل Microsoft Azure والانتقال إلى IoT hub الخاص بك.
- حدد Queries من قسم Device management في قائمة التنقل.
- أدخل الاستعلام في مربع النص وحدد تشغيل الاستعلام.
يمكنك أيضا تشغيل الاستعلامات داخل تطبيقاتك باستخدام حزم SDK لخدمة Azure IoT وواجهات برمجة التطبيقات للخدمة.
على سبيل المثال، التعليمات البرمجية التي تنفذ استعلامات IoT Hub، راجع قسم Query examples with the service SDKs .
للحصول على ارتباطات إلى صفحات وعينات مرجعية ل SDK، راجع Azure IoT SDKs.
أساسيات استعلام IoT Hub
يتكون كل استعلام IoT Hub من عبارات SELECT وFROM مع عبارات WHERE وGROUP BY الاختيارية.
يتم تشغيل الاستعلامات على مجموعة من مستندات JSON، على سبيل المثال توائم الجهاز. تشير عبارة FROM إلى مجموعة المستندات التي سيتم تكرارها (إما الأجهزة أو الأجهزة.الوحدات النمطية أو devices.jobs).
بعد ذلك، يتم تطبيق عامل التصفية في عبارة WHERE. مع التجميعات، يتم تجميع نتائج هذه الخطوة على النحو المحدد في عبارة GROUP BY. لكل مجموعة، يتم إنشاء صف على النحو المحدد في عبارة SELECT.
SELECT <select_list>
FROM <from_specification>
[WHERE <filter_condition>]
[GROUP BY <group_specification>]
عبارة SELECT
العبارة SELECT <select_list> مطلوبة في كل استعلام IoT Hub. يحدد القيم التي يتم استردادها من الاستعلام. إنها تحدد قيم JSON التي سيتم استخدامها لإنشاء عناصر JSON جديدة. لكل عنصر من عناصر المجموعة الفرعية التي تمت تصفيتها (والمجمعة اختياريًا) من مجموعة FROM، تُنشئ مرحلة الإسقاط عنصر JSON جديدًا. يتم إنشاء هذا العنصر بالقيم المحددة في عبارة SELECT.
على سبيل المثال:
إرجاع كافة القيم
SELECT *
إرجاع خصائص محددة
SELECT DeviceID, LastActivityTime
تجميع نتائج استعلام لإرجاع عدد
SELECT COUNT() as TotalNumber
حاليا، يتم دعم عبارات التحديد المختلفة عن SELECT فقط في الاستعلامات المجمعة على توائم الجهاز.
بناء الجملة التالي هو النحوي لجملة SELECT:
SELECT [TOP <max number>] <projection list>
<projection_list> ::=
'*'
| <projection_element> AS alias [, <projection_element> AS alias]+
<projection_element> :==
attribute_name
| <projection_element> '.' attribute_name
| <aggregate>
<aggregate> :==
count()
| avg(<projection_element>)
| sum(<projection_element>)
| min(<projection_element>)
| max(<projection_element>)
يشير Attribute_name إلى أي خاصية لمستند JSON داخل مجموعة FROM.
عبارة FROM
العبارة FROM <from_specification> مطلوبة في كل استعلام ioT Hub. يجب أن تكون واحدة من ثلاث قيم:
- أجهزة للاستعلام عن توائم الجهاز
- devices.modules للاستعلام عن توائم الوحدة النمطية
- devices.jobs للاستعلام عن تفاصيل المهمة لكل جهاز
على سبيل المثال:
استرداد جميع توائم الجهاز
SELECT * FROM devices
عبارة WHERE
العبارة WHERE <filter_condition> اختيارية. إنها تحدد شرطًا واحدًا أو أكثر يجب أن تفي به مستندات JSON في مجموعة FROM ليتم تضمينها كجزء من النتيجة. يجب على أي مستند JSON تقييم الشروط المحددة إلى «true» ليتم تضمينها في النتيجة.
على سبيل المثال:
استرداد جميع المهام التي تستهدف جهازا معينا
SELECT * FROM devices.jobs WHERE devices.jobs.deviceId = 'myDeviceId'
يتم وصف الشروط المسموح بها في قسم التعبيرات والشروط .
عبارة GROUP BY
عبارة GROUP_SPECIFICATION> GROUP BY <اختيارية. يتم تنفيذ هذه العبارة بعد عامل التصفية المحدد في عبارة WHERE، وقبل الإسقاط المحدد في SELECT. إنها تقوم بتجميع المستندات بناءً على قيمة السمة. يتم استخدام هذه المجموعات لإنشاء قيم مجمعة على النحو محدد في عبارة SELECT.
على سبيل المثال:
إرجاع عدد الأجهزة التي تقوم بالإبلاغ عن كل حالة تكوين بيانات تتبع الاستخدام
SELECT properties.reported.telemetryConfig.status AS status, COUNT() AS numberOfDevices FROM devices GROUP BY properties.reported.telemetryConfig.status
يتم حاليًا دعم عبارة GROUP BY فقط عند الاستعلام عن توائم الجهاز.
تنبيه
يتم التعامل مع المصطلح group
حاليًا على أنه كلمة أساسية خاصة في الاستعلامات. في حالة استخدام group
على أنه اسم خاصية، ضع في اعتبارك إحاطته بأقواس مزدوجة لتجنب الأخطاء، على سبيل المثال، SELECT * FROM devices WHERE tags.[[group]].name = 'some_value'
.
الصيغة الرسمية لـ GROUP BY هي:
GROUP BY <group_by_element>
<group_by_element> :==
attribute_name
| < group_by_element > '.' attribute_name
يشير Attribute_name إلى أي خاصية لمستند JSON داخل مجموعة FROM.
ترقيم صفحات نتائج الاستعلام
يتم إنشاء مثيل لكائن استعلام بحجم صفحة أقصى أقل من أو يساوي 100 سجل. للحصول على صفحات متعددة، اتصل ب nextAsTwin على Node.js SDK أو GetNextAsTwinAsync على أسلوب .Net SDK عدة مرات. يمكن لعنصر الاستعلام عرض قيم Next متعددة، اعتمادا على خيار إلغاء التسلسل المطلوب من قبل الاستعلام. على سبيل المثال، يمكن لعنصر استعلام إرجاع كائنات توأم الجهاز أو الوظيفة، أو JSON العادي عند استخدام الإسقاطات.
التعبيرات والشروط
على مستوى عالٍ، تعبير:
- يقيّم إلى مثيل من نوع JSON (مثل منطقي أو رقم أو سلسلة أو صفيف أو عنصر).
- يتم تعريفه من خلال معالجة البيانات القادمة من مستند JSON للجهاز والثوابت التي تستخدم عوامل التشغيل والوظائف المضمنة.
الشروط هي تعبيرات يتم تقييمها إلى قيمة منطقية. أي ثابت مختلف عن القيمة المنطقية true يعتبر خطأ. تشمل هذه القاعدة قيمة خالية وغير محددة وأي عنصر أو مثيل صفيف، وأي سلسلة، والقيمة المنطقية false.
صيغة التعبيرات هي:
<expression> ::=
<constant> |
attribute_name |
<function_call> |
<expression> binary_operator <expression> |
<create_array_expression> |
'(' <expression> ')'
<function_call> ::=
<function_name> '(' expression ')'
<constant> ::=
<undefined_constant>
| <null_constant>
| <number_constant>
| <string_constant>
| <array_constant>
<undefined_constant> ::= undefined
<null_constant> ::= null
<number_constant> ::= decimal_literal | hexadecimal_literal
<string_constant> ::= string_literal
<array_constant> ::= '[' <constant> [, <constant>]+ ']'
لفهم ما يمثله كل رمز في صيغة التعبيرات، انظر الجدول التالي:
الرمز | التعريف |
---|---|
attribute_name | أي خاصية لمستند JSON في المجموعة FROM. |
binary_operator | أي عامل تشغيل ثنائي يتم إدراجه في القسم عوامل التشغيل. |
function_name | أي دالة يتم إدراجها في القسم الدوال. |
decimal_literal | عدد عشري معبر عنه بالتدوين العشري. |
hexadecimal_literal | رقم يتم التعبير عنه بالسلسلة «0x» متبوع بسلسلة من الأرقام السداسية العشرية. |
string_literal | سلاسل Unicode ممثلة بتسلسل من صفر أو أكثر من أحرف Unicode أو تسلسلات الإلغاء. يتم وضع القيم الحرفية للسلاسل بين علامتي اقتباس مفردتين أو علامتي اقتباس مزدوجتين. عمليات الهروب المسموح بها: \' ، \" ، \\ ، \uXXXX لأحرف Unicode المعرفة بأربعة أرقام سداسية عشرية. |
العوامل
يتم دعم العوامل التالية:
العائلة | العوامل |
---|---|
حسابي | +, -, *, /, % |
منطقي | AND, OR, NOT |
المقارنة | =, !=, <, >, <=, =, ><> |
الوظائف
عند الاستعلام عن التوائم والوظائف، فإن الوظيفة الوحيدة المدعومة هي:
الوظيفة | الوصف |
---|---|
IS_DEFINED(property) | تُرجع قيمة منطقية تشير إلى ما إذا كان قد تم تعيين قيمة للخاصية (بما في ذلك null ). |
في ظروف المسارات، تُدعم وظائف الرياضيات التالية:
الوظيفة | الوصف |
---|---|
ABS(x) | ترجع القيمة المطلقة (الموجبة) للتعبير الرقمي المحدد. |
EXP(x) | تُرجع القيمة الأسية للتعبير الرقمي المحدد (e^x). |
POWER(x,y) | تُرجع قيمة التعبير المحدد إلى القوة المحددة (x^y). |
SQUARE(x) | تقوم بإرجاع مربع القيمة الرقمية المحددة. |
CEILING(x) | مسؤول عن إرجاع أصغر قيمة عدد صحيح أكبر من التعبير الرقمي المحدد أو مساوياً له. |
FLOOR(x) | يقوم بإرجاع أكبر عدد صحيح أقل من التعبير الرقمي المحدد أو يساويه. |
SIGN(x) | تُرجع هذه الدالة الموجبة (+1)، أو الصفر (0)، أو السالب (-1) للتعبير الرقمي المحدد. |
SQRT(x) | تقوم بإرجاع الجذر التربيعي للقيمة الرقمية المحددة. |
في ظروف المسارات، تُدعم وظائف التحقق من النوع والإرسال التالية:
الوظيفة | الوصف |
---|---|
AS_NUMBER | تحوّل سلسلة الإدخال لرقم. noop إذا كان الإدخال رقما؛ Undefined إذا كانت السلسلة لا تمثل رقما. |
IS_ARRAY | ترجع قيمة منطقية تشير إلى ما إذا كان نوع التعبير المحدد عبارة عن صفيف. |
IS_BOOL | إرجاع قيمة منطقية تشير إلى ما إذا كان نوع التعبير المحدد منطقي. |
IS_DEFINED | يرجع منطقية تشير إلى ما إذا تم تعيين قيمة للخاصية. يتم دعم هذه الدالة فقط عندما تكون القيمة من النوع الأولي. تشمل الأنواع البدائية سلسلة أو منطقية أو رقمية أو null . DateTime وأنواع الكائنات والصفائف غير مدعومة. |
IS_NULL | إرجاع قيمة منطقية تشير إلى ما إذا كان نوع التعبير المحدد خالياً. |
IS_NUMBER | ترجع قيمة منطقية تشير إلى ما إذا كان نوع التعبير المحدد عبارة عن رقم. |
IS_OBJECT | إرجاع قيمة منطقية تشير إلى ما إذا كان نوع التعبير المحدد يكون عنصر JSON. |
IS_PRIMITIVE | تُرجع قيمة منطقية تشير إلى ما إذا كان نوع التعبير المحدد بدائيًا (سلسلة أو منطقية أو رقمية أو null ). |
IS_STRING | يقوم بإرجاع قيمة منطقية تشير إلى ما إذا كان نوع التعبير المحدد عبارة عن سلسلة. |
في ظروف المسارات، تُدعم وظائف السلسلة التالية:
الوظيفة | الوصف |
---|---|
CONCAT(x, y, …) | تُرجع سلسلة ناتجة عن تسلسل قيمتين أو أكثر من قيم السلسلة. |
LENGTH(x) | تُرجع عدد أحرف تعبير السلسلة المحدد. |
LOWER(x) | استعادة التسلسل السريع بعد تحويل بيانات الأحرف الكبيرة إلى أحرف صغيرة. |
UPPER(x) | يرجع تعبير سلسلة بعد تحويل بيانات الأحرف الصغيرة إلى أحرف كبيرة. |
SUBSTRING(string, start [, length]) | تُرجع جزءاً من تعبير سلسلة يبدأ من الموضع الصفري للحرف المحدد ويستمر حتى الطول المحدد، أو حتى نهاية السلسلة. |
INDEX_OF(string, fragment) | إرجاع موضع البداية للتكبير الأول لتعبير السلسلة الثاني ضمن تعبير السلسلة المحدد الأول، أو -1 إذا لم يتم العثور على السلسلة. |
STARTSWITH(x, y) | إرجاع قيمة منطقية تشير إلى ما إذا كان تعبير السلسلة الأول يبدأ بالتعبير الثاني. |
ENDSWITH(x, y) | إرجاع قيمة منطقية تشير إلى ما إذا كان تعبير السلسلة الأول ينتهي بالتعبير الثاني. |
تحتوي على (س، ص) | إرجاع تعبير منطقي يشير إلى ما إذا كان تعبير السلسلة الأولى يطابق الثاني. |
أمثلة الاستعلام باستخدام حزم SDK للخدمة
مثال C#
يتم عرض وظيفة الاستعلام من قِبل لـ SDK لخدمة C# في فئة RegistryManager.
فيما يلي مثال على استعلام بسيط:
var query = registryManager.CreateQuery("SELECT * FROM devices", 100);
while (query.HasMoreResults)
{
var page = await query.GetNextAsTwinAsync();
foreach (var twin in page)
{
// do work on twin object
}
}
يتم إنشاء مثيل لكائن الاستعلام مع المعلمات المذكورة في قسم ترقيم الصفحات لنتائج الاستعلام. يتم استرداد صفحات متعددة عن طريق استدعاء أساليب GetNextAsTwinAsync عدة مرات.
مثال على Node.js
يتم عرض وظيفة الاستعلام من قِبل SDK لخدمة Azure IoT لـ Node.js في عنصر السجل.
فيما يلي مثال على استعلام بسيط:
var query = registry.createQuery('SELECT * FROM devices', 100);
var onResults = function(err, results) {
if (err) {
console.error('Failed to fetch the results: ' + err.message);
} else {
// Do something with the results
results.forEach(function(twin) {
console.log(twin.deviceId);
});
if (query.hasMoreResults) {
query.nextAsTwin(onResults);
}
}
};
query.nextAsTwin(onResults);
يتم إنشاء مثيل لكائن الاستعلام مع المعلمات المذكورة في قسم ترقيم الصفحات لنتائج الاستعلام. يتم استرداد صفحات متعددة عن طريق استدعاء الأسلوب NextAsTwin عدة مرات.
الخطوات التالية
- تعرف على توجيه الرسائل استنادا إلى خصائص الرسالة أو نص الرسالة باستخدام بناء جملة استعلام توجيه رسالة IoT Hub.
- احصل على أمثلة محددة من الاستعلامات لتوائم الجهاز والوحدة النمطية أو استعلامات الوظائف.