كيفية استخدام واجهة برمجة تطبيقات REST ل IoT Central للاستعلام عن الأجهزة
تتيح لك واجهة برمجة تطبيقات REST في IoT Central تطوير تطبيقات العميل التي تتكامل مع تطبيقات IoT Central. يمكنك استخدام واجهة برمجة تطبيقات REST للاستعلام عن الأجهزة في تطبيق IoT Central. فيما يلي أمثلة على كيفية استخدام الاستعلام REST API:
- احصل على آخر 10 قيم بيانات تتبع الاستخدام تم الإبلاغ عنها بواسطة جهاز.
- ابحث عن جميع الأجهزة التي تكون في حالة خطأ ولديها برامج ثابتة قديمة.
- اتجاهات بيانات تتبع الاستخدام من الأجهزة، متوسطها في نوافذ مدتها 10 دقائق.
- احصل على إصدار البرنامج الثابت الحالي لجميع أجهزة منظم الحرارة.
توضح هذه المقالة كيفية استخدام /query
واجهة برمجة التطبيقات للاستعلام عن الأجهزة.
يمكن للجهاز تجميع الخصائص وبيانات تتبع الاستخدام والأوامر التي يدعمها في المكونات والوحدات النمطية.
يتطلب كل استدعاء لواجهة برمجة تطبيقات REST ل IoT Central عنوان تخويل. لمعرفة المزيد، راجع كيفية مصادقة وتخويل استدعاءات واجهة برمجة تطبيقات REST ل IoT Central.
للحصول على الوثائق المرجعية لواجهة برمجة تطبيقات REST ل IoT Central، راجع مرجع واجهة برمجة تطبيقات REST ل Azure IoT Central.
لمعرفة كيفية الاستعلام عن الأجهزة باستخدام واجهة مستخدم IoT Central، راجع كيفية استخدام مستكشف البيانات لتحليل بيانات الجهاز.
تشغيل استعلام
استخدم الطلب التالي لتشغيل استعلام:
POST https://{your app subdomain}.azureiotcentral.com/api/query?api-version=2022-10-31-preview
الاستعلام موجود في نص الطلب ويبدو مثل المثال التالي:
{
"query": "SELECT $id, $ts, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D)"
}
dtmi:eclipsethreadx:devkit:hlby5jgib2o
القيمة في العبارة FROM
هي معرف قالب الجهاز. للعثور على معرف قالب جهاز، انتقل إلى صفحة الأجهزة في تطبيق IoT Central وقم بالمرور فوق جهاز يستخدم القالب. تتضمن البطاقة معرف قالب الجهاز:
تتضمن الاستجابة بيانات تتبع الاستخدام من أجهزة متعددة تشترك في نفس قالب الجهاز. تبدو الاستجابة لهذا الطلب مثل المثال التالي:
{
"results": [
{
"$id": "sample-003",
"$ts": "2021-09-10T12:59:52.015Z",
"temperature": 47.632160152311016,
"humidity": 49.726422005390816
},
{
"$id": "sample-001",
"$ts": "2021-09-10T13:01:34.286Z",
"temperature": 58.898120617808495,
"humidity": 44.66125772328022
},
{
"$id": "sample-001",
"$ts": "2021-09-10T13:04:04.96Z",
"temperature": 52.79601469228174,
"humidity": 71.5067230188416
},
{
"$id": "sample-002",
"$ts": "2021-09-10T13:04:36.877Z",
"temperature": 49.610062789623264,
"humidity": 52.78538601804491
}
]
}
بناء الجملة
بناء جملة الاستعلام مشابه لبناء جملة SQL و يتكون من العبارات التالية:
SELECT
مطلوب ويحدد البيانات التي تريد استردادها، مثل قيم بيانات تتبع الاستخدام للجهاز.FROM
مطلوب ويحدد نوع الجهاز الذي تقوم بالاستعلام. تحدد هذه العبارة معرف قالب الجهاز.WHERE
اختياري ويتيح لك تصفية النتائج.ORDER BY
اختياري ويتيح لك فرز النتائج.GROUP BY
اختياري ويتيح لك تجميع النتائج.
تصف الأقسام التالية هذه العبارات بمزيد من التفصيل.
عبارة SELECT
تسرد SELECT
العبارة قيم البيانات المراد تضمينها في إخراج الاستعلام ويمكن أن تتضمن العناصر التالية:
- بيانات تتبع الاستخدام. استخدم أسماء بيانات تتبع الاستخدام من قالب الجهاز.
$id
. معرف الجهاز$provisioned
. قيمة منطقية تظهر ما إذا كان الجهاز قد تم توفيره حتى الآن.$simulated
. قيمة منطقية تظهر ما إذا كان الجهاز جهاز محاكاة.$ts
. الطابع الزمني المقترن بقيمة بيانات تتبع الاستخدام.
إذا كان قالب جهازك يستخدم مكونات، فستشير إلى القياس عن بعد المحدد في المكون كما يلي:
{
"query": "SELECT ComponentName.TelemetryName FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o"
}
يمكنك العثور على اسم المكون في قالب الجهاز:
تنطبق الحدود التالية في SELECT
عبارة :
- لا يوجد عامل تشغيل حرف بدل.
- لا يمكنك الحصول على أكثر من 15 عنصرا في قائمة التحديد.
- يقوم الاستعلام بإرجاع 10000 سجل كحد أقصى.
الأسماء المستعارة
AS
استخدم الكلمة الأساسية لتعريف اسم مستعار لعنصر في SELECT
عبارة . يتم استخدام الاسم المستعار في إخراج الاستعلام. يمكنك أيضا استخدامه في مكان آخر في الاستعلام. على سبيل المثال:
{
"query": "SELECT $id as ID, $ts as timestamp, temperature as t, pressure as p FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D) AND t > 0 AND p > 50"
}
تلميح
لا يمكنك استخدام عنصر آخر في قائمة التحديد باعتباره اسما مستعارا. على سبيل المثال، ما يلي غير مسموح به SELECT id, temp AS id...
.
تبدو النتيجة مثل الإخراج التالي:
{
"results": [
{
"ID": "sample-002",
"timestamp": "2021-09-10T11:40:29.188Z",
"t": 40.20355053736378,
"p": 79.26806508746755
},
{
"ID": "sample-001",
"timestamp": "2021-09-10T11:43:42.61Z",
"t": 68.03536237975348,
"p": 58.33517075380311
}
]
}
TOP
TOP
استخدم للحد من عدد النتائج التي يرجعها الاستعلام. على سبيل المثال، يرجع الاستعلام التالي أول 10 نتائج:
{
"query": "SELECT TOP 10 $id as ID, $ts as timestamp, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o"
}
إذا لم تستخدم TOP
، يرجع الاستعلام 10000 نتيجة كحد أقصى.
لفرز النتائج قبل TOP
تحديد عدد النتائج، استخدم ORDER BY.
عبارة FROM
FROM
يجب أن تحتوي العبارة على معرف قالب الجهاز. FROM
تحدد العبارة نوع الجهاز الذي تقوم بالاستعلام.
للعثور على معرف قالب جهاز، انتقل إلى صفحة الأجهزة في تطبيق IoT Central وقم بالمرور فوق جهاز يستخدم القالب. تتضمن البطاقة معرف قالب الجهاز:
يمكنك أيضا استخدام الأجهزة - الحصول على استدعاء واجهة برمجة تطبيقات REST للحصول على معرف قالب الجهاز للجهاز.
عبارة WHERE
WHERE
تتيح لك عبارة استخدام القيم ونوافذ الوقت لتصفية النتائج:
الإطارات الزمنية
للحصول على بيانات تتبع الاستخدام التي يتلقاها التطبيق الخاص بك خلال نافذة زمنية محددةWHERE
، استخدم WITHIN_WINDOW
كجزء من عبارة . على سبيل المثال، لاسترداد القياس عن بعد لدرجة الحرارة والرطوبة لليوم الأخير، استخدم الاستعلام التالي:
{
"query": "SELECT $id, $ts, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D)"
}
تستخدم قيمة النافذة الزمنية تنسيق مدد ISO 8601. يتضمن الجدول التالي بعض الأمثلة:
مثال | الوصف |
---|---|
PT10M | آخر 10 دقائق |
P1D | اليوم الماضي |
P2DT12H | آخر يومين و12 ساعة |
P1W | الأسبوع الماضي |
PT5H | الساعات الخمس الماضية |
'2021-06-13T13:00:00Z/2021-06-13T15:30:00Z' | نطاق زمني محدد |
مقارنات القيم
يمكنك الحصول على بيانات تتبع الاستخدام استنادا إلى قيم محددة. على سبيل المثال، يرجع الاستعلام التالي جميع الرسائل حيث تكون درجة الحرارة أكبر من الصفر، والضغط أكبر من 50، ومعرف الجهاز هو واحد من sample-002 و sample-003:
{
"query": "SELECT $id, $ts, temperature AS t, pressure AS p FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D) AND t > 0 AND p > 50 AND $id IN ['sample-002', 'sample-003']"
}
يتم دعم العوامل التالية:
- عوامل التشغيل المنطقية
AND
وOR
. - عوامل المقارنة
=
و!=
>
و<
و>=
<=
<>
.IN
إشعار
IN
عامل التشغيل يعمل فقط مع بيانات تتبع الاستخدام و$id
.
تنطبق الحدود التالية في WHERE
عبارة :
- يمكنك استخدام 10 عوامل تشغيل كحد أقصى في استعلام واحد.
- في استعلام، يمكن أن تحتوي العبارة
WHERE
على عوامل تصفية بيانات تعريف الجهاز وبيانات تتبع الاستخدام فقط. - في استعلام، يمكنك استرداد ما يصل إلى 10000 سجل.
التجميعات وعبارة GROUP BY
تتيح لك وظائف التجميع حساب قيم مثل المتوسط والحد الأقصى والحد الأدنى لبيانات تتبع الاستخدام ضمن إطار زمني. على سبيل المثال، يحسب الاستعلام التالي متوسط درجة الحرارة والرطوبة من الجهاز sample-001
في نوافذ مدتها 10 دقائق:
{
"query": "SELECT AVG(temperature), AVG(pressure) FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D) AND $id='{{DEVICE_ID}}' GROUP BY WINDOW(PT10M)"
}
تبدو النتائج مثل الإخراج التالي:
{
"results": [
{
"$ts": "2021-09-14T11:40:00Z",
"avg_temperature": 49.212146114456104,
"avg_pressure": 48.590304135023764
},
{
"$ts": "2021-09-14T11:30:00Z",
"avg_temperature": 52.44844454703927,
"avg_pressure": 52.25973211022142
},
{
"$ts": "2021-09-14T11:20:00Z",
"avg_temperature": 50.14626272506926,
"avg_pressure": 48.98400386898757
}
]
}
يتم دعم وظائف التجميع التالية: SUM
و MAX
وAVG
FIRST
MIN
COUNT
.LAST
استخدم GROUP BY WINDOW
لتحديد حجم النافذة. إذا لم تستخدم GROUP BY WINDOW
، يقوم الاستعلام بتجميع بيانات تتبع الاستخدام على مدار آخر 30 يوما.
إشعار
يمكنك فقط تجميع قيم بيانات تتبع الاستخدام.
عبارة ORDER BY
ORDER BY
تتيح لك العبارة فرز نتائج الاستعلام حسب قيمة بيانات تتبع الاستخدام أو الطابع الزمني أو معرف الجهاز. يمكنك الفرز بترتيب تصاعدي أو تنازلي. على سبيل المثال، يقوم الاستعلام التالي بإرجاع أحدث النتائج أولا:
{
"query": "SELECT $id as ID, $ts as timestamp, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o ORDER BY timestamp DESC"
}
تلميح
ادمج ORDER BY
مع TOP
لتحديد عدد النتائج التي يرجعها الاستعلام بعد الفرز.
الحدود
الحدود الحالية للاستعلامات هي:
- لا يزيد عن 15 عنصرا في
SELECT
قائمة العبارات. - لا يزيد عن 10 عمليات منطقية
WHERE
في عبارة . - الحد الأقصى لطول سلسلة الاستعلام هو 350 حرفا.
- لا يمكنك استخدام حرف البدل (
*
) فيSELECT
قائمة العبارات. - يمكن للاستعلامات استرداد ما يصل إلى 10000 سجل.
الخطوات التالية
الآن بعد أن تعلمت كيفية الاستعلام عن الأجهزة باستخدام واجهة برمجة تطبيقات REST، فإن الخطوة التالية المقترحة هي معرفة كيفية استخدام واجهة برمجة تطبيقات REST ل IoT Central لإدارة المستخدمين والأدوار.