ابدأ مع توائم الجهاز (Java)

مقالة
03/18/2023

توائم الجهاز عبارة عن مستندات JSON تُخزِّن معلومات حالة الجهاز، بما في ذلك بيانات التعريف والتكوينات والحالات. يحتفظ IoT Hub بتوأم جهاز لكل جهاز يتصل به.

إشعار

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

استخدم توائم الجهاز من أجل ما يلي:

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

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

تخزن مراكز IoT توائم الجهاز، والتي تحتوي على العناصر التالية:

العلامات. يمكن الوصول إلى بيانات التعريف للجهاز فقط من خلال النهاية الخلفية للحل.
الخصائص المرغوبة. عناصر JSON قابلة للتعديل من خلال النهاية الخلفية للحل ويمكن ملاحظتها بواسطة تطبيق الجهاز.
الخصائص المبلغ عنها. عناصر JSON قابلة للتعديل من خلال تطبيق الجهاز ويمكن قراءتها بواسطة النهاية الخلفية للحل.

لا يمكن أن تحتوي العلامات والخصائص على صفائف، ولكن يمكن أن تحتوي على كائنات متداخلة.

يوضح الرسم التوضيحي التالي تنظيم توأم الجهاز:

لقطة شاشة لمخطط مفهوم توأم الجهاز.

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

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

استخدم تطبيق جهاز محاكاة للإبلاغ عن قناة الاتصال الخاصة به كخاصية تم الإبلاغ عنها على توأم الجهاز.
استعلم عن الأجهزة من تطبيقك الخلفي باستخدام عوامل تصفية على العلامات والخصائص التي تم إنشاؤها مسبقًا.

في هذه المقالة، يمكنك إنشاء تطبيقي وحدة تحكم Java:

add-tags-query: تطبيق للجهة الخلفية يضيف علامات واستعلامات توائم الجهاز.
simulated-device: تطبيق جهاز محاكاة يتصل بمركز IoT ويبلغ عن حالة الاتصال.

إشعار

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

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

IoT Hub. أنشئ واحدا باستخدام CLI أو مدخل Microsoft Azure.
جهاز مسجل. سجَل واحدًا في مدخل Azure.
حزمة تطور Java SE 8. تأكد من تحديد Java 8 ضمن الدعم طويل الأجل للوصول إلى التنزيلات لـ JDK 8.
Maven 3
تأكد من أن المنفذ 8883 مفتوح في جدار الحماية. يستخدم نموذج الجهاز في هذه المقالة بروتوكول MQTT، الذي يتصل عبر المنفذ 8883. قد يُحظر هذا المنفذ في بعض بيئات الشبكات التعليمية، وشبكات الشركات. لمزيد من المعلومات وطرق التغلب على هذه المشكلة، راجع الاتصال بمركز IoT (MQTT).

احصل على سلسلة اتصال IoT hub

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

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

في مدخل Microsoft Azure، حدد Resource groups. حدد مجموعة الموارد حيث يوجد المركز الخاص بك، ثم حدد المركز الخاص بك من قائمة الموارد.
في الجزء الأيسر من مركز IoT، قم بتحديد Shared access policies.
من القائمة أعلى قائمة النهج، حدّد إضافة نهج الوصول المشترك.
ضمن جزء إضافة نهج الوصول المشترك، على اليمين، أدخل اسماً وصفياً للنهج الخاص بك، مثل serviceAndRegistryRead. ضمن الأذونات، حدد قراءة السجل و اتصال الخدمة، ثم حدد إضافة.
حدد النهج الخاص بك الجديدة من قائمة النُهج.
حدد أيقونة النسخ لسلسلة الاتصال الأساسية واحفظ القيمة.

للمزيد من المعلومات حول نهج الوصول المشترك لـIoT Hub والأذونات، راجع التحكم في الوصول والأذونات.

إنشاء تطبيق جهاز يقوم بتحديث الخصائص المبلغ عنها

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

في المجلد iot-java-twin-getstarted، أنشئ مشروع Maven باسم simulated-device باستخدام الأمر التالي في موجه الأوامر:
```
mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=simulated-device -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
```
في موجه الأوامر، انتقل إلى المجلد simulated-device.
باستخدام محرر نصوص، افتح الملف pom.xml في مجلد schedule-jobs وأضف التبعية التالية إلى عقدة dependencies. تتيح لك هذه التبعية استخدام حزمة iot-device-client في تطبيقك للتواصل مع IoT Hub الخاص بك.
```
<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-device-client</artifactId>
  <version>1.17.5</version>
</dependency>
```
إشعار

يمكنك التحقق من أحدث إصدار من iot-device-client باستخدام Maven search.
أضف التبعية التالية إلى عقدة التبعيات. تهيئ هذه التبعية NOP لواجهة تسجيل Apache SLF4J، والتي يتم استخدامها بواسطة عميل الجهاز SDK لتنفيذ التسجيل. هذا التكوين اختياري، ولكن إذا حذفته، فقد ترى تحذيراً في وحدة التحكم عند تشغيل التطبيق. لمزيد من المعلومات حول تسجيل الدخول إلى عدة تطوير البرامج لعميل الجهاز، راجع تسجيل الدخولإلى عينات لملف عدة تطوير البرامج لجهاز Azure IoT لـ Java readme.
```
<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-nop</artifactId>
  <version>1.7.28</version>
</dependency>
```

أضف عقدة إنشاء التالية بعد عقدة التبعيات. يوجه هذا التكوين Maven لاستخدام Java 1.8 لإنشاء التطبيق:

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-compiler-plugin</artifactId>
      <version>3.3</version>
      <configuration>
        <source>1.8</source>
        <target>1.8</target>
      </configuration>
    </plugin>
  </plugins>
</build>

حفظ ملف pom.xml وإغلاقه.
باستخدام محرر نصوص، افتح الملف simulated-device\src\main\java\com\mycompany\app\App.java.

أضف عبارات import التالية إلى الملف:

import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.DeviceTwin.*;

import java.io.IOException;
import java.net.URISyntaxException;
import java.util.Scanner;

أضف متغيرات مستوى الفئة التالية إلى فئة التطبيق. استبدل {yourdeviceconnectionstring} بسلسلة اتصال الجهاز التي رأيتها عند تسجيل جهاز في مركز IoT:
```
private static String connString = "{yourdeviceconnectionstring}";
private static IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
private static String deviceId = "myDeviceId";
```
يستخدم هذا النموذج من التطبيق متغير البروتوكول عندما ينشئ عنصر DeviceClient.

أضف الطريقة التالية إلى فئة التطبيق لطباعة معلومات حول التحديثات المزدوجة:

protected static class DeviceTwinStatusCallBack implements IotHubEventCallback {
    @Override
    public void execute(IotHubStatusCode status, Object context) {
      System.out.println("IoT Hub responded to device twin operation with status " + status.name());
    }
  }

استبدل التعليمة البرمجية في الطريقة main بالتعليمة البرمجية التالية من أجل:

أنشئ عميل جهاز للتواصل مع IoT Hub.
أنشئ عنصر جهاز لتخزين خصائص الجهاز المزدوج.

DeviceClient client = new DeviceClient(connString, protocol);

// Create a Device object to store the device twin properties
Device dataCollector = new Device() {
  // Print details when a property value changes
  @Override
  public void PropertyCall(String propertyKey, Object propertyValue, Object context) {
    System.out.println(propertyKey + " changed to " + propertyValue);
  }
};

أضف التعليمة البرمجية التالية إلى الأسلوب main لإنشاء خاصية تم الإبلاغ عن connectivityType وإرسالها إلى IoT Hub:

try {
  // Open the DeviceClient and start the device twin services.
  client.open();
  client.startDeviceTwin(new DeviceTwinStatusCallBack(), null, dataCollector, null);

  // Create a reported property and send it to your IoT hub.
  dataCollector.setReportedProp(new Property("connectivityType", "cellular"));
  client.sendReportedProperties(dataCollector.getReportedProp());
}
catch (Exception e) {
  System.out.println("On exception, shutting down \n" + " Cause: " + e.getCause() + " \n" + e.getMessage());
  dataCollector.clean();
  client.closeNow();
  System.out.println("Shutting down...");
}

أضف التعليمة البرمجية التالي إلى نهاية الطريقة main. يتيح انتظار المفتاح Enter الوقت لمركز IoT للإبلاغ عن حالة عمليات الجهاز المزدوجة.
```
System.out.println("Press any key to exit...");

Scanner scanner = new Scanner(System.in);
scanner.nextLine();

dataCollector.clean();
client.close();
```
قم بتعديل توقيع الطريقة main لتضمين الاستثناءات على النحو التالي:
```
public static void main(String[] args) throws URISyntaxException, IOException
```
احفظ ملف simulated-device\src\main\java\com\mycompany\app\App.java وأغلقه.
أنشئ تطبيق simulated-device وصحح أي أخطاء. في موجه الأوامر، انتقل إلى المجلد simulated-device وقم بتشغيل الأمر التالي:
```
mvn clean package -DskipTests
```

إنشاء تطبيق خدمة يقوم بتحديث الخصائص المطلوبة والاستعلامات المزدوجة

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

على جهاز التطوير لديك، قم بإنشاء مجلد فارغ باسم iot-java-twin-getstarted.
في المجلد iot-java-twin-getstarted، أنشئ مشروع Maven باسم add-tags-query باستخدام الأمر التالي في موجه الأوامر:
```
mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=add-tags-query -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
```
في موجه الأوامر، انتقل إلى المجلد add-tags-query.
باستخدام محرر نصوص، افتح الملف pom.xml في المجلد add-tags-query وأضف التبعية التالية إلى عقدة التبعيات. تمكنك هذه التبعية من استخدام حزمة iot-service-client في تطبيقك للاتصال بـ IoT Hub الخاص بك:
```
<dependency>
  <groupId>com.microsoft.azure.sdk.iot</groupId>
  <artifactId>iot-service-client</artifactId>
  <version>1.17.1</version>
  <type>jar</type>
</dependency>
```
إشعار

يمكنك التحقق من أحدث إصدار من iot-service-client باستخدام Maven search.

أضف عقدة إنشاء التالية بعد عقدة التبعيات. يوجه هذا التكوين Maven لاستخدام Java 1.8 لبناء التطبيق.

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-compiler-plugin</artifactId>
      <version>3.3</version>
      <configuration>
        <source>1.8</source>
        <target>1.8</target>
      </configuration>
    </plugin>
  </plugins>
</build>

حفظ ملف pom.xml وإغلاقه.
باستخدام محرر نصوص، افتح الملف add-tags-query\src\main\java\com\mycompany\app\App.java.

أضف عبارات import التالية إلى الملف:

import com.microsoft.azure.sdk.iot.service.devicetwin.*;
import com.microsoft.azure.sdk.iot.service.exceptions.IotHubException;

import java.io.IOException;
import java.util.HashSet;
import java.util.Set;

أضف متغيرات مستوى الفئة التالية إلى فئة التطبيق. استبدل {youriothubconnectionstring} بسلسلة اتصال IoT hub التي نسختها في الحصول على سلسلة اتصال IoT hub.
```
public static final String iotHubConnectionString = "{youriothubconnectionstring}";
public static final String deviceId = "myDeviceId";

public static final String region = "US";
public static final String plant = "Redmond43";
```
حدّث توقيع الأسلوب الرئيسي لتضمين عبارة throws التالية:
```
public static void main( String[] args ) throws IOException
```
استبدل التعليمة البرمجية في الأسلوب main بالتعليمة البرمجية التالية لإنشاء عنصرين DeviceTwin وDeviceTwinDevice. يتعامل عنصر DeviceTwin مع الاتصال بمركز IoT الخاص بك. يمثل العنصر DeviceTwinDevice الجهاز المزدوج بخصائصه وعلاماته:
```
// Get the DeviceTwin and DeviceTwinDevice objects
DeviceTwin twinClient = DeviceTwin.createFromConnectionString(iotHubConnectionString);
DeviceTwinDevice device = new DeviceTwinDevice(deviceId);
```

أضف كتلة try/catch التالية إلى الطريقة main :

try {
  // Code goes here
} catch (IotHubException e) {
  System.out.println(e.getMessage());
} catch (IOException e) {
  System.out.println(e.getMessage());
}

لتحديث العلامات المزدوجة لجهاز المنطقة والمصنع في الجهاز المزدوج، أضف التعليمة البرمجية التالية في الكتلة try :

// Get the device twin from IoT Hub
System.out.println("Device twin before update:");
twinClient.getTwin(device);
System.out.println(device);

// Update device twin tags if they are different
// from the existing values
String currentTags = device.tagsToString();
if ((!currentTags.contains("region=" + region) && !currentTags.contains("plant=" + plant))) {
  // Create the tags and attach them to the DeviceTwinDevice object
  Set<Pair> tags = new HashSet<Pair>();
  tags.add(new Pair("region", region));
  tags.add(new Pair("plant", plant));
  device.setTags(tags);

  // Update the device twin in IoT Hub
  System.out.println("Updating device twin");
  twinClient.updateTwin(device);
}

// Retrieve the device twin with the tag values from IoT Hub
System.out.println("Device twin after update:");
twinClient.getTwin(device);
System.out.println(device);

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

// Query the device twins in IoT Hub
System.out.println("Devices in Redmond:");

// Construct the query
SqlQuery sqlQuery = SqlQuery.createSqlQuery("*", SqlQuery.FromType.DEVICES, "tags.plant='Redmond43'", null);

// Run the query, returning a maximum of 100 devices
Query twinQuery = twinClient.queryTwin(sqlQuery.getQuery(), 100);
while (twinClient.hasNextDeviceTwin(twinQuery)) {
  DeviceTwinDevice d = twinClient.getNextDeviceTwin(twinQuery);
  System.out.println(d.getDeviceId());
}

System.out.println("Devices in Redmond using a cellular network:");

// Construct the query
sqlQuery = SqlQuery.createSqlQuery("*", SqlQuery.FromType.DEVICES, "tags.plant='Redmond43' AND properties.reported.connectivityType = 'cellular'", null);

// Run the query, returning a maximum of 100 devices
twinQuery = twinClient.queryTwin(sqlQuery.getQuery(), 3);
while (twinClient.hasNextDeviceTwin(twinQuery)) {
  DeviceTwinDevice d = twinClient.getNextDeviceTwin(twinQuery);
  System.out.println(d.getDeviceId());
}

احفظ وأغلق ملف add-tags-query src main java com mycompany app App.java
أنشئ تطبيق add-tags-query وصحح أي أخطاء. في موجه الأوامر، انتقل إلى المجلد add-tags-query وقم بتشغيل الأمر التالي:
```
mvn clean package -DskipTests
```

قم بتشغيل التطبيقات

أنت الآن جاهز لتشغيل تطبيقات وحدة التحكم.

في موجه الأوامر في المجلد add-tags-query، قم بتشغيل الأمر التالي لتشغيل تطبيق خدمة add-tags-query :
```
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
```
يمكنك مشاهدة علامتي المصنع والمنطقة مضافتين إلى توأم الجهاز. يقوم الاستعلام الأول بإرجاع جهازك، ولكن الثاني لا يقوم بذلك.
في موجه الأوامر في المجلد simulated-device، قم بتشغيل الأمر التالي لإضافة الخاصية التي تم الإبلاغ عنها connectivityType إلى الجهاز الثنائي:
```
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
```
في موجه الأوامر في المجلد add-tags-query، قم بتشغيل الأمر التالي لتشغيل تطبيق خدمة add-tags-query مرة ثانية:
```
mvn exec:java -Dexec.mainClass="com.mycompany.app.App"
```
الآن وبعد أن أرسل جهازك خاصية connectivityType إلى IoT Hub، فإن الاستعلام الثاني يعيد جهازك.