فهم واستدعاء الأساليب المباشرة من مركز IoT

  • مقالة

يمنحك IoT Hub القدرة على استدعاء طرق مباشرة على الأجهزة من السحابة. تمثل الطرق المباشرة تفاعلًا بين الطلب والرد مع جهاز مشابه لاستدعاء HTTP من حيث أنها تنجح أو تفشل على الفور (بعد انتهاء مهلة يحددها المستخدم). هذا النهج مفيد للسيناريوهات التي يكون فيها مسار الإجراء الفوري مختلفًا تبعًا لما إذا كان الجهاز قادرًا على الاستجابة.

ملاحظة

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

كل أسلوب مباشر يستهدف جهاز واحد. يوضح جدولة المهام على أجهزة متعددة كيفية توفير طريقة لاستدعاء الأساليب المباشرة على أجهزة متعددة، وجدولة استدعاء الأسلوب للأجهزة غير المتصلة.

يجوز لأي شخص لديه أذونات اتصال الخدمة على مركز IoT استدعاء أسلوب الجهاز.

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

راجع إرشادات الاتصال من السحابة إلى الجهاز إذا كان هناك شك بين استخدام الخصائص المطلوبة أو الأساليب المباشرة أو الرسائل من السحابة إلى الجهاز.

دورة حياة الأسلوب

يتم تنفيذ الأساليب المباشرة على الجهاز وقد تتطلب صفرًا أو أكثر من المدخلات في حمولة الأسلوب للإنشاء بشكل صحيح. استدعاء أسلوب مباشر من خلال URI مواجهة للخدمة ({iot hub}/twins/{device id}/methods/). يتلقى الجهاز أسلوبًا مباشرة من خلال موضوع MQTT خاص بالجهاز ($iothub/methods/POST/{method name}/) أو من خلال روابط AMQP (وخصائص التطبيق IoThub-methodname وIoThub-status).

ملاحظة

عند استدعاء أسلوب مباشر على جهاز، يمكن أن تحتوي أسماء الخصائص والقيم على الأبجدية الرقمية القابلة للطباعة من ASCII بالولايات المتحدة فقط، باستثناء أي منها في المجموعة التالية:{'$', '(', ')', '<', '>', '@', ',', ';', ':', '\', '"', '/', '[', ']', '?', '=', '{', '}', SP, HT}

الطرق المباشرة متزامنة وإما أن تنجح أو تفشل بعد فترة المهلة (الافتراضي: 30 ثانية، يمكن ضبطها في نطاق 5 ثانية و 300 ثانية). تعتبر الطرق المباشرة مفيدة في السيناريوهات التفاعلية حيث تريد أن يعمل الجهاز إذا وفقط إذا كان الجهاز متصلاً بالإنترنت ويتلقى الأوامر. على سبيل المثال، تشغيل ضوء من هاتف. في هذه السيناريوهات، تريد أن ترى نجاحًا أو فشلًا فوريًا حتى تتمكن الخدمة السحابية من التصرف بناءً على النتيجة في أسرع وقت ممكن. قد يقوم الجهاز بإرجاع بعض نص الرسالة كنتيجة للطريقة، ولكن هذا ليس مطلوبًا للطريقة للقيام بذلك. لا يوجد ضمان على الطلب أو أي دلالات التزامن على استدعاءات الطريقة.

الأساليب المباشرة هي HTTPS فقط من جانب السحابة وMQTT أو AMQP أو MQTT عبر WebSockets أو AMQP عبر WebSockets من جانب الجهاز.

الحمولة لطلبات الطريقة والاستجابات هي مستند JSON يصل حجمه إلى 128 كيلوبايت.

استدعاء أسلوب مباشر من تطبيق نهاية خلفية

لاستدعاء أسلوب مباشر من تطبيق نهاية خلفية، استخدم واجهة برمجة تطبيقات REST لاستدعاء أسلوب الجهاز أو ما يعادلها في إحدى SDKs لخدمة IoT Hub.

استدعاء الأسلوب

استدعاءات الطريقة المباشرة على الجهاز هي استدعاءات HTTPS تتكون من العناصر التالية:

  • عنوان URI للطلب الخاص بالجهاز مع إصدار واجهة برمجة التطبيقات:

    https://fully-qualified-iothubname.azure-devices.net/twins/{deviceId}/methods?api-version=2021-04-12

  • أسلوب POST

  • العناوين التي تحتوي على التفويض ونوع المحتوى وترميز المحتوى.

  • نص JSON شفاف بالتنسيق التالي:

    {
    "connectTimeoutInSeconds": 200,
    "methodName": "reboot",
    "responseTimeoutInSeconds": 200,
    "payload": {
        "input1": "someInput",
        "input2": "anotherInput"
    }
}

القيمة المقدمة كما responseTimeoutInSecondsفي الطلب هي مقدار الوقت الذي يجب أن تنتظره خدمة مركز IoT لإكمال تنفيذ الأسلوب المباشر على الجهاز. عيِّن هذه المهلة بحيث تكون على الأقل بطول وقت التنفيذ المتوقع لطريقة مباشرة بواسطة الجهاز. إذا لم يتم توفير timeout، فسيتم استخدام القيمة الافتراضية وهي 30 ثانية. الحد الأدنى والحد الأقصى لقيمresponseTimeoutInSeconds هما 5 و300 ثانية، على التوالي.

القيمة المقدمة كما هو الحال connectTimeoutInSeconds في الطلب هي مقدار الوقت عند استدعاء أسلوب مباشر يجب أن تنتظره خدمة مركز IoT حتى يأتي جهاز غير متصل بالإنترنت. القيمة الافتراضية هي 0، ما يعني أنه يجب أن تكون الأجهزة متصلة بالفعل عند استدعاء أسلوب مباشر. الحد الأقصى لقيمة connectTimeoutInSeconds هو 300 ثانية.

مثال

سيسمح لك هذا المثال ببدء طلب بشكل آمن لاستدعاء أسلوب مباشر على جهاز IoT مسجل في مركز Azure IoT.

للبدء، استخدم ملحق Microsoft Azure IoT ل Azure CLI لإنشاء SharedAccessSignature.

az iot hub generate-sas-token -n <iothubName> --du <duration>

بعد ذلك، استبدل عنوان التخويل ب SharedAccessSignature الذي تم إنشاؤه حديثا، ثم قم بتعديل iothubNamedeviceIdmethodNameالمعلمات وpayload لمطابقة التنفيذ الخاص بك في الأمر المثال curl أدناه.

curl -X POST \
  https://<iothubName>.azure-devices.net/twins/<deviceId>/methods?api-version=2021-04-12\
  -H 'Authorization: SharedAccessSignature sr=iothubname.azure-devices.net&sig=x&se=x&skn=iothubowner' \
  -H 'Content-Type: application/json' \
  -d '{
    "methodName": "reboot",
    "responseTimeoutInSeconds": 200,
    "payload": {
        "input1": "someInput",
        "input2": "anotherInput"
    }
}'

تنفيذ الأمر المعدل لاستدعاء الأسلوب المباشر المحدد. سترجع الطلبات الناجحة رمز حالة HTTP 200.

ملاحظة

يوضح المثال أعلاه استدعاء أسلوب مباشر على جهاز. إذا كنت ترغب في استدعاء أسلوب مباشر في وحدة IoT Edge النمطية، فستحتاج إلى تعديل طلب url كما هو موضح أدناه:

https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12

الاستجابة

يتلقى تطبيق النهاية استجابة مكونة من العناصر التالية:

  • رمز حالة HTTP:

    • 200 يشير إلى التنفيذ الناجح للأسلوب المباشر؛
    • يشير 404 إلى أن إما معرف الجهاز غير صالح، أو أن الجهاز لم يكن متصلا بالإنترنت عند استدعاء أسلوب مباشر وبعد connectTimeoutInSeconds ذلك (استخدم رسالة الخطأ المصاحبة لفهم السبب الجذري)؛
    • يشير 504 إلى انتهاء مهلة البوابة بسبب عدم استجابة الجهاز لاستدعاء أسلوب مباشر داخل responseTimeoutInSeconds.

  • العناوين التي تحتوي على معرف الطلب ونوع المحتوى وترميز المحتوى.

  • نص JSON بالتنسيق التالي:

    {
    "status" : 201,
    "payload" : {...}
}

    يتم توفير كل من status وpayload من قبل الجهاز ويتم استخدامهما للرد برمز الحالة الخاص بالجهاز واستجابة الأسلوب.

استدعاء الأسلوب لوحدات IoT Edge

يتم دعم استدعاء الأساليب المباشرة في وحدة نمطية من خلال واجهة برمجة تطبيقات REST لاستدعاء لأسلوب الوحدة النمطية أو ما يعادلها في إحدى SDKs لخدمة IoT Hub.

يتم تمرير moduleId مع deviceId في URI للطلب عند استخدام واجهة برمجة تطبيقات REST أو كمعامل عند استخدام SDK للخدمة. على سبيل المثال، ⁧https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12⁩. يتشابه نص الطلب والاستجابة مع تلك الخاصة بالأساليب المباشرة التي يتم استدعاؤها على الجهاز.

معالجة أسلوب مباشر على جهاز

على جهاز IoT، يمكن تلقي الأساليب المباشرة عبر MQTT أو AMQP أو أي من هذه البروتوكولات عبر WebSockets. تساعدك SDKs لجهاز IoT Hub على تلقي الأساليب المباشرة على الأجهزة والاستجابة لها دون الحاجة إلى القلق بشأن تفاصيل البروتوكول الأساسية.

MQTT

المقطع التالي هو لبروتوكول AMQP. لمعرفة المزيد حول استخدام بروتوكول MQTT مباشرة مع IoT Hub، راجع دعم بروتوكول MQTT.

استدعاء الأسلوب

تتلقى الأجهزة طلبات الطريقة المباشرة على موضوع MQTT: $iothub/methods/POST/{method name}/?$rid={request id}. ومع ذلك، يتم إنشاء request id بواسطة IoT Hub ولا يمكن معرفتها مسبقًا، لذا اشترك في $iothub/methods/POST/# ثم قم بتصفية الرسائل التي تم تسليمها استنادًا إلى أسماء الأساليب التي يدعمها جهازك. (ستستخدم request id للرد.)

النص الأساسي الذي يتلقى الجهاز بالتنسيق التالي:

{
    "input1": "someInput",
    "input2": "anotherInput"
}

طلبات الأسلوب هي QoS 0.

الاستجابة

يرسل الجهاز استجابات إلى $iothub/methods/res/{status}/?$rid={request id}، حيث:

  • status هي الخاصية هي حالة الجهاز الموفرة لتنفيذ الأسلوب.

  • الخاصية $rid هي معرف الطلب من استدعاء الأسلوب المستلم من IoT Hub. معرف الطلب هو قيمة منسقة سداسية عشرية.

يتم تعيين الجسم بواسطة الجهاز ويمكن أن يكون أي حالة.

AMQP

المقطع التالي هو لبروتوكول AMQP. لمعرفة المزيد حول استخدام بروتوكول AMQP مباشرة مع IoT Hub، راجع دعم بروتوكول AMQP.

استدعاء الأسلوب

يتلقى الجهاز طلبات الطريقة المباشرة عن طريق إنشاء ارتباط استلام على العنوان amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound.

تصل رسالة AMQP إلى رابط الاستلام الذي يمثل طلب الأسلوب. يتضمن الملفات التالية:

  • خاصية معرف الارتباط، التي تحتوي على معرف الطلب الذي يجب إعادته مع استجابة الطريقة المقابلة.

  • خاصية تطبيق مسماة IoThub-methodname، والتي تحتوي على اسم الطريقة التي يتم استدعاؤها.

  • نص رسالة AMQP الذي يحتوي على حمولة الأسلوب مثل JSON.

الاستجابة

يقوم الجهاز بإنشاء ارتباط إرسال لإرجاع استجابة الطريقة على العنوان amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound.

يتم إرجاع استجابة الطريقة على ارتباط الإرسال ويتم تنظيمها على النحو التالي:

  • خاصية معرف الارتباط الذي يحتوي على معرف الطلب الذي تم تمريره في رسالة طلب الأسلوب.

  • اسم خاصية تطبيق IoThub-status، والتي تحتوي على حالة الطريقة التي يوفرها المستخدم.

  • نص رسالة AMQP الذي يحتوي على استجابة الطريقة مثل JSON.

مواد مرجعية إضافية

تتضمن الموضوعات المرجعية الأخرى في دليل مطور IoT Hub ما يلي:

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

الآن تعلمت كيفية استخدام الأساليب المباشرة، قد تكون مهتما بمقالة دليل مطور مركز IoT التالية:

إذا كنت ترغب في تجربة بعض المفاهيم الموضحة في هذه المقالة، فقد تكون مهتما بالبرنامج التعليمي التالي لمركز IoT: