مشاركة عبر

تكوين عمليات تحميل ملفات IoT Hub باستخدام Azure CLI

  • مقالة

توضح لك هذه المقالة كيفية تكوين عمليات تحميل الملفات على مركز IoT باستخدام Azure CLI.

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

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

  • حساب Azureنشط. إذا لم يكن لديك حساب، يمكنك إنشاء حساب مجاني في دقيقتين فقط.

  • مركز IoT في اشتِراك Azure الخاص بك. إذا لم تكن لديك مركز بعد، فإنه يمكنك اتباع الخطوات الواردة في إنشاء مركز IoT.

  • حساب تخزين Azure وحاوية blob. إذا لم يكن لديك حساب Azure Storage، يمكنك استخدام Azure CLI لإنشاء حساب. لمزيد من المعلومات، راجع إنشاء حساب تخزين.

إشعار

تستخدم هذه المقالة أحدث إصدار من ملحق Azure IoT، ويطلق عليه azure-iot. يسمى الإصدار القديم azure-cli-iot-ext. يجب أن يكون لديك إصدار واحد فقط مُثبت في كل مرة. يمكنك استخدام الأمر az extension list للتحقق من صحة الملحقات المثبتة حالياً.

استخدم az extension remove --name azure-cli-iot-ext لإزالة الإصدار القديم من الملحق.

استخدم az extension add --name azure-iot لإضافة الإصدار الجديد من الملحق.

لمعرفة ما هي الملحقات التي قمت بتثبيتها، استخدم az extension list.

قم بتسجيل الدخول وتعيين حساب Azure الخاص بك

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

  1. للقيام بتسجيل الدخول في موجه الأوامر، شغّل أمر تسجيل الدخول:

    az login

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

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

    az account list

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

    az account set --subscription {your subscription name or id}

تكوين الوصول إلى حساب التخزين

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

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

يمكنك استخدام المصادقة المستندة إلى المفتاح أو المصادقة المستندة إلى الهوية لتوفير أذونات الوصول. توصي Microsoft بالمصادقة المستندة إلى الهوية كخيار أكثر أمانا.

المصادقة المستندة إلى المفتاح

للمصادقة المستندة إلى المفتاح، قم بتوفير سلسلة الاتصال لحساب التخزين الخاص بك. استخدم الأمر az storage account show-connection-string لاسترداد مفاتيح حساب التخزين.

دوّن ملاحظة عن القيمة connectionString. يبدو سلسلة الاتصال مشابها للإخراج التالي:

{
  "connectionString": "DefaultEndpointsProtocol=https;EndpointSuffix=core.windows.net;AccountName={your_storage_account_name};AccountKey={your_storage_account_key}"
}

المصادقة المستندة إلى الهوية

يمكنك استخدام الهويات المدارة المعينة من قبل النظام أو الهويات المدارة المعينة من قبل المستخدم للمصادقة المستندة إلى الهوية. لمزيد من المعلومات، راجع دعم IoT Hub للهويات المدارة.

استخدم الأمر az role assignment create لتعيين دور لهويتك المدارة. لمزيد من المعلومات، راجع تعيين دور Azure للوصول إلى بيانات كائن ثنائي كبير الحجم.

تكوين مركز IoT الأشياء الخاص بك

يمكنك الآن تكوين مركز IoT لتمكين القدرة على تحميل الملفات إلى مركز IoT باستخدام تفاصيل حساب التخزين الخاص بكم.

يتطلب التكوين القيم الآتية:

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

  • استلام إعلامات للملفات التي تم تحميلها: تمكين إعلامات تحميل الملفات أو تعطيلها.

  • SAS TTL: هذا الإعداد هو وقت البقاء لواجهات SAS URIs التي تم إرجاعها إلى الجهاز عن طريق IoT Hub. تعيين إلى ساعة واحدة بشكل افتراضي.

  • إعدادات إعلام الملف الافتراضية TTL: وقت البقاء لإشعار تحميل الملف قبل انتهاء صلاحيته. تعيين إلى يوم واحد بشكل افتراضي.

  • الحد الأقصى لعدد تسليم إعلامات الملفات: عدد المرات التي يحاول فيها مركز IoT تسليم إعلام تحميل ملف. اضبط على 10 افتراضياً.

  • مدة تأمين إعلام الملف: مدة تأمين قائمة انتظار إعلامات الملف. تعيين إلى 60 ثانية بشكل افتراضي.

  • نوع المصادقة: نوع المصادقة لـ IoT Hub لاستخدامها مع Azure Storage. يحدد هذا الإعداد كيفية مصادقة مركز IoT الخاص بك وتخويله باستخدام Azure Storage. الإعداد الافتراضي هو المصادقة المستندة إلى المفتاح؛ ومع ذلك، يوصى بخيارات مصادقة الهوية المدارة المعينة من قبل النظام أو المعينة من قبل المستخدم. توفر الهويات المدارة خدمات Azure بهوية مدارة تلقائيا في معرف Microsoft Entra بطريقة آمنة.

    إشعار

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

توضح الأوامر التالية كيفية تكوين إعدادات تحميل الملف على مركز IoT. يتم عرض هذه الأوامر بشكل منفصل للوضوح، ولكن عادة ما تصدر أمرا واحدا مع جميع المعلمات المطلوبة للسيناريو الخاص بكم. قم بتضمين علامات الاقتباس حيث تظهر لك في سطر الأوامر. لا تقم بتضمين الأقواس. يمكن العثور على المزيد من التفاصيل بشأن كل معلمة في وثائق Azure CLI للأمر az iot hub update.

يقوم الأمر الآتي بتكوين حساب التخزين وحاوية الكائن الثنائي كبير الحجم.

az iot hub update --name {your iot hub name} \
    --fileupload-storage-connectionstring "{your storage account connection string}" \
    --fileupload-storage-container-name "{your container name}"

يعين الأمر الآتي وقت SAS URI للعيش إلى الافتراضي (ساعة واحدة فقط).

az iot hub update --name {your iot hub name} \
    --fileupload-sas-ttl 1

يقوم الأمر التالي بتمكين إعلامات الملف وتعيين خصائص إعلام الملف على قيمها الافتراضية. (يتم تعيين وقت إعلامات تحميل الملف إلى ساعة واحدة ويتم تعيين مدة التأمين إلى 60 ثانية.)

az iot hub update --name {your iot hub name} \
    --fileupload-notifications true  \
    --fileupload-notification-max-delivery-count 10 \
    --fileupload-notification-ttl 1 \
    --fileupload-notification-lock-duration 60

يقوم الأمر الآتي بتكوين المصادقة المستندة إلى المفتاح:

az iot hub update --name {your iot hub name} \
    --fileupload-storage-auth-type keyBased

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

az iot hub update --name {your iot hub name} \
    --fileupload-storage-auth-type identityBased \
    --fileupload-storage-identity [system]

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

للاستعلام عن الهويات المدارة المحددة من قبل المستخدم على مركز IoT، استخدم الأمر az iot hub identity show.

az iot hub identity show --name {your iot hub name} --query userAssignedIdentities

يقوم الأمر باسترجاع مجموعة من الهويات المدارة المعينة من قبل المستخدم التي تم تكوينها على مركز IoT الخاص بك. يُظهر الإخراج التالي مجموعة تحتوي على هوية مُدارة واحدة مُعيَّنة من قِبل المستخدم.

{
  "/subscriptions/{your subscription ID}/resourcegroups/{your resource group}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{your user-assigned managed identity name}": 
  {
    "clientId": "<client ID GUID>",
    "principalId": "<principal ID GUID>"
  }
}

يقوم الأمر الآتي بتكوين المصادقة لاستخدام الهوية المعينة من قبل المستخدم أعلاه.

az iot hub update --name {your iot hub name} \
    --fileupload-storage-auth-type identityBased \
    --fileupload-storage-identity  "/subscriptions/{your subscription ID}/resourcegroups/{your resource group}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{your user-assigned managed identity name}"

يمكنك مراجعة الإعدادات على مركز IoT باستخدام الأمر الآتي:

az iot hub show --name {your iot hub name}

لمراجعة إعدادات تحميل الملف فقط، استخدم الأمر الآتي:

az iot hub show --name {your iot hub name}
    --query '[properties.storageEndpoints, properties.enableFileUploadNotifications, properties.messagingEndpoints.fileNotifications]'

بالنسبة لمعظم الحالات، يعد استخدام المعلمات المسماة في أوامر Azure CLI أسهل؛ ومع ذلك، يمكنكم أيضاً تكوين إعدادات تحميل الملف باستخدام المعلمة --set. يمكن أن تساعدك الأوامر التالية على فهم كيفية القيام بذلك.

az iot hub update --name {your iot hub name} \
  --set properties.storageEndpoints.'$default'.connectionString="{your storage account connection string}"

az iot hub update --name {your iot hub name} \
  --set properties.storageEndpoints.'$default'.containerName="{your storage container name}"

az iot hub update --name {your iot hub name} \
  --set properties.storageEndpoints.'$default'.sasTtlAsIso8601=PT1H0M0S

az iot hub update --name {your iot hub name} \
  --set properties.enableFileUploadNotifications=true

az iot hub update --name {your iot hub name} \
  --set properties.messagingEndpoints.fileNotifications.maxDeliveryCount=10

az iot hub update --name {your iot hub name} \
  --set properties.messagingEndpoints.fileNotifications.ttlAsIso8601=PT1H0M0S

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