التوائم الرقمية والرسم البياني المزدوج

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

تلميح

"Azure Digital Twins" تشير إلى خدمة التوأم الرقمي هذه في Azure ككل. "التوأم الرقمي (التوائم)" أو فقط "التوأم (التوائم)" يشير إلى عقد التوأم الفردية داخل المثيل الخاص بك من الخدمة.

التوائم الرقمية

قبل أن تتمكن من إنشاء توأم رقمي في مثيل Azure Digital Twins، تحتاج إلى تحميل نموذج إلى الخدمة. يصف النموذج مجموعة الخصائص والعلاقات التي يمكن أن يكون لها توأم معين، من بين أمور أخرى. للحصول على أنواع المعلومات المحددة في نموذج، راجع النماذج المخصصة.

بعد إنشاء نموذج وتحميله، يمكن لتطبيق العميل إنشاء مثيل من النوع. هذا المثيل هو توأم رقمي. على سبيل المثال، بعد إنشاء نموذج Floor، يمكنك إنشاء توأم رقمي واحد أو عدة توائم رقمية تستخدم هذا النوع (مثل توأم من نوع Floor يسمى GroundFloor، وآخر يسمى Floor2، وما إلى ذلك).

إشعار

تختلف التوائم الرقمية في Azure Digital Twins عن توائم الأجهزة في IoT Hub. غالبًا ما تركّز توائم الأجهزة في IoT Hub على وصف جوانب الجهاز نفسه وإمكاناته، في حين أن التوائم في Azure Digital Twins هي تمثيلات مفاهيمية أكثر يمكنها تخزين رؤى محددة من المستخدم حول جهاز أو العديد من الأجهزة ذات الصلة.

يمكن توصيل الأجهزة في IoT Hub ب Azure Digital Twins كجزء من حل شامل يمثل جهازك عبر الخدمات.

العلاقات: رسم بياني للتوأم الرقمي

يتم توصيل التوائم في الرسم البياني للتوأم من علاقاتهم. يتم تعريف العلاقات التي يمكن أن يكون التوأم كجزء من نموذجه.

على سبيل المثال، قد يحدد contains نموذج Floor علاقة تستهدف توائم من نوع Room. مع هذا التعريف، سيسمح لك Azure Digital Twins بإنشاء contains علاقات من أي توأم أرضي إلى أي توأم غرفة (بما في ذلك التوائم من أنواع فرعية للغرفة).

نتيجة هذه العملية هي مجموعة من العقد (التوائم الرقمية) متصلة عبر حواف (علاقاتهم) في الرسم البياني.

الرسوم المرئية

Azure Digital Twins Explorer هو أداة مرئية لاستكشاف البيانات في الرسم البياني Azure Digital Twins. يمكنك استخدام المستكشف لعرض نماذجك وتوائمك وعلاقاتك والاستعلام عنهما وتحريرهما.

للقراءة عن أداة Azure Digital Twins Explorer، راجع Azure Digital Twins Explorer. للحصول على خطوات مفصلة حول كيفية استخدام ميزاته، راجع استخدام Azure Digital Twins Explorer.

إليك الشكل الذي تبدو عليه المرئيات:

إنشاء باستخدام واجهات برمجة التطبيقات

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

إنشاء التوائم الرقمية

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

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

// Define a custom model type for the twin to be created

internal class CustomDigitalTwin
{
    [JsonPropertyName(DigitalTwinsJsonPropertyNames.DigitalTwinId)]
    public string Id { get; set; }

    [JsonPropertyName(DigitalTwinsJsonPropertyNames.DigitalTwinETag)]
    public string ETag { get; set; }

    [JsonPropertyName("temperature")]
    public double Temperature { get; set; }

    [JsonPropertyName("humidity")]
    public double Humidity{ get; set; }
}

// Initialize properties and create the twin
public class TwinOperationsCreateTwin
{
    public async Task CreateTwinAsync(DigitalTwinsClient client)
    {
        // Initialize the twin properties
        var myTwin = new CustomDigitalTwin
        {
            Temperature = 25.0,
            Humidity = 50.0,
        };

        // Create the twin
        const string twinId = "<twin-ID>";
        Response<CustomDigitalTwin> response = await client.CreateOrReplaceDigitalTwinAsync(twinId, myTwin);
        Console.WriteLine($"Temperature value: {response.Value.Temperature}");
    }
}

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

إشعار

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

إنشاء علاقات

فيما يلي بعض أمثلة التعليمات البرمجية للعميل التي تستخدم واجهات برمجة تطبيقات DigitalTwins لبناء علاقة من توأم رقمي واحد (التوأم "المصدر") إلى توأم رقمي آخر (التوأم "الهدف").

public async Task CreateRelationship(DigitalTwinsClient client)
{
    var rel = new BasicRelationship
    {
        TargetId = "myTargetTwin",
        Name = "contains", // a relationship with this name must be defined in the model
        // Initialize properties
        Properties =
        {
            { "active", true },
        },
    };
    await client.CreateOrReplaceRelationshipAsync("mySourceTwin", "rel001", rel);
}

إنشاء توائم وعلاقات بشكل مجمع باستخدام واجهة برمجة تطبيقات استيراد المهام

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

حذف عناصر الرسم البياني

لحذف توائم وعلاقات معينة، استخدم DigitalTwins Delete و DigitalTwins DeleteRelationship APIs (متوفرة أيضا كأوامر CLI ومكالمات SDK).

لحذف جميع النماذج والتوائم والعلاقات في مثيل في وقت واحد، استخدم واجهة برمجة تطبيقات Delete Jobs.

تمثيلات JSON لعناصر الرسم البياني

يتم تخزين بيانات التوأم الرقمي وبيانات العلاقات بتنسيق JSON، ما يعني أنه عند الاستعلام عن الرسم البياني المزدوج في مثيل Azure Digital Twins، ستكون النتيجة تمثيل JSON للتوائم الرقمية والعلاقات التي قمت بإنشائها.

تنسيق JSON التوأم الرقمي

عند تمثيله ككائن JSON، سيعرض التوأم الرقمي الحقول التالية:

اسم الحقل	‏‏الوصف
$dtId	سلسلة يوفرها المستخدم تمثل معرف التوأم الرقمي
$etag	حقل HTTP القياسي المعين من قبل خادم الويب
$metadata.$model	معرف واجهة النموذج التي تميز هذا التوأم الرقمي
$metadata.<property-name>	معلومات بيانات التعريف الأخرى حول خصائص التوأم الرقمي
$metadata.<property-name>.lastUpdateTime	تاريخ/وقت معالجة رسالة تحديث الخاصية بواسطة Azure Digital Twins
$metadata.<property-name>.sourceTime	خاصية اختيارية قابلة للكتابة تمثل الطابع الزمني عند ملاحظة تحديث الخاصية في العالم الحقيقي. يمكن كتابة هذه الخاصية فقط باستخدام الإصدار 2022-05-31 من واجهات برمجة تطبيقات/SDKs Azure Digital Twins ويجب أن تتوافق القيمة مع تنسيق التاريخ والوقت ISO 8601. لمزيد من المعلومات حول كيفية تحديث هذه الخاصية، راجع تحديث مصدر الخاصيةTime.
<property-name>	قيمة خاصية في JSON (stringأو نوع الرقم أو الكائن)
$relationships	عنوان URL للمسار إلى مجموعة العلاقات. هذا الحقل غير موجود إذا لم يكن لدى التوأم الرقمي حواف علاقة صادرة.
<component-name>	كائن JSON يحتوي على قيم خصائص المكون وبيانات التعريف، على غرار تلك الخاصة بالعنصر الجذر. هذا الكائن موجود حتى إذا لم يكن للمكون خصائص.
<component-name>.$metadata	معلومات بيانات التعريف للمكون، على غرار مستوى الجذر $metadata
<component-name>.<property-name>	قيمة خاصية المكون في JSON (stringأو نوع الرقم أو الكائن)

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

{
    "$dtId": "myRoomID",
    "$etag": "W/\"8e6d3e89-1166-4a1d-9a99-8accd8fef43f\"",
    "$metadata": {
        "$model": "dtmi:example:Room23;1",
        "Humidity": {
          "lastUpdateTime": "2021-11-30T18:47:53.7648958Z"
        },
        "Temperature": {
          "lastUpdateTime": "2021-11-30T18:47:53.7648958Z"
        }
    },
    "Humidity": 55,
    "Temperature": 35,
    "Thermostat": {
        "$metadata": {}
    }

تنسيق JSON للعلاقة

عند تمثيله كعنصر JSON، ستعرض العلاقة من التوأم الرقمي الحقول التالية:

اسم الحقل	‏‏الوصف
$relationshipId	سلسلة يوفرها المستخدم تمثل معرف هذه العلاقة. هذه السلسلة فريدة في سياق التوأم الرقمي المصدر، ما يعني أيضا أن sourceId + relationshipId فريد في سياق مثيل Azure Digital Twins.
$etag	حقل HTTP القياسي المعين من قبل خادم الويب
$sourceId	معرف التوأم الرقمي المصدر
$targetId	معرف التوأم الرقمي المستهدف
$relationshipName	اسم العلاقة
<property-name>	[اختياري] قيمة خاصية لهذه العلاقة، في JSON (stringأو نوع الرقم أو الكائن)

فيما يلي مثال على علاقة منسقة ككائن JSON:

{
  "$relationshipId": "relationship-01",
  "$etag": "W/\"506e8391-2b21-4ac9-bca3-53e6620f6a90\"",
  "$sourceId": "GroundFloor",
  "$targetId": "Cafe",
  "$relationshipName": "contains",
  "startDate": "2020-02-04"
}

الخطوات التالية

راجع كيفية إدارة عناصر الرسم البياني باستخدام واجهات برمجة تطبيقات Azure Digital Twin:

• إدارة التوائم الرقمية
• إدارة الرسم البياني المزدوج والعلاقات

أو تعرف على الاستعلام عن الرسم البياني المزدوج Azure Digital Twins للحصول على معلومات:

• لغة الاستعلام