Dotazování grafu dvojčat Azure Digital Twins

Tento článek nabízí příklady dotazů a pokyny pro použití dotazovacího jazyka Azure Digital Twins k dotazování na graf dvojčete s informacemi. (Úvod do dotazovacího jazyka najdete v tématu .Dotazovací jazyk.)

Článek obsahuje ukázkové dotazy, které ilustrují strukturu dotazovacího jazyka a běžné operace dotazů pro digitální dvojčata. Popisuje také, jak po napsání dotazů spouštět dotazy pomocí rozhraní API pro dotazy Azure Digital Twins nebo sady SDK.

Poznámka:

Pokud spouštíte ukázkové dotazy níže s voláním rozhraní API nebo sady SDK, budete muset text dotazu zkondenzovat na jeden řádek.

Referenční dokumentace

Referenční informace k dotazovacímu jazyku najdete v části Referenční informace v levém obsahu pro dokumentaci ke službě Azure Digital Twins. Můžete také přejít přímo do referenčních oddílů pomocí následujících odkazů:

• Klauzule
  • SELECT
  • FROM
  • UTKÁNÍ
  • PŘIPOJIT
  • WHERE
• Functions
• Operátory
• Vyhrazená klíčová slova

Zobrazit všechna digitální dvojčata

Tady je základní dotaz, který vrátí seznam všech digitálních dvojčat v instanci:

SELECT * FROM DIGITALTWINS

Dotazování podle vlastnosti

Získání digitálních dvojčat podle vlastností (včetně ID a metadat):

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

Jak je znázorněno v dotazu výše, ID digitálního dvojčete se dotazuje pomocí pole $dtIdmetadat .

Tip

Pokud ke spuštění dotazu používáte Cloud Shell s poli metadat, která začínají $, měli byste utéct $ zpětným lomítkem, aby cloud Shell věděl, že se nejedná o proměnnou a měl by být v textu dotazu využit jako literál.

Můžete také získat dvojčata na základě toho, jestli je definována určitá vlastnost. Tady je dotaz, který získá dvojčata s definovanou Location vlastností:

SELECT *​ FROM DIGITALTWINS WHERE IS_DEFINED(Location)

Tento dotaz vám může pomoct získat dvojčata podle jejich tag vlastností, jak je popsáno v tématu Přidání značek do digitálních dvojčat. Tady je dotaz, který získá všechna dvojčata označená red:

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

Můžete také získat dvojčata na základě typu vlastnosti. Tady je dotaz, který získá dvojčata, jejichž Temperature vlastnost je číslo:

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

Vlastnosti mapy dotazů

Pokud je vlastnost komplexního typu Map, můžete použít mapové klíče a hodnoty přímo v dotazu, například takto:

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

Pokud klíč mapy začíná číselným znakem, budete muset klíč zabalit do dvojitých hranatých závorek ([[<mapKey>]]), aby se uvozil do dotazu, podobně jako u strategie pro dotazování s rezervovanými klíčovými slovy.

Dotazování podle modelu

Operátor IS_OF_MODEL lze použít k filtrování na základě modelu dvojčete.

Považuje dědičnost a správu verzí modelu a vyhodnotí true se pro dané dvojče, pokud dvojče splňuje některou z těchto podmínek:

• Dvojče přímo implementuje model poskytnutý pro IS_OF_MODEL()a číslo verze modelu ve dvojčeti je větší nebo rovno číslu verze poskytnutého modelu.
• Dvojče implementuje model, který rozšiřuje model poskytnutý na IS_OF_MODEL(), a číslo rozšířené verze modelu dvojčete je větší nebo rovno číslu verze poskytnutého modelu.

Pokud tedy například zadáte dotaz na dvojčata modelu dtmi:example:widget;4, dotaz vrátí všechna dvojčata založená na verzi 4 nebo vyšší modelu widgetu a také dvojčata založená na verzi 4 nebo vyšší ze všech modelů, které dědí z widgetu.

IS_OF_MODEL může mít několik různých parametrů a zbytek této části je vyhrazený pro různé možnosti přetížení.

Nejjednodušší použití IS_OF_MODEL přebírá pouze twinTypeName parametr: IS_OF_MODEL(twinTypeName). Tady je příklad dotazu, který předá hodnotu v tomto parametru:

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

Pokud chcete zadat kolekci dvojčat, která se má hledat, když je více než jedna (například při JOIN použití), přidejte twinCollection parametr: IS_OF_MODEL(twinCollection, twinTypeName). Tady je příklad dotazu, který přidá hodnotu pro tento parametr:

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

Chcete-li provést přesnou shodu, přidejte exact parametr: IS_OF_MODEL(twinTypeName, exact). Tady je příklad dotazu, který přidá hodnotu pro tento parametr:

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

Můžete také předat všechny tři argumenty dohromady: IS_OF_MODEL(twinCollection, twinTypeName, exact). Tady je příklad dotazu určující hodnotu pro všechny tři parametry:

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

Dotazování podle relace

Při dotazování na základě relací digitálních dvojčat má dotazovací jazyk Azure Digital Twins speciální syntaxi.

Relace jsou načteny do oboru dotazu v klauzuli FROM. Na rozdíl od "klasických" jazyků typu SQL není každý výraz v FROM klauzuli tabulka. Tato klauzule spíše FROM vyjadřuje procházení relace mezi entitami. K procházení mezi relacemi používá Služba Azure Digital Twins vlastní verzi JOINslužby .

Vzpomeňte si, že s možnostmi modelu Azure Digital Twins neexistují relace nezávisle na dvojčatech, což znamená, že relace se zde nedají dotazovat nezávisle a musí být svázané s dvojčetem. Pro vyjádření tohoto faktu se klíčové slovo RELATED v JOIN klauzuli používá k načtení sady určitého typu relace pocházející z kolekce dvojčat. Dotaz pak musí filtrovat v WHERE klauzuli, aby bylo možné určit, která konkrétní dvojčata se mají použít v dotazu relace (pomocí hodnot dvojčat $dtId ).

V následujících částech najdete příklady toho, jak to vypadá.

Základní dotaz na relaci

Tady je ukázkový dotaz založený na relacích. Tento fragment kódu vybere všechna digitální dvojčata s ID vlastností ABCa všechna digitální dvojčata související s těmito digitálními dvojčaty prostřednictvím contains relace.

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

Typ relace (contains v příkladu výše) je označen pomocí pole relace name z jeho definice DTDL.

Poznámka:

Vývojář to nemusí korelovat JOIN s hodnotou klíče v WHERE klauzuli (nebo zadat hodnotu klíče vloženou s definicí JOIN ). Tato korelace se počítá automaticky systémem, protože samotné vlastnosti relace identifikují cílovou entitu.

Dotazování podle zdroje nebo cíle relace

Strukturu dotazu relace můžete použít k identifikaci digitálního dvojčete, které je zdrojem nebo cílem relace.

Můžete například začít se zdrojovým dvojčem a sledovat jeho relace a najít cílová dvojčata relací. Tady je příklad dotazu, který najde cílová dvojčata relací pocházejících feeds ze zdrojového dvojčete dvojčete.

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

Můžete také začít s cílem relace a trasovat relaci zpět a najít zdrojové dvojče. Tady je příklad dotazu, který najde zdrojové dvojče feeds relace s dvojčetem cíle-dvojče.

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

Dotazování vlastností relace

Podobně jako mají digitální dvojčata vlastnosti popisované pomocí DTDL i relace mohou mít vlastnosti. Na dvojčata se můžete dotazovat na základě vlastností jejich relací. Dotazovací jazyk Azure Digital Twins umožňuje filtrování a projekci relací přiřazením aliasu k relaci v rámci JOIN klauzule.

Představte si servicedBy například relaci, která má reportedCondition vlastnost. V následujícím dotazu má tato relace alias R odkaz na jeho vlastnost.

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

V předchozím příkladu si všimněte, jak reportedCondition je vlastnost servicedBy samotné relace (NE u některého digitálního dvojčete, které má servicedBy relaci).

Dotazování s více názvy JOIN

V jednom dotazu se podporuje až pět JOINs, což umožňuje procházet více úrovní relací najednou.

K dotazování na více úrovní relací použijte jeden FROM příkaz následovaný příkazy N JOIN , kde JOIN příkazy vyjadřují relace na základě výsledku předchozího FROM nebo JOIN příkazu.

Tady je příklad dotazu s více spojeními, který získá všechny žárovky obsažené v světlých panelech v místnostech 1 a 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']

Počet položek

Pomocí klauzule můžete spočítat počet položek v sadě Select COUNT výsledků:

SELECT COUNT()
FROM DIGITALTWINS

WHERE Přidejte klauzuli pro spočítání počtu položek, které splňují určitá kritéria. Tady je několik příkladů počítání s použitým filtrem na základě typu modelu dvojčete (další informace o této syntaxi najdete v části Dotaz podle modelu níže):

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

Můžete také použít COUNT společně s klauzulí JOIN . Tady je dotaz, který spočítá všechny žárovky obsažené v světlých panelech místností 1 a 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']

Výsledky filtrování: výběr horních položek

Pomocí klauzule můžete vybrat několik "horních" položek v dotazu Select TOP .

SELECT TOP (5)
FROM DIGITALTWINS
WHERE ...

Výsledky filtru: Určení návratové sady s projekcemi

Pomocí projekcí v SELECT příkazu můžete zvolit sloupce, které dotaz vrátí. Projekce je nyní podporována pro primitivní i komplexní vlastnosti. Další informace o projekcích s Azure Digital Twins najdete v referenční dokumentaci k klauzuli SELECT.

Tady je příklad dotazu, který pomocí projekce vrací dvojčata a relace. Následující dotazuje příjemce, továrnu a Edge ze scénáře, ve kterém objekt factory s ID ABC souvisí s příjemcem prostřednictvím relace Factory.customer, a tato relace se zobrazí jako Edge.

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

Pomocí projekce můžete také vrátit vlastnost dvojčete. Následující dotaz projektuje Name vlastnost Uživatele, které souvisí s objektem factory s ID ABC prostřednictvím relace Factory.customer.

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

K vrácení vlastnosti relace můžete použít také projekci. Podobně jako v předchozím příkladu následující dotazuje Name vlastnost Uživatele související s Objektem pro vytváření s ID ABC prostřednictvím relace Factory.customer; ale nyní také vrátí dvě vlastnosti této relace, prop1 a prop2. Dělá to pojmenováním relace Edge a shromážděním jeho vlastností.

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

Aliasy můžete také použít ke zjednodušení dotazů s projekcí.

Následující dotaz provede stejné operace jako v předchozím příkladu, ale aliasuje názvy vlastností na consumerName, first, seconda 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'

Tady je podobný dotaz, který dotazuje stejnou sadu jako výše, ale projekty pouze Consumer.name vlastnost jako consumerNamea projekty dokončená továrna jako dvojče.

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

Vytváření efektivních dotazů pomocí operátoru IN

Počet dotazů, které potřebujete, můžete výrazně snížit vytvořením pole dvojčat a dotazováním pomocí operátoru IN .

Představte si například scénář, ve kterém budovy obsahují podlahy a podlahy pokoje. Pokud chcete vyhledat místnosti v budově, která je horká, je jedním ze způsobů, jak postupovat podle těchto kroků.

1. Najděte podlahy v budově na základě vztahu contains .

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

2. Pokud chcete najít místnosti, nemusíte zvažovat podlahy 1 po druhém a spouštět JOIN dotaz, abyste našli místnosti pro každou z nich, můžete dotazovat s kolekcí podlah v budově (pojmenovanou Podlaha v dotazu níže).

   V klientské aplikaci:

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

   V dotazu:

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

Další příklady složených dotazů

Pomocí kombinovaných operátorů můžete zkombinovat libovolný z výše uvedených typů dotazů, abyste do jednoho dotazu zahrnuli více podrobností. Tady je několik dalších příkladů složených dotazů, které se dotazují na více než jeden typ popisovače dvojčete najednou.

• Ze zařízení, která má místnost 123, vraťte zařízení MxChip, která obsluhuje roli operátora.

  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'
  

• Získání dvojčat, která mají relaci s Contains názvem jiného dvojčete s ID id1

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

• Získejte všechny pokoje tohoto modelu místnosti, které jsou součástí podlahy11.

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

Spouštění dotazů pomocí rozhraní API

Jakmile se rozhodnete pro řetězec dotazu, spustíte ho voláním rozhraní API pro dotazy.

Rozhraní API můžete volat přímo nebo můžete použít některou ze sad SDK dostupných pro Azure Digital Twins.

Následující fragment kódu znázorňuje volání sady .NET (C#) SDK z klientské aplikace:

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

Dotaz použitý v tomto volání vrátí seznam digitálních dvojčat, které výše uvedený příklad představuje s objekty BasicDigitalTwin . Návratový typ dat pro každý dotaz bude záviset na tom, jaké termíny zadáte pomocí SELECT příkazu:

• Dotazy, které začínají SELECT * FROM ... , vrátí seznam digitálních dvojčat (které lze serializovat jako BasicDigitalTwin objekty nebo jiné vlastní typy digitálních dvojčat, které jste mohli vytvořit).
• Dotazy, které začínají ve formátu SELECT <A>, <B>, <C> FROM ... , vrátí slovník s klíči <A>, <B>a <C>.
• Další formáty SELECT příkazů lze vytvořit tak, aby vracely vlastní data. Můžete zvážit vytvoření vlastních tříd pro zpracování přizpůsobených sad výsledků.

Dotaz se stránkováním

Volání dotazů podporují stránkování. Tady je úplný příklad použití BasicDigitalTwin jako typu výsledku dotazu se zpracováním chyb a stránkováním:

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;
}

Další kroky

Přečtěte si další informace o rozhraních API a sadách SDK služby Azure Digital Twins, včetně rozhraní API pro dotazy, které se používá ke spouštění dotazů z tohoto článku.