مشاركة عبر

تحميل الملفات من جهازك إلى السحابة باستخدام Azure IoT Hub (Node.js)

  • مقالة

توضح هذه المقالة كيفية تحميل ملف إمكانات IoT Hub لتحميل ملف إلى Azure blob storage، باستخدام Node.js.

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

  • ملفات الفيديو
  • ملفات كبيرة تحتوي على صور
  • بيانات الاهتزاز التي تم أخذ عينات لها بتردد عال
  • بعض أشكال البيانات المعالجة مسبقاً.

تتم عادةً معالجة هذه الملفات دفعة واحدة في السحابة باستخدام أدوات مثل Azure Data Factory أو مكدس Hadoop. عندما تحتاج إلى ملفات upland من جهاز، فلا يزال بإمكانك استخدام أمان وموثوقية IoT Hub. يوضح لك هذا المقال كيف.

في نهاية هذه المقالة، يمكنك تشغيل تطبيقات وحدة تحكم Node.js:

  • FileUpload.js، الذي يقوم بتحميل ملف لتخزين باستخدام SAS URI الذي يوفره مركز إنترنت الأشياء الخاص بك.

  • FileUploadNotification.js، الذي يتلقى إعلامات تحميل الملفات من مركز إنترنت الأشياء الخاص بك.

إشعار

يدعم IoT Hub العديد من الأنظمة الأساسية واللغات للأجهزة، بما في ذلك C وJava وPython وJavaScript، من خلال حزم SDK الخاصة بجهاز Azure IoT. ارجع إلى مركز مطور Azure IoT للحصول على إرشادات خطوة بخطوة بشأن كيفية توصيل جهازك بـ Azure IoT Hub.

هام

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

المتطلبات الأساسية

  • IoT Hub. أنشئ واحدا باستخدام CLI أو مدخل Microsoft Azure.

  • جهاز مسجل. سجَل واحدًا في مدخل Azure.

  • Node.js الإصدار 10.0.x أو أحدث. يوصى بإصدار LTS. يمكنك تنزيل Node.js من nodejs.org.

  • يجب فتح المنفذ 8883 في جدار الحماية الخاص بك. يستخدم نموذج الجهاز في هذه المقالة بروتوكول MQTT، الذي يتصل عبر المنفذ 8883. قد يُحظر هذا المنفذ في بعض بيئات الشبكات التعليمية، وشبكات الشركات. لمزيد من المعلومات وطرق التغلب على هذه المشكلة، راجع الاتصال بمركز IoT (MQTT).

إقران حساب Azure Storage بـ IoT Hub

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

لإقران حساب Azure Storage بمركز IoT الخاص بك:

  1. ضمن Hub settings، حدد File upload في الجزء الأيسر من IoT Hub الخاص بك.

    لقطة شاشة تعرض إعدادات تحميل الملفات من المدخل.

  2. في جزء File upload، حدد Azure Storage Container. بالنسبة لهذه المقالة، يوصى بأن يكون حساب التخزين الخاص بك ومركز IoT Hub موجودين في نفس المنطقة.

    • إذا كان لديك بالفعل حساب تخزين تريد استخدامه، فحدده من القائمة.

    • لإنشاء حساب تخزين جديد، حدد +Storage account. أدخل اسماً لحساب التخزين وتأكد من تعيين Location على نفس المنطقة مثل IoT Hub، ثم حدد OK. تم إنشاء الحساب الجديد في نفس مجموعة الموارد مثل IoT Hub الخاص بك. عند اكتمال التوزيع، حدد حساب التخزين من القائمة.

    بعد تحديد حساب التخزين، يتم فتح جزء Containers.

  3. في جزء Containers، حدد حاوية البيانات الثنائية الكبيرة.

    • إذا كان لديك بالفعل حاوية blob تريد استخدامها، فحددها من القائمة وانقر على Select.

    • لإنشاء حاوية blob جديدة، حدد + Container. أدخل اسماً للحاوية الجديدة. لأغراض هذه المقالة، يمكنك ترك جميع الحقول الأخرى على وضعها الافتراضي. حدد إنشاء. عند اكتمال التوزيع، حدد الحاوية من القائمة وانقر على Select.

  4. مرة أخرى في جزء File upload، تأكد من تعيين إعلامات الملف على On. يمكنك ترك جميع الإعدادات الأخرى على الإعدادات الافتراضية الخاصة بهم. حدد Save وانتظر حتى تكتمل الإعدادات قبل الانتقال إلى القسم التالي.

    لقطة شاشة تعرض تأكيد إعدادات تحميل الملفات في المدخل.

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

تحميل ملف من تطبيق جهاز

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

  1. إنشاء مجلد فارغ يسمى fileupload. في fileupload المجلد، قم بإنشاء ملف package.json باستخدام الأمر التالي في موجه الأوامر. قبول جميع الافتراضيات:

    npm init

  2. في موجه الأوامر في المجلد fileupload، قم بتشغيل الأمر التالي لتثبيت عدة تطوير البرامج لجهاز azure-iot-device وazure-iot-device-mqtt وحزم @azure/storage-blob:

    npm install azure-iot-device azure-iot-device-mqtt @azure/storage-blob --save

  3. باستخدام محرر نص، قم بإنشاء ملف FileUpload.js في المجلد fileupload، وانسخ التعليمات البرمجية التالية فيه.

    'use strict';

const Client = require('azure-iot-device').Client;
const Protocol = require('azure-iot-device-mqtt').Mqtt;
const errors = require('azure-iot-common').errors;
const path = require('path');

const {
  AnonymousCredential,
  BlockBlobClient,
  newPipeline
} = require('@azure/storage-blob');

// make sure you set these environment variables prior to running the sample.
const deviceConnectionString = process.env.DEVICE_CONNECTION_STRING;
const localFilePath = process.env.PATH_TO_FILE;
const storageBlobName = path.basename(localFilePath);

async function uploadToBlob(localFilePath, client) {
  const blobInfo = await client.getBlobSharedAccessSignature(storageBlobName);
  if (!blobInfo) {
    throw new errors.ArgumentError('Invalid upload parameters');
  }

  const pipeline = newPipeline(new AnonymousCredential(), {
    retryOptions: { maxTries: 4 },
    telemetry: { value: 'HighLevelSample V1.0.0' }, // Customized telemetry string
    keepAliveOptions: { enable: false }
  });

  // Construct the blob URL to construct the blob client for file uploads
  const { hostName, containerName, blobName, sasToken } = blobInfo;
  const blobUrl = `https://${hostName}/${containerName}/${blobName}${sasToken}`;

  // Create the BlockBlobClient for file upload to the Blob Storage Blob
  const blobClient = new BlockBlobClient(blobUrl, pipeline);

  // Setup blank status notification arguments to be filled in on success/failure
  let isSuccess;
  let statusCode;
  let statusDescription;

  try {
    const uploadStatus = await blobClient.uploadFile(localFilePath);
    console.log('uploadStreamToBlockBlob success');

    // Save successful status notification arguments
    isSuccess = true;
    statusCode = uploadStatus._response.status;
    statusDescription = uploadStatus._response.bodyAsText;

    // Notify IoT Hub of upload to blob status (success)
    console.log('notifyBlobUploadStatus success');
  }
  catch (err) {
    isSuccess = false;
    statusCode = err.code;
    statusDescription = err.message;

    console.log('notifyBlobUploadStatus failed');
    console.log(err);
  }

  await client.notifyBlobUploadStatus(blobInfo.correlationId, isSuccess, statusCode, statusDescription);
}

// Create a client device from the connection string and upload the local file to blob storage.
const deviceClient = Client.fromConnectionString(deviceConnectionString, Protocol);
uploadToBlob(localFilePath, deviceClient)
  .catch((err) => {
    console.log(err);
  })
  .finally(() => {
    process.exit();
  });

  4. احفظ الملف FileUpload.js وأغلقه.

  5. انسخ ملف صورة إلى المجلد fileupload وامنحه اسماً مثل myimage.png.

  6. إضافة متغيرات البيئة لسلسلة اتصال الجهاز والمسار إلى الملف الذي تريد تحميله. حصلت على الجهاز سلسلة الاتصال عند تسجيل جهاز في مركز IoT.

    • لـ Windows:

      set DEVICE_CONNECTION_STRING={your device connection string}
set PATH_TO_FILE={your image filepath}

    • بالنسبة إلى Linux/Bash:

      export DEVICE_CONNECTION_STRING="{your device connection string}"
export PATH_TO_FILE="{your image filepath}"

احصل على سلسلة اتصال IoT hub

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

للحصول على سلسلة اتصال IoT Hub لنهج الخدمة، اتبع الخطوات التالية:

  1. في مدخل Microsoft Azure، حدد Resource groups. حدد مجموعة الموارد حيث يوجد المركز الخاص بك، ثم حدد المركز الخاص بك من قائمة الموارد.

  2. في الجزء الأيسر من IoT Hub، حدد Shared access policies.

  3. من قائمة النُهج، حدد نهج service.

  4. انسخ سلسلة الاتصال الأساسية واحفظ القيمة.

لقطة شاشة تعرض كيفية استرداد سلسلة الاتصال من IoT Hub في مدخل Microsoft Azure.

للمزيد من المعلومات حول نهج الوصول المشترك لـIoT Hub والأذونات، راجع التحكم في الوصول والأذونات.

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

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

  1. إنشاء مجلد فارغ يسمى fileuploadnotification. في fileuploadnotification المجلد، قم بإنشاء ملف package.json باستخدام الأمر التالي في موجه الأوامر. قبول جميع الافتراضيات:

    npm init

  2. في موجه الأوامر في المجلد fileuploadnotification، قم بتشغيل الأمر التالي لتثبيت حزمة عدة تطوير البرامج azure-iothub:

    npm install azure-iothub --save

  3. باستخدام محرر نص، قم بإنشاء ملف ⁧⁩ExtractDevice.js⁧⁩ جديد في المجلد ⁧fileuploadnotification⁩.

  4. قم بإضافة العبارات التالية require في بداية ملف RegisterDevice.js:

    'use strict';

const Client = require('azure-iothub').Client;

  5. قراءة سلسلة الاتصال الخاصة بمركز إنترنت الأشياء من البيئة:

    const connectionString = process.env.IOT_HUB_CONNECTION_STRING;

  6. إضافة التعليمات البرمجية التالية لإنشاء عميل خدمة من سلسلة الاتصال:

    const serviceClient = Client.fromConnectionString(connectionString);

  7. افتح العميل واستخدم الدالة getFileNotificationReceiver لتلقي تحديثات الحالة.

    serviceClient.open(function (err) {
  if (err) {
    console.error('Could not connect: ' + err.message);
  } else {
    console.log('Service client connected');
    serviceClient.getFileNotificationReceiver(function receiveFileUploadNotification(err, receiver){
      if (err) {
        console.error('error getting the file notification receiver: ' + err.toString());
      } else {
        receiver.on('message', function (msg) {
          console.log('File upload from device:')
          console.log(msg.getData().toString('utf-8'));
          receiver.complete(msg, function (err) {
            if (err) {
              console.error('Could not finish the upload: ' + err.message);
            } else {
              console.log('Upload complete');
            }
          });
        });
      }
    });
  }
});

    إشعار

    إذا كنت تريد تلقي إعلامات قطع الاتصال أثناء الاستماع إلى إعلامات تحميل الملفات، فستحتاج إلى التسجيل 'error' باستخدام receiver.on. لمتابعة تلقي إعلامات تحميل الملف، تحتاج إلى إعادة الاتصال بمركز إنترنت الأشياء باستخدام الأسلوب serviceClient.open.

  8. احفظ الملف FileUploadNotification.js وأغلقه.

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

    • لـ Windows:

      set IOT_HUB_CONNECTION_STRING={your iot hub connection string}

    • بالنسبة إلى Linux/Bash:

      export IOT_HUB_CONNECTION_STRING="{your iot hub connection string}"

تشغيل التطبيقات

الآن أنت جاهز لتشغيل التطبيقات.

في موجه الأوامر في المجلد fileuploadnotification، قم بتشغيل الأمر التالي:

node FileUploadNotification.js

في موجه الأوامر في المجلد fileupload، قم بتشغيل الأمر التالي:

node FileUpload.js

الإخراج التالي من تطبيق FileUpload بعد اكتمال التحميل:

uploadStreamToBlockBlob success
notifyBlobUploadStatus success

إخراج العينة التالي من تطبيق FileUploadNotification بعد اكتمال التحميل:

Service client connected
File upload from device:
{"deviceId":"myDeviceId","blobUri":"https://{your storage account name}.blob.core.windows.net/device-upload-container/myDeviceId/image.png","blobName":"myDeviceId/image.png","lastUpdatedTime":"2021-07-23T23:27:06+00:00","blobSizeInBytes":26214,"enqueuedTimeUtc":"2021-07-23T23:27:07.2580791Z"}

تحقق من تحميل الملف

يمكنك استخدام المدخل لعرض الملف الذي تم تحميله في حاوية التخزين التي قمت بتكوينها:

  1. انتقل إلى حساب التخزين الخاص بك في مدخل Microsoft Azure.

  2. في الجزء الأيسر من حساب التخزين الخاص بك، حدد Containers.

  3. حدد الحاوية التي قمت بتحميل الملف إليها.

  4. حدد المجلد المسمى بعد جهازك.

  5. حدد النقطة التي قمت بتحميل ملفك إليها. في هذه المقالة، إنه الكائن الثنائي كبير الحجم بنفس اسم الملف الخاص بك.

    لقطة شاشة تعرض الملف الذي تم تحميله في مدخل Azure.

  6. عرض خصائص الكائن الثنائي كبير الحجم على الصفحة التي تفتح. يمكنك تحديد Download لتنزيل الملف وعرض محتوياته محلياً.

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

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