إضافة علامات إلى التوائم الرقمية

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

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

يصف هذا المستند الأنماط التي يمكن استخدامها لتنفيذ العلامات على التوائم الرقمية.

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

علامات العلامة

علامة العلامة هي سلسلة بسيطة تستخدم لوضع علامة على التوأم الرقمي أو تصنيفه، مثل "أزرق" أو "أحمر". هذه السلسلة هي اسم العلامة، وعلامات العلامة ليس لها قيمة ذات معنى - العلامة مهمة فقط من خلال وجودها (أو غيابها).

إضافة علامات علامة إلى النموذج

يتم تصميم علامات العلامة كخريطة DTDL من string إلى boolean. يتم تجاهل القيمة المنطقية mapValue ، حيث إن وجود العلامة هو كل ما هو مهم.

فيما يلي مقتطف من نموذج مزدوج ينفذ علامة علامة كخاصية:

{
      "@type": "Property",
      "name": "tags",
      "schema": {
        "@type": "Map",
        "mapKey": {
          "name": "tagName",
          "schema": "string"
        },
        "mapValue": {
          "name": "tagValue",
          "schema": "boolean"
        }
      }
    },

إضافة علامات العلامة إلى التوائم الرقمية

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

فيما يلي مثال على التعليمات البرمجية حول كيفية تعيين علامة tags لتوأم باستخدام .NET SDK:

IDictionary<string, bool> tags = new Dictionary<string, bool>
{
    { "oceanview", true },
    { "VIP", true }
};
var twin = new BasicDigitalTwin
{
    Metadata = { ModelId = "dtmi:example:Room;1" },
    Contents =
    {
        { "Temperature", 75 },
        { "tags", tags },
    },
};
await client.CreateOrReplaceDigitalTwinAsync<BasicDigitalTwin>("myTwinID", twin);

بعد إنشاء توأم مع خصائص العلامة وفقا للمثال أعلاه، سيبدو التوأم كما يلي:

{
  "$dtId": "myTwinID",
  "$etag": "W/\"e7429259-6833-46b4-b443-200a77a468c2\"",
  "$metadata": {
    "$model": "dtmi:example:Room;1",
    "Temperature": {
      "lastUpdateTime": "2021-08-03T14:24:42.0850614Z"
    },
    "tags": {
      "lastUpdateTime": "2021-08-03T14:24:42.0850614Z"
    }
  },
  "Temperature": 75,
  "tags": {
    "VIP": true,
    "oceanview": true
  }
}

استعلام بعلامات علامة

بمجرد إضافة العلامات إلى التوائم الرقمية، يمكن استخدام العلامات لتصفية التوائم في الاستعلامات.

فيما يلي استعلام للحصول على جميع التوائم التي تم وضع علامة عليها على أنها "حمراء":

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

يمكنك أيضا دمج العلامات للاستعلامات الأكثر تعقيدا. فيما يلي استعلام للحصول على جميع التوائم التي تكون مستديرة، وليست حمراء:

SELECT * FROM DIGITALTWINS WHERE NOT IS_DEFINED(tags.red) AND IS_DEFINED(tags.round)

علامات القيمة

علامة القيمة هي زوج من قيم المفاتيح يستخدم لمنح كل علامة قيمة، مثل "color": "blue" أو "color": "red". بمجرد إنشاء علامة قيمة، يمكن استخدامها أيضا كعلامة عن طريق تجاهل قيمة العلامة.

إضافة علامات القيمة إلى النموذج

يتم تصميم علامات القيمة كخريطة DTDL من string إلى string. كل من mapKey و mapValue مهمان.

فيما يلي مقتطف من نموذج مزدوج ينفذ علامة قيمة كخاصية:

{
  "@type": "Property",
  "name": "tags",
  "schema": {
    "@type": "Map",
    "mapKey": {
      "name": "tagName",
      "schema": "string"
    },
    "mapValue": {
      "name": "tagValue",
      "schema": "string"
    }
  }
}

إضافة علامات القيمة إلى التوائم الرقمية

كما هو الحال مع علامات العلامة، يمكنك تعيين علامة القيمة في التوأم الرقمي عن طريق تعيين قيمة هذه tags الخاصية من النموذج. لاستخدام علامة قيمة كعلامة علامة، يمكنك تعيين tagValue الحقل إلى قيمة السلسلة الفارغة ("").

فيما يلي أجسام JSON لاثنين من التوائم التي تحتوي على علامات قيمة لتمثيل أحجامها. تحتوي التوائم في المثال أيضا على علامات قيمة ل "أحمر" أو "أرجواني" يتم استخدامها كعلامات علامة.

مثال Twin1، مع علامة قيمة لحجم كبير وعلامة "أحمر":

{
  "$dtId": "Twin1",
  "$etag": "W/\"d3997593-cc5f-4d8a-8683-957becc2bcdd\"",
  "$metadata": {
    "$model": "dtmi:example:ValueTags;1",
    "tags": {
      "lastUpdateTime": "2021-08-03T14:43:02.3150852Z"
    }
  },
  "tags": {
    "red": "",
    "size": "large"
  }
}

مثال Twin2، مع علامة قيمة لحجم صغير وعلامة "أرجواني":

{
  "$dtId": "Twin2",
  "$etag": "W/\"e215e586-b14a-4234-8ddb-be69ebfef878\"",
  "$metadata": {
    "$model": "dtmi:example:ValueTags;1",
    "tags": {
      "lastUpdateTime": "2021-08-03T14:43:53.1517123Z"
    }
  },
  "tags": {
    "purple": "",
    "size": "small"
  }
}

استعلام بعلامات القيمة

كما هو الحال مع علامات العلامة، يمكنك استخدام علامات القيمة لتصفية التوائم في الاستعلامات. يمكنك أيضا استخدام علامات القيمة وعلامات العلامة معا.

من المثال أعلاه، red يتم استخدام كعلامة. تذكر أن هذا استعلام للحصول على جميع التوائم التي تم وضع علامة عليها على أنها "حمراء":

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

فيما يلي استعلام للحصول على جميع الكيانات الصغيرة (علامة القيمة)، وليست حمراء:

SELECT * FROM DIGITALTWINS WHERE NOT IS_DEFINED(tags.red) AND tags.size = 'small'

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

اقرأ المزيد حول تصميم وإدارة نماذج التوأم الرقمي:

• إدارة نماذج DTDL

اقرأ المزيد حول الاستعلام عن الرسم البياني المزدوج:

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