Upload الملفات باستخدام IoT Hub

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

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

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

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

هام

توجد وظيفة تحميل الملفات على الأجهزة التي تستخدم مصادقة المرجع المصدق X.509 (CA) في المعاينة العامة، ويجب تمكين وضع المعاينة. وهي متوفرة بشكل عام على الأجهزة التي تستخدم مصادقة بصمة الإبهام X.509 أو شهادة X.509 مع خدمة توفير الأجهزة من Azure. لمعرفة المزيد حول مصادقة X.509 باستخدام IoT Hub، راجع شهادات X.509 المدعومة.

نظرة عامة على تحميل الملف

يسهل مركز إنترنت الأشياء عمليات تحميل الملفات من الأجهزة المتصلة من خلال تزويدها بعناوين URI لتوقيع الوصول المشترك (SAS) على أساس كل تحميل لحاوية blob وحساب تخزين Azure اللذين تم تكوينهما مسبقا باستخدام لوحة الوصل. هناك ثلاثة أجزاء لاستخدام تحميلات الملفات مع IoT Hub: التكوين المسبق لحساب تخزين Azure وحاوية blob على مركز إنترنت الأشياء، وتحميل الملفات من الأجهزة، واختياريا، إخطار خدمات الواجهة الخلفية بتحميلات الملفات المكتملة.

قبل أن تتمكن من استخدام ميزة تحميل الملفات، يجب عليك إقران حساب تخزين Azureوحاوية blob بمركز إنترنت الأشياء الخاص بك. يمكنك أيضا تكوين الإعدادات التي تتحكم في كيفية مصادقة IoT Hub باستخدام وحدة تخزين Azure، ووقت بدء التشغيل (TTL) لعناوين SAS URI التي يسلمها مركز إنترنت الأشياء إلى الأجهزة، وإعلامات تحميل الملفات إلى خدمات الواجهة الخلفية. لمعرفة المزيد، راجع إقران حساب تخزين Azure بمركز إنترنت الأشياء.

تتبع الأجهزة عملية من ثلاث خطوات لتحميل ملف إلى حاوية blob المقترنة:

  1. يبدأ الجهاز تحميل الملف باستخدام مركز إنترنت الأشياء. يمرر اسم نقطة في الطلب ويحصل على SAS URI ومعرف ارتباط في المقابل. يحتوي SAS URI على رمز SAS المميز لتخزين Azure الذي يمنح الجهاز إذن القراءة والكتابة على النقطة المطلوبة في حاوية blob. لمعرفة التفاصيل، يرجى الاطلاع على الجهاز: تهيئة تحميل ملف.

  2. يستخدم الجهاز SAS URI للاتصال بأمان بواجهات برمجة تطبيقات تخزين Azure blob لتحميل الملف إلى حاوية blob. للحصول على التفاصيل، راجع الجهاز: Upload الملف باستخدام واجهات برمجة تطبيقات تخزين Azure.

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

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

يتم دعم تحميل الملفات بالكامل بواسطة أجهزة Azure IoT ومجموعات SDK للخدمة. لمعرفة التفاصيل، يرجى الاطلاع على تحميل الملف باستخدام SDK.

حصص وحدود تحميل الملفات

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

إقران حساب تخزين Azure بمركز إنترنت الأشياء

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

إذا كنت تستخدم البوابة الإلكترونية، فيمكنك إنشاء حساب تخزين وحاوية أثناء التكوين. وإلا، لإنشاء حساب تخزين، راجع إنشاء حساب تخزين في وثائق تخزين Azure. بمجرد أن يكون لديك حساب تخزين، يمكنك معرفة كيفية إنشاء حاوية blob في عمليات التشغيل السريع لتخزين Azure blob.

هناك العديد من الإعدادات الأخرى التي تتحكم في سلوك عمليات تحميل الملفات وإشعارات تحميل الملفات. تسرد الأقسام التالية جميع الإعدادات المتاحة. استنادا إلى ما إذا كنت تستخدم مدخل Azure أو Azure CLI أو PowerShell أو واجهات برمجة تطبيقات الإدارة لتكوين عمليات تحميل الملفات، قد لا تتوفر بعض هذه الإعدادات. تأكد من تعيين إعداد enableFileUploadNotifications إذا كنت تريد إرسال إشعارات إلى خدمات الواجهة الخلفية عند اكتمال تحميل ملف.

إعدادات التخزين والمصادقة في Iot Hub

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

الخاصية الوصف النطاق والافتراضي
storageEndpoints.$default.authenticationType يتحكم في كيفية مصادقة IoT Hub باستخدام وحدة تخزين Azure. القيم المحتملة هي keyBased و identityBased. الافتراضي: يستند إلى المفاتيح.
storageEndpoints.$default.connectionString سلسلة الاتصال بحساب تخزين Azure لاستخدامها في عمليات تحميل الملفات. الافتراضي: سلسلة فارغة.
storageEndpoints.$default.containerName اسم الحاوية المراد تحميل الملفات إليها. الافتراضي: سلسلة فارغة.
storageEndpoints.$default.identity الهوية المدارة لاستخدامها في المصادقة المستندة إلى الهوية. القيم المحتملة هي [system] للهوية المدارة المعينة من قبل النظام أو معرف مورد لهوية مدارة معينة من قبل المستخدم. لا يتم استخدام القيمة للمصادقة المستندة إلى المفتاح. الافتراضي: فارغ.

إعدادات تحميل الملفات

تتحكم الإعدادات التالية في عمليات تحميل الملفات من الجهاز.

الخاصية الوصف النطاق والافتراضي
التخزيننقاط النهاية.$default.ttlAsIso8601 TTL الافتراضي لعناوين SAS URI التي تم إنشاؤها بواسطة IoT Hub. ISO_8601 فاصل زمني يصل إلى 48 ساعة (الحد الأدنى 1 دقيقة). الافتراضي: 1 ساعة.

إعدادات إشعارات تحميل الملفات

تتحكم الإعدادات التالية في إعلامات تحميل الملفات إلى خدمات الواجهة الخلفية.

الخاصية الوصف النطاق والافتراضي
enableFileUploadNotifications يتحكم في ما إذا كانت إعلامات تحميل الملفات مكتوبة إلى نقطة نهاية إعلامات الملفات. بول. الافتراضي: خطأ.
fileNotifications.ttlAsIso8601 TTL الافتراضي لإشعارات تحميل الملفات. ISO_8601 فاصل زمني يصل إلى 48 ساعة (الحد الأدنى 1 دقيقة). الافتراضي: 1 ساعة.
fileNotifications.lockDuration مدة القفل لقائمة انتظار إشعارات تحميل الملف. 5 إلى 300 ثانية. الافتراضي: 60 ثانية.
fileNotifications.maxDeliveryCount الحد الأقصى لعدد التسليم لقائمة انتظار إشعارات تحميل الملف. 1 إلى 100. الافتراضي: 100.

تحميل الملف باستخدام SDK

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

الدلائل الإرشادية مثال على حزمة SDK للجهاز مثال على حزمة تطوير البرامج (SDK) للخدمة
.NET نعم نعم
Java نعم نعم
Node.js نعم نعم
Python نعم لا (غير مدعوم)

ملاحظة

تستخدم حزمة SDK لجهاز C مكالمة واحدة على عميل الجهاز لإجراء عمليات تحميل الملفات. لمزيد من المعلومات، راجع IoTHubDeviceClient_UploadToBlobAsync () و IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync(). تقوم هذه الوظائف بتنفيذ جميع جوانب تحميل الملف في مكالمة واحدة - بدء التحميل وتحميل الملف إلى وحدة تخزين Azure وإخطار IoT Hub عند اكتماله. وهذا يعني أنه بالإضافة إلى أي بروتوكول يستخدمه الجهاز للتواصل مع IoT Hub، سيحتاج أيضا إلى أن يكون قادرا على التواصل عبر HTTPS مع تخزين Azure حيث تقوم هذه الوظائف بإجراء مكالمات إلى واجهات برمجة تطبيقات تخزين Azure.

الجهاز: تهيئة تحميل ملف

يستدعي الجهاز واجهة برمجة تطبيقات SAS URI REST API أو واجهة برمجة التطبيقات المكافئة لإنشاء ملف Upload أو واجهة برمجة التطبيقات المكافئة في إحدى مجموعات SDK الخاصة بالجهاز لبدء تحميل ملف.

البروتوكولات المدعومة: HTTPS
نقطة النهاية: {iot hub}.azure-devices.net/devices/{deviceId}/files
الطريقة: POST

{
    "blobName":"myfile.txt"
}
الخاصية الوصف
بلوبنام اسم النقطة لإنشاء SAS URI ل.

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

{
    "correlationId":"MjAyMTA3MzAwNjIxXzBiNjgwOGVkLWZjNzQtN...MzYzLWRlZmI4OWQxMzdmNF9teWZpbGUudHh0X3ZlcjIuMA==",
    "hostName":"contosostorageaccount.blob.core.windows.net",
    "containerName":"device-upload-container",
    "blobName":"mydevice/myfile.txt",
    "sasToken":"?sv=2018-03-28&sr=b&sig=mBLiODhpKXBs0y9RVzwk1S...l1X9qAfDuyg%3D&se=2021-07-30T06%3A11%3A10Z&sp=rw"
}
الخاصية الوصف
correlationId المعرف الذي يجب على الجهاز استخدامه عند إرسال إشعار إكمال تحميل الملف إلى IoT Hub.
hostName اسم مضيف حساب تخزين Azure لحساب التخزين الذي تم تكوينه على مركز إنترنت الأشياء
containerName اسم حاوية blob التي تم تكوينها على مركز إنترنت الأشياء.
بلوبنام الموقع الذي سيتم فيه تخزين الفقاعة في الحاوية. الاسم بالتنسيق التالي: {device ID of the device making the request}/{blobName in the request}
ساس توكين رمز SAS المميز الذي يمنح حق الوصول للقراءة والكتابة على النقطة باستخدام تخزين Azure. يتم إنشاء الرمز المميز وتوقيعه بواسطة IoT Hub.

عندما يتلقى الجهاز الاستجابة، يقوم بما يلي:

  • يحفظ معرف الارتباط لتضمينه في الإشعار الكامل لتحميل الملف إلى مركز إنترنت الأشياء عند إكمال التحميل.

  • يستخدم الخصائص الأخرى لإنشاء SAS URI للنقطة التي يستخدمها للمصادقة باستخدام تخزين Azure. يحتوي SAS URI على مورد URI للنقطة المطلوبة والرمز المميز SAS. يأخذ الشكل التالي: https://{hostName}/{containerName}/{blobName}{sasToken} (تحتوي sasToken الخاصية في الاستجابة على حرف '?' بادئ.) لا يتم تضمين الأقواس.

    على سبيل المثال، بالنسبة للقيم التي تم إرجاعها في النموذج أعلاه، يكون SAS URI هو، https://contosostorageaccount.blob.core.windows.net/device-upload-container/mydevice/myfile.txt?sv=2018-03-28&sr=b&sig=mBLiODhpKXBs0y9RVzwk1S...l1X9qAfDuyg%3D&se=2021-07-30T06%3A11%3A10Z&sp=rw

    لمزيد من المعلومات حول الرمز المميز SAS URI وSAS، راجع إنشاء خدمة SAS في وثائق تخزين Azure.

الجهاز: ملف Upload باستخدام واجهات برمجة تطبيقات تخزين Azure

يستخدم الجهاز واجهات برمجة تطبيقات REST لتخزين Azure Blob أو واجهات برمجة تطبيقات SDK لتخزين Azure المكافئة لتحميل الملف إلى النقطة في وحدة تخزين Azure.

البروتوكولات المدعومة: HTTPS

يوضح المثال التالي طلب Put Blob لإنشاء نقطة كتلة صغيرة أو تحديثها. لاحظ أن عنوان URI المستخدم لهذا الطلب هو SAS URI الذي تم إرجاعه بواسطة IoT Hub في القسم السابق. x-ms-blob-type يشير الرأس إلى أن هذا الطلب مخصص لنقطة كتلة. في حالة نجاح الطلب، يقوم تخزين Azure بإرجاع 201 Createdملف .

PUT https://contosostorageaccount.blob.core.windows.net/device-upload-container/mydevice/myfile.txt?sv=2018-03-28&sr=b&sig=mBLiODhpKXBs0y9RVzwk1S...l1X9qAfDuyg%3D&se=2021-07-30T06%3A11%3A10Z&sp=rw HTTP/1.1
Content-Length: 11
Content-Type: text/plain; charset=UTF-8
Host: contosostorageaccount.blob.core.windows.net
x-ms-blob-type: BlockBlob

hello world

العمل مع واجهات برمجة تطبيقات تخزين Azure خارج نطاق هذه المقالة. بالإضافة إلى واجهات برمجة تطبيقات REST لتخزين Azure Blob المرتبطة سابقا في هذا القسم، يمكنك استكشاف الوثائق التالية لمساعدتك على البدء:

الجهاز: إخطار IoT Hub بتحميل ملف مكتمل

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

البروتوكولات المدعومة: HTTPS
نقطة النهاية: {iot hub}.azure-devices.net/devices/{deviceId}/files/notifications
الطريقة: POST

{
    "correlationId": "MjAyMTA3MzAwNjIxXzBiNjgwOGVkLWZjNzQtN...MzYzLWRlZmI4OWQxMzdmNF9teWZpbGUudHh0X3ZlcjIuMA==",
    "isSuccess": true,
    "statusCode": 200,
    "statusDescription": "File uploaded successfully"
}
الخاصية الوصف
correlationId معرف الارتباط المستلم في طلب SAS URI الأولي.
هو النجاح منطقي يشير إلى ما إذا كان تحميل الملف ناجحا أم لا.
statusCode عدد صحيح يمثل رمز الحالة الخاص بتحميل الملف. عادة ثلاثة أرقام. على سبيل المثال ، 200 أو 201.
statusDescription وصف لحالة تحميل الملف.

عندما يتلقى إشعارا كاملا بتحميل ملف من الجهاز، يقوم IoT Hub بما يلي:

  • يؤدي إلى تشغيل إشعار تحميل ملف إلى خدمات الواجهة الخلفية إذا تم تكوين إشعارات تحميل الملف.

  • يصدر الموارد المقترنة بتحميل الملف. بدون تلقي إشعار، سيحتفظ IoT Hub بالموارد حتى تنتهي صلاحية وقت SAS URI (TTL) المرتبط بالتحميل.

الخدمة: إشعارات تحميل الملفات

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

البروتوكولات المدعومة AMQP, AMQP-WS
نقطة النهاية: {iot hub}.azure-devices.net/messages/servicebound/fileuploadnotifications
أسلوب حصل

كل رسالة تم استردادها من نقطة نهاية إشعار تحميل الملف هي سجل JSON:

{
    "deviceId":"mydevice",
    "blobUri":"https://contosostorageaccount.blob.core.windows.net/device-upload-container/mydevice/myfile.txt",
    "blobName":"mydevice/myfile.txt",
    "lastUpdatedTime":"2021-07-31T00:26:50+00:00",
    "blobSizeInBytes":11,
    "enqueuedTimeUtc":"2021-07-31T00:26:51.5134008Z"
}
الخاصية الوصف
enqueuedTimeUtc طابع زمني يشير إلى وقت إنشاء الإشعار.
معرف الجهاز معرف الجهاز للجهاز الذي قام بتحميل الملف.
بلوبوري عنوان URI للملف الذي تم تحميله.
بلوبنام اسم الملف الذي تم تحميله. الاسم بالتنسيق التالي: {device ID of the device}/{name of the blob}
اخاختحديثالوقت الطابع الزمني يشير إلى تاريخ آخر تحديث للملف.
blobSizeInBytes عدد صحيح يمثل حجم الملف الذي تم تحميله بالبايت.

يمكن للخدمات استخدام الإشعارات لإدارة التحميلات. على سبيل المثال، يمكنهم تشغيل المعالجة الخاصة بهم لبيانات blob أو تشغيل معالجة بيانات blob باستخدام خدمات Azure الأخرى أو تسجيل إشعار تحميل الملف لمراجعته لاحقا.

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