استخدام المهام لجدولة المهام لمجموعات الأجهزة - Azure IoT Hub

يتطلب Visual Studio

نظرة عامة

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

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

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

استخدام عبارات

أضف العبارات التالية باستخدام .

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

using System.Threading;
using System.Threading.Tasks;

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

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

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

هام

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

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

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

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

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

static JobClient jobClient;
static string connectionString = "{Shared access policy connection string}";
jobClient = JobClient.CreateFromConnectionString(connString);

الاتصال باستخدام 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);

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

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

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

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

جدولة مهمة أسلوب مباشر

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

استخدم كائن CloudToDeviceMethod لتحديد اسم الأسلوب المباشر وقيم مهلة اتصال الجهاز.

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

// The CloudToDeviceMethod record specifies the direct method name and device connection time-out
CloudToDeviceMethod directMethod = 
new CloudToDeviceMethod("LockDoor", TimeSpan.FromSeconds(5), 
TimeSpan.FromSeconds(5));

يقوم هذا المثال بجدولة مهمة لأسلوب مباشر يسمى "LockDoor" على جهاز واحد يسمى "Device-1". تحتوي الأجهزة المضمنة في المهمة المجدولة على المعلمة الثانية كشرط استعلام. لمزيد من المعلومات حول شروط الاستعلام، راجع لغة استعلام IoT Hub لتوائم الجهاز والوحدة النمطية والمهام وتوجيه الرسائل.

string methodJobId = Guid.NewGuid().ToString();  // a unique job ID
static string deviceId = "Device-1";             // In this example, there is only one device affected
JobResponse result = await jobClient.ScheduleDeviceMethodAsync(methodJobId,
   $"DeviceId IN ['{deviceId}']",
   directMethod,
   DateTime.UtcNow,
   (long)TimeSpan.FromMinutes(2).TotalSeconds);

جدولة مهمة تحديث الجهاز المزدوج

استخدم ScheduleTwinUpdateAsync لجدولة مهمة تحديث الخصائص وتحديث العلامات المزدوجة لجهاز جديد لتشغيلها على جهاز واحد أو أكثر.

أولا، قم بإنشاء وملء كائن توأم الجهاز للتحديث. على سبيل المثال:

static string deviceId = "Device-1";

Twin twin = new Twin(deviceId);
twin.Tags = new TwinCollection();
twin.Tags["Building"] = "43";
twin.Tags["Floor"] = "3";
twin.ETag = "*";
twin.Properties.Desired["LocationUpdate"] = DateTime.UtcNow;

بعد ذلك، اتصل ب ScheduleTwinUpdateAsync. حدد الأجهزة التي سيتم تحديثها كتعلام في المعلمة الثانية. لمزيد من المعلومات حول شروط الاستعلام، راجع لغة استعلام IoT Hub لتوائم الجهاز والوحدة النمطية والمهام وتوجيه الرسائل.

string twinJobId = Guid.NewGuid().ToString();

JobResponse createJobResponse = jobClient.ScheduleTwinUpdateAsync(
   twinJobId,
   $"DeviceId IN ['{deviceId}']", 
   twin, 
   DateTime.UtcNow, 
   (long)TimeSpan.FromMinutes(2).TotalSeconds).Result;

مراقبة مهمة

استخدم GetJobAsync لمراقبة حالة الوظيفة لمعرف مهمة معين.

يتحقق هذا المثال من حالة الوظيفة لمعرف الوظيفة بشكل دوري حتى تكتمل حالة الوظيفة أو تفشل. على سبيل المثال:

JobResponse result;
do
{
   result = await jobClient.GetJobAsync(jobId);
   Console.WriteLine("Job Status : " + result.Status.ToString());
   Thread.Sleep(2000);
} while ((result.Status != JobStatus.Completed) && (result.Status != JobStatus.Failed));

أمثلة مهمة جدولة SDK

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

جدولة نموذج التحديث المزدوج
نموذج تحديث مزدوج لجدول E2E.

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

نظرة عامة

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

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

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

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

import com.microsoft.azure.sdk.iot.service.devicetwin.DeviceTwinDevice;
import com.microsoft.azure.sdk.iot.service.devicetwin.Pair;
import com.microsoft.azure.sdk.iot.service.devicetwin.Query;
import com.microsoft.azure.sdk.iot.service.devicetwin.SqlQuery;
import com.microsoft.azure.sdk.iot.service.jobs.JobClient;
import com.microsoft.azure.sdk.iot.service.jobs.JobResult;
import com.microsoft.azure.sdk.iot.service.jobs.JobStatus;

import java.util.Date;
import java.time.Instant;
import java.util.HashSet;
import java.util.Set;
import java.util.UUID;

الاتصال بـ IoT hub

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

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

هام

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

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

استخدم منشئ JobClient لإنشاء الاتصال بمركز IoT. JobClient يعالج الكائن الاتصال مع مركز IoT الخاص بك.

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

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

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

public static final String iotHubConnectionString = "{Shared access policy connection string}";
JobClient jobClient = new JobClient(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:

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

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

جدولة مهمة تحديث أسلوب مباشر

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

يقوم أسلوب المثال هذا بجدولة مهمة لأسلوب مباشر يسمى "lockDoor" على جهاز يسمى "Device-1".

// Schedule a job now to call the lockDoor direct method
// against a single device. Response and connection
// timeouts are set to 5 seconds.
String deviceId = "Device-1";
String jobId = "DMCMD" + UUID.randomUUID();  //Job ID must be unique

// How long the job is permitted to run without
// completing its work on the set of devices
private static final long maxExecutionTimeInSeconds = 30;

System.out.println("Schedule job " + jobId + " for device " + deviceId);
try {
  JobResult jobResult = jobClient.scheduleDeviceMethod(jobId,
    "deviceId='" + deviceId + "'",
    "lockDoor",
    5L, 5L, null,
    new Date(),
    maxExecutionTimeInSeconds);
} catch (Exception e) {
  System.out.println("Exception scheduling direct method job: " + jobId);
  System.out.println(e.getMessage());
}

جدولة مهمة تحديث الجهاز المزدوج

استخدم scheduleUpdateTwin لجدولة مهمة لتشغيل تحديث توأم جهاز على جهاز واحد أو عدة أجهزة.

أولا، قم بإعداد سجل DeviceTwinDevice لتحديث الجهاز المزدوج. على سبيل المثال:

String deviceId = "Device-1";

//Create a device twin desired properties update object
DeviceTwinDevice twin = new DeviceTwinDevice(deviceId);
Set<Pair> desiredProperties = new HashSet<Pair>();
desiredProperties.add(new Pair("Building", 43));
desiredProperties.add(new Pair("Floor", 3));
twin.setDesiredProperties(desiredProperties);
// Optimistic concurrency control
twin.setETag("*");

ثم اتصل scheduleUpdateTwin بجدولة مهمة التحديث. على سبيل المثال:

String jobId = "DPCMD" + UUID.randomUUID();  //Unique job ID

// How long the job is permitted to run without
// completing its work on the set of devices
private static final long maxExecutionTimeInSeconds = 30;

// Schedule the update twin job to run now for a single device
System.out.println("Schedule job " + jobId + " for device " + deviceId);
try {
  JobResult jobResult = jobClient.scheduleUpdateTwin(jobId, 
    "deviceId='" + deviceId + "'",
    twin,
    new Date(),
    maxExecutionTimeInSeconds);
} catch (Exception e) {
  System.out.println("Exception scheduling desired properties job: " + jobId);
  System.out.println(e.getMessage());
}

مراقبة مهمة

استخدم getJob لجلب معلومات الوظيفة استنادا إلى معرف وظيفة معين. getJob إرجاع كائن JobResult الذي يحتوي على أساليب وخصائص يمكنك استخدامها للتحقق من معلومات المهمة بما في ذلك حالة التشغيل.

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

try {
  JobResult jobResult = jobClient.getJob(jobId);
  if(jobResult == null)
  {
    System.out.println("No JobResult for: " + jobId);
    return;
  }
  // Check the job result until it's completed
  while(jobResult.getJobStatus() != JobStatus.completed)
  {
    Thread.sleep(100);
    jobResult = jobClient.getJob(jobId);
    System.out.println("Status " + jobResult.getJobStatus() + " for job " + jobId);
  }
  System.out.println("Final status " + jobResult.getJobStatus() + " for job " + jobId);
} catch (Exception e) {
  System.out.println("Exception monitoring job: " + jobId);
  System.out.println(e.getMessage());
  return;
}

الاستعلام عن حالة الوظيفة

استخدم queryDeviceJob للاستعلام عن حالة الوظيفة لوظيفة واحدة أو أكثر.

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

private static void queryDeviceJobs(JobClient jobClient, String start) throws Exception {
  System.out.println("\nQuery device jobs since " + start);

  // Create a jobs query using the time the jobs started
  Query deviceJobQuery = jobClient
      .queryDeviceJob(SqlQuery.createSqlQuery("*", SqlQuery.FromType.JOBS, "devices.jobs.startTimeUtc > '" + start + "'", null).getQuery());

  // Iterate over the list of jobs and print the details
  while (jobClient.hasNextJob(deviceJobQuery)) {
    System.out.println(jobClient.getNextJob(deviceJobQuery));
  }
}

مثال على مهمة جدولة SDK

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

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

نظرة عامة

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

تثبيت الحزمة

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

pip install azure-iot-hub

عبارات الاستيراد

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

أضف عبارات import التالية.

import os
import sys
import datetime
import time
import threading
import uuid
import msrest

from azure.iot.hub import IoTHubJobManager
from azure.iot.hub.models import JobProperties, JobRequest, Twin, TwinProperties, CloudToDeviceMethod

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

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

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

هام

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

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

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

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

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

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

IoTHubConnectionString = "{Shared access policy connection string}"
iothub_job_manager = IoTHubJobManager.from_connection_string(IoTHubConnectionString)

الاتصال باستخدام 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);

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

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

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

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

جدولة مهمة أسلوب مباشر

استخدم create_scheduled_job لجدولة أسلوب مباشر جديد لتشغيل أسلوب مباشر على جهاز واحد أو عدة أجهزة:

create_scheduled_job ملاحظات المعلمة:

job_id يجب أن يكون فريدا
تعيين type إلى scheduleDeviceMethod
استخدم cloud_to_device_method لتعيين اسم الأسلوب المباشر والحمولة
استخدم max_execution_time_in_seconds لتحديد وقت التنفيذ بالثوان
استخدم query_condition لتحديد الأجهزة التي سيتم تضمينها لاستدعاء الأسلوب المباشر. لمزيد من المعلومات حول شروط الاستعلام، راجع لغة استعلام IoT Hub لتوائم الجهاز والوحدة النمطية والمهام وتوجيه الرسائل.

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

METHOD_NAME = "lockDoor"
METHOD_PAYLOAD = "{\"lockTime\":\"10m\"}"
job_id = uuid.uuid4()
DEVICE_ID = "Device-1"
TIMEOUT = 60

job_request = JobRequest()
job_request.job_id = job_id
job_request.type = "scheduleDeviceMethod"
job_request.start_time = datetime.datetime.utcnow().isoformat()
job_request.cloud_to_device_method = CloudToDeviceMethod(method_name=METHOD_NAME, payload=METHOD_PAYLOAD)
job_request.max_execution_time_in_seconds = TIMEOUT
job_request.query_condition = "DeviceId in ['{}']".format(device_id)

new_job_response = iothub_job_manager.create_scheduled_job(job_id, job_request)

جدولة مهمة تحديث الجهاز المزدوج

استخدم create_scheduled_job لإنشاء مهمة جديدة لتشغيل تحديث خصائص الجهاز المزدوج المطلوب على جهاز واحد أو عدة أجهزة.

create_scheduled_job ملاحظات المعلمة:

job_id يجب أن يكون فريدا
تعيين type إلى scheduleUpdateTwin
استخدم update_twin لتعيين اسم الأسلوب المباشر والحمولة
استخدم max_execution_time_in_seconds لتحديد وقت التنفيذ بالثوان
استخدم query_condition لتحديد شرط لجهاز واحد أو أكثر يحتوي على استدعاء الأسلوب المباشر. لمزيد من المعلومات حول شروط الاستعلام، راجع لغة استعلام IoT Hub لتوائم الجهاز والوحدة النمطية والمهام وتوجيه الرسائل.

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

UPDATE_PATCH = {"building":43,"floor":3}
job_id = uuid.uuid4()
TIMEOUT = 60

job_request = JobRequest()
job_request.job_id = job_id
job_request.type = "scheduleUpdateTwin"
job_request.start_time = datetime.datetime.utcnow().isoformat()
job_request.update_twin = Twin(etag="*", properties=TwinProperties(desired=UPDATE_PATCH))
job_request.max_execution_time_in_seconds = TIMEOUT
job_request.query_condition = "DeviceId in ['{}']".format(device_id)

new_job_response = iothub_job_manager.create_scheduled_job(job_id, job_request)

مراقبة مهمة

استخدم get_scheduled_job لاسترداد تفاصيل مهمة معينة على IoT Hub.

يتحقق هذا المثال من حالة الوظيفة لمعرف وظيفة معين كل خمس ثوان حتى تكتمل المهمة.

while True:
    get_job_response = iothub_job_manager.get_scheduled_job(job_request.job_id)
    print_job_response("Get job response: ", get_job_response)
    if get_job_response.status == "completed":
      print ( "Job is completed." )
    time.sleep(5)

أمثلة مهمة جدولة SDK

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

جدولة مهمة أسلوب مباشر
جدولة تحديث توأم الجهاز.

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

نظرة عامة

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

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

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

npm install azure-iothub --save

تعرض فئة JobClient جميع الأساليب المطلوبة للتفاعل مع جدولة الوظائف من تطبيق الخلفية.

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

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

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

هام

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

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

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

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

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

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

'use strict';
var JobClient = require('azure-iothub').JobClient;
var connectionString = '{Shared access policy connection string}';
var jobClient = JobClient.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. ثم يتم توفير 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.

إنشاء مهمة أسلوب مباشر

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

أولا، قم بإنشاء متغير تحديث أسلوب مباشر مع اسم الأسلوب والحمولة ومعلومات مهلة الاستجابة. على سبيل المثال:

var methodParams = {
    methodName: 'lockDoor',
    payload: null,
    responseTimeoutInSeconds: 15 // Time-out after 15 seconds if device is unable to process method
};

ثم استدع scheduleDeviceMethod لجدولة مهمة استدعاء الأسلوب المباشر:

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

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

var methodJobId = uuid.v4();
var queryCondition = "deviceId IN ['myDeviceId']";
var startTime = new Date();
var maxExecutionTimeInSeconds =  300;

jobClient.scheduleDeviceMethod(methodJobId,
                            queryCondition,
                            methodParams,
                            startTime,
                            maxExecutionTimeInSeconds,
                            function(err) {
    if (err) {
        console.error('Could not schedule direct method job: ' + err.message);
    } else {
        monitorJob(methodJobId, function(err, result) {
            if (err) {
                console.error('Could not monitor direct method job: ' + err.message);
            } else {
                console.log(JSON.stringify(result, null, 2));
            }
        });
    }
});

جدولة مهمة تحديث الجهاز المزدوج

استخدم scheduleTwinUpdate لإنشاء مهمة جديدة لتشغيل تحديث توأم جهاز على جهاز واحد أو عدة أجهزة.

أولا، قم بإنشاء متغير تحديث الخاصية المطلوبة لجهاز مزدوج.

var twinPatch = {
   etag: '*',
   properties: {
       desired: {
           building: '43',
           floor: 3
       }
   }
};

ثم اتصل scheduleTwinUpdate بجدولة مهمة تحديث الخاصية المطلوبة لتوائم الجهاز:

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

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

var twinJobId = uuid.v4();
var queryCondition = "deviceId IN ['myDeviceId']";
var startTime = new Date();
var maxExecutionTimeInSeconds =  300;

console.log('scheduling Twin Update job with id: ' + twinJobId);
jobClient.scheduleTwinUpdate(twinJobId,
                            queryCondition,
                            twinPatch,
                            startTime,
                            maxExecutionTimeInSeconds,
                            function(err) {
    if (err) {
        console.error('Could not schedule twin update job: ' + err.message);
    } else {
        monitorJob(twinJobId, function(err, result) {
            if (err) {
                console.error('Could not monitor twin update job: ' + err.message);
            } else {
                console.log(JSON.stringify(result, null, 2));
            }
        });
    }
});

مراقبة مهمة

استخدم getJob لمراقبة حالة الوظيفة لمعرف وظيفة معين.

تتحقق وظيفة المثال هذه من حالة الوظيفة لمعرف مهمة معين بشكل دوري حتى تكتمل المهمة أو تفشل.

function monitorJob (jobId, callback) {
    var jobMonitorInterval = setInterval(function() {
        jobClient.getJob(jobId, function(err, result) {
        if (err) {
            console.error('Could not get job status: ' + err.message);
        } else {
            console.log('Job: ' + jobId + ' - status: ' + result.status);
            if (result.status === 'completed' || result.status === 'failed' || result.status === 'cancelled') {
            clearInterval(jobMonitorInterval);
            callback(null, result);
            }
        }
        });
    }, 5000);
}

مثال على مهمة جدولة SDK

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

كيفية جدولة المهام وبثها

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

نظرة عامة

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

استخدام عبارات

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

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

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

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

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

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

جدولة مهمة أسلوب مباشر

جدولة مهمة تحديث الجهاز المزدوج

مراقبة مهمة

أمثلة مهمة جدولة SDK

نظرة عامة

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

الاتصال بـ IoT hub

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

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

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

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

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

فئات المصادقة الأخرى

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

جدولة مهمة تحديث أسلوب مباشر

جدولة مهمة تحديث الجهاز المزدوج

مراقبة مهمة

الاستعلام عن حالة الوظيفة

مثال على مهمة جدولة SDK

نظرة عامة

تثبيت الحزمة

عبارات الاستيراد

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

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

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

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

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

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

جدولة مهمة أسلوب مباشر

جدولة مهمة تحديث الجهاز المزدوج

مراقبة مهمة

أمثلة مهمة جدولة SDK

نظرة عامة

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

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

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

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

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

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

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

إنشاء مهمة أسلوب مباشر

جدولة مهمة تحديث الجهاز المزدوج

مراقبة مهمة

مثال على مهمة جدولة SDK

الملاحظات

الموارد الإضافية