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

  • مقالة

تمكنك الأساليب المباشرة ل 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 لتضمينه /modules/<moduleName> كما هو موضح أدناه:

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 التالية: