مشاركة عبر

كيفية استخدام واجهة برمجة تطبيقات REST ل IoT Central لتحميل ملف

  • مقالة

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

  • استخدم واجهة برمجة تطبيقات REST لتكوين إمكانية تحميل الملف في تطبيق IoT Central.
  • اختبر تحميل الملف عن طريق تشغيل بعض نماذج التعليمات البرمجية للجهاز.

تتيح لك واجهة برمجة التطبيقات الخاصة بـ IoT Central ما يلي:

  • إضافة تكوين حساب تخزين تحميل ملف
  • تحديث تكوين حساب تخزين تحميل الملفات
  • الحصول على تكوين حساب تخزين تحميل الملف
  • حذف تكوين تخزين تحميل الملف

يتطلب كل استدعاء لواجهة برمجة تطبيقات REST ل IoT Central عنوان تخويل. لمعرفة المزيد، راجع كيفية مصادقة وتخويل استدعاءات واجهة برمجة تطبيقات REST ل IoT Central.

للحصول على الوثائق المرجعية لواجهة برمجة تطبيقات REST ل IoT Central، راجع مرجع واجهة برمجة تطبيقات REST ل Azure IoT Central.

تلميح

يمكنك استخدام Postman لتجربة استدعاءات واجهة برمجة تطبيقات REST الموضحة في هذه المقالة. قم بتنزيل مجموعة IoT Central Postman واستوردها إلى Postman. في المجموعة، ستحتاج إلى تعيين متغيرات مثل المجال الفرعي للتطبيق والرمز المميز للمسؤول.

لمعرفة كيفية تحميل الملفات باستخدام واجهة مستخدم IoT Central، راجع كيفية تكوين تحميلات الملفات.

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

لاختبار تحميل الملف، قم بتثبيت المتطلبات الأساسية التالية في بيئة التطوير المحلية الخاصة بك:

إضافة تكوين حساب تخزين تحميل ملف

لإضافة تكوين حساب تخزين تحميل ملف:

إنشاء حساب تخزين

لاستخدام Azure Storage REST API، تحتاج إلى رمز حامل للمورد management.azure.com . للحصول على رمز مميز للحامل، يمكنك استخدام Azure CLI:

az account get-access-token --resource https://management.azure.com

إذا لم يكن لديك حساب تخزين للكائنات الثنائية كبيرة الحجم، يمكنك استخدام الطلب التالي لإنشاء حساب في اشتراكك:

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}?api-version=2021-09-01

تحتوي رؤوس الطلبات على الحقول التالية:

  • subscriptionId : معرف الاشتراك الهدف.
  • resourceGroupName: اسم مجموعة الموارد في اشتراكك. الاسم غير حساس لحالة الأحرف.
  • accountName : اسم حساب التخزين ضمن مجموعة الموارد المحددة. يجب أن تكون أسماء حسابات التخزين بين 3 أحرف و24 حرفاً في الطول واستخدام أرقام وأحرف صغيرة فقط.

يحتوي نص الطلب على الحقول المطلوبة التالية:

  • kind : نوع حساب التخزين
  • location : الموقع الجغرافي حيث يعيش المورد
  • sku: اسم SKU.
{
 "kind": "BlockBlobStorage",
 "location": "West US",
 "sku": "Premium_LRS"
}

إنشاء حاوية

استخدم الطلب التالي لإنشاء حاوية تسمى fileuploads في حساب التخزين الخاص بك للكائنات الثنائية كبيرة الحجم الخاصة بك:

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}/blobServices/default/containers/fileuploads?api-version=2021-09-01
  • containerName : يجب أن يتراوح طول أسماء حاويات Blob بين 3 و63 حرفا واستخدام الأرقام والأحرف الصغيرة والشرطة (-) فقط. يجب أن يسبق كل حرف شرطة (-) مباشرة ويتبعه حرف أو رقم.

إرسال نص طلب فارغ مع هذا الطلب الذي يشبه المثال التالي:

{
}

تبدو الاستجابة لهذا الطلب مثل المثال التالي:

{
  "id": "/subscriptions/your-subscription-id/resourceGroups/yourResourceGroupName/providers/Microsoft.Storage/storageAccounts/yourAccountName/blobServices/default/containers/fileuploads",
  "name": "fileuploads",
  "type": "Microsoft.Storage/storageAccounts/blobServices/containers"
}

احصل على مفاتيح حساب التخزين

استخدم الطلب التالي لاسترداد مفاتيح حساب التخزين التي تحتاجها عند تكوين التحميل في IoT Central:

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}/listKeys?api-version=2021-09-01

تبدو الاستجابة لهذا الطلب مثل المثال التالي:

{
  "keys": [
    {
      "creationTime": "2022-05-19T19:22:40.9132287Z",
      "keyName": "key1",
      "value": "j3UTm**************==",
      "permissions": "FULL"
    },
    {
      "creationTime": "2022-05-19T19:22:40.9132287Z",
      "keyName": "key2",
      "value": "Nbs3W**************==",
      "permissions": "FULL"
    }
  ]
}

إنشاء تكوين التحميل

استخدم الطلب التالي لإنشاء تكوين حساب تخزين كائن ثنائي كبير الحجم لتحميل ملف في تطبيق IoT Central الخاص بك:

PUT https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31

يحتوي نص الطلب على الحقول التالية:

  • account: اسم حساب التخزين حيث يتم تحميل الملف إليه.
  • connectionString: سلسلة الاتصال للاتصال بحساب التخزين. استخدم إحدى القيم من value الطلب السابق listKeys كقيمة AccountKey .
  • container: اسم الحاوية داخل حساب التخزين. يستخدم المثال التالي الاسم fileuploads.
  • etag: ETag لمنع التعارض مع التحميلات المتعددة
  • sasTtl: معيار مدة ISO 8601، مقدار الوقت الذي يكون فيه طلب الجهاز لتحميل ملف صالحا قبل انتهاء صلاحيته.
{
  "account": "yourAccountName",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
  "container": "fileuploads",
  "sasTtl": "PT1H"
}

تبدو الاستجابة لهذا الطلب مثل المثال التالي:

{
  "account": "yourAccountName",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
  "container": "fileuploads",
  "sasTtl": "PT1H",
  "state": "pending",
  "etag": "\"7502ac89-0000-0300-0000-627eaf100000\""

}

الحصول على تكوين حساب تخزين تحميل الملف

استخدم الطلب التالي لاسترداد تفاصيل تكوين حساب تخزين كائن ثنائي كبير الحجم لتحميل ملف في تطبيق IoT Central الخاص بك:

GET https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31

تبدو الاستجابة لهذا الطلب مثل المثال التالي:

{
  "account": "yourAccountName",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
  "container": "yourContainerName",
  "state": "succeeded",
  "etag": "\"7502ac89-0000-0300-0000-627eaf100000\""

}

تحديث تكوين حساب تخزين تحميل الملف

استخدم الطلب التالي لتحديث حساب تخزين blob تحميل ملف سلسلة الاتصال في تطبيق IoT Central الخاص بك:

PATCH https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31

{
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/"
}

تبدو الاستجابة لهذا الطلب مثل المثال التالي:


{
  "account": "yourAccountName",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
  "container": "yourContainerName",
  "sasTtl": "PT1H",
  "state": "succeeded",
  "etag": "\"7502ac89-0000-0300-0000-627eaf100000\""
}

إزالة تكوين حساب تخزين تحميل الملف

استخدم الطلب التالي لحذف تكوين حساب تخزين:

DELETE https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31

اختبار تحميل الملف

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

git clone https://github.com/azure-Samples/iot-central-file-upload-device
cd iotc-file-upload-device
npm i
npm build

إنشاء قالب الجهاز واستيراد النموذج

لاختبار تحميل الملف، يمكنك تشغيل نموذج تطبيق جهاز. إنشاء قالب جهاز لنموذج الجهاز لاستخدامه.

  1. افتح تطبيقك في واجهة مستخدم IoT Central.

  2. انتقل إلى علامة التبويب Device Templates في الجزء الأيمن، وحدد + New:

  3. اختر جهاز IoT كنوع القالب.

  4. في صفحة تخصيص المعالج، أدخل اسما مثل File Upload Device Sample لقالب الجهاز.

  5. في صفحة مراجعة+ إنشاء حدد إنشاء.

  6. حدد استيراد نموذج وتحميل ملف نموذج FileUploadDeviceDcm.json من المجلد iotc-file-upload-device\setup في المستودع الذي قمت بتنزيله مسبقا.

  7. حدد نشر لنشر قالب الجهاز.

أضف جهاز

لإضافة جهاز إلى تطبيق Azure IoT Central:

  1. اختر الأجهزة في الجزء الأيمن.

  2. حدد قالب File Upload Device Sample الذي قمت بإنشائه سابقا.

  3. حدد + جديد وحدد إنشاء.

  4. حدد الجهاز الذي أنشأته وحدد الاتصال

انسخ قيم ID scopeو Device IDو.Primary key يمكنك استخدام هذه القيم في نموذج التعليمات البرمجية للجهاز.

شغل التعليمات البرمجية النموذجية

افتح مستودع git الذي قمت بتنزيله في VS Code. أنشئ ملف ".env" في جذر المشروع وأضف القيم التي نسختها مسبقا. يجب أن يبدو الملف مثل النموذج التالي مع القيم التي قمت بتدوينها مسبقا.

scopeId=<YOUR_SCOPE_ID>
deviceId=<YOUR_DEVICE_ID>
deviceKey=<YOUR_PRIMARY_KEY>
modelId=dtmi:IoTCentral:IotCentralFileUploadDevice;1

افتح مستودع git الذي قمت بتنزيله في VS Code. اضغط على F5 لتشغيل/تصحيح العينة. في نافذة المحطة الطرفية، ترى أن الجهاز مسجل ومتصل ب IoT Central:

Starting IoT Central device...
 > Machine: Windows_NT, 8 core, freemem=6674mb, totalmem=16157mb
Starting device registration...
DPS registration succeeded
Connecting the device...
IoT Central successfully connected device: 7z1xo26yd8
Sending telemetry: {
    "TELEMETRY_SYSTEM_HEARTBEAT": 1
}
Sending telemetry: {
    "TELEMETRY_SYSTEM_HEARTBEAT": 1
}
Sending telemetry: {
    "TELEMETRY_SYSTEM_HEARTBEAT": 1
}

يأتي نموذج المشروع مع نموذج ملف يسمى datafile.json. يتم تحميل هذا الملف عند استخدام الأمر تحميل ملف في تطبيق IoT Central.

لاختبار التحميل، افتح التطبيق الخاص بك وحدد الجهاز الذي أنشأته. حدد علامة التبويب Command وشاهد زرا يسمى Run. عند تحديد هذا الزر، يستدعي تطبيق IoT Central أسلوبا مباشرا على جهازك لتحميل الملف. يمكنك مشاهدة هذا الأسلوب المباشر في نموذج التعليمات البرمجية في ملف /device.ts. يسمى الأسلوب uploadFileCommand.

حدد علامة التبويب Raw data للتحقق من حالة تحميل الملف.

Screenshot showing the U I of how to verify a file upload.

يمكنك أيضا إجراء استدعاء REST API للتحقق من حالة تحميل الملف في حاوية التخزين.

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

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