الاستعلام عن الرسم البياني المزدوج ل Azure Digital Twins

تقدم هذه المقالة أمثلة استعلام وإرشادات لاستخدام لغة استعلام Azure Digital Twins للاستعلام عن الرسم البياني المزدوج للحصول على معلومات. (للحصول على مقدمة إلى لغة الاستعلام، راجع لغة الاستعلام.)

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

الوثائق المرجعية

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

• شروط
  • حدد ⁧.
  • من
  • كبريتة
  • ينضم
  • WHERE
• الوظائف
• العوامل
• الكلمات الأساسية المحجوزة

عرض كل التوائم الرقمية

إليك الاستعلام الأساسي الذي سيعيد قائمة بجميع التوائم الرقمية في المثيل:

SELECT * FROM DIGITALTWINS

الاستعلام عن طريق الملكية

احصل على توائم رقمية حسب الخصائص (بما في ذلك المعرف وبيانات التعريف):

SELECT  *
FROM DIGITALTWINS T  
WHERE T.firmwareVersion = '1.1'
AND T.$dtId in ['123', '456']
AND T.Temperature = 70

كما هو موضح في الاستعلام أعلاه، يتم الاستعلام عن معرف التوأم الرقمي باستخدام حقل بيانات التعريف $dtId.

يمكنك أيضًا الحصول على توائم بناءً على ما إذا كانت خاصية معينة محددة أم لا. فيما يلي استعلام يحصل على توائم لها خاصية محددة Location :

SELECT *​ FROM DIGITALTWINS WHERE IS_DEFINED(Location)

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

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

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

SELECT * FROM DIGITALTWINS​ T WHERE IS_NUMBER(T.Temperature)

خصائص مخطط الاستعلام

إذا كانت الخاصية من النوع Mapالمعقد ، يمكنك استخدام مفاتيح الخريطة والقيم مباشرة في الاستعلام، مثل هذا:

SELECT * FROM DIGITALTWINS​ T WHERE T.<propertyName>.<mapKey> = '<mapValue>'

إذا بدأ مفتاح الخريطة بحرف رقمي، فستحتاج إلى تضمين المفتاح بين أقواس مربعة مزدوجة ([[<mapKey>]]) للهروب منه في الاستعلام، على غرار استراتيجية الاستعلام باستخدام الكلمات الأساسية المحجوزة.

الاستعلام عن طريق النموذج

IS_OF_MODEL يمكن استخدام عامل التشغيل للتصفية استنادا إلى نموذج التوأم.

وهو يأخذ في الاعتبار التوريث وتعيين إصدار النموذج، ويقيم إلى true لتوأم معين إذا كان التوأم يفي بأي من هذه الشروط:

• ينفذ التوأم مباشرة النموذج المقدم إلى IS_OF_MODEL()، ورقم إصدار النموذج على التوأم أكبر من أو يساوي رقم إصدار النموذج المقدم
• ينفذ التوأم نموذجا يوسع النموذج المقدم إلى IS_OF_MODEL()، ورقم إصدار النموذج الموسع للتوأم أكبر من أو يساوي رقم إصدار النموذج المقدم

لذلك على سبيل المثال، إذا قمت بالاستعلام عن توائم النموذج dtmi:example:widget;4، فسيرجع الاستعلام جميع التوائم استنادا إلى الإصدار 4 أو أحدث من نموذج عنصر واجهة المستخدم، وكذلك التوائم استنادا إلى الإصدار 4 أو أحدث من أي نماذج ترث من عنصر واجهة المستخدم.

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

أبسط استخدام يأخذ IS_OF_MODEL معلمة twinTypeName فقط: IS_OF_MODEL(twinTypeName). فيما يلي مثال استعلام يمرر قيمة في هذه المعلمة:

SELECT * FROM DIGITALTWINS WHERE IS_OF_MODEL('dtmi:example:thing;1')

لتحديد مجموعة مزدوجة للبحث عند وجود أكثر من مجموعة (مثل عند JOIN استخدام)، أضف المعلمة twinCollection : IS_OF_MODEL(twinCollection, twinTypeName). فيما يلي مثال استعلام يضيف قيمة لهذه المعلمة:

SELECT * FROM DIGITALTWINS DT WHERE IS_OF_MODEL(DT, 'dtmi:example:thing;1')

للقيام بمطابقة تامة، أضف المعلمة exact : IS_OF_MODEL(twinTypeName, exact). فيما يلي مثال استعلام يضيف قيمة لهذه المعلمة:

SELECT * FROM DIGITALTWINS WHERE IS_OF_MODEL('dtmi:example:thing;1', exact)

يمكنك أيضا تمرير جميع الوسيطات الثلاثة معا: IS_OF_MODEL(twinCollection, twinTypeName, exact). فيما يلي مثال استعلام يحدد قيمة لجميع المعلمات الثلاثة:

SELECT * FROM DIGITALTWINS DT WHERE IS_OF_MODEL(DT, 'dtmi:example:thing;1', exact)

الاستعلام عن طريق العلاقة

عند الاستعلام بناءً على علاقات التوائم الرقمية، فإن لغة الاستعلام في Azure Digital Twins لها صيغة خاصة.

تُسحب العلاقات الموجودة في نطاق الاستعلام في عبارة FROM. على عكس اللغات "الكلاسيكية" من نوع SQL، كل تعبير في FROM العبارة ليس جدولا؛ بدلا من ذلك، FROM تعبر العبارة عن اجتياز علاقة عبر الكيانات. للاجتياز عبر العلاقات، يستخدم Azure Digital Twins إصدارا مخصصا من JOIN.

تذكر أنه مع قدرات نموذج Azure Digital Twins، لا توجد العلاقات بشكل مستقل عن التوائم، ما يعني أنه لا يمكن الاستعلام عن العلاقات هنا بشكل مستقل ويجب ربطها بتوأم. لتعكس هذه الحقيقة، يتم استخدام الكلمة الأساسية RELATED في JOIN عبارة لسحب مجموعة نوع معين من العلاقة القادمة من مجموعة التوأم. يجب أن يقوم الاستعلام بعد ذلك بالتصفية WHERE في عبارة ، للإشارة إلى التوأم (التوأم) المحدد الذي يجب استخدامه في استعلام العلاقة (باستخدام قيم التوائم $dtId ).

تقدم الأقسام التالية أمثلة على الشكل الذي يبدو عليه هذا.

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

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

SELECT T, CT
FROM DIGITALTWINS T
JOIN CT RELATED T.contains
WHERE T.$dtId = 'ABC'

يشار إلى نوع العلاقة (containsفي المثال أعلاه) باستخدام حقل العلاقة name من تعريف DTDL الخاص به.

الاستعلام حسب مصدر العلاقة أو هدفها

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

على سبيل المثال، يمكنك البدء بتوأم مصدر واتباع علاقاته للعثور على التوائم المستهدفة للعلاقات. فيما يلي مثال على استعلام يعثر على التوائم المستهدفة للعلاقات feeds القادمة من التوأم المصدر المزدوج.

SELECT target 
FROM DIGITALTWINS source 
JOIN target RELATED source.feeds 
WHERE source.$dtId = 'source-twin'

يمكنك أيضا البدء بهدف العلاقة وتتبع العلاقة مرة أخرى للعثور على التوأم المصدر. فيما يلي مثال على استعلام يعثر على التوأم المصدر لعلاقة feeds بالتوأم الهدف المزدوج.

SELECT source 
FROM DIGITALTWINS source 
JOIN target RELATED source.feeds 
WHERE target.$dtId = 'target-twin'

الاستعلام عن خصائص العلاقة

على غرار الطريقة التي تحتوي بها التوائم الرقمية على خصائص موصوفة عبر DTDL، يمكن أن يكون للعلاقات أيضا خصائص. يمكنك الاستعلام عن التوائم استنادًا إلى خصائص علاقاتهم. تسمح لغة استعلام Azure Digital Twins بتصفية العلاقات وإسقاطها، عن طريق تعيين اسم مستعار للعلاقة داخل JOIN عبارة .

على سبيل المثال، ضع في اعتبارك servicedBy علاقة لها خاصية reportedCondition . في الاستعلام أدناه، يتم إعطاء هذه العلاقة R اسما مستعارا للإشارة إلى الخاصية الخاصة بها.

SELECT T, SBT, R
FROM DIGITALTWINS T
JOIN SBT RELATED T.servicedBy R
WHERE T.$dtId = 'ABC'
AND R.reportedCondition = 'clean'

في المثال أعلاه، لاحظ كيف reportedCondition هي خاصية للعلاقة servicedBy نفسها (وليس لبعض التوأم الرقمي الذي له servicedBy علاقة).

الاستعلام باستخدام عدة JOINs

يتم دعم ما يصل إلى خمسة JOINs في استعلام واحد، والذي يسمح لك باجتياز مستويات متعددة من العلاقات في وقت واحد.

للاستعلام عن مستويات متعددة من العلاقات، استخدم عبارة واحدة FROM متبوعة بجمل N JOIN ، حيث JOIN تعبر العبارات عن العلاقات بناء على نتيجة سابقة FROM أو JOIN عبارة.

فيما يلي مثال على استعلام متعدد الصلات، والذي يحصل على جميع المصابيح الموجودة في لوحات الضوء في الغرف 1 و2.

SELECT LightBulb
FROM DIGITALTWINS Room
JOIN LightPanel RELATED Room.contains
JOIN LightBulb RELATED LightPanel.contains
WHERE IS_OF_MODEL(LightPanel, 'dtmi:contoso:com:lightpanel;1')
AND IS_OF_MODEL(LightBulb, 'dtmi:contoso:com:lightbulb ;1')
AND Room.$dtId IN ['room1', 'room2']

عدد العناصر

يمكنك حساب عدد العناصر في مجموعة نتائج باستخدام Select COUNT عبارة :

SELECT COUNT()
FROM DIGITALTWINS

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

SELECT COUNT()
FROM DIGITALTWINS
WHERE IS_OF_MODEL('dtmi:sample:Room;1')

SELECT COUNT()
FROM DIGITALTWINS c
WHERE IS_OF_MODEL('dtmi:sample:Room;1') AND c.Capacity > 20

يمكنك أيضا استخدام COUNT مع JOIN عبارة . فيما يلي استعلام يحسب جميع المصابيح الكهربائية الموجودة في اللوحات الضوئية للغرف 1 و2:

SELECT COUNT()  
FROM DIGITALTWINS Room  
JOIN LightPanel RELATED Room.contains  
JOIN LightBulb RELATED LightPanel.contains  
WHERE IS_OF_MODEL(LightPanel, 'dtmi:contoso:com:lightpanel;1')  
AND IS_OF_MODEL(LightBulb, 'dtmi:contoso:com:lightbulb;1')  
AND Room.$dtId IN ['room1', 'room2']

تصفية النتائج: حدد أهم العناصر

يمكنك تحديد العديد من العناصر "العلوية" في استعلام باستخدام Select TOP عبارة .

SELECT TOP (5)
FROM DIGITALTWINS
WHERE ...

نتائج التصفية: تحديد مجموعة الإرجاع مع الإسقاطات

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

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

SELECT Consumer, Factory, Edge
FROM DIGITALTWINS Factory
JOIN Consumer RELATED Factory.customer Edge
WHERE Factory.$dtId = 'ABC'

يمكنك أيضا استخدام الإسقاط لإرجاع خاصية التوأم. يعرض Name الاستعلام التالي خاصية المستهلكين المرتبطة بالمصنع بمعرف من ABC خلال علاقة .Factory.customer

SELECT Consumer.name
FROM DIGITALTWINS Factory
JOIN Consumer RELATED Factory.customer Edge
WHERE Factory.$dtId = 'ABC'

يمكنك أيضا استخدام الإسقاط لإرجاع خاصية علاقة. كما هو الحال في المثال السابق، يعرض Name الاستعلام التالي خاصية المستهلكين المتعلقة بالمصنع بمعرف من ABC خلال علاقة Factory.customer؛ ولكن الآن يقوم أيضا بإرجاع خاصيتين لتلك العلاقة، prop1 و prop2. يقوم بذلك عن طريق تسمية العلاقة Edge وجمع خصائصها.

SELECT Consumer.name, Edge.prop1, Edge.prop2, Factory.area
FROM DIGITALTWINS Factory
JOIN Consumer RELATED Factory.customer Edge
WHERE Factory.$dtId = 'ABC'

يمكنك أيضا استخدام الأسماء المستعارة لتبسيط الاستعلامات مع الإسقاط.

يقوم الاستعلام التالي بنفس العمليات مثل المثال السابق، ولكنه يسمي أسماء consumerNameالخصائص باسم و firstsecondو وfactoryArea.

SELECT Consumer.name AS consumerName, Edge.prop1 AS first, Edge.prop2 AS second, Factory.area AS factoryArea
FROM DIGITALTWINS Factory
JOIN Consumer RELATED Factory.customer Edge
WHERE Factory.$dtId = 'ABC'

فيما يلي استعلام مشابه يستعلم عن نفس المجموعة كما هو موضح أعلاه، ولكنه يعرض الخاصية فقط Consumer.name ك consumerName، ويعرض المصنع الكامل كتوأم.

SELECT Consumer.name AS consumerName, Factory
FROM DIGITALTWINS Factory
JOIN Consumer RELATED Factory.customer Edge
WHERE Factory.$dtId = 'ABC'

إنشاء استعلامات فعالة باستخدام عامل تشغيل IN

يمكنك تقليل عدد الاستعلامات التي تحتاجها بشكل كبير عن طريق إنشاء صفيف من التوائم والاستعلام مع IN عامل التشغيل.

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

1. العثور على أرضيات في المبنى بناء على العلاقة contains .

   SELECT Floor
   FROM DIGITALTWINS Building
   JOIN Floor RELATED Building.contains
   WHERE Building.$dtId = @buildingId
   

2. للعثور على الغرف، بدلا من النظر في الطوابق واحدا تلو الآخر وتشغيل JOIN استعلام للعثور على الغرف لكل غرفة، يمكنك الاستعلام باستخدام مجموعة من الطوابق في المبنى (تسمى Floor في الاستعلام أدناه).

   في تطبيق العميل:

   var floors = "['floor1','floor2', ..'floorn']"; 
   

   في الاستعلام:

   SELECT Room
   FROM DIGITALTWINS Floor
   JOIN Room RELATED Floor.contains
   WHERE Floor.$dtId IN ['floor1','floor2', ..'floorn']
   AND Room. Temperature > 72
   AND IS_OF_MODEL(Room, 'dtmi:com:contoso:Room;1')
   

أمثلة استعلام مركبة أخرى

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

• من الأجهزة التي تحتويها الغرفة 123، قم بإعادة أجهزة MxChip التي تخدم دور المشغل

  SELECT device
  FROM DIGITALTWINS space
  JOIN device RELATED space.has
  WHERE space.$dtid = 'Room 123'
  AND device.$metadata.model = 'dtmi:contoso:com:DigitalTwins:MxChip:3'
  AND has.role = 'Operator'
  

• الحصول على توائم لها علاقة مسماة Contains مع توأم آخر يحتوي على معرف id1

  SELECT Room
  FROM DIGITALTWINS Room
  JOIN Thermostat RELATED Room.Contains
  WHERE Thermostat.$dtId = 'id1'
  

• احصل على جميع غرف طراز الغرفة هذه التي يحتوي عليها floor11

  SELECT Room
  FROM DIGITALTWINS Floor
  JOIN Room RELATED Floor.Contains
  WHERE Floor.$dtId = 'floor11'
  AND IS_OF_MODEL(Room, 'dtmi:contoso:com:DigitalTwins:Room;1')
  

تشغيل الاستعلامات باستخدام واجهة برمجة التطبيقات

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

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

توضح القصاصة البرمجية التالية استدعاء .NET (C#) SDK من تطبيق عميل:

// Run a query for all twins   
string query = "SELECT * FROM DIGITALTWINS";
AsyncPageable<BasicDigitalTwin> result = client.QueryAsync<BasicDigitalTwin>(query);

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

• سترجع الاستعلامات التي تبدأ SELECT * FROM ... بقائمة من التوائم الرقمية (والتي يمكن تسلسلها ككائنات BasicDigitalTwin ، أو أنواع توائم رقمية مخصصة أخرى قد تكون قمت بإنشائها).
• سترجع الاستعلامات التي تبدأ بالتنسيق SELECT <A>, <B>, <C> FROM ... قاموسا بالمفاتيح <A>و <B>و.<C>
• يمكن صياغة تنسيقات أخرى من SELECT العبارات لإرجاع بيانات مخصصة. قد تفكر في إنشاء الفئات الخاصة بك للتعامل مع مجموعات النتائج المخصصة.

استعلام مع ترحيل الصفحات

استدعاءات الاستعلام تدعم ترحيل الصفحات. فيما يلي مثال كامل باستخدام BasicDigitalTwin كنوع نتيجة الاستعلام مع معالجة الأخطاء وترحيلها:

AsyncPageable<BasicDigitalTwin> result = client.QueryAsync<BasicDigitalTwin>("Select * From DigitalTwins");
try
{
    await foreach (BasicDigitalTwin twin in result)
    {
        // You can include your own logic to print the result
        // The logic below prints the twin's ID and contents
        Console.WriteLine($"Twin ID: {twin.Id} \nTwin data");
        foreach (KeyValuePair<string, object> kvp in twin.Contents)
        {
            Console.WriteLine($"{kvp.Key}  {kvp.Value}");
        }
    }
}
catch (RequestFailedException ex)
{
    Console.WriteLine($"Error {ex.Status}, {ex.ErrorCode}, {ex.Message}");
    throw;
}

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

تعرف على المزيد حول واجهات برمجة تطبيقات Azure Digital Twins وSDKs، بما في ذلك واجهة برمجة تطبيقات الاستعلام المستخدمة لتشغيل الاستعلامات من هذه المقالة.