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í grafu dvojčat na informace. (Ú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 spouštět dotazy po jejich napsání pomocí rozhraní API pro dotazy Azure Digital Twins nebo sady SDK.

Poznámka

Pokud spouštíte níže uvedené ukázkové dotazy s voláním rozhraní API nebo sady SDK, budete muset text dotazu zhustit do jednoho řádku.

Referenční dokumentace

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

• Klauzule
  • SELECT
  • Z
  • ZÁPAS
  • PŘIPOJIT
  • KDE
• 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

Dotaz 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 používáte Cloud Shell ke spuštění dotazu s poli metadat, která začínají $na , měli byste do řídicího $ pole zadat zpětné lomítko, abyste Cloud Shell věděli, že se nejedná o proměnnou a měl by se v textu dotazu používat jako literál.

Můžete také získat dvojčata na základě toho, jestli je definovaná 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ý všechna dvojčata označí pomocí 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 klíče a hodnoty mapování přímo v dotazu, například takto:

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

Pokud klávesa mapy začíná číselným znakem, budete ho muset zabalit do dvojitých hranatých závorek ([[<mapKey>]]), aby se v dotazu uvozil, podobně jako u strategie 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.

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

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

Pokud se například dotazujete na dvojčata modelu dtmi:example:widget;4, vrátí dotaz všechna dvojčata založená na verzi 4 nebo vyšší modelu widgetu a také dvojčata založená na verzi 4 nebo vyšší z 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í metody IS_OF_MODEL přebírá pouze twinTypeName parametr: IS_OF_MODEL(twinTypeName). Tady je příklad dotazu, který předává hodnotu v tomto parametru:

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

Pokud chcete zadat kolekci dvojčat, která se má prohledávat, když je jich více (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')

Pokud chcete 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, který určuje 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, FROM ale spíše klauzule vyjadřuje procházení relací mezi entitami. Azure Digital Twins používá k procházení relací vlastní verzi nástroje JOIN.

Vzpomeňte si, že díky možnostem modelu Azure Digital Twins neexistují relace nezávisle na dvojčatech, což znamená, že se zde na relace nelze dotazovat nezávisle a musí být svázány s dvojčetem. Aby se tato skutečnost projevila, používá se klíčové slovo RELATED v JOIN klauzuli k načtení sady určitého typu relace pocházející z kolekce dvojčat. Dotaz pak musí vyfiltrovat klauzuli WHERE , aby bylo možné určit, která konkrétní dvojčata se mají použít v dotazu na relaci (pomocí hodnot dvojčat $dtId ).

Následující části obsahují příklady, 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 vlastností ABCa všechna digitální dvojčata související s ID 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 ve výše uvedeném příkladu) je označen pomocí pole relace name z definice DTDL.

Poznámka

Vývojář to nemusí korelovat JOIN s hodnotou klíče v klauzuli WHERE (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.

Dotaz podle zdroje nebo cíle relace

Strukturu dotazu na 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četem a podle jeho relací 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čat.

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, abyste našli zdrojové dvojče. Tady je příklad dotazu, který najde zdrojové dvojče feeds vztahu k cílovému dvojčeti dvojčete.

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 promítání relací přiřazením aliasu k relaci v rámci klauzule JOIN .

Představte si servicedBy například relaci, která má reportedCondition vlastnost. V následujícím dotazu je této relaci přidělen alias R pro 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'

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

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

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

Pokud chcete dotazovat 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 výsledku předchozího FROM příkazu nebo JOIN příkazu.

Tady je příklad dotazu s více spojeními, který získá všechny žárovky obsažené na světelný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

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

SELECT COUNT()
FROM DIGITALTWINS

WHERE Přidáním klauzule spočítejte počet 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čat (další informace o této syntaxi najdete v části Dotazování 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é na světelný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 filtrování: Zadejte návratovou sadu s projekcemi.

Pomocí projekcí v SELECT příkazu můžete zvolit, které sloupce dotaz vrátí. Projekce se teď podporuje pro primitivní i komplexní vlastnosti. Další informace o projekcích s využitím Azure Digital Twins najdete v referenční dokumentaci k klauzulím SELECT.

Tady je příklad dotazu, který pomocí projekce vrací dvojčata a relace. Následující dotaz promítá objekty Consumer, Factory a Edge ze scénáře, ve kterém je objekt Factory s ID ABC ve vztahu ke spotřebiteli 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 promítá Name vlastnost Příjemci, které souvisejí 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'

Můžete také použít projekci k vrácení vlastnosti relace. Stejně jako v předchozím příkladu následující dotaz promítá Name vlastnost Consumers související s objektem Factory s ID ABC prostřednictvím relace Factory.customer; ale nyní vrátí také dvě vlastnosti této relace prop1 a prop2. Provede to tak, že relaci Edge pojme a shromáždí její vlastnosti.

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 projektuje pouze Consumer.name vlastnost jako consumerNamea projektuje kompletní factory 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 potřebných dotazů 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 obsahují místnosti. Pokud chcete vyhledat místnosti v budově, které jsou horké, jedním ze způsobů je postupovat podle těchto kroků.

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

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

2. Pokud chcete najít místnosti, místo toho, abyste zvažovali jednotlivá patra a spustili JOIN dotaz k vyhledání místností pro každou z nich, můžete dotazovat s kolekcí podlah v budově (v níže uvedeném dotazu s názvem Floor).

   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í operátorů kombinace můžete zkombinovat kterýkoli z výše uvedených typů dotazů a zahrnout do jednoho dotazu více podrobností. Tady je několik dalších příkladů složených dotazů, které se dotazují na více než jeden typ dvojčete popisovače najednou.

• Ze zařízení, která má místnost 123, vraťte zařízení MxChip, která plní 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 názvem Contains s jiným dvojčetem s ID id1

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

• Získejte všechny místnosti tohoto modelu místnosti, které jsou obsaženy v podlaží 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')
  

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

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

Můžete volat rozhraní API přímo nebo 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 příkazem SELECT :

• Dotazy, které začínají SELECT * FROM ... na, 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ů je možné 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ů.

Dotazování pomocí stránkování

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.