كيفية استخدام واجهة برمجة تطبيقات 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.

تلميح

يمكنك استخدام Postman لتجربة استدعاءات واجهة برمجة تطبيقات REST الموضحة في هذه المقالة. قم بتنزيل مجموعة IoT Central Postman واستوردها إلى Postman. في المجموعة، ستحتاج إلى تعيين متغيرات مثل المجال الفرعي للتطبيق والرمز المميز للمسؤول.

لمعرفة كيفية الاستعلام عن الأجهزة باستخدام واجهة مستخدم 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 وقم بالمرور فوق جهاز يستخدم القالب. تتضمن البطاقة معرف قالب الجهاز:

لقطة شاشة توضح كيفية العثور على معرف قالب الجهاز في عنوان URL للصفحة.

تتضمن الاستجابة بيانات تتبع الاستخدام من أجهزة متعددة تشترك في نفس قالب الجهاز. تبدو الاستجابة لهذا الطلب مثل المثال التالي:

{
  "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وAVGFIRSTMINCOUNT.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 لإدارة المستخدمين والأدوار.