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 również sposób uruchamiania zapytań po ich zapisaniu przy użyciu interfejsu API zapytań usługi Azure Digital Twins lub zestawu SDK.

Uwaga

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

Dokumentacja referencyjna

Odwołanie do języka zapytań można znaleźć 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
  • Z
  • MECZ
  • DOŁĄCZYĆ
  • GDZIE
• 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

Wykonywanie zapytań według właściwości

Pobieranie cyfrowych reprezentacji bliźniaczych 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 badany przy użyciu pola $dtIdmetadanych .

Porada

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

Można również uzyskać 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)

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

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

Właściwości mapy zapytań

Jeśli właściwość ma typ Mapzłożony , 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 owinąć klucz w podwójnych nawiasach kwadratowych ([[<mapKey>]]), aby uciec od niego w zapytaniu, podobnie jak strategia wykonywania zapytań za pomocą zarezerwowanych 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 wartość true dla danej reprezentacji bliźniaczej, jeśli bliźniacze reprezentacja spełnia jeden z następujących warunków:

• Bliźniacze reprezentacja bezpośrednio implementuje model podany w IS_OF_MODEL()usłudze , a numer wersji modelu na bliźniaczej reprezentacji jest większy lub równy numerowi wersji dostarczonego modelu
• Bliźniacze implementuje 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 wykonasz zapytanie dotyczące bliźniaczych reprezentacji modelu dtmi:example:widget;4, zapytanie zwróci wszystkie bliźniacze reprezentacje na podstawie wersji 4 lub nowszej modelu widżetu, a także bliźniacze reprezentacje na podstawie wersji 4 lub nowszej wszystkich modeli dziedziczynych z widżetu.

IS_OF_MODEL może przyjmować kilka różnych parametrów, a reszta tej sekcji jest poświęcona różnym opcjom przeciążenia.

Najprostszym użyciem 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 gdy JOIN jest używana), 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 wykonać dokładne dopasowanie, 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żesz 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 języka "klasycznego" sql-type, każde wyrażenie w FROM klauzuli nie jest tabelą, a raczej FROM klauzula wyraża przechodzenie relacji między jednostkami. Aby przechodzić przez relacje, usługa Azure Digital Twins używa niestandardowej wersji .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 bliźniaczą reprezentacją. Aby odzwierciedlić ten fakt, słowo kluczowe RELATED jest używane w JOIN klauzuli , aby ściągnąć zestaw określonej relacji pochodzącej z kolekcji bliźniaczej. Zapytanie musi następnie filtrować w klauzuli WHERE , aby wskazać, które określone bliźniacze reprezentacje 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.

Zapytanie o relację podstawową

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 bliźniaczymi reprezentacjami za pośrednictwem contains relacji.

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

Typ relacji (contains w powyższym przykładzie) jest wskazywany przy użyciu pola relacji name z definicji DTDL.

Uwaga

Deweloper nie musi korelować 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 elementu docelowego 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 relacje. 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ż zacząć od elementu docelowego relacji i śledzić relację z powrotem, aby znaleźć źródłową reprezentację bliźniaczą. Oto przykład zapytania, które znajduje źródłową reprezentację bliźniaczej relacji z bliźniaczą reprezentacją feeds docelową bliźniaczej reprezentacji.

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ę, 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

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

Aby wykonać zapytanie o wiele poziomów relacji, użyj pojedynczej FROM instrukcji, JOIN po której instrukcje N JOIN wyrażają relacje w 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 opartego na typie modelu bliźniaczej reprezentacji (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 elementów "top" w zapytaniu przy użyciu klauzuli Select TOP .

SELECT TOP (5)
FROM DIGITALTWINS
WHERE ...

Wyniki filtrowania: określ zestaw zwracany z projekcjami

Za pomocą projekcji w instrukcji SELECT można wybrać kolumny, które zwróci zapytanie. Projekcja jest teraz obsługiwana dla właściwości pierwotnych i złożonych. Aby uzyskać więcej informacji na temat projekcji za pomocą usługi Azure Digital Twins, zobacz dokumentację referencyjną klauzuli SELECT.

Oto przykład zapytania, które używa projekcji do zwracania bliźniaczych reprezentacji 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żna również użyć projekcji, aby zwrócić właściwość bliźniaczej reprezentacji. Poniższe zapytanie projektuje Name właściwość Konsumenci, którzy są powiązani z fabryką z identyfikatorem 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ązaną 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żna również użyć aliasów, aby uprościć zapytania przy użyciu projekcji.

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 w tym samym zestawie co powyżej, ale projektuje tylko Consumer.name właściwość jako consumerName, i projektuje kompletną fabrykę jako bliźniaczą reprezentację.

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ę 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, w których znajdują się 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 na contains podstawie relacji.

   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 drugim i uruchomić JOIN zapytanie w celu znalezienia pomieszczeń dla każdego z nich, można wykonać zapytanie o kolekcję podłóg w budynku (o nazwie Floor w zapytaniu poniżej).

   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 przykłady zapytań złożonych

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ą zapytanie o więcej niż jeden typ deskryptora reprezentacji bliźniaczej jednocześnie.

• Z urządzeń, 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'
  

• Pobieranie reprezentacji bliźniaczych, 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 pomieszczenia, 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 wybraniu ciągu zapytania należy wykonać go, 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 będzie zależeć od terminów określonych za pomocą instrukcji SELECT :

• Zapytania rozpoczynające się od SELECT * FROM ... funkcji 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 utworzyć w celu zwrócenia 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.