فهم الأساليب المباشرة من IoT Hub واستدعاؤها

  • مقالة
  • قراءة خلال 6 دقائق

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

ملاحظة

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

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

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

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

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

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

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

ملاحظة

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

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

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

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

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

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

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

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

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

    https://fully-qualified-iothubname.azure-devices.net/twins/{deviceId}/methods?api-version=2018-06-30

  • طريقة POST

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

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

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

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

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

مثال

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

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

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

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

curl -X POST \
  https://<iothubName>.azure-devices.net/twins/<deviceId>/methods?api-version=2018-06-30 \
  -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=2018-06-30

الاستجابة

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

  • رمز حالة HTTP:

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

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

  • هيئة JSON بالتنسيق التالي:

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

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

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

يتم دعم استدعاء الأساليب المباشرة باستخدام معرف الوحدة النمطية في عميل خدمة إنترنت الأشياء C # SDK.

لهذا الغرض، استخدم الأسلوب ServiceClient.InvokeDeviceMethodAsync() وقم بتمرير deviceId وmoduleId كمعلمات.

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

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

MQTT

القسم التالي مخصص لبروتوكول MQTT.

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

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

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

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

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

الاستجابة

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

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

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

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

AMQP

المقطع التالي هو لبروتوكول 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 Hub التالية:

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