مشاركة عبر

تحميل الملفات من جهاز إلى السحابة باستخدام Azure IoT Hub

توضح هذه المقالة كيفية:

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

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

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

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

تهدف هذه المقالة إلى استكمال نماذج SDK القابلة للتشغيل والتي تمت الإشارة إليها من داخل هذه المقالة.

لمزيد من المعلومات، راجع:

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

  • مركز إنترنت الأشياء. تتطلب بعض استدعاءات SDK سلسلة الاتصال الأساسية ل IoT Hub، لذا قم بتدوين سلسلة الاتصال.

  • جهاز مسجل. تتطلب بعض استدعاءات SDK سلسلة الاتصال الأساسية للجهاز، لذا قم بتدوين سلسلة الاتصال.

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

  • قم بتكوين تحميل الملفات في مركز IoT عن طريق ربط حساب Azure Storageوحاوية Azure Blob Storage. يمكنك تكوينها باستخدام مدخل Microsoft Azure أو Azure CLI أو Azure PowerShell.

نظرة عامة‬

تحتوي هذه الإرشادات على قسمين:

  • تحميل ملف من تطبيق جهاز
  • تلقي إعلام تحميل الملف في تطبيق الواجهة الخلفية

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

يصف هذا القسم كيفية تحميل ملف من جهاز إلى مركز IoT باستخدام فئة DeviceClient في Azure IoT SDK ل .NET.

اتبع هذا الإجراء لتحميل ملف من جهاز إلى مركز إنترنت الأشياء:

  1. الاتصال بمركز إنترنت الأشياء
  2. احصل على SAS URI من مركز إنترنت الأشياء
  3. تحميل الملف إلى تخزين Azure
  4. إخطار مركز إنترنت الأشياء بحالة تحميل الملف

توصيل جهاز ب IoT Hub

يمكن لتطبيق الجهاز المصادقة باستخدام IoT Hub باستخدام الطرق التالية:

  • شهادة X.509
  • مفتاح الوصول المشترك

المصادقة باستخدام شهادة X.509

لتوصيل جهاز ب IoT Hub باستخدام شهادة X.509:

  1. استخدم DeviceAuthenticationWithX509Certificate لإنشاء كائن يحتوي على معلومات الجهاز والشهادة. DeviceAuthenticationWithX509Certificate كمعلمة ثانية إلى DeviceClient.Create (الخطوة 2).

  2. استخدم DeviceClient.Create لتوصيل الجهاز ب IoT Hub باستخدام شهادة X.509.

في هذا المثال، يتم ملء معلومات الجهاز والشهادة في الكائن authDeviceAuthenticationWithX509Certificate الذي تم تمريره إلى DeviceClient.Create.

يوضح هذا المثال قيم معلمات إدخال الشهادة كمتغيرات محلية للوضوح. في نظام الإنتاج، قم بتخزين معلمات الإدخال الحساسة في متغيرات البيئة أو موقع تخزين آخر أكثر أمانا. على سبيل المثال، استخدم Environment.GetEnvironmentVariable("HOSTNAME") لقراءة متغير بيئة اسم المضيف.

RootCertPath = "~/certificates/certs/sensor-thl-001-device.cert.pem";
Intermediate1CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate1.cert.pem";
Intermediate2CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate2.cert.pem";
DevicePfxPath = "~/certificates/certs/sensor-thl-001-device.cert.pfx";
DevicePfxPassword = "1234";
DeviceName = "MyDevice";
HostName = "xxxxx.azure-devices.net";

var chainCerts = new X509Certificate2Collection();
chainCerts.Add(new X509Certificate2(RootCertPath));
chainCerts.Add(new X509Certificate2(Intermediate1CertPath));
chainCerts.Add(new X509Certificate2(Intermediate2CertPath));
using var deviceCert = new X509Certificate2(DevicePfxPath, DevicePfxPassword);
using var auth = new DeviceAuthenticationWithX509Certificate(DeviceName, deviceCert, chainCerts);

using var deviceClient = DeviceClient.Create(
    HostName,
    auth,
    TransportType.Amqp);

لمزيد من المعلومات حول مصادقة الشهادة، راجع:

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

للحصول على عينات عمل لمصادقة شهادة الجهاز X.509، راجع:

المصادقة باستخدام مفتاح وصول مشترك

اتصل ب CreateFromConnectionString للاتصال بالجهاز. قم بتمرير سلسلة الاتصال الأساسية للجهاز.

AMQP هو بروتوكول النقل الافتراضي.

static string connectionString = "{device primary connection string}";
deviceClient = DeviceClient.CreateFromConnectionString(connectionString);

احصل على SAS URI من مركز إنترنت الأشياء

اتصل ب GetFileUploadSasUriAsync للحصول على تفاصيل تحميل الملفات. يتم استخدام SAS URI في الخطوة التالية لتحميل ملف من جهاز إلى Blob Storage.

const string filePath = "TestPayload.txt";
using var fileStreamSource = new FileStream(filePath, FileMode.Open);
var fileName = Path.GetFileName(fileStreamSource.Name);
var fileUploadSasUriRequest = new FileUploadSasUriRequest
{
    BlobName = fileName
};

FileUploadSasUriResponse sasUri = await _deviceClient.GetFileUploadSasUriAsync(fileUploadSasUriRequest, System.Threading.CancellationToken cancellationToken = default);
Uri uploadUri = sasUri.GetBlobUri();

تحميل ملف إلى تخزين Azure

لتحميل ملف إلى تخزين Azure:

  1. قم بإنشاء عنصر blockBlobClient ، وتمرير URI لتحميل ملف.

  2. استخدم الأسلوب UploadAsync لتحميل ملف إلى Blob Storage، مع تمرير SAS URI. يمكنك اختياريا إضافة خيارات تحميل Blob ومعلمات الرمز المميز للإلغاء.

يستخدم عميل Azure Blob دائما HTTPS كبروتوكول لتحميل الملف إلى Azure Storage.

في هذا المثال، BlockBlobClient يتم تمرير SAS URI لإنشاء عميل كائن ثنائي كبير الحجم لكتلة تخزين Azure وتحميل الملف:

var blockBlobClient = new BlockBlobClient(uploadUri);
await blockBlobClient.UploadAsync(fileStreamSource, null, null);

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

استخدم CompleteFileUploadAsync لإعلام مركز IoT بأن عميل الجهاز أكمل التحميل، وتمرير كائن FileUploadCompletionNoticial . تشير العلامة IsSuccess إلى ما إذا كان التحميل ناجحا أم لا. بعد الإخطار، سيقوم مركز إنترنت الأشياء بإصدار الموارد المقترنة بالتحميل (SAS URI).

إذا تم تمكين إعلامات تحميل الملفات، يرسل مركز IoT رسالة إعلام تحميل ملف إلى خدمات الواجهة الخلفية التي تم تكوينها لإشعار تحميل الملفات.

var successfulFileUploadCompletionNotification = new FileUploadCompletionNotification
{
    // Mandatory. Must be the same value as the correlation id returned in the sas uri response
    CorrelationId = sasUri.CorrelationId,

    // Mandatory. Will be present when service client receives this file upload notification
    IsSuccess = true,

    // Optional, user defined status code. Will be present when service client receives this file upload notification
    StatusCode = 200,

    // Optional, user-defined status description. Will be present when service client receives this file upload notification
    StatusDescription = "Success"
};

await _deviceClient.CompleteFileUploadAsync(successfulFileUploadCompletionNotification);

نموذج تحميل ملف SDK

تتضمن SDK نموذج تحميل الملف هذا.

تلقي إشعار تحميل ملف في تطبيق خلفية

يمكنك إنشاء خدمة خلفية لتلقي رسائل إعلام تحميل الملفات من مركز إنترنت الأشياء.

تحتوي فئة ServiceClient على طرق يمكن للخدمات استخدامها لتلقي إعلامات تحميل الملفات.

إضافة خدمة باقة NuGet

تتطلب تطبيقات خدمة الواجهة الخلفية حزمة Microsoft.Azure.Devices NuGet.

الاتصال بمركز إنترنت الأشياء

يمكنك توصيل خدمة الواجهة الخلفية ب IoT Hub باستخدام الطرق التالية:

  • نهج الوصول المشترك
  • Microsoft Entra

هام

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

الاتصال باستخدام نهج وصول مشترك

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

على سبيل المثال:

using Microsoft.Azure.Devices;
static ServiceClient serviceClient;
static string connectionString = "{Shared access policy connection string}";
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);

الاتصال باستخدام Microsoft Entra

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

تكوين تطبيق Microsoft Entra

يجب عليك إعداد تطبيق Microsoft Entra الذي تم تكوينه لبيانات اعتماد المصادقة المفضلة لديك. يحتوي التطبيق على معلمات مثل سر العميل التي يستخدمها تطبيق الواجهة الخلفية للمصادقة. تكوينات مصادقة التطبيق المتاحة هي:

  • سر العميل
  • شهادة
  • بيانات اعتماد الهوية الموحدة

قد تتطلب تطبيقات Microsoft Entra أذونات دور محددة اعتمادا على العمليات التي يتم تنفيذها. على سبيل المثال، مطلوب IoT Hub Twin Contributor لتمكين الوصول للقراءة والكتابة إلى جهاز IoT Hub وتوائم الوحدة النمطية. لمزيد من المعلومات، راجع إدارة الوصول إلى IoT Hub باستخدام تعيين دور Azure RBAC.

لمزيد من المعلومات حول إعداد تطبيق Microsoft Entra، راجع التشغيل السريع: تسجيل تطبيق باستخدام النظام الأساسي للهويات في Microsoft.

المصادقة باستخدام DefaultAzureCredential

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

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

يتطلب Microsoft Entra حزم NuGet هذه والعبارات المقابلة using :

  • Azure.Core
  • Azure.Identity
using Azure.Core;
using Azure.Identity;

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

string clientSecretValue = "xxxxxxxxxxxxxxx";
string clientID = "xxxxxxxxxxxxxx";
string tenantID = "xxxxxxxxxxxxx";

Environment.SetEnvironmentVariable("AZURE_CLIENT_SECRET", clientSecretValue);
Environment.SetEnvironmentVariable("AZURE_CLIENT_ID", clientID);
Environment.SetEnvironmentVariable("AZURE_TENANT_ID", tenantID);

TokenCredential tokenCredential = new DefaultAzureCredential();

يمكن بعد ذلك تمرير TokenCredential الناتج إلى أسلوب الاتصال ب IoT Hub لأي عميل SDK يقبل بيانات اعتماد Microsoft Entra:

في هذا المثال، يتم تمرير الملف TokenCredential إلى ServiceClient.Create لإنشاء كائن اتصال ServiceClient .

string hostname = "xxxxxxxxxx.azure-devices.net";
using var serviceClient = ServiceClient.Create(hostname, tokenCredential, TransportType.Amqp);

في هذا المثال، يتم تمرير إلى TokenCredentialRegistryManager.Create لإنشاء كائن RegistryManager .

string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);
نموذج التعليمات البرمجية

للحصول على عينة عمل من مصادقة خدمة Microsoft Entra، راجع نموذج المصادقة المستندة إلى الدور.

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

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

  1. قم بإنشاء CancellationToken.
  2. اتصل ب GetFileNotificationReceiver لإنشاء جهاز استقبال إعلام.
  3. استخدم حلقة مع ReceiveAsync لانتظار إشعار تحميل الملف.

على سبيل المثال:

// Define the cancellation token
CancellationTokenSource source = new CancellationTokenSource();
CancellationToken token = source.Token;

// Create a notification receiver
var notificationReceiver = serviceClient.GetFileNotificationReceiver();
Console.WriteLine("\nReceiving file upload notification from service");

// Check for file upload notifications
while (true)
{
    var fileUploadNotification = await notificationReceiver.ReceiveAsync(token);
    if (fileUploadNotification == null) continue;
    Console.ForegroundColor = ConsoleColor.Yellow;
    Console.WriteLine("Received file upload notification: {0}", 
        string.Join(", ", fileUploadNotification.BlobName));
    Console.ResetColor();
    await notificationReceiver.CompleteAsync(fileUploadNotification);
}

نموذج مستقبل تحميل ملف SDK

تتضمن SDK نموذج مستقبل تحميل الملفات هذا.

نظرة عامة‬

تحتوي هذه الإرشادات على قسمين:

  • تحميل ملف من تطبيق جهاز
  • تلقي إعلام تحميل الملف في تطبيق الواجهة الخلفية

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

يصف هذا القسم كيفية تحميل ملف من جهاز إلى مركز IoT باستخدام فئة DeviceClient من Azure IoT SDK ل Java.

اتبع هذا الإجراء لتحميل ملف من جهاز إلى مركز إنترنت الأشياء:

  1. قم بتوصيل الجهاز ب IoT Hub
  2. احصل على SAS URI من مركز إنترنت الأشياء
  3. تحميل الملف إلى Azure Storage
  4. إرسال إعلام حالة تحميل الملف إلى مركز إنترنت الأشياء

توصيل جهاز ب IoT Hub

يمكن لتطبيق الجهاز المصادقة باستخدام IoT Hub باستخدام الطرق التالية:

  • شهادة X.509
  • مفتاح الوصول المشترك

المصادقة باستخدام شهادة X.509

لتوصيل جهاز ب IoT Hub باستخدام شهادة X.509:

  1. قم بإنشاء كائن SSLContext باستخدام buildSSLContext.
  2. أضف SSLContext المعلومات إلى كائن ClientOptions .
  3. اتصل ب DeviceClient باستخدام ClientOptions المعلومات لإنشاء اتصال الجهاز بمركز إنترنت الأشياء.

يوضح هذا المثال قيم معلمات إدخال الشهادة كمتغيرات محلية للوضوح. في نظام الإنتاج، قم بتخزين معلمات الإدخال الحساسة في متغيرات البيئة أو موقع تخزين آخر أكثر أمانا. على سبيل المثال، استخدم Environment.GetEnvironmentVariable("PUBLICKEY") لقراءة متغير بيئة سلسلة شهادة المفتاح العام.

private static final String publicKeyCertificateString =
        "-----BEGIN CERTIFICATE-----\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "-----END CERTIFICATE-----\n";

//PEM encoded representation of the private key
private static final String privateKeyString =
        "-----BEGIN EC PRIVATE KEY-----\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "-----END EC PRIVATE KEY-----\n";

SSLContext sslContext = SSLContextBuilder.buildSSLContext(publicKeyCertificateString, privateKeyString);
ClientOptions clientOptions = ClientOptions.builder().sslContext(sslContext).build();
DeviceClient client = new DeviceClient(connString, protocol, clientOptions);

لمزيد من المعلومات حول مصادقة الشهادة، راجع:

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

للحصول على عينات عمل لمصادقة شهادة الجهاز X.509، راجع:

المصادقة باستخدام مفتاح وصول مشترك

تستخدم عمليات تحميل الملفات دائما HTTPS، ولكن يمكن ل DeviceClient تحديد بروتوكول IotHubClientProtocol لخدمات أخرى مثل القياس عن بعد وأسلوب الجهاز والجهاز المزدوج.

IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;

قم بإنشاء DeviceClient مثيل للاتصال بالجهاز باستخدام سلسلة الاتصال الأساسية للجهاز.

String connString = "{IoT hub connection string}";
DeviceClient client = new DeviceClient(connString, protocol);

احصل على SAS URI من مركز إنترنت الأشياء

قم باستدعاء getFileUploadSasUri للحصول على كائن FileUploadSasUriResponse .

FileUploadSasUriResponse يتضمن هذه الطرق وقيم الإرجاع. يمكن تمرير قيم الإرجاع إلى طرق تحميل الملفات.

الطريقة قيمة الإرجاع
getCorrelationId() معرف الارتباط
getContainerName() اسم الحاوية
getBlobName() اسم الكائن الثنائي كبير الحجم
getBlobUri() كتلة URI

على سبيل المثال:

FileUploadSasUriResponse sasUriResponse = client.getFileUploadSasUri(new FileUploadSasUriRequest(file.getName()));

System.out.println("Successfully got SAS URI from IoT hub");
System.out.println("Correlation Id: " + sasUriResponse.getCorrelationId());
System.out.println("Container name: " + sasUriResponse.getContainerName());
System.out.println("Blob name: " + sasUriResponse.getBlobName());
System.out.println("Blob Uri: " + sasUriResponse.getBlobUri());

تحميل الملف إلى Azure Storage

قم بتمرير نقطة نهاية URI الكائن الثنائي كبير الحجم إلى BlobClientBuilder.buildclient لإنشاء كائن BlobClient .

BlobClient blobClient =
    new BlobClientBuilder()
        .endpoint(sasUriResponse.getBlobUri().toString())
        .buildClient();

قم باستدعاء uploadFromFile لتحميل الملف إلى Blob Storage.

String fullFileName = "Path of the file to upload";
blobClient.uploadFromFile(fullFileName);

إرسال إعلام حالة تحميل الملف إلى مركز إنترنت الأشياء

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

قم بإنشاء كائن FileUploadCompletionNoticial . اجتياز correlationId حالة نجاح تحميل الملف isSuccess . قم بتمرير isSuccesstrue قيمة عندما يكون تحميل الملف ناجحا، false عندما لا يكون ناجحا.

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

يمر هذا المثال بحالة ناجحة.

FileUploadCompletionNotification completionNotification = new FileUploadCompletionNotification(sasUriResponse.getCorrelationId(), true);
client.completeFileUpload(completionNotification);

إغلاق العميل

حرر الموارد client .

client.closeNow();

إنشاء تطبيق الواجهة الخلفية

يصف هذا القسم كيفية تلقي إعلام تحميل ملف في تطبيق خلفي.

تحتوي فئة ServiceClient على طرق يمكن للخدمات استخدامها لتلقي إعلامات تحميل الملفات.

إضافة عبارات الاستيراد

أضف عبارات الاستيراد هذه لاستخدام Azure IoT Java SDK ومعالج الاستثناءات.

import com.microsoft.azure.sdk.iot.service.*;
import java.io.IOException;
import java.net.URISyntaxException;

الاتصال بمركز إنترنت الأشياء

يمكنك توصيل خدمة الواجهة الخلفية ب IoT Hub باستخدام الطرق التالية:

  • نهج الوصول المشترك
  • Microsoft Entra

هام

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

الاتصال باستخدام نهج وصول مشترك

تحديد بروتوكول الاتصال

استخدم IotHubServiceClientProtocol لتحديد بروتوكول طبقة التطبيق الذي يستخدمه عميل الخدمة للاتصال بمركز إنترنت الأشياء.

IotHubServiceClientProtocol يقبل فقط أو AMQPSAMQPS_WS تعداد.

private static final IotHubServiceClientProtocol protocol =    
    IotHubServiceClientProtocol.AMQPS;
إنشاء كائن ServiceClient

قم بإنشاء كائن ServiceClient ، مع توفير سلسلة وبروتوكول اتصال IoT Hub.

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

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

String iotHubConnectionString = "HostName=xxxxx.azure-devices.net;SharedAccessKeyName=service;SharedAccessKey=xxxxxxxxxxxxxxxxxxxxxxxx";
private static final ServiceClient serviceClient (iotHubConnectionString, protocol);
افتح الاتصال بين التطبيق وIoT Hub

افتح اتصال مرسل AMQP. تنشئ هذه الطريقة الاتصال بين التطبيق وIoT Hub.

serviceClient.open();

الاتصال باستخدام Microsoft Entra

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

للحصول على نظرة عامة على مصادقة Java SDK، راجع مصادقة Azure باستخدام Java وAzure Identity.

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

تكوين تطبيق Microsoft Entra

يجب عليك إعداد تطبيق Microsoft Entra الذي تم تكوينه لبيانات اعتماد المصادقة المفضلة لديك. يحتوي التطبيق على معلمات مثل سر العميل التي يستخدمها تطبيق الواجهة الخلفية للمصادقة. تكوينات مصادقة التطبيق المتاحة هي:

  • سر العميل
  • شهادة
  • بيانات اعتماد الهوية الموحدة

قد تتطلب تطبيقات Microsoft Entra أذونات دور محددة اعتمادا على العمليات التي يتم تنفيذها. على سبيل المثال، مطلوب IoT Hub Twin Contributor لتمكين الوصول للقراءة والكتابة إلى جهاز IoT Hub وتوائم الوحدة النمطية. لمزيد من المعلومات، راجع إدارة الوصول إلى IoT Hub باستخدام تعيين دور Azure RBAC.

لمزيد من المعلومات حول إعداد تطبيق Microsoft Entra، راجع التشغيل السريع: تسجيل تطبيق باستخدام النظام الأساسي للهويات في Microsoft.

المصادقة باستخدام DefaultAzureCredential

أسهل طريقة لاستخدام Microsoft Entra لمصادقة تطبيق الواجهة الخلفية هي استخدام DefaultAzureCredential ، ولكن يوصى باستخدام طريقة مختلفة في بيئة إنتاج بما في ذلك طريقة محددة TokenCredential أو مخفضة ChainedTokenCredential. لمزيد من المعلومات حول إيجابيات وسلبيات الاستخدام DefaultAzureCredential، راجع سلاسل بيانات الاعتماد في مكتبة عميل Azure Identity ل Java.

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

يمكنك مصادقة بيانات اعتماد تطبيق Microsoft Entra باستخدام DefaultAzureCredentialBuilder. احفظ معلمات الاتصال مثل معرف المستأجر السري للعميل ومعرف العميل وقيم سر العميل كمتغيرات بيئية. بمجرد إنشائه TokenCredential ، قم بتمريره إلى ServiceClient أو منشئ آخر كمعلمة "بيانات الاعتماد".

في هذا المثال، DefaultAzureCredentialBuilder يحاول مصادقة اتصال من القائمة الموضحة في DefaultAzureCredential. نتيجة مصادقة Microsoft Entra الناجحة هي بيانات اعتماد رمز الأمان المميز التي يتم تمريرها إلى منشئ مثل ServiceClient.

TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build();
المصادقة باستخدام ClientSecretCredentialBuilder

يمكنك استخدام ClientSecretCredentialBuilder لإنشاء بيانات اعتماد باستخدام معلومات سرية للعميل. إذا نجحت، ترجع هذه الطريقة TokenCredential التي يمكن تمريرها إلى ServiceClient أو منشئ آخر كمعلمة "بيانات الاعتماد".

في هذا المثال، تمت إضافة سر عميل تسجيل تطبيق Microsoft Entra ومعرف العميل ومعرف المستأجر إلى متغيرات البيئة. يتم استخدام متغيرات البيئة هذه لإنشاء ClientSecretCredentialBuilder بيانات الاعتماد.

string clientSecretValue = System.getenv("AZURE_CLIENT_SECRET");
string clientID = System.getenv("AZURE_CLIENT_ID");
string tenantID = System.getenv("AZURE_TENANT_ID");

TokenCredential credential =
     new ClientSecretCredentialBuilder()
          .tenantId(tenantID)
          .clientId(clientID)
          .clientSecret(clientSecretValue)
          .build();
فئات المصادقة الأخرى

يتضمن Java SDK أيضا هذه الفئات التي تصادق على تطبيق الواجهة الخلفية باستخدام Microsoft Entra:

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

للحصول على عينات عمل من مصادقة خدمة Microsoft Entra، راجع نموذج المصادقة المستندة إلى الدور.

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

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

  1. قم بإنشاء كائن getFileUploadNotificationReceiver .
  2. استخدم open للاتصال بمركز إنترنت الأشياء.
  3. اتصل بتلقي الاتصال للتحقق من حالة تحميل الملف. ترجع هذه الطريقة كائن fileUploadNotification . في حال تلقي إشعار تحميل، يمكنك عرض حقول حالة التحميل باستخدام طرق fileUploadNotice .

على سبيل المثال:

FileUploadNotificationReceiver receiver = serviceClient.getFileUploadNotificationReceiver();
receiver.open();
FileUploadNotification fileUploadNotification = receiver.receive(2000);

if (fileUploadNotification != null)
{
    System.out.println("File Upload notification received");
    System.out.println("Device Id : " + fileUploadNotification.getDeviceId());
    System.out.println("Blob Uri: " + fileUploadNotification.getBlobUri());
    System.out.println("Blob Name: " + fileUploadNotification.getBlobName());
    System.out.println("Last Updated : " + fileUploadNotification.getLastUpdatedTimeDate());
    System.out.println("Blob Size (Bytes): " + fileUploadNotification.getBlobSizeInBytes());
    System.out.println("Enqueued Time: " + fileUploadNotification.getEnqueuedTimeUtcDate());
}
else
{
    System.out.println("No file upload notification");
}

// Close the receiver object
receiver.close();

نماذج تحميل ملف SDK

هناك نوعان من نماذج تحميل ملف Java.

تثبيت الحزم

يجب تثبيت مكتبة azure-iot-device قبل استدعاء أي تعليمات برمجية ذات صلة.

pip install azure-iot-device

يتم استخدام الحزمة azure.storage.blob لإجراء تحميل الملف.

pip install azure.storage.blob

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

يصف هذا القسم كيفية تحميل ملف من جهاز إلى مركز IoT باستخدام فئة IoTHubDeviceClient من Azure IoT SDK ل Python.

استيراد المكتبات

import os
from azure.iot.device import IoTHubDeviceClient
from azure.core.exceptions import AzureError
from azure.storage.blob import BlobClient

توصيل جهاز ب IoT Hub

يمكن لتطبيق الجهاز المصادقة باستخدام IoT Hub باستخدام الطرق التالية:

  • شهادة X.509
  • مفتاح الوصول المشترك

المصادقة باستخدام شهادة X.509

لتوصيل جهاز ب IoT Hub باستخدام شهادة X.509:

  1. استخدم create_from_x509_certificate لإضافة معلمات شهادة X.509
  2. اتصل بالاتصال لتوصيل عميل الجهاز

يوضح هذا المثال قيم معلمات إدخال الشهادة كمتغيرات محلية للوضوح. في نظام الإنتاج، قم بتخزين معلمات الإدخال الحساسة في متغيرات البيئة أو موقع تخزين آخر أكثر أمانا. على سبيل المثال، استخدم os.getenv("HOSTNAME") لقراءة متغير بيئة اسم المضيف.

# The Azure IoT hub name
hostname = "xxxxx.azure-devices.net"

# The device that has been created on the portal using X509 CA signing or self-signing capabilities
device_id = "MyDevice"

# The X.509 certificate file name
cert_file = "~/certificates/certs/sensor-thl-001-device.cert.pfx"
key_file = "~/certificates/certs/sensor-thl-001-device.cert.key"
# The optional certificate pass phrase
pass_phrase = "1234"

x509 = X509(
    cert_file,
    key_file,
    pass_phrase,
)

# The client object is used to interact with your Azure IoT hub.
device_client = IoTHubDeviceClient.create_from_x509_certificate(
    hostname=hostname, device_id=device_id, x509=x509
)

# Connect to IoT Hub
await device_client.connect()

لمزيد من المعلومات حول مصادقة الشهادة، راجع:

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

للحصول على عينات عمل لمصادقة شهادة الجهاز X.509، راجع الأمثلة التي تنتهي أسماء ملفاتها ب x509 في سيناريوهات المركز غير المتزامن.

المصادقة باستخدام مفتاح وصول مشترك

لتوصيل جهاز ب IoT Hub:

  1. اتصل create_from_connection_string لإضافة سلسلة الاتصال الأساسية للجهاز.
  2. اتصل بالاتصال لتوصيل عميل الجهاز.

على سبيل المثال:

# Add your IoT hub primary connection string
CONNECTION_STRING = "{Device primary connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(CONNECTION_STRING)

# Connect the client
device_client.connect()

الحصول على معلومات تخزين كائن ثنائي كبير الحجم

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

# Get the storage info for the blob
PATH_TO_FILE = "{Full path to local file}"
blob_name = os.path.basename(PATH_TO_FILE)
blob_info = device_client.get_storage_info_for_blob(blob_name)

تحميل ملف إلى Blob Storage

لتحميل ملف إلى Blob Storage:

  1. استخدم from_blob_url لإنشاء عنصر BlobClient من عنوان URL لكائن ثنائي كبير الحجم.
  2. اتصل upload_blob لتحميل الملف إلى تخزين كائن ثنائي كبير الحجم.

يحلل هذا المثال البنية blob_info لإنشاء عنوان URL يستخدمه لتهيئة BlobClient. ثم يستدعي upload_blob تحميل الملف إلى Blob Storage.

try:
    sas_url = "https://{}/{}/{}{}".format(
        blob_info["hostName"],
        blob_info["containerName"],
        blob_info["blobName"],
        blob_info["sasToken"]
    )

    print("\nUploading file: {} to Azure Storage as blob: {} in container {}\n".format(file_name, blob_info["blobName"], blob_info["containerName"]))

    # Upload the specified file
    with BlobClient.from_blob_url(sas_url) as blob_client:
        with open(file_name, "rb") as f:
            result = blob_client.upload_blob(f, overwrite=True)
            return (True, result)

except FileNotFoundError as ex:
    # catch file not found and add an HTTP status code to return in notification to IoT hub
    ex.status_code = 404
    return (False, ex)

except AzureError as ex:
    # catch Azure errors that might result from the upload operation
    return (False, ex)

إخطار مركز إنترنت الأشياء بحالة التحميل

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

يقوم هذا المثال بإعلام مركز إنترنت الأشياء بتحميل ملف ناجح:

device_client.notify_blob_upload_status(storage_info["correlationId"], True, 200, "OK: {}".format(PATH_TO_FILE)

إيقاف تشغيل عميل الجهاز

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

device_client.shutdown()

نماذج تحميل ملف SDK

تتضمن SDK نموذجين لتحميل الملفات:

نظرة عامة‬

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

إنشاء تطبيق جهاز

يصف هذا القسم كيفية تحميل ملف من جهاز إلى مركز IoT باستخدام حزمة azure-iot-device في Azure IoT SDK ل Node.js.

تثبيت حزم SDK

قم بتشغيل هذا الأمر لتثبيت azure-iot-device device SDK وazure-iot-device-mqtt وحزم @azure/storage-blob على جهاز التطوير الخاص بك:

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

تحتوي حزمة azure-iot-device على كائنات تتفاعل مع أجهزة إنترنت الأشياء.

اتبع هذا الإجراء لتحميل ملف من جهاز إلى مركز إنترنت الأشياء:

  1. قم بتوصيل الجهاز ب IoT Hub
  2. الحصول على رمز مميز لتوقيع الوصول المشترك (SAS) لكائن ثنائي كبير الحجم من IoT Hub
  3. تحميل الملف إلى Azure Storage
  4. إرسال إعلام حالة تحميل الملف إلى مركز إنترنت الأشياء

إنشاء وحدات

قم بإنشاء وحدات العميل والبروتوكول والأخطاء والمسار باستخدام الحزم المثبتة.

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

توصيل جهاز ب IoT Hub

يمكن لتطبيق الجهاز المصادقة باستخدام IoT Hub باستخدام الطرق التالية:

  • شهادة X.509
  • مفتاح الوصول المشترك

المصادقة باستخدام شهادة X.509

يتم إرفاق شهادة X.509 بنقل اتصال الجهاز إلى IoT Hub.

لتكوين اتصال من جهاز إلى IoT Hub باستخدام شهادة X.509:

  1. قم باستدعاء fromConnectionString لإضافة سلسلة اتصال الجهاز أو الوحدة النمطية للهوية، ونوع النقل إلى Client الكائن. أضف x509=true إلى سلسلة الاتصال للإشارة إلى إضافة شهادة إلى DeviceClientOptions. على سبيل المثال:

    • سلسلة اتصال الجهاز :

      HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true

    • سلسلة اتصال وحدة الهوية :

      HostName=xxxxx.azure-devices.net;DeviceId=Device-1;ModuleId=Module-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true

  2. قم بتكوين متغير JSON بتفاصيل الشهادة وقم بتمريره إلى DeviceClientOptions.

  3. استدعاء setOptions لإضافة شهادة X.509 ومفتاح (واختياريا، عبارة مرور) إلى نقل العميل.

  4. المكالمة مفتوحة لفتح الاتصال من الجهاز إلى IoT Hub.

يعرض هذا المثال معلومات تكوين الشهادة داخل متغير JSON. يتم تمرير تكوين clientOptions الشهادة إلى setOptions، ويتم فتح الاتصال باستخدام open.

const Client = require('azure-iot-device').Client;
const Protocol = require('azure-iot-device-mqtt').Mqtt;
// Connection string illustrated for demonstration only. Never hard-code the connection string in production. Instead use an environmental variable or other secure storage.
const connectionString = `HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true`
const client = Client.fromConnectionString(connectionString, Protocol);

var clientOptions = {
   cert: myX509Certificate,
   key: myX509Key,
   passphrase: passphrase,
   http: {
     receivePolicy: {
       interval: 10
     }
   }
 }

 client.setOptions(clientOptions);
 client.open(connectCallback);

لمزيد من المعلومات حول مصادقة الشهادة، راجع:

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

للحصول على عينة عمل لمصادقة شهادة الجهاز X.509، راجع نموذج بسيط للجهاز X.509.

المصادقة باستخدام مفتاح وصول مشترك

اختر بروتوكول نقل

يدعم الكائن Client هذه البروتوكولات:

  • Amqp
  • Http - عند الاستخدام Http، يتحقق المثيل Client من الرسائل الواردة من IoT Hub بشكل غير متكرر (كل 25 دقيقة على الأقل).
  • Mqtt
  • MqttWs
  • AmqpWs

قم بتثبيت بروتوكولات النقل المطلوبة على جهاز التطوير الخاص بك.

على سبيل المثال، يقوم هذا الأمر بتثبيت البروتوكول Amqp :

npm install azure-iot-device-amqp --save

لمزيد من المعلومات حول الاختلافات بين دعم MQTT وAMQP وHTTPS، راجع إرشادات الاتصالات من السحابة إلى الجهازواختيار بروتوكول اتصال.

إنشاء كائن عميل

قم بإنشاء Client كائن باستخدام الحزمة المثبتة.

على سبيل المثال:

const Client = require('azure-iot-device').Client;
إنشاء كائن بروتوكول

قم بإنشاء Protocol كائن باستخدام حزمة نقل مثبتة.

يقوم هذا المثال بتعيين بروتوكول AMQP:

const Protocol = require('azure-iot-device-amqp').Amqp;
إضافة سلسلة اتصال الجهاز وبروتوكول النقل

اتصل fromConnectionString لتوفير معلمات اتصال الجهاز:

  • connStr - سلسلة اتصال الجهاز.
  • transportCtor - بروتوكول النقل.

يستخدم Amqp هذا المثال بروتوكول النقل:

const deviceConnectionString = "{IoT hub device connection string}"
const Protocol = require('azure-iot-device-mqtt').Amqp;
let client = Client.fromConnectionString(deviceConnectionString, Protocol);
افتح الاتصال ب IoT Hub

استخدم الطريقة المفتوحة لفتح الاتصال بين جهاز IoT وIoT Hub.

على سبيل المثال:

client.open(function(err) {
  if (err) {
    console.error('error connecting to hub: ' + err);
    process.exit(1);
  }
})

احصل على رمز SAS المميز من مركز إنترنت الأشياء

استخدم getBlobSharedAccessSignature للحصول على رمز SAS المميز لحساب التخزين المرتبط من مركز IoT.

على سبيل المثال:

// make sure you set these environment variables prior to running the sample.
const localFilePath = process.env.PATH_TO_FILE;
const storageBlobName = path.basename(localFilePath);
const blobInfo = await client.getBlobSharedAccessSignature(storageBlobName);
if (!blobInfo) {
throw new errors.ArgumentError('Invalid upload parameters');
}

تحميل الملف إلى مركز إنترنت الأشياء

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

  1. إنشاء مسار دفق
  2. إنشاء عنوان URL للكائن الثنائي كبير الحجم
  3. إنشاء BlockBlobClient لتحميل الملفات إلى Blob Storage
  4. استدعاء uploadFile لتحميل الملف إلى Blob Storage
  5. استدعاء notifyBlobUploadStatus لإعلام مركز إنترنت الأشياء بنجاح التحميل أو فشله

على سبيل المثال:

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

// Construct the blob URL
const { hostName, containerName, blobName, sasToken } = blobInfo;
const blobUrl = `https://${hostName}/${containerName}/${blobName}${sasToken}`;

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

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

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

  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);
  }

// Send file upload status notification to IoT hub
await client.notifyBlobUploadStatus(blobInfo.correlationId, isSuccess, statusCode, statusDescription);

تحميل الملف المحلي إلى تخزين الكائن الثنائي كبير الحجم

يمكنك تحميل ملف محلي إلى تخزين كائن ثنائي كبير الحجم من جهاز كمبيوتر

const deviceClient = Client.fromConnectionString(deviceConnectionString, Protocol);
uploadToBlob(localFilePath, deviceClient)
  .catch((err) => {
    console.log(err);
  })
  .finally(() => {
    process.exit();
  });

نموذج تحميل ملف SDK

تتضمن SDK نموذجا متقدما للتحميل إلى كائن ثنائي كبير الحجم .

إنشاء تطبيق الواجهة الخلفية

يصف هذا القسم كيفية تلقي إعلامات تحميل الملفات في تطبيق خلفي.

تحتوي فئة ServiceClient على طرق يمكن للخدمات استخدامها لتلقي إعلامات تحميل الملفات.

تثبيت حزمة SDK للخدمة

قم بتشغيل هذا الأمر لتثبيت azure-iothub على جهاز التطوير الخاص بك:

npm install azure-iothub --save

الاتصال بمركز إنترنت الأشياء

يمكنك توصيل خدمة الواجهة الخلفية ب IoT Hub باستخدام الطرق التالية:

  • نهج الوصول المشترك
  • Microsoft Entra

هام

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

الاتصال باستخدام نهج وصول مشترك

استخدم fromConnectionString للاتصال بمركز IoT.

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

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

var Client = require('azure-iothub').Client;
var connectionString = '{IoT hub shared access policy connection string}';
var client = Client.fromConnectionString(connectionString);

الاتصال باستخدام Microsoft Entra

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

للحصول على نظرة عامة على مصادقة Node.js SDK، راجع:

تكوين تطبيق Microsoft Entra

يجب عليك إعداد تطبيق Microsoft Entra الذي تم تكوينه لبيانات اعتماد المصادقة المفضلة لديك. يحتوي التطبيق على معلمات مثل سر العميل التي يستخدمها تطبيق الواجهة الخلفية للمصادقة. تكوينات مصادقة التطبيق المتاحة هي:

  • سر العميل
  • شهادة
  • بيانات اعتماد الهوية الموحدة

قد تتطلب تطبيقات Microsoft Entra أذونات دور محددة اعتمادا على العمليات التي يتم تنفيذها. على سبيل المثال، مطلوب IoT Hub Twin Contributor لتمكين الوصول للقراءة والكتابة إلى جهاز IoT Hub وتوائم الوحدة النمطية. لمزيد من المعلومات، راجع إدارة الوصول إلى IoT Hub باستخدام تعيين دور Azure RBAC.

لمزيد من المعلومات حول إعداد تطبيق Microsoft Entra، راجع التشغيل السريع: تسجيل تطبيق باستخدام النظام الأساسي للهويات في Microsoft.

المصادقة باستخدام DefaultAzureCredential

أسهل طريقة لاستخدام Microsoft Entra لمصادقة تطبيق الواجهة الخلفية هي استخدام DefaultAzureCredential ، ولكن يوصى باستخدام طريقة مختلفة في بيئة إنتاج بما في ذلك طريقة محددة TokenCredential أو مخفضة ChainedTokenCredential. للتبسيط، يصف هذا القسم المصادقة باستخدام DefaultAzureCredential سر العميل. لمزيد من المعلومات حول إيجابيات وسلبيات الاستخدام DefaultAzureCredential، راجع سلاسل بيانات الاعتماد في مكتبة عميل Azure Identity ل JavaScript

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

يتطلب Microsoft Entra هذه الحزمة:

npm install --save @azure/identity

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

import { DefaultAzureCredential } from "@azure/identity";

// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();

يمكن بعد ذلك تمرير الرمز المميز لبيانات الاعتماد الناتج إلى fromTokenCredential للاتصال ب IoT Hub لأي عميل SDK يقبل بيانات اعتماد Microsoft Entra:

fromTokenCredential يتطلب معلمتين:

  • عنوان URL لخدمة Azure - يجب أن يكون عنوان URL لخدمة Azure بالتنسيق {Your Entra domain URL}.azure-devices.net بدون https:// بادئة. على سبيل المثال، MyAzureDomain.azure-devices.net
  • الرمز المميز لبيانات اعتماد Azure

في هذا المثال، يتم الحصول على بيانات اعتماد Azure باستخدام DefaultAzureCredential. ثم يتم توفير عنوان URL لمجال Azure وبيانات الاعتماد لإنشاء Registry.fromTokenCredential الاتصال ب IoT Hub.

const { DefaultAzureCredential } = require("@azure/identity");

let Registry = require('azure-iothub').Registry;

// Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

// Set environment variables
process.env['AZURE_CLIENT_SECRET'] = clientSecretValue;
process.env['AZURE_CLIENT_ID'] = clientID;
process.env['AZURE_TENANT_ID'] = tenantID;

// Acquire a credential object
const credential = new DefaultAzureCredential()

// Create an instance of the IoTHub registry
hostName = 'MyAzureDomain.azure-devices.net';
let registry = Registry.fromTokenCredential(hostName,credential);
نماذج التعليمات البرمجية

للحصول على عينات عمل من مصادقة خدمة Microsoft Entra، راجع أمثلة هوية Azure.

إنشاء جهاز استقبال معاودة الاتصال بإشعار تحميل الملف

لإنشاء جهاز استقبال معاودة الاتصال بإشعار تحميل الملف:

  1. اتصل ب getFileNotificationReceiver. قم بتوفير اسم طريقة معاودة الاتصال بتحميل الملف التي يتم استدعاؤها عند تلقي رسائل الإعلام.
  2. معالجة إشعارات تحميل الملفات بطريقة معاودة الاتصال.

يقوم هذا المثال بإعداد receiveFileUploadNotification جهاز استقبال معاودة الاتصال بالإعلام. يفسر جهاز الاستقبال معلومات حالة تحميل الملف ويطبع رسالة حالة على وحدة التحكم.

//Set up the receiveFileUploadNotification notification message callback receiver
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');
      }
    });
  });
}

نموذج إشعار تحميل ملف SDK

تتضمن SDK عينة تحميل ملف .

  • Last updated on