البدء باستخدام إدارة الأجهزة

• يتطلب Visual Studio

نظرة عامة

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

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

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

حزم NuGet للجهاز المطلوب

تتطلب تطبيقات عميل الجهاز المكتوبة بلغة C# حزمة Microsoft.Azure.Devices.Client NuGet.

أضف هذه using العبارات لاستخدام مكتبة الجهاز.

using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;

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

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

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

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

تعرض فئة DeviceClient جميع الطرق المطلوبة للتفاعل مع رسائل الجهاز من الجهاز.

الاتصال بالجهاز باستخدام أسلوب CreateFromConnectionString جنبا إلى جنب مع سلسلة الاتصال الجهاز وبروتوكول نقل الاتصال.

CreateFromConnectionString تدعم معلمة بروتوكول النقل TransportType بروتوكولات النقل التالية:

• Mqtt
• Mqtt_WebSocket_Only
• Mqtt_Tcp_Only
• Amqp
• Amqp_WebSocket_Only
• Amqp_Tcp_Only
• Http1

يتصل هذا المثال بجهاز باستخدام Mqtt بروتوكول النقل.

static string DeviceConnectionString = "{IoT hub device connection string}";
static deviceClient = null;
deviceClient = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
   TransportType.Mqtt);

المصادقة باستخدام شهادة 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

إنشاء مستمع رد اتصال أسلوب مباشر

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

يقوم هذا المثال بإعداد وحدة استماع رد الاتصال المسماة onReboot التي سيتم تشغيلها عند استدعاء اسم الأسلوب المباشر "إعادة التشغيل".

try
{
      // setup callback for "reboot" method
      deviceClient.SetMethodHandlerAsync("reboot", onReboot, null).Wait();
      Console.WriteLine("Waiting for reboot method\n Press enter to exit.");
      Console.ReadLine();

      Console.WriteLine("Exiting...");

      // as a good practice, remove the "reboot" handler
      deviceClient.SetMethodHandlerAsync("reboot", null, null).Wait();
      deviceClient.CloseAsync().Wait();
}
catch (Exception ex)
{
      Console.WriteLine();
      Console.WriteLine("Error in sample: {0}", ex.Message);
}

استمرارا للمثال، onReboot يقوم أسلوب رد الاتصال بتنفيذ الأسلوب المباشر على الجهاز.

تستدعي دالة المعالج MethodResponse لإرسال إقرار استجابة إلى تطبيق الاستدعاء.

static Task<MethodResponse> onReboot(MethodRequest methodRequest, object userContext)
{
      // In a production device, you would trigger a reboot 
      // scheduled to start after this method returns.
      // For this sample, we simulate the reboot by writing to the console
      // and updating the reported properties.
      try
      {
         Console.WriteLine("Rebooting!");
      }
      catch (Exception ex)
      {
         Console.WriteLine();
         Console.WriteLine("Error in sample: {0}", ex.Message);
      }

      string result = @"{""result"":""Reboot started.""}";
      return Task.FromResult(new MethodResponse(Encoding.UTF8.GetBytes(result), 200));
}

عينات جهاز SDK

يوفر Azure IoT SDK ل .NET نماذج عمل لتطبيقات الجهاز التي تتعامل مع مهام الأسلوب المباشر. لمزيد من المعلومات، راجع:

• نموذج الأسلوب
• جهاز محاكاة مع أمر
• وحدة تحكم درجة الحرارة
• عينة منظم الحرارة

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

يصف هذا القسم كيفية تشغيل أسلوب مباشر على جهاز.

تعرض فئة ServiceClient جميع الأساليب المطلوبة لإنشاء تطبيق خلفية لإرسال استدعاءات الأسلوب المباشر إلى الأجهزة.

حزمة NuGet للخدمة المطلوبة

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

أضف هذه using العبارات لاستخدام مكتبة الخدمة.

using Microsoft.Azure.Devices;
using Microsoft.Azure.Devices.Shared;

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

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

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

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

قم بتوصيل تطبيق الواجهة الخلفية باستخدام CreateFromConnectionString.

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

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

ServiceClient serviceClient;
string connectionString = "{IoT hub service 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. إنشاء كائن CloudToDeviceMethod . مرر اسم الأسلوب المباشر للجهاز كمعلمة.
2. استدعاء InvokeDeviceMethodAsync لاستدعاء الأسلوب على الجهاز.

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

string targetDevice = "myDeviceId";
CloudToDeviceMethod method = new CloudToDeviceMethod("reboot");
method.ResponseTimeout = TimeSpan.FromSeconds(30);

CloudToDeviceMethodResult response = await serviceClient.InvokeDeviceMethodAsync(targetDevice, method);

Console.WriteLine("Invoked firmware update on device.");

عينات خدمة SDK

يوفر Azure IoT SDK ل .NET نماذج عمل لتطبيقات الخدمة التي تتعامل مع مهام الرسائل. لمزيد من المعلومات، راجع:

• استدعاء أسلوب الجهاز
• اختبارات الأسلوب E2E
• وحدة تحكم درجة الحرارة
• عينة منظم الحرارة

• يتطلب Java SE Development Kit 8. تأكد من تحديد Java 8 ضمن الدعم طويل المدى للانتقال إلى التنزيلات ل JDK 8.

نظرة عامة

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

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

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

تعرض فئة DeviceClient جميع الأساليب التي تحتاجها للتفاعل مع الأساليب المباشرة على الجهاز.

عبارات استيراد الجهاز

استخدم عبارات استيراد الجهاز التالية للوصول إلى Azure IoT SDK ل Java.

import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.exceptions.IotHubClientException;
import com.microsoft.azure.sdk.iot.device.twin.DirectMethodPayload;
import com.microsoft.azure.sdk.iot.device.twin.DirectMethodResponse;
import com.microsoft.azure.sdk.iot.device.twin.MethodCallback;
import com.microsoft.azure.sdk.iot.device.transport.IotHubConnectionStatus;
import com.microsoft.azure.sdk.iot.device.twin.SubscriptionAcknowledgedCallback;

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

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

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

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

للاتصال بجهاز:

1. استخدم IotHubClientProtocol لاختيار بروتوكول نقل. على سبيل المثال:

   IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
   

2. استخدم الدالة DeviceClient الإنشائية لإضافة سلسلة الاتصال الأساسي للجهاز والبروتوكول.

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

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

   client.open(true);
   

المصادقة باستخدام شهادة 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

إنشاء مستمع رد اتصال أسلوب مباشر

استخدم subscribeToMethods لتهيئة مستمع رد اتصال أسلوب مباشر. subscribeToMethods يستمع للأساليب المباشرة الواردة حتى يتم إنهاء الاتصال. يتم تلقي اسم الأسلوب والحمولة لكل استدعاء أسلوب مباشر.

يجب على وحدة الاستماع استدعاء DirectMethodResponse لإرسال إقرار استجابة الأسلوب إلى تطبيق الاستدعاء.

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

client.subscribeToMethods(
    (methodName, methodData, context) ->
    {
        System.out.println("Received a direct method invocation with name " + methodName + " and payload " + methodData.getPayloadAsJsonString());
        return new DirectMethodResponse(200, methodData);
    },
    null);
System.out.println("Successfully subscribed to direct methods");

عينات جهاز SDK

يتضمن Azure IoT SDK ل Java عينة عمل لاختبار مفاهيم تطبيق الجهاز الموضحة في هذه المقالة. لمزيد من المعلومات، راجع نموذج الأسلوب المباشر.

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

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

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

عبارات استيراد الخدمة

استخدم عبارات استيراد الخدمة التالية للوصول إلى Azure IoT SDK ل Java.

import com.microsoft.azure.sdk.iot.service.methods.DirectMethodRequestOptions;
import com.microsoft.azure.sdk.iot.service.methods.DirectMethodsClient;
import com.microsoft.azure.sdk.iot.service.methods.DirectMethodResponse;

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

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

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

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

استخدم منشئ DeviceMethod لإضافة سلسلة الاتصال الأساسي للخدمة والاتصال ب IoT Hub.

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

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

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

String iotHubConnectionString = "HostName=xxxxx.azure-devices.net;SharedAccessKeyName=service;SharedAccessKey=xxxxxxxxxxxxxxxxxxxxxxxx";
DeviceMethod methodClient = new DeviceMethod(iotHubConnectionString);

الاتصال باستخدام 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، راجع نموذج المصادقة المستندة إلى الدور.

استدعاء أسلوب على جهاز

استدعاء DeviceMethod.invoke لاستدعاء أسلوب على جهاز وإرجاع حالة النتيجة.

معلمة الحمولة invoke اختيارية. استخدم null إذا لم يتم توفير حمولة. يمكن أن تتخذ معلمة الحمولة أشكال بيانات مختلفة بما في ذلك سلسلة وصفيف بايت و HashMap. للحصول على أمثلة، راجع اختبارات الأسلوب المباشر.

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

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

String deviceId = "myFirstDevice";
String methodName = "reboot";
String payload = "Test payload";
Long responseTimeout = TimeUnit.SECONDS.toSeconds(30);
Long connectTimeout = TimeUnit.SECONDS.toSeconds(5);

MethodResult result = methodClient.invoke(deviceId, methodName, responseTimeout, connectTimeout, payload);
if (result == null)
{
    throw new IOException("Method invoke returns null");
}
System.out.println("Status=" + result.getStatus());

عينات خدمة SDK

يوفر Azure IoT SDK ل Java عينة عمل من تطبيقات الخدمة التي تتعامل مع مهام الأسلوب المباشر. لمزيد من المعلومات، راجع:

• نموذج أسلوب مباشر
• عينة خدمة منظم الحرارة

• Python SDK - يوصى باستخدام Python الإصدار 3.7 أو أحدث . تأكد من استخدام التثبيت 32 بت أو 64 بت كما هو مطلوب من قبل الإعداد الخاص بك. عند المطالبة في أثناء التثبيت، تأكد من إضافة Python إلى متغيرات البيئة الخاصة بالنظام الأساسي.

نظرة عامة

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

تثبيت الحزم

يجب تثبيت مكتبة جهاز azure-iot لإنشاء تطبيقات الجهاز.

pip install azure-iot-device

يجب تثبيت مكتبة azure-iot-hub لإنشاء تطبيقات خدمة الواجهة الخلفية.

pip install azure-iot-hub

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

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

تحتوي فئة IoTHubDeviceClient على أساليب يمكن استخدامها للعمل مع الأساليب المباشرة.

عبارة استيراد الجهاز

أضف عبارة الاستيراد هذه للوصول IoTHubDeviceClient و MethodResponse.

# import the device client library
from azure.iot.device import IoTHubDeviceClient, MethodResponse

الاتصال بجهاز

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

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

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

استخدم create_from_connection_string لتوصيل تطبيق بجهاز باستخدام جهاز سلسلة الاتصال.

# substitute the device connection string in conn_str
# and add it to the IoTHubDeviceClient object
conn_str = "{IoT hub device connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(conn_str)

المصادقة باستخدام شهادة 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.

إنشاء رد اتصال أسلوب مباشر

استخدم on_method_request_received لإنشاء دالة معالج أو coroutine يتم استدعاؤها عند تلقي أسلوب مباشر. وحدة الاستماع مقترنة بكلمة أساسية لاسم الأسلوب، مثل "إعادة التشغيل". يمكن استخدام اسم الأسلوب في IoT Hub أو تطبيق الخلفية لتشغيل أسلوب رد الاتصال على الجهاز.

يجب أن تنشئ دالة المعالج MethodResponse وتمريرها إلى send_method_response لإرسال إقرار استجابة أسلوب مباشر إلى تطبيق الاستدعاء.

يقوم هذا المثال بإعداد معالج أسلوب مباشر يسمى method_request_handler.

try:
    # Attach the handler to the client
    client.on_method_request_received = method_request_handler
except:
    # In the event of failure, clean up
    client.shutdown()

في هذا المثال، method_request_handler ينفذ أسلوب رد الاتصال الأسلوب المباشر على الجهاز. يتم تنفيذ التعليمات البرمجية عند استدعاء الأسلوب المباشر "rebootDevice" من تطبيق خدمة. يستدعي send_method_response الأسلوب لإرسال إقرار استجابة أسلوب مباشر إلى تطبيق الاستدعاء.

# Define the handler for method requests
def method_request_handler(method_request):
    if method_request.name == "rebootDevice":
        # Act on the method by rebooting the device
        print("Rebooting device")
        time.sleep(20)
        print("Device rebooted")
        # Create a method response indicating the method request was resolved
        resp_status = 200
        resp_payload = {"Response": "This is the response from the device"}
        method_response = MethodResponse(method_request.request_id, resp_status, resp_payload)
    else:
        # Create a method response indicating the method request was for an unknown method
        resp_status = 404
        resp_payload = {"Response": "Unknown method"}
        method_response = MethodResponse(method_request.request_id, resp_status, resp_payload)

    # Send the method response
    client.send_method_response(method_response)

عينات جهاز SDK

يوفر Azure IoT SDK ل Python عينة عمل لتطبيق جهاز يعالج مهام الأسلوب المباشر. لمزيد من المعلومات، راجع تلقي أسلوب مباشر.

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

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

تعرض فئة IoTHubRegistryManager جميع الطرق المطلوبة لإنشاء تطبيق الخلفية لإرسال الرسائل إلى جهاز.

عبارات استيراد الخدمة

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

from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import CloudToDeviceMethod, CloudToDeviceMethodResult

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

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

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

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

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

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

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

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

# Connect to IoT hub
IOTHUB_CONNECTION_STRING = "{IoT hub service connection string}"
iothub_registry_manager = IoTHubRegistryManager.from_connection_string(IOTHUB_CONNECTION_STRING)

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

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

للحصول على نظرة عامة حول مصادقة Python SDK، راجع مصادقة تطبيقات Python على خدمات Azure باستخدام Azure SDK ل Python

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

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

يتطلب Microsoft Entra حزمة الاستيراد هذه والبيان المقابل import :

pip install azure-identity

from azure.identity import DefaultAzureCredential

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

from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()

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

• IoTHubRegistryManager لإنشاء اتصال خدمة ب IoT Hub باستخدام بيانات اعتماد الرمز المميز ل Entra.
• IoTHubJobManager
• DigitalTwinClient
• IoTHubHttpRuntimeManager
• IoTHubConfigurationManager

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

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

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

import sys
import os

from azure.identity import DefaultAzureCredential
from azure.iot.hub import IoTHubRegistryManager

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

# Set environment variables
os.environ['AZURE_CLIENT_SECRET'] = clientSecretValue
os.environ['AZURE_CLIENT_ID'] = clientID
os.environ['AZURE_TENANT_ID'] = tenantID

# Acquire a credential object
credential = DefaultAzureCredential()

# Use Entra to authorize IoT Hub service
print("Connecting to IoTHubRegistryManager...")
iothub_registry_manager = IoTHubRegistryManager.from_token_credential(
url="MyAzureDomain.azure-devices.net",
token_credential=credential)

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

للحصول على نماذج العمل لمصادقة خدمة Microsoft Entra، راجع مكتبة مصادقة Microsoft (MSAL) ل Python.

استدعاء أسلوب على جهاز

يمكنك استدعاء أسلوب مباشر بالاسم على جهاز. يعرف اسم الأسلوب الأسلوب . في مثال الجهاز التالي والسابق الموضح في إنشاء رد اتصال أسلوب مباشر، اسم الأسلوب المباشر هو "rebootDevice".

لطلب أسلوب مباشر على الجهاز:

1. إنشاء كائن CloudToDeviceMethod . توفير اسم الأسلوب والحمولة كمعلمات.
2. استدعاء invoke_device_method لاستدعاء أسلوب مباشر على جهاز. قم بتوفير معرف الجهاز وكائن CloudToDeviceMethod البيانات الأساسية كمعلمات.

يستدعي CloudToDeviceMethod هذا المثال استدعاء أسلوب مباشر يسمى "rebootDevice" على جهاز. بعد استدعاء الأسلوب المباشر بنجاح، يتم عرض حمولة استجابة الأسلوب المباشر.

CONNECTION_STRING = "{IoTHubConnectionString}"
DEVICE_ID = "{deviceId}"

METHOD_NAME = "rebootDevice"
METHOD_PAYLOAD = "{\"method_number\":\"42\"}"
TIMEOUT = 60
WAIT_COUNT = 10

try:
    print ( "" )
    print ( "Invoking device to reboot..." )

    # Call the direct method.
    deviceMethod = CloudToDeviceMethod(method_name=METHOD_NAME, payload=METHOD_PAYLOAD)
    response = registry_manager.invoke_device_method(DEVICE_ID, deviceMethod)

    print ( "Successfully invoked the device to reboot." )

    print ( "The device has returned this payload:" )
    print ( response.payload )

except Exception as ex:
    print ( "" )
    print ( "Unexpected error {0}".format(ex) )
    return

عينات خدمة SDK

يوفر Azure IoT SDK ل Python نماذج عمل لتطبيقات الخدمة التي تتعامل مع مهام الأسلوب المباشر. لمزيد من المعلومات، راجع:

• مزامنة مساعد الخدمة
• عمليات الخدمة

• يتطلب Node.js الإصدار 10.0.x أو أحدث

نظرة عامة

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

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

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

تثبيت حزمة SDK

تحتوي حزمة azure-iot-device على كائنات واجهة مع أجهزة IoT. قم بتشغيل هذا الأمر لتثبيت Azure-iot-device SDK على جهاز التطوير الخاص بك:

npm install azure-iot-device --save

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

إنشاء رد اتصال أسلوب مباشر

استدعاء onDeviceMethod لإنشاء دالة معالج رد اتصال أو coroutine التي يتم استدعاؤها عند تلقي أسلوب مباشر. وحدة الاستماع مقترنة بكلمة أساسية لاسم الأسلوب، مثل "إعادة التشغيل". يمكن استخدام اسم الأسلوب في IoT Hub أو تطبيق الخلفية لتشغيل أسلوب رد الاتصال على الجهاز.

يجب أن تستدعي response.send دالة معالج رد الاتصال لإرسال رسالة إقرار استجابة إلى تطبيق الاستدعاء.

يقوم هذا المثال بإعداد معالج أسلوب مباشر يسمى onReboot يسمى عند استخدام اسم الأسلوب المباشر "إعادة التشغيل".

client.onDeviceMethod('reboot', onReboot);

في هذا المثال، onReboot ينفذ أسلوب رد الاتصال الأسلوب المباشر على الجهاز. يتم تنفيذ التعليمات البرمجية عند استدعاء الأسلوب المباشر "إعادة التشغيل" من تطبيق خدمة. تستدعي response.send الدالة لإرسال رسالة إقرار استجابة إلى تطبيق الاستدعاء.

var onReboot = function(request, response) {

    // Respond the cloud app for the direct method
    response.send(200, 'Reboot started', function(err) {
        if (err) {
            console.error('An error occurred when sending a method response:\n' + err.toString());
        } else {
            console.log('Response to method \'' + request.methodName + '\' sent successfully.');
        }
    });

    // Add your device's reboot API for physical restart.
    console.log('Rebooting!');
};

عينات جهاز SDK

يوفر Azure IoT SDK for Node.js نماذج عمل لتطبيقات الأجهزة التي تتعامل مع مهام إدارة الجهاز. لمزيد من المعلومات، راجع:

• نموذج أسلوب الجهاز
• اختبار أساليب الجهاز E2E
• إعادة تشغيل الجهاز لأنماط DM

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

يصف هذا القسم كيفية استدعاء أسلوب مباشر على جهاز.

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

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

npm install azure-iothub --save

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

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

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

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

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

لاستدعاء أسلوب مباشر على جهاز من خلال مركز 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.

استدعاء أسلوب على جهاز

استخدم invokeDeviceMethod لاستدعاء أسلوب مباشر بالاسم على جهاز. تحدد معلمة اسم الأسلوب الأسلوب المباشر.

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

var startRebootDevice = function(deviceToReboot) {

    var methodName = "reboot";

    var methodParams = {
        methodName: methodName,
        payload: null,
        timeoutInSeconds: 30
    };

    client.invokeDeviceMethod(deviceToReboot, methodParams, function(err, result) {
        if (err) {
            console.error("Direct method error: "+err.message);
        } else {
            console.log("Successfully invoked the device to reboot.");  
        }
    });
};

عينات خدمة SDK

يوفر Azure IoT SDK for Node.js نماذج عمل لتطبيقات الخدمة التي تتعامل مع مهام إدارة الجهاز. لمزيد من المعلومات، راجع:

• أساليب الوحدة النمطية
• اختبارات أسلوب الجهاز
• اختبارات E2E لأسلوب الجهاز
• قطع اتصال الأسلوب