الاستعلام عن الرسم البياني التوأم ل Azure Digital Twins

هل هذه الصفحة مفيدة؟

هل لديك ملاحظات إضافية؟

سيتم إرسال الملاحظات إلى Microsoft: بالضغط على الزر «إرسال»، سيتم استخدام ملاحظاتك لتحسين منتجات Microsoft وخدماتها. نهج الخصوصية.

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

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

ملاحظة

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

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

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

• شروط
  • حدد
  • من
  • المباراة (معاينة)
  • ينضم
  • المكان‬
• الوظائف
• المشغلون
• الكلمات المفتاحية المحجوزة

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

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

SELECT * FROM DIGITALTWINS

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

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

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

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

تلميح

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

يمكنك أيضًا الحصول على توائم بناءً على ما إذا كانت خاصية معينة محددة أم لا. في ما يلي استعلام يحصل على توائم لها خاصية محددة 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>'

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

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في المثال أعلاه) باستخدام حقل العلاقة من تعريف DTDL الخاصname بها.

ملاحظة

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

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

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

على سبيل المثال ، يمكنك البدء بتوأم مصدر ومتابعة علاقاته للعثور على التوائم المستهدفة للعلاقات. في ما يلي مثال على استعلام يعثر على التوائم المستهدفة للعلاقات 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 ).

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

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

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

فيما يلي مثال على استعلام متعدد الوصلات ، والذي يحصل على جميع المصابيح الكهربائية الموجودة في لوحات الإضاءة في الغرفتين 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'

يمكنك أيضا استخدام الإسقاط لإرجاع خاصية علاقة. كما هو الحال في المثال السابق ، يقوم الاستعلام التالي بعرض خاصية المستهلكين المتعلقة بالمصنع مع معرف من ABC خلال علاقة Factory.customer؛ ولكنه الآن يقوم Name أيضا بإرجاع خاصيتين لتلك العلاقة ، 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 استعلام للعثور على الغرف لكل منها ، يمكنك الاستعلام باستخدام مجموعة من الطوابق في المبنى (تسمى الطابق في الاستعلام أدناه).

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

   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'
  

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

  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')
  

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

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

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

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

// 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 ومجموعات SDK، بما في ذلك واجهة برمجة تطبيقات الاستعلام المستخدمة لتشغيل الاستعلامات من هذه المقالة.