مشاركة عبر

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

  • مقالة

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

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

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

هام

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

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

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

قبل أن تتمكن من استخدام ميزة تحميل الملف، يجب إقران حساب تخزين Azure وحاوية كائن ثنائي كبير الحجمبمركز إنترنت الأشياء الخاص بك. يمكنك أيضًا تكوين الإعدادات التي تتحكم في طريقة مصادقة مركز إنترنت الأشياء مع تخزين Azure، ووقت البقاء (TTL) لموارد URIs SAS التي يوزعها مركز إنترنت الأشياء على الأجهزة، وإخطارات تحميل الملفات إلى خدمات الواجهة الخلفية. لمعرفة المزيد، راجع اقتران حساب تخزين Azure بمركز إنترنت الأشياء.

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

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

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

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

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

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

الحصص النسبية وحدود تحميل الملفات

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

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

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

إن كنت تستخدم المدخل، يمكنك إنشاء حساب تخزين وحاوية أثناء التكوين. وإلا، لإنشاء حساب تخزين، راجع إنشاء حساب تخزين في وثائق تخزين Azure. بمجرد أن يكون لديك حساب تخزين، يمكنك معرفة كيفية إنشاء حاوية كائن ثنائي كبير الحجم في التشغيل السريع ل Azure Blob Storage. بشكل افتراضي، يستخدم مركز إنترنت الأشياء في Azure المصادقة المستندة إلى المفتاح للاتصال والتخويل باستخدام تخزين Azure. يمكنك أيضًا تكوين الهويات المدارة المعينة من قبل المستخدم أو المعينة من قبل النظام لمصادقة مركز إنترنت الأشياء في Azure باستخدام تخزين Azure. توفر الهويات المدارة خدمات Azure بهوية مدارة تلقائيا في معرف Microsoft Entra بطريقة آمنة. لمعرفة كيفية تكوين الهويات المدارة، راجع قسم تكوين تحميل الملف باستخدام الهويات المدارة في دعم IoT Hub للهويات المدارة.

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

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

إعدادات التخزين والمصادقة في مركز إنترنت الأشياء

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

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

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

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

الخاصية ‏‏الوصف النطاق والوضع الافتراضي
storageEndpoints.$default.ttlAsIso8601 TTL الافتراضي لواجهات URL SAS التي أنشئت بواسطة مركز إنترنت الأشياء. ISO_8601 الفاصل الزمني حتى 48 ساعة (دقيقة واحدة على الأقل). الافتراضي: ساعة واحدة.

إعدادات الإخطار بتحميل الملفات

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

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

تحميل الملف باستخدام عدة تطوير البرامج

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

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

إشعار

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

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

يستدعي الجهاز واجهة برمجة تطبيقات REST Create File Upload SAS URI أو واجهة برمجة التطبيقات المكافئة في إحدى مجموعات عدة تطوير برامج الجهاز لبدء تحميل ملف.

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

{
    "blobName":"myfile.txt"
}
الخاصية ‏‏الوصف
blobName اسم الكائن الثنائي كبير الحجم لإنشاء SAS URI.

يستجيب مركز إنترنت الأشياء بمعرف ارتباط وعناصر 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 معرف الجهاز لاستخدامه عند إرسال إخطار كامل بتحميل الملف إلى مركز إنترنت الأشياء.
hostName اسم مضيف حساب تخزين Azure لحساب التخزين الذي تكوّن على مركز إنترنت الأشياء
containerName اسم حاوية كائن ثنائي كبير الحجم التي تكونت على مركز إنترنت الأشياء.
blobName الموقع حيث تخزن الكائنات الثنائية كبيرة الحجم في الحاوية. يكون الاسم بالتنسيق التالي: {device ID of the device making the request}/{blobName in the request}
sasToken رمز SAS المميز الذي يمنح حق الوصول للقراءة والكتابة على الكائنات الثنائية كبيرة الحجم باستخدام تخزين Azure. يتم إنشاء الرمز المميز وتوقيعه بواسطة مركز إنترنت الأشياء.

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

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

  • استخدام الخصائص الأخرى لإنشاء 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.

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

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

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

يوضح المثال التالي طلب Put Blob لإنشاء كائن ثنائي كبير الحجم للكتلة الصغيرة أو تحديثه. لاحظ أن URI المستخدم لهذا الطلب هو SAS URI الذي استعيد بواسطة مركز إنترنت الأشياء كما هو موضح في القسم السابق. 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 المرتبطة سابقًا في هذا القسم، يمكنك استكشاف الوثائق التالية لمساعدتك على البدء:

  • لمعرفة المزيد حول العمل مع الكائنات الثنائية كبيرة الحجم في تخزين Azure، راجع وثائق Azure Blob Storage.

  • للحصول على معلومات عن استخدام مجموعات عدة تطوير البرامج لعميل تخزين Azure لتحميل الكائنات الثنائية كبيرة الحجم، راجع مرجع Azure Blob Storage API.

الجهاز: إخطار مركز إنترنت الأشياء بتحميل ملف مكتمل

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

البروتوكولات المدعومة: 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 المبدئي.
isSuccess قيمة منطقية تشير إلى إذا كان تحميل الملف ناجحًا أم لا.
statusCode عدد صحيح يمثل تعليمة برمجية حالة تحميل الملف. عادة بتنسيق ثلاثة أرقام؛ على سبيل المثال، 200 أو 201.
statusDescription وصف لحالة تحميل الملفات.

عندما يتلقى إخطارًا كاملاً بتحميل الملف من الجهاز، يقوم مركز إنترنت الأشياء بما يلي:

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

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

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

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

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

تعتبر كل رسالة يتم استردادها من نقطة نهاية إخطار تحميل الملفات هي سجل 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 طابع زمني يشير إلى وقت إنشاء الإخطار.
deviceId معرف الجهاز للجهاز الذي حمل الملف.
blobUri URI للملف الذي تم تحميله.
blobName اسم الملف الذي تم تحميله. يكون الاسم بالتنسيق التالي: {device ID of the device}/{name of the blob}
lastUpdatedTime طابع زمني يشير إلى آخر تحديث للملف.
blobSizeInBytes عدد صحيح يمثل حجم الملف الذي تم تحميله بالبايت.

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

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