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

مقالة
03/25/2023

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

تحتوي المقالة على نماذج استعلامات توضح بنية لغة الاستعلام وعمليات الاستعلام الشائعة للتوائم الرقمية. كما يصف كيفية تشغيل استعلاماتك بعد كتابتها، باستخدام واجهة برمجة تطبيقات استعلام Azure Digital Twins أو 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>'

إذا بدأ مفتاح الخريطة بحرف رقمي، فستحتاج إلى تضمين المفتاح بين أقواس مربعة مزدوجة ([[<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 الخاص به.

ملاحظة

لا يحتاج المطور إلى ربط هذا 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 متعددة

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

للاستعلام عن مستويات متعددة من العلاقات، استخدم عبارة واحدة 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'

يمكنك أيضا استخدام الإسقاط لإرجاع خاصية لعلاقة. كما هو الحال في المثال السابق، يعرض 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 عامل التشغيل.

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

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

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

للعثور على الغرف، بدلا من النظر في الطوابق واحدا تلو الآخر وتشغيل 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')

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

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

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

Share via