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

نظرة عامة

تحتوي هذه الكيفية على قسمين:

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

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

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

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

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

توصيل جهاز بـ 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
• البرنامج التعليمي: إنشاء الشهادات وتحميلها للاختبار

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

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

• الاتصال بشهادة X.509
• DeviceClientX509AuthenticationE2ETests
• مشروع موجه - توفير أجهزة IoT بشكل آمن وعلى نطاق واسع باستخدام خدمة توفير جهاز IoT Hub

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

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

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

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

الحصول على SAS URI من مركز IoT

اتصل ب 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 لإنشاء عميل Blob لكتلة تخزين Azure وتحميل الملف:

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

إعلام مركز IoT بحالة تحميل الملف

استخدم CompleteFileUploadAsync لإعلام مركز IoT بأن عميل الجهاز أكمل التحميل، وتمرير كائن FileUploadCompletionNotification . IsSuccess تشير العلامة إلى ما إذا كان التحميل ناجحا أم لا. بعد إعلامك، سيصدر مركز IoT الموارد المرتبطة بالتحميل (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 نموذج تحميل الملف هذا.

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

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

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

إضافة حزمة NuGet للخدمة

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

الاتصال بمركز IoT

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

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

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

قم بتوصيل تطبيق الواجهة الخلفية بجهاز باستخدام 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:

• JobClient
• إدارة السجل
• DigitalTwinClient
• ServiceClient

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

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

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

string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);

Code sample

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

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

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

1. إنشاء رمز إلغاء.
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.

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

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

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

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

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

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

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

1. إنشاء كائن SSLContext باستخدام buildSSLContext.
2. SSLContext أضف المعلومات إلى كائن ClientOptions.
3. اتصل ب DeviceClient باستخدام ClientOptions المعلومات لإنشاء اتصال Device-to-IoT Hub.

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

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

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

• عينة إرسال وتلقي x509
• إرسال الحدث x509

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

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

IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;

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

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

الحصول على SAS URI من مركز IoT

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

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

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

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

مرر نقطة نهاية blob 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

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

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

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

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

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

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

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

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

تعريف بروتوكول الاتصال

استخدم IotHubServiceClientProtocol لتحديد بروتوكول طبقة التطبيق المستخدم من قبل عميل الخدمة للاتصال بمركز IoT.

IotHubServiceClientProtocol يقبل AMQPS فقط قائمة التعداد أو AMQPS_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.

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:

• AuthorizationCodeCredential
• AzureCliCredential
• AzureDeveloperCliCredential
• AzurePipelinesCredential
• ChainedTokenCredential
• ClientAssertionCredential
• ClientCertificateCredential
• DeviceCodeCredential
• بيئة معتمدة
• InteractiveBrowserCredential
• ManagedIdentityCredential
• OnBehalfOfCredential

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

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

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

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

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

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

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 قبل استدعاء أي تعليمات برمجية ذات صلة.

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
• البرنامج التعليمي: إنشاء الشهادات وتحميلها للاختبار

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

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

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

لتوصيل جهاز ب 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()

الحصول على معلومات Blob Storage

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

# 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 Storage.

يوزع 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)

إعلام مركز IoT بحالة التحميل

استخدم notify_blob_upload_status لإعلام مركز IoT بحالة عملية Blob Storage. قم بتمرير الذي correlation_id تم الحصول عليه بواسطة get_storage_info_for_blob الأسلوب . correlation_id يستخدم مركز IoT لإعلام أي خدمة قد تستمع إلى إشعار يتعلق بحالة مهمة تحميل الملف.

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

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

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

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

device_client.shutdown()

عينات تحميل ملف SDK

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

• تحميل إلى كائن ثنائي كبير الحجم
• تحميل إلى كائن ثنائي كبير الحجم باستخدام شهادة X.509

نظرة عامة

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

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

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

تثبيت حزم SDK

قم بتشغيل هذا الأمر لتثبيت azure-iot-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 على كائنات واجهة مع أجهزة IoT.

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

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

إنشاء وحدات نمطية

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

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.

لتكوين اتصال Device-to-IoT Hub باستخدام شهادة X.509:

1. اتصل منConnectionString لإضافة وحدة الجهاز أو الهوية سلسلة الاتصال، ونوع النقل إلى 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
• إنشاء الشهادات وتحميلها للاختبار

Code sample

للحصول على نموذج عمل لمصادقة شهادة الجهاز 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;

إضافة سلسلة الاتصال الجهاز وبروتوكول النقل

استدعاء منConnectionString لتوفير معلمات اتصال الجهاز:

• 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 المميز من مركز IoT

استخدم 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');
}

تحميل الملف إلى مركز IoT

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

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

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

// 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

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

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

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

استخدم منConnectionString للاتصال بمركز 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، راجع:

• الشروع في العمل مع مصادقة المستخدم على Azure
• مكتبة عميل Azure Identity لـ JavaScript

تكوين تطبيق 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:

• التسجيل
• العميل
• JobClient

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

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

في هذا المثال، يتم الحصول على بيانات اعتماد Azure باستخدام DefaultAzureCredential. ثم يتم توفير Registry.fromTokenCredential عنوان URL لمجال Azure وبيانات الاعتماد لإنشاء الاتصال ب 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 عينة تحميل ملف.