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

مقالة
06/13/2024

توفر 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.
احصل على أمثلة محددة من الاستعلامات لتوائم الجهاز والوحدة النمطية أو استعلامات الوظائف.

مشاركة عبر

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

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

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

عبارة SELECT

عبارة FROM

عبارة WHERE

عبارة GROUP BY

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

العوامل

الوظائف

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

مثال C#‎

مثال على Node.js

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

الملاحظات

الملاحظات

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