لغة استعلام IoT Hub لتوائم الجهاز والوحدة والوظائف وتوجيه الرسائل

مقالة
06/01/2023

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

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

للحصول على أمثلة محددة، راجع استعلامات الجهاز والوحدة النمطية المزدوجة أو الاستعلامات للوظائف.

ملاحظة

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

تشغيل استعلامات IoT Hub

يمكنك تشغيل الاستعلامات مقابل مركز IoT مباشرة في Azure-Portal.

سجل الدخول إلى مدخل Microsoft Azure والانتقال إلى IoT hub الخاص بك.
حدد Queries من قسم Device management في قائمة التنقل.
أدخل الاستعلام في مربع النص وحدد تشغيل الاستعلام.

يمكنك أيضا تشغيل الاستعلامات داخل تطبيقاتك باستخدام حزم SDK لخدمة Azure IoT وواجهات برمجة تطبيقات الخدمة.

على سبيل المثال، التعليمات البرمجية التي تنفذ استعلامات IoT Hub، راجع قسم أمثلة الاستعلام مع حزم SDK للخدمة.

للحصول على ارتباطات إلى صفحات وعينات مرجع SDK، راجع Azure IoT SDKs.

أساسيات استعلام IoT Hub

يتكون كل استعلام IoT Hub من عبارات SELECT وFROM مع عبارات WHERE وGROUP BY الاختيارية.

يتم تشغيل الاستعلامات على مجموعة من مستندات JSON، على سبيل المثال توائم الجهاز. تشير عبارة FROM إلى مجموعة المستندات المراد تكرارها (إما الأجهزة أو devices.modules أو 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.
احصل على أمثلة محددة من الاستعلامات لتوائم الجهاز والوحدة النمطية أو الاستعلامات للوظائف.

لغة استعلام IoT Hub لتوائم الجهاز والوحدة والوظائف وتوجيه الرسائل

تشغيل استعلامات IoT Hub

أساسيات استعلام IoT Hub

عبارة SELECT

عبارة FROM

عبارة WHERE

عبارة GROUP BY

ترقيم صفحات نتائج الاستعلام

التعبيرات والشروط

المشغلون

الوظائف

أمثلة الاستعلام باستخدام حزم SDK للخدمة

مثال C#‎

مثال على Node.js

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

الموارد الإضافية