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

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

ملحوظة

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

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

أي شخص لديه صلاحيات اتصال الخدمة على IoT Hub يمكنه استدعاء طريقة على جهاز معين.

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

دورة حياة الطريقة

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

ملحوظة

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

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

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

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

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

لاستدعاء طريقة مباشرة من تطبيق خلفي، استخدم واجهة برمجة تطبيقات Devices - Invoke Method REST API أو ما يعادلها في أحد مجموعات SDK لخدمات IoT Hub.

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

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

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

  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 Hub لإكمال تنفيذ طريقة مباشرة على الجهاز. اضبط هذا الوقت ليكون على الأقل بطول الوقت المتوقع لتنفيذ طريقة مباشرة بواسطة جهاز. إذا لم يتم توفير قيمة انتهاء الوقت، تستخدم القيمة الافتراضية البالغة 30 ثانية. القيم الدنيا والعظمى ل responseTimeoutInSeconds هي 5 و300 ثانية على التوالي.

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

مثال

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

للبدء، استخدم إضافة Microsoft Azure IoT الخاصة ب Azure CLI لإنشاء توقيع مشترك.

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

بعد ذلك، استبدل رأس التفويض بتوقيع SharedAccessSignature الذي تم إنشاؤه حديثا، ثم عدل ال ، iothubNamedeviceId، methodName، والمعلمات 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 الجهاز ويستخدمان للرد برمز الحالة الخاص بالجهاز واستجابة الطريقة.

استدعاء الطرق لوحدات إنترنت الأشياء

لاستدعاء طريقة مباشرة على وحدة، استخدم واجهة برمجة تطبيقات Modules - Invoke Method REST أو ما يعادلها في أحد مجموعات SDK لخدمات IoT Hub.

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

التعامل مع طريقة مباشرة على جهاز

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

MQTT

القسم التالي مخصص لبروتوكول MQTT. لمعرفة المزيد حول استخدام بروتوكول MQTT مباشرة مع مركز إنترنت الأشياء، راجع التواصل مع مركز إنترنت الأشياء باستخدام بروتوكول 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 الخاصية هي معرف الطلب من استدعاء الأسلوب المستلم من مركز إنترنت الأشياء. معرف الطلب هو قيمة منسقة سداسية عشرية.

الجهاز يحدد الجسم ويمكن أن يكون أي حالة.

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

• جدولة المهام على أجهزة متعددة
• تسرد مجموعات تطوير تطبيقات Azure IoT Hub للغات المختلفة التي يمكنك استخدامها عند تطوير تطبيقات الأجهزة والخدمات التي تتفاعل مع IoT Hub.
• لغة استعلام IoT Hub لتوائم الأجهزة والوحدات، والوظائف، وتوجيه الرسائل تصف لغة استعلام IoT Hub التي يمكنك استخدامها لاسترجاع المعلومات من IoT Hub حول توأم ووظائف جهازك.