Az Azure Digital Twins ikergráfjának lekérdezése

Ez a cikk lekérdezési példákat és utasításokat tartalmaz az Azure Digital Twins lekérdezési nyelvének használatával az ikergráf adatainak lekérdezéséhez. (A lekérdezés nyelvének bemutatása: Lekérdezés nyelve.)

A cikk minta lekérdezéseket tartalmaz, amelyek bemutatják a digitális ikerpéldányok lekérdezési nyelvének szerkezetét és gyakori lekérdezési műveleteit. Azt is ismerteti, hogyan futtathatja a lekérdezéseket, miután megírta őket az Azure Digital Twins Query API vagy egy SDK használatával.

Referenciadokumentáció

A lekérdezés nyelvi referenciája az Azure Digital Twins dokumentációjának bal oldali tartalomjegyzékében található Hivatkozás területen található. Az alábbi hivatkozások használatával közvetlenül is megnyithatja a referenciaszakaszokat:

• Záradékok
  • SELECT
  • TÓL
  • GYUFA
  • CSATLAKOZIK
  • HOL
• Functions
• Operátorok
• Fenntartott kulcsszavak

Az összes digitális ikerpéldány megjelenítése

Az alábbi egyszerű lekérdezés az összes digitális ikerpéldány listáját adja vissza a példányban:

SELECT * FROM DIGITALTWINS

Lekérdezés tulajdonság szerint

Digitális ikerpéldányok lekérése tulajdonságok szerint (beleértve az azonosítót és a metaadatokat):

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

A fenti lekérdezésben látható módon a rendszer lekérdezi egy digitális ikerpéldány azonosítóját a metaadatmező $dtIdhasználatával.

Ikerpéldányokat is lekérhet attól függően, hogy egy adott tulajdonság definiálva van-e. Az alábbiakban egy meghatározott tulajdonságú Location ikerpéldányokat kérdezünk le:

SELECT *​ FROM DIGITALTWINS WHERE IS_DEFINED(Location)

Ez a lekérdezés segíthet az ikerpéldányok tulajdonságai alapján tag történő lekérésében a Címkék hozzáadása digitális ikerpéldányokhoz című cikkben leírtak szerint. Az alábbiakban egy lekérdezést talál, amely az összes ikerpéldányt a következő címkével címkézi red:

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

Az ikerpéldányokat a tulajdonság típusa alapján is lekérheti. Íme egy lekérdezés, amely lekéri azokat az ikerpéldányokat, akiknek Temperature a tulajdonsága egy szám:

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

Lekérdezési megfeleltetés tulajdonságai

Ha egy tulajdonság összetett típusú Map, a leképezési kulcsokat és az értékeket közvetlenül a lekérdezésben használhatja, például a következőt:

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

Ha a térképkulcs numerikus karakterrel kezdődik, a kulcsot dupla szögletes zárójelekbe ([[<mapKey>]]) kell burkolnia, hogy elkerülje azt a lekérdezésben, hasonlóan a fenntartott kulcsszavakkal való lekérdezés stratégiájához.

Lekérdezés modell szerint

Az IS_OF_MODEL operátor segítségével az ikermodell alapján szűrhet.

Figyelembe veszi az öröklést és a modell verziószámozását, és kiértékeli true egy adott ikerpéldányra, ha az ikerpéldány megfelel az alábbi feltételek valamelyikének:

• Az ikerpéldány közvetlenül implementálja a megadott IS_OF_MODEL()modellt, és az ikerpéldányon lévő modell verziószáma nagyobb vagy egyenlő a megadott modell verziószámával
• Az iker olyan modellt implementál, amely kibővíti a megadott IS_OF_MODEL()modellt, és az iker kiterjesztett modellverziószáma nagyobb vagy egyenlő a megadott modell verziószámával

Így például ha a modell dtmi:example:widget;4ikerpéldányait kérdezi le, a lekérdezés a widgetmodell 4. vagy annál nagyobb verzióján alapuló összes ikerpéldányt, valamint a widgettől öröklő modellek 4. vagy annál nagyobb verzióján alapuló ikerpéldányokat is visszaadja.

IS_OF_MODEL több különböző paramétert is igénybe vehet, és ennek a szakasznak a többi része a különböző túlterhelési lehetőségeknek van szentelve.

A legegyszerűbb használat IS_OF_MODEL csak egy paramétert twinTypeName vesz igénybe: IS_OF_MODEL(twinTypeName). Íme egy lekérdezési példa, amely átad egy értéket ebben a paraméterben:

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

Ha meg szeretne adni egy ikergyűjteményt, amely egynél több (például egy használat esetén) keresésre szolgál, adja hozzá a twinCollection következő paramétertJOIN: IS_OF_MODEL(twinCollection, twinTypeName). Íme egy lekérdezési példa, amely hozzáad egy értéket ehhez a paraméterhez:

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

A pontos egyezéshez adja hozzá a következő paramétert exact : IS_OF_MODEL(twinTypeName, exact). Íme egy lekérdezési példa, amely hozzáad egy értéket ehhez a paraméterhez:

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

Mindhárom argumentumot együtt is átadhatja: IS_OF_MODEL(twinCollection, twinTypeName, exact). Íme egy lekérdezési példa, amely mindhárom paraméter értékét megadja:

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

Lekérdezés kapcsolat szerint

A digitális ikerpéldányok kapcsolatai alapján végzett lekérdezéshez az Azure Digital Twins lekérdezési nyelv speciális szintaxissal rendelkezik.

A kapcsolatok a FROM záradékkal vannak bevonva a lekérdezés hatókörébe. A "klasszikus" SQL-típusú nyelvektől eltérően a FROM záradék minden kifejezése nem tábla, FROM hanem egy entitásközi kapcsolat bejárását fejezi ki. A kapcsolatok közötti átjáráshoz az Azure Digital Twins a JOIN.

Ne feledje, hogy az Azure Digital Twins-modell képességeivel a kapcsolatok nem léteznek ikerpéldánytól függetlenül, ami azt jelenti, hogy az itt található kapcsolatok nem kérdezhetők le egymástól függetlenül, és ikerpéldányhoz kell kötniük. Ennek a ténynek a tükrözésére a záradék a JOIN kulcsszót RELATED használja az ikergyűjteményből származó bizonyos típusú kapcsolat halmazának lekéréséhez. A lekérdezésnek ezután szűrnie kell a WHERE záradékban, hogy jelezze, melyik ikerpéldány(ok) legyenek használva a kapcsolati lekérdezésben (az ikerpéldányok $dtId értékeinek használatával).

Az alábbi szakaszok példákat mutatnak be ennek a megjelenésére.

Egyszerű kapcsolati lekérdezés

Íme egy példa kapcsolatalapú lekérdezésre. Ez a kódrészlet kiválasztja az összes digitális ikerpéldányt, amely rendelkezik egy tulajdonsággal IDABC, és az összes digitális ikerpéldányt, amely ezekhez a digitális ikerpéldányokhoz kapcsolódik egy contains kapcsolaton keresztül.

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

A kapcsolat típusa (containsa fenti példában) a kapcsolat DTDL-definíciójának mezője name alapján van jelezve.

Lekérdezés egy kapcsolat forrása vagy célja szerint

A kapcsolat lekérdezési struktúrájával azonosíthat egy olyan digitális ikerpéldányt, amely egy kapcsolat forrása vagy célja.

Például egy forrás ikerpéldánysal kezdheti, és a kapcsolatait követve megkeresheti a kapcsolatok cél ikerpéldányait. Íme egy példa egy lekérdezésre, amely megkeresi feeds az ikerpéldány-ikerpéldányból származó kapcsolatok célikreit.

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

A kapcsolat céljával is kezdhet, és visszakövetheti a kapcsolatot a forrás ikerpéldány megkereséséhez. Íme egy példa egy lekérdezésre, amely megkeresi az ikerpéldány-ikerpéldányhoz való kapcsolat forrás ikerpéldányát feeds .

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

Kapcsolat tulajdonságainak lekérdezése

Hasonlóan ahhoz, ahogyan a digitális ikerpéldányok a DTDL által leírt tulajdonságokkal rendelkeznek, a kapcsolatoknak is lehetnek tulajdonságaik. Ikerpéldányok lekérdezhetők a kapcsolataik tulajdonságai alapján. Az Azure Digital Twins lekérdezési nyelve lehetővé teszi a kapcsolatok szűrését és kivetítését azáltal, hogy aliast rendel a záradékon belüli JOIN kapcsolathoz.

Vegyük servicedBy például egy tulajdonságot reportedCondition tartalmazó kapcsolatot. Az alábbi lekérdezésben ez a kapcsolat egy aliast R kap a tulajdonságára való hivatkozáshoz.

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

A fenti példában figyelje meg, hogy a kapcsolatnak milyen reportedCondition tulajdonsága servicedBy van (nem egy olyan digitális ikerpéldány, amely kapcsolatban áll servicedBy ).

Lekérdezés több JOIN-nel

Egyetlen lekérdezés legfeljebb öt JOINs-t támogat, így egyszerre több kapcsolatszintet is át lehet haladni.

Több kapcsolatszint lekérdezéséhez használjon egyetlen FROM utasítást, majd N JOIN utasítást, ahol az JOIN utasítások egy előző FROM vagy JOIN utasítás eredményén fejezik ki a kapcsolatokat.

Íme egy példa egy többcsatlakozásos lekérdezésre, amely az 1. és a 2. szobában található villanykörte-elemeket tartalmazza.

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

Elemek megszámlálása

A záradék használatával Select COUNT megszámolhatja az eredményhalmaz elemeinek számát:

SELECT COUNT()
FROM DIGITALTWINS

Adjon hozzá egy záradékot WHERE az egyes feltételeknek megfelelő elemek számának megszámlálásához. Íme néhány példa az ikermodell típusán alapuló alkalmazott szűrővel történő számlálásra (erről a szintaxisról további információt az alábbi Lekérdezés modell szerint című témakörben talál):

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

A záradékkal JOIN együtt is használhatóCOUNT. Íme egy lekérdezés, amely az 1. és a 2. szoba fénypaneljeiben található összes villanykörtét megszámolja:

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

Találatok szűrése: a legfontosabb elemek kijelölése

A záradék használatával kiválaszthatja a lekérdezés több "felső" elemét Select TOP .

SELECT TOP (5)
FROM DIGITALTWINS
WHERE ...

Eredmények szűrése: visszatérési csoport megadása vetületekkel

Ha az SELECT utasításban előrejelzéseket használ, kiválaszthatja, hogy a lekérdezés mely oszlopokat adja vissza. A kivetítés mostantól a primitív és az összetett tulajdonságok esetében is támogatott. Az Azure Digital Twins-beli előrejelzésekről további információt a SELECT záradék referenciadokumentációjában talál.

Íme egy példa egy lekérdezésre, amely az ikerpéldányok és kapcsolatok visszaadásához használ előrejelzést. Az alábbi lekérdezés a Fogyasztót, a Factoryt és az Edge-et egy olyan forgatókönyvből mutatja be, amelyben egy azonosítóval rendelkező ABC gyár a Fogyasztóhoz kapcsolódik egy kapcsolaton Factory.customerkeresztül, és ez a kapcsolat jelenik meg.Edge

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

Az ikerpéldányok tulajdonságát a vetítéssel is visszaadhatja. Az alábbi lekérdezés a Name Gyárhoz kapcsolódó fogyasztók tulajdonságát a következő kapcsolaton Factory.customerkeresztüli azonosítóval ABC adja vissza:

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

A leképezéssel egy kapcsolat tulajdonságát is visszaadhatja. Az előző példához hasonlóan az alábbi lekérdezés a Gyárhoz kapcsolódó Fogyasztók tulajdonságát is kivetüli Name egy Factory.customerazonosítóvalABC; de most a kapcsolat két tulajdonságát is visszaadja. prop1prop2 Ezt úgy teszi, hogy elnevozza a kapcsolatot Edge , és összegyűjti annak tulajdonságait.

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

Aliasokkal is egyszerűsítheti a lekérdezéseket a kivetítéssel.

Az alábbi lekérdezés ugyanazokat a műveleteket hajtja végre, mint az előző példában, de a tulajdonságneveket a következőre consumerNamealiasozza: , first, secondés 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'

Íme egy hasonló lekérdezés, amely a fentiekkel megegyező készletet kérdez le, de csak a Consumer.name tulajdonságot állítja be, és consumerNamea teljes Factoryt ikerpéldányként projekteli.

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

Hatékony lekérdezések létrehozása az IN operátorral

Az ikerpéldányok tömbjének létrehozásával és az operátorral való lekérdezéssel jelentősen csökkentheti a IN szükséges lekérdezések számát.

Vegyük például azt a forgatókönyvet, amelyben az épületek emeleteket és emeleteket tartalmaznak. Ha forró szobákat szeretne keresni egy épületen belül, kövesse az alábbi lépéseket.

1. Keresse meg a padlót az épületben a contains kapcsolat alapján.

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

2. A szobák kereséséhez ahelyett, hogy egyenként mérlegeli a padlókat, és egy JOIN lekérdezést futtat, hogy megkeresse az egyes helyiségeket, lekérdezheti az épület emeleteinek gyűjteményét (az alábbi lekérdezésben a Floor nevet).

   Ügyfélalkalmazásban:

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

   Lekérdezésben:

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

Egyéb összetett lekérdezési példák

A fenti lekérdezéstípusok bármelyikét kombinálhatja kombinációs operátorokkal, hogy több részletet is belefoglaljon egyetlen lekérdezésbe. Íme néhány további példa olyan összetett lekérdezésekre, amelyek egyszerre több ikerleírót is lekérdeznek.

• A Room 123 által használt eszközök közül adja vissza az operátori szerepkört szolgáló MxChip-eszközöket

  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'
  

• Olyan ikerpéldányok lekérése, amelyek kapcsolatban Contains vannak egy másik ikerpéldány azonosítójával id1

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

• Szerezze be ennek a szobamodellnek az összes helyiségét, amelyet a 11. emelet tartalmaz

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

Lekérdezések futtatása az API-val

Miután eldöntötte a lekérdezési sztringet, a lekérdezési API meghívásával hajthatja végre.

Közvetlenül meghívhatja az API-t, vagy használhatja az Azure Digital Twinshez elérhető SDK-k egyikét.

Az alábbi kódrészlet egy ügyfélalkalmazás .NET (C#) SDK-hívását mutatja be:

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

A hívásban használt lekérdezés a digitális ikerpéldányok listáját adja vissza, amelyet a fenti példa BasicDigitalTwin objektumokkal jelöl. Az egyes lekérdezések adatainak visszatérési típusa attól függ, hogy milyen kifejezéseket ad meg az SELECT utasítással:

• A kezdő lekérdezések SELECT * FROM ... visszaadják a digitális ikerpéldányok listáját (amelyek objektumként BasicDigitalTwin szerializálhatók, vagy más egyéni digitális ikerpéldányokat, amelyeket esetleg létrehozott).
• A formátumban SELECT <A>, <B>, <C> FROM ... kezdődő lekérdezések a kulcsokkal <A><B><C>és a .
• Más utasításformátumok SELECT is létrehozhatóak az egyéni adatok visszaadásához. Érdemes lehet saját osztályokat létrehozni a testreszabott eredményhalmazok kezeléséhez.

Lekérdezés lapozással

A lekérdezéshívások támogatják a lapozást. Íme egy teljes példa a lekérdezés eredménytípusának hibakezeléssel és lapozással történő használatával 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;
}

Következő lépések

További információ az Azure Digital Twins API-król és SDK-król, beleértve a lekérdezések futtatásához használt Query API-t is.