استعلامات لجهاز IoT Hub وتوائم الوحدة النمطية

يمكن أن تحتوي توائم الجهاز وتوائم الوحدة على عناصر JSON عشوائية كعلامات وخصائص على حدٍّ سواء. تمكّنك IoT Hub من الاستعلام عن توائم الجهاز وتوائم الوحدة كمستند JSON واحد يحتوي على جميع المعلومات التوأمية.

فيما يلي نموذج لجهاز IoT hub twin (ستكون الوحدة المزدوجة مشابهة تماما مع معلمة ل moduleId):

{
    "deviceId": "myDeviceId",
    "etag": "AAAAAAAAAAc=",
    "status": "enabled",
    "statusUpdateTime": "0001-01-01T00:00:00",
    "connectionState": "Disconnected",
    "lastActivityTime": "0001-01-01T00:00:00",
    "cloudToDeviceMessageCount": 0,
    "authenticationType": "sas",
    "x509Thumbprint": {
        "primaryThumbprint": null,
        "secondaryThumbprint": null
    },
    "version": 2,
    "tags": {
        "location": {
            "region": "US",
            "plant": "Redmond43"
        }
    },
    "properties": {
        "desired": {
            "telemetryConfig": {
                "configId": "db00ebf5-eeeb-42be-86a1-458cccb69e57",
                "sendFrequencyInSecs": 300
            },
            "$metadata": {
            ...
            },
            "$version": 4
        },
        "reported": {
            "connectivity": {
                "type": "cellular"
            },
            "telemetryConfig": {
                "configId": "db00ebf5-eeeb-42be-86a1-458cccb69e57",
                "sendFrequencyInSecs": 300,
                "status": "Success"
            },
            "$metadata": {
            ...
            },
            "$version": 7
        }
    }
}

الاستعلامات المزدوجة في الجهاز

تعرض IoT Hub توائم الجهاز كمجموعة مستندات تسمى devices. على سبيل المثال، يسترد الاستعلام الأساسي مجموعة كاملة من توائم الجهاز:

SELECT * FROM devices

ملاحظة

تقوم SDK لـ Azure IoT بدعم ترحيل النتائج الكبيرة.

يمكنك تجميع نتائج استعلام باستخدام عبارة SELECT. على سبيل المثال، يحصل الاستعلام التالي على العدد الإجمالي للأجهزة في مركز إنترنت الأشياء:

SELECT COUNT() as totalNumberOfDevices FROM devices

تصفية نتائج الاستعلام باستخدام عبارة WHERE. على سبيل المثال، لتلقي توائم الجهاز حيث يتم تعيين علامة location.region إلى الولايات المتحدة ، استخدم الاستعلام التالي:

SELECT * FROM devices
WHERE tags.location.region = 'US'

إنشاء عبارات WHERE المعقدة باستخدام عوامل التشغيل المنطقية والمقارنات الحسابية. على سبيل المثال، يسترد الاستعلام التالي توائم الجهاز الموجودة في الولايات المتحدة ويتم تكوينها لإرسال بيانات تتبع الاستخدام أقل من كل دقيقة:

SELECT * FROM devices
  WHERE tags.location.region = 'US'
    AND properties.reported.telemetryConfig.sendFrequencyInSecs >= 60

يمكنك أيضا استخدام ثوابت الصفيف مع عاملي التشغيل INوNN (غير داخل). على سبيل المثال، يسترد الاستعلام التالي توائم الجهاز التي تبلغ إما عن WiFi أو الاتصال السلكي:

SELECT * FROM devices
  WHERE properties.reported.connectivity IN ['wired', 'wifi']

غالبا ما يكون من الضروري تحديد جميع توائم الجهاز التي تحتوي على خاصية معينة. تدعم IoT Hub الوظيفة is_defined() لهذا الغرض. على سبيل المثال، يسترد الاستعلام التالي توائم الجهاز التي تحدد الخاصية connectivity :

SELECT * FROM devices
  WHERE is_defined(properties.reported.connectivity)

ارجع إلى القسم عبارة WHERE للحصول على المرجع الكامل لإمكانيات التصفية.

يتم دعم التجميع أيضًا. على سبيل المثال، يقوم الاستعلام التالي بإرجاع عدد الأجهزة في كل حالة تكوين بيانات تتبع الاستخدام:

SELECT properties.reported.telemetryConfig.status AS status,
    COUNT() AS numberOfDevices
  FROM devices
  GROUP BY properties.reported.telemetryConfig.status

قد يعرض استعلام التجميع هذا نتيجة مشابهة للمثال التالي:

[
    {
        "numberOfDevices": 3,
        "status": "Success"
    },
    {
        "numberOfDevices": 2,
        "status": "Pending"
    },
    {
        "numberOfDevices": 1,
        "status": "Error"
    }
]

في هذا المثال، أبلغت ثلاثة أجهزة عن نجاح التكوين ولا يزال اثنان يطبقان التكوين وأبلغ جهاز واحد عن خطأ.

تسمح استعلامات الإسقاط للمطورين بإعادة الخصائص التي يهتمون بها فقط. على سبيل المثال، لاسترداد وقت النشاط الأخير جنبًا إلى جنب مع معرّف الجهاز لجميع الأجهزة الممكّنة التي تم قطع اتصالها، استخدم الاستعلام التالي:

SELECT DeviceId, LastActivityTime FROM devices WHERE status = 'enabled' AND connectionState = 'Disconnected'

ستبدو نتيجة هذا الاستعلام مثل المثال التالي:

[
  {
    "deviceId": "AZ3166Device",
    "lastActivityTime": "2021-05-07T00:50:38.0543092Z"
  }
]

استعلامات توأم الوحدة

الاستعلام عن توائم الوحدة مشابه للاستعلام عن توائم الجهاز، ولكن يستخدم مجموعة/مساحة اسم مختلفة؛ بدلاً من الاستعلام من devices، تستعلم من devices.modules:

SELECT * FROM devices.modules

لا نسمح بالربط بين مجموعات الأجهزة وdevices.modules. إذا كنت ترغب في الاستعلام عن توائم الوحدة عبر الأجهزة، يمكنك القيام بذلك بناءً على العلامات. يقوم الاستعلام التالي بإرجاع جميع توائم الوحدة النمطية عبر جميع الأجهزة بحالة الفحص:

SELECT * FROM devices.modules WHERE properties.reported.status = 'scanning'

يرجع الاستعلام التالي جميع توائم الوحدة النمطية بحالة الفحص، ولكن فقط على المجموعة الفرعية المحددة من الأجهزة:

SELECT * FROM devices.modules
  WHERE properties.reported.status = 'scanning'
  AND deviceId IN ['device1', 'device2']

قيود الاستعلام المزدوج

هام

نتائج الاستعلام هي عمليات متسقة في النهاية ويجب التسامح مع التأخيرات التي تصل إلى 30 دقيقة. في معظم الحالات، يقوم الاستعلام المزدوج بإرجاع النتائج بترتيب بضع ثوان. يسعى مركز IoT إلى تخفيض زمن الانتقال في جميع العمليات. ومع ذلك، بسبب ظروف الشبكة وعوامل أخرى لا يمكن التنبؤ بها فإنه لا يمكن ضمان زمن انتقال محدد.

يتمثل الخيار البديل للاستعلامات المزدوجة في الاستعلام عن توائم الجهاز الفردية حسب المعرف باستخدام واجهة برمجة تطبيقات get twin REST. تُرجع واجهة برمجة التطبيقات هذه دائمًا أحدث القيم ولها حدود تقييد أعلى. يمكنك إصدار واجهة برمجة تطبيقات REST مباشرةً أو استخدام الوظائف المكافئة في أي منحزم SDK لخدمة Azure IoT Hub.

يمكن أن يبلغ الحد الأقصى لطول تعبيرات الاستعلام 8192 حرفًا.

يتم حاليًا دعم المقارنات فقط بين الأنواع البدائية (لا توجد عناصر)، على سبيل المثال، يتم دعم ... WHERE properties.desired.config = properties.reported.config فقط إذا كانت هذه الخصائص لها قيم بدائية.

نوصي بعدم الاعتماد على lastActivityTime الموجود في خصائص هوية الجهاز للاستعلامات المزدوجة لأي سيناريو. لا يضمن هذا الحقل مقياسا دقيقا لحالة الجهاز. بدلا من ذلك، يرجى استخدام أحداث دورة حياة جهاز IoT لإدارة حالة الجهاز وأنشطته. لمزيد من المعلومات حول كيفية استخدام أحداث دورة حياة IoT Hub في الحل الخاص بك، يرجى زيارة React إلى أحداث IoT Hub باستخدام Event Grid لتشغيل الإجراءات.

ملاحظة

تجنب وضع أي افتراضات حول الحد الأقصى لزمن الانتقال لهذه العملية. يرجى الرجوع إلى حلول زمن الانتقال لمزيد من المعلومات حول كيفية إنشاء الحل الخاص بك مع مراعاة زمن الانتقال.

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

• فهم أساسيات لغة استعلام IoT Hub