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

Cikk
03/25/2023

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ési nyelv.)

A cikk mintaleké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.

Megjegyzés

Ha az alábbi mintalekérdezéseket API- vagy SDK-hívással futtatja, a lekérdezés szövegét egyetlen sorba kell tömörítenie.

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
- FORRÁS
- MÉRKŐZÉS
- CSATLAKOZZON
- AHOL
Functions
Operátorok
Fenntartott kulcsszavak

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

Íme az alapszintű lekérdezés, amely a példány összes digitális ikerpéldányának listáját adja vissza:

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.

Tipp

Ha Cloud Shell használ egy, a következővel $kezdődő metaadatmezőkkel rendelkező lekérdezés futtatásához, akkor egy fordított perjellel kell kikerülnie $ a függvényből, hogy Cloud Shell tudja, hogy ez nem változó, és a lekérdezés szövegében literálként kell használni.

Ikerpéldányokat is lekérhet attól függően, hogy egy adott tulajdonság definiálva van-e. Íme egy lekérdezés, amely meghatározott Location tulajdonságú ikerpéldányokat kap:

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ű témakörben leírtak szerint. Íme egy lekérdezés, amely lekéri az összes ikerpéldány címkéjét a következővel 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 az ikerpéldányokat, amelyeknek Temperature a tulajdonsága egy szám:

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

Lekérdezéstérkép tulajdonságai

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

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 kell burkolnia ([[<mapKey>]]), hogy elkerülje 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 használható az ikerpéldány modellje alapján történő szűrésre.

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 számára biztosított 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 ikerpéldány olyan modellt implementál, amely kiterjeszti a modellt a -ra IS_OF_MODEL(), és az ikerpéldány 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ója alapján az összes ikerpéldányt, valamint a widgettől öröklődő modellek 4- vagy 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űbben csak egy twinTypeName paramétert használIS_OF_MODEL: IS_OF_MODEL(twinTypeName). Íme egy lekérdezési példa, amely egy értéket ad át 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 a JOIN használt) kereséshez keres, adja hozzá a twinCollection következő paramétert: 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 egyezteté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éterhez megad egy értéket:

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 egyéni verzióját JOINhasználja.

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éhez a záradék a JOIN kulcsszót RELATED használja az ikergyűjteményből származó bizonyos típusú kapcsolatok 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ányt kell használnia a kapcsolati lekérdezésben (az ikerpéldányok $dtId értékeit használva).

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

Alapszintű kapcsolati lekérdezés

Íme egy kapcsolatalapú mintalekérdezés. Ez a kódrészlet kiválasztja az összes, tulajdonsággal ABCrendelkező ID digitális ikerpéldányt, valamint a digitális ikerpéldányokhoz kapcsolódó összes digitális ikerpéldányt 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 feltüntetve.

Megjegyzés

A fejlesztőnek ezt nem kell egy kulcsértékkel korrelálnia JOIN a WHERE záradékban (vagy a definícióval JOIN beágyazott kulcsértéket kell megadnia). Ezt az összefüggést a rendszer automatikusan számítja ki, mivel maguk a kapcsolat tulajdonságai azonosítják a célentitást.

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

A kapcsolat lekérdezési struktúrájával azonosíthatja a kapcsolat forrását vagy célját képező digitális ikerpéldányt.

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

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 JOIN záradékon belüli kapcsolathoz.

Példaként tekintsünk egy servicedBy tulajdonságot tartalmazó kapcsolatra reportedCondition . 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 reportedCondition maga a servicedBy kapcsolat tulajdonsága (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énye alapján fejezik ki a kapcsolatokat.

Íme egy példa egy többcsatlakozásos lekérdezésre, amely lekéri az 1. és 2. helyiség villanypaneljeiben található összes villanykörtét.

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

Az eredményhalmazban lévő elemek számát a Select COUNT záradék használatával számolhatja meg:

SELECT COUNT()
FROM DIGITALTWINS

Adjon hozzá egy záradékot WHERE az adott feltételnek megfelelő elemek számának megszámlálásához. Íme néhány példa az ikermodell típusa alapján alkalmazott szűrővel történő számlálásra (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

Használhatja a záradékot JOIN isCOUNT. Íme egy lekérdezés, amely megszámolja az 1. és 2. szoba fénypaneljeiben található összes villanykörtét:

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

Eredmények szűrése: a felső elemek kiválasztása

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: visszaadott készlet megadása vetületekkel

Ha a 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-vetületekkel kapcsolatos további információkért tekintse meg a SELECT záradék referenciadokumentációját.

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

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

Az ikerpéldány tulajdonságának visszaadására is használhat vetületet. Az alábbi lekérdezés a Name Factoryhoz 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 a következő lekérdezés a Factoryhoz kapcsolódó Fogyasztók tulajdonságát veti Name ki egy azonosítóval ABC a () kapcsolaton Factory.customerkeresztül, de most a kapcsolat két tulajdonságát is visszaadja, prop1 a és prop2a tulajdonságot. Ezt a kapcsolat Edge elnevezésével és tulajdonságainak összegyűjtésével teszi meg.

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

Aliasok használatával is egyszerűsítheti a lekérdezéseket a leképezéssel.

A következő lekérdezés ugyanazokat a műveleteket hajtja végre, mint az előző példában, de a tulajdonságneveket consumerNamea következőre aliasosítja: , 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 fenti halmazt kérdezi le, de csak a Consumer.name tulajdonságot ikreként consumerName, a teljes Factoryt pedig ikerpéldányként projekteli ki.

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 történő 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 olyan helyiségeket szeretne keresni egy épületen belül, amelyek melegek, az egyik módszer az alábbi lépések végrehajtása.

Az épület emeleteinek megkeresése a contains kapcsolat alapján.

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

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

Az ü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.

Azon eszközök közül, amelyekkel a Room 123 rendelkezik, az operátori szerepkört szolgáló MxChip-eszközöket adja vissza

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 neve egy másik ikerpéldánysal van elnevezve Contains , amelynek azonosítója id1
```
SELECT Room
FROM DIGITALTWINS Room
JOIN Thermostat RELATED Room.Contains
WHERE Thermostat.$dtId = 'id1'
```

A 11. emelet által tartalmazott szobamodell összes helyiségének lekérése

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ést a Query API meghívásával hajthatja végre.

Az API-t meghívhatja közvetlenül, 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 visszaadja a digitális ikerpéldányok listáját, 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 következővel SELECT * FROM ... kezdődő lekérdezések 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ány-típusokat, amelyeket esetleg létrehozott).
A formátumban SELECT <A>, <B>, <C> FROM ... kezdődő lekérdezések a , és <B><C>billentyűkkel <A>rendelkező szótárat ad vissza.
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 az SDK-król, beleértve a lekérdezések futtatásához használt Query API-t ebből a cikkből.

Megosztás a következőn keresztül: