Wykonywanie zapytań względem grafu bliźniaczej reprezentacji usługi Azure Digital Twins

Ten artykuł zawiera przykłady zapytań i instrukcje dotyczące używania języka zapytań usługi Azure Digital Twins w celu wykonywania zapytań względem grafu bliźniaczej reprezentacji w celu uzyskania informacji. (Aby zapoznać się z wprowadzeniem do języka zapytań, zobacz Język zapytań).

Artykuł zawiera przykładowe zapytania ilustrujące strukturę języka zapytań i typowe operacje zapytań dla cyfrowych reprezentacji bliźniaczych. Opisano w nim również sposób uruchamiania zapytań po ich napisaniu przy użyciu interfejsu API zapytań usługi Azure Digital Twins lub zestawu SDK.

Uwaga

Jeśli uruchamiasz poniższe przykładowe zapytania z wywołaniem interfejsu API lub zestawu SDK, musisz skondensować tekst zapytania do pojedynczego wiersza.

Dokumentacja referencyjna

Dokumentacja języka zapytań znajduje się w sekcji Dokumentacja po lewej stronie spisu treści dokumentacji usługi Azure Digital Twins. Możesz również przejść bezpośrednio do sekcji referencyjnych, korzystając z poniższych linków:

• Klauzule
  • SELECT
  • FROM
  • ZAPAŁKA
  • DOŁĄCZYĆ
  • WHERE
• Funkcje
• Operatory
• Zastrzeżone słowa kluczowe

Pokaż wszystkie cyfrowe reprezentacje bliźniacze

Oto podstawowe zapytanie, które zwróci listę wszystkich cyfrowych reprezentacji bliźniaczych w wystąpieniu:

SELECT * FROM DIGITALTWINS

Zapytanie według właściwości

Pobierz cyfrowe reprezentacje bliźniacze według właściwości (w tym identyfikatora i metadanych):

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

Jak pokazano w powyższym zapytaniu, identyfikator cyfrowej reprezentacji bliźniaczej jest odpytywane przy użyciu pola $dtIdmetadanych .

Napiwek

Jeśli używasz usługi Cloud Shell do uruchamiania zapytania z polami metadanych rozpoczynającymi się od $, należy użyć $ ukośnika odwrotnego, aby poinformować usługę Cloud Shell, że nie jest to zmienna i powinna być używana jako literał w tekście zapytania.

Można również pobrać bliźniacze reprezentacje na podstawie tego, czy określona właściwość jest zdefiniowana. Oto zapytanie, które pobiera reprezentacje bliźniacze, które mają zdefiniowaną Location właściwość:

SELECT *​ FROM DIGITALTWINS WHERE IS_DEFINED(Location)

To zapytanie może ułatwić uzyskanie bliźniaczych reprezentacji według ich tag właściwości, zgodnie z opisem w temacie Dodawanie tagów do cyfrowych reprezentacji bliźniaczych. Oto zapytanie, które pobiera wszystkie reprezentacje bliźniacze oznaczone tagiem red:

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

Można również pobrać bliźniacze reprezentacje na podstawie typu właściwości. Oto zapytanie, które pobiera reprezentacje bliźniacze, których Temperature właściwość jest liczbą:

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

Właściwości mapy zapytania

Jeśli właściwość jest typu Mapzłożonego, możesz użyć kluczy mapy i wartości bezpośrednio w zapytaniu, w następujący sposób:

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

Jeśli klucz mapy zaczyna się od znaku liczbowego, musisz opakowować klucz w podwójnych nawiasach kwadratowych ([[<mapKey>]]), aby uniknąć go w zapytaniu, podobnie jak strategia wykonywania zapytań za pomocą zastrzeżonych słów kluczowych.

Wykonywanie zapytań według modelu

Operator IS_OF_MODEL może służyć do filtrowania na podstawie modelu bliźniaczej reprezentacji.

Uwzględnia dziedziczenie i przechowywanie wersji modelu oraz ocenia true dla danej reprezentacji bliźniaczej, jeśli reprezentacja bliźniacze spełnia jeden z następujących warunków:

• Bliźniacze reprezentacje bezpośrednio implementują model dostarczony do IS_OF_MODEL()elementu , a numer wersji modelu w bliźniaczej reprezentacji bliźniaczej jest większy lub równy numerowi wersji dostarczonego modelu
• Bliźniacze reprezentacje implementują model, który rozszerza udostępniony model na IS_OF_MODEL(), a numer wersji rozszerzonej modelu bliźniaczej reprezentacji jest większy lub równy numerowi wersji dostarczonego modelu

Jeśli na przykład wykonujesz zapytanie o bliźniacze reprezentacje modelu dtmi:example:widget;4, zapytanie zwróci wszystkie reprezentacje bliźniacze na podstawie wersji 4 lub nowszej modelu widżetu, a także bliźniacze reprezentacje oparte na wersji 4 lub nowszej dowolnego modelu dziedziczonego z widżetu.

IS_OF_MODEL może przyjmować kilka różnych parametrów, a pozostała część tej sekcji jest przeznaczona dla różnych opcji przeciążenia.

Najprostszym zastosowaniem parametru IS_OF_MODEL jest tylko parametr : IS_OF_MODEL(twinTypeName).twinTypeName Oto przykład zapytania, który przekazuje wartość w tym parametrze:

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

Aby określić kolekcję bliźniaczej reprezentacji do wyszukiwania, gdy istnieje więcej niż jedna (na przykład w przypadku użycia elementu JOIN ), dodaj twinCollection parametr : IS_OF_MODEL(twinCollection, twinTypeName). Oto przykład zapytania, który dodaje wartość dla tego parametru:

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

Aby dokładnie dopasować, dodaj exact parametr : IS_OF_MODEL(twinTypeName, exact). Oto przykład zapytania, który dodaje wartość dla tego parametru:

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

Można również przekazać wszystkie trzy argumenty razem: IS_OF_MODEL(twinCollection, twinTypeName, exact). Oto przykład zapytania określający wartość dla wszystkich trzech parametrów:

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

Wykonywanie zapytań według relacji

Podczas wykonywania zapytań na podstawie relacji cyfrowych reprezentacji bliźniaczych język zapytań usługi Azure Digital Twins ma specjalną składnię.

Relacje są ściągane do zakresu zapytania w klauzuli FROM. W przeciwieństwie do "klasycznych" języków typu SQL każde wyrażenie w klauzuli FROM nie jest tabelą; klauzula FROM wyraża przechodzenie relacji między jednostkami. Aby przejść przez relacje, usługa Azure Digital Twins używa niestandardowej wersji programu JOIN.

Pamiętaj, że w przypadku możliwości modelu usługi Azure Digital Twins relacje nie istnieją niezależnie od bliźniaczych reprezentacji bliźniaczych, co oznacza, że nie można wykonywać zapytań dotyczących relacji niezależnie i muszą być powiązane z reprezentacją bliźniaczą. Aby odzwierciedlić ten fakt, słowo kluczowe RELATED jest używane w JOIN klauzuli w celu ściągnięcia zestawu relacji określonego typu pochodzącego z kolekcji bliźniaczych reprezentacji. Zapytanie musi następnie filtrować w klauzuli WHERE , aby wskazać, które określone reprezentacje bliźniacze mają być używane w zapytaniu relacji (przy użyciu wartości bliźniaczych $dtId reprezentacji).

W poniższych sekcjach przedstawiono przykłady tego, jak wygląda to.

Podstawowe zapytanie dotyczące relacji

Oto przykładowe zapytanie oparte na relacji. Ten fragment kodu wybiera wszystkie cyfrowe reprezentacje bliźniacze z właściwością IDABC, a wszystkie cyfrowe reprezentacje bliźniacze powiązane z tymi cyfrowymi reprezentacjami bliźniaczymi za pośrednictwem contains relacji.

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

Typ relacji (containsw powyższym przykładzie) jest wskazywany przy użyciu pola relacji name z definicji języka DTDL.

Uwaga

Deweloper nie musi skorelować tego JOIN z wartością klucza w klauzuli WHERE (lub określić wartość klucza w tekście z definicją JOIN ). Ta korelacja jest obliczana automatycznie przez system, ponieważ właściwości relacji same identyfikują jednostkę docelową.

Wykonywanie zapytań według źródła lub celu relacji

Możesz użyć struktury zapytań relacji, aby zidentyfikować cyfrową reprezentację bliźniaczą, która jest źródłem lub elementem docelowym relacji.

Na przykład możesz zacząć od bliźniaczej reprezentacji źródłowej i śledzić jej relacje, aby znaleźć docelowe bliźniacze reprezentacje relacji. Oto przykład zapytania, które znajduje docelowe bliźniacze reprezentacje feeds relacji pochodzących z bliźniaczej reprezentacji bliźniaczej reprezentacji bliźniaczej.

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

Możesz również rozpocząć od celu relacji i prześledzić relację z powrotem, aby znaleźć źródłową reprezentację bliźniaczą. Oto przykład zapytania, które znajduje źródłową reprezentację bliźniaczą relacji z bliźniaczą reprezentacją feeds docelową reprezentacji bliźniaczej.

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

Zapytanie o właściwości relacji

Relacje mogą mieć właściwości podobnie do sposobu, w jaki cyfrowe reprezentacje bliźniacze mają właściwości opisywane za pośrednictwem języka DTDL. Możliwe jest wykonywanie zapytań do reprezentacji bliźniaczych w oparciu o właściwości ich relacji. Język zapytań usługi Azure Digital Twins umożliwia filtrowanie i projekcję relacji przez przypisanie aliasu do relacji w klauzuli JOIN .

Rozważmy na przykład relację servicedByreportedCondition , która ma właściwość. W poniższym zapytaniu ta relacja ma alias R , aby odwołać się do jej właściwości.

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

W powyższym przykładzie zwróć uwagę na to, jak reportedCondition jest właściwością servicedBy samej relacji (NIE niektórych cyfrowych reprezentacji bliźniaczych, które mają relację servicedBy ).

Wykonywanie zapytań z wieloma numerami JOIN

W jednym zapytaniu jest obsługiwanych maksymalnie pięć JOINs, co umożliwia przechodzenie wielu poziomów relacji jednocześnie.

Aby wykonać zapytanie na wielu poziomach relacji, użyj pojedynczej FROM instrukcji, po której JOIN instrukcje N JOIN wyrażają relacje na wyniku poprzedniej FROM instrukcji lub JOIN instrukcji.

Oto przykład zapytania z wieloma sprzężeniami, które pobiera wszystkie żarówki zawarte w panelach świetlnych w pokojach 1 i 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']

Liczba elementów

Liczbę elementów w zestawie wyników można policzyć przy użyciu klauzuli Select COUNT :

SELECT COUNT()
FROM DIGITALTWINS

Dodaj klauzulę, WHERE aby zliczyć liczbę elementów spełniających określone kryteria. Poniżej przedstawiono kilka przykładów zliczania za pomocą zastosowanego filtru na podstawie typu modelu reprezentacji bliźniaczej (aby uzyskać więcej informacji na temat tej składni, zobacz Zapytanie według modelu poniżej):

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

Można również użyć COUNT klauzuli wraz z klauzulą JOIN . Oto zapytanie, które zlicza wszystkie żarówki zawarte w lekkich panelach pomieszczeń 1 i 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']

Wyniki filtrowania: wybierz najważniejsze elementy

Możesz wybrać kilka "pierwszych" elementów w zapytaniu przy użyciu klauzuli Select TOP .

SELECT TOP (5)
FROM DIGITALTWINS
WHERE ...

Wyniki filtrowania: określ zestaw zwracany z projekcjami

Korzystając z projekcji w instrukcji SELECT , możesz wybrać kolumny, które będzie zwracać zapytanie. Projekcja jest teraz obsługiwana zarówno dla właściwości pierwotnych, jak i złożonych. Aby uzyskać więcej informacji na temat projekcji w usłudze Azure Digital Twins, zobacz dokumentację referencyjną klauzuli SELECT.

Oto przykład zapytania, które używa projekcji do zwracania reprezentacji bliźniaczych i relacji. Poniższe zapytanie projektuje klienta, fabrykę i przeglądarkę Edge ze scenariusza, w którym fabryka o identyfikatorze ABC jest powiązana z konsumentem za pośrednictwem relacji Factory.customer, a ta relacja jest przedstawiana jako Edge.

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

Możesz również użyć projekcji, aby zwrócić właściwość bliźniaczej reprezentacji. Następujące zapytanie projektuje Name właściwość Konsumenci, którzy są powiązani z fabryką o identyfikatorze ABC za pośrednictwem relacji Factory.customer.

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

Możesz również użyć projekcji, aby zwrócić właściwość relacji. Podobnie jak w poprzednim przykładzie, następujące zapytanie projektuje Name właściwość Konsumenci powiązane z fabryką o identyfikatorze ABC za pośrednictwem relacji Factory.customer; ale teraz zwraca również dwie właściwości tej relacji i prop1prop2. Robi to, nazywając relację Edge i zbierając jej właściwości.

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

Możesz również użyć aliasów, aby uprościć zapytania z projekcją.

Poniższe zapytanie wykonuje te same operacje co w poprzednim przykładzie, ale aliasuje nazwy właściwości na consumerName, , firstsecondi 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'

Oto podobne zapytanie, które wykonuje zapytanie dotyczące tego samego zestawu co powyżej, ale projektuje tylko Consumer.name właściwość jako consumerName, i projektuje pełną fabrykę jako reprezentację bliźniaczą.

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

Tworzenie wydajnych zapytań za pomocą operatora IN

Możesz znacznie zmniejszyć liczbę potrzebnych zapytań, tworząc tablicę bliźniaczych reprezentacji bliźniaczych i wykonując zapytania za pomocą IN operatora .

Rozważmy na przykład scenariusz, w którym budynki zawierają podłogi i podłogi zawierające pokoje. Aby wyszukać pokoje w budynku, który jest gorący, jednym ze sposobów jest wykonanie tych kroków.

1. Znajdź podłogi w budynku w oparciu o relację contains .

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

2. Aby znaleźć pokoje, zamiast rozważać podłogi jeden po jednym i uruchomić JOIN zapytanie w celu znalezienia pomieszczeń dla każdego z nich, możesz wykonać zapytanie o kolekcję pomieszczeń w budynku (o nazwie Floor w poniższym zapytaniu).

   W aplikacji klienckiej:

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

   W zapytaniu:

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

Inne złożone przykłady zapytań

Można połączyć dowolne z powyższych typów zapytań przy użyciu operatorów kombinacji, aby uwzględnić więcej szczegółów w jednym zapytaniu. Oto kilka innych przykładów złożonych zapytań, które wysyłają zapytania dotyczące więcej niż jednego typu deskryptora bliźniaczej reprezentacji jednocześnie.

• Poza urządzeniami, które ma pokój 123, zwróć urządzenia MxChip, które pełnią rolę Operatora

  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'
  

• Pobierz reprezentacje bliźniacze, które mają relację o nazwie Contains z inną reprezentacją bliźniaczą, która ma identyfikator id1

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

• Pobierz wszystkie pokoje tego modelu pomieszczeń, które znajdują się na piętrze 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')
  

Uruchamianie zapytań za pomocą interfejsu API

Po podjęciu decyzji o ciągu zapytania należy go wykonać, wykonując wywołanie interfejsu API zapytań.

Interfejs API można wywołać bezpośrednio lub użyć jednego z zestawów SDK dostępnych dla usługi Azure Digital Twins.

Poniższy fragment kodu ilustruje wywołanie zestawu SDK platformy .NET (C#) z aplikacji klienckiej:

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

Zapytanie używane w tym wywołaniu zwraca listę cyfrowych reprezentacji bliźniaczych, które w powyższym przykładzie reprezentuje obiekty BasicDigitalTwin . Zwracany typ danych dla każdego zapytania zależy od terminów określonych za pomocą instrukcji SELECT :

• Zapytania rozpoczynające się od SELECT * FROM ... będą zwracać listę cyfrowych reprezentacji bliźniaczych (które mogą być serializowane jako BasicDigitalTwin obiekty lub inne niestandardowe typy cyfrowych reprezentacji bliźniaczych, które mogły zostać utworzone).
• Zapytania rozpoczynające się w formacie SELECT <A>, <B>, <C> FROM ... zwracają słownik z kluczami <A>, <B>i <C>.
• Inne formaty instrukcji SELECT można tworzyć w celu zwracania danych niestandardowych. Możesz rozważyć utworzenie własnych klas do obsługi dostosowanych zestawów wyników.

Wykonywanie zapytań przy użyciu stronicowania

Wywołania zapytań obsługują stronicowanie. Oto kompletny przykład użycia BasicDigitalTwin jako typu wyniku zapytania z obsługą błędów i stronicowaniem:

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

Następne kroki

Dowiedz się więcej o interfejsach API i zestawach SDK usługi Azure Digital Twins, w tym o interfejsie API zapytań używanym do uruchamiania zapytań z tego artykułu.