Abfragen des Zwillingsdiagramms von Azure Digital Twins

  • Artikel

Dieser Artikel bietet Abfragebeispiele und Anleitungen zur Verwendung der Azure Digital Twins-Abfragesprache zum Abfragen von Informationen aus Ihrem Zwillingsgraphen. (Eine Einführung in die Abfragesprache finden Sie unter Abfragesprache.)

Der vorliegende Artikel enthält Beispielabfragen, die die Struktur der Abfragesprache sowie gängige Abfragevorgänge für digitale Zwillinge veranschaulichen. Außerdem wird beschrieben, wie Sie Ihre Abfragen ausführen, nachdem Sie sie geschrieben haben, indem Sie die Azure Digital Twins-Abfrage-API oder ein SDK verwenden.

Hinweis

Wenn Sie die Beispielabfragen unten mit einem API- oder SDK-Aufruf ausführen, müssen Sie den Abfragetext in eine einzelne Zeile zusammenfassen.

Referenzdokumentation

Die Referenz zur Abfragesprache finden Sie unter Referenz im linken Inhaltsverzeichnis der Azure Digital Twins-Dokumentation. Über die unten stehenden Links können Sie auch direkt zu den Referenzabschnitten wechseln:

Anzeigen aller digitalen Zwillinge

Mit der folgenden grundlegenden Abfrage wird eine Liste aller digitalen Zwillinge in der Instanz zurückgegeben:

SELECT * FROM DIGITALTWINS

Abfrage nach Eigenschaft

Abrufen von digitalen Zwillingen nach Eigenschaften (einschließlich ID und Metadaten):

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

Wie in der obigen Abfrage gezeigt, wird die ID eines digitalen Zwillings mithilfe des Metadatenfelds $dtId abgefragt.

Tipp

Wenn Sie Cloud Shell verwenden, um eine Abfrage mit Metadatenfeldern auszuführen, die mit $ beginnen, müssen Sie $ mit einem umgekehrten Schrägstrich als Escapezeichen versehen, um Cloud Shell mitzuteilen, dass es sich dabei nicht um eine Variable handelt und dieses Zeichen im Abfragetext als Literal behandelt werden soll.

Sie können Zwillinge auch auf der Grundlage abrufen, ob eine bestimmte Eigenschaft definiert ist. Mit der folgenden Abfrage werden Zwillinge abgerufen, die eine definierte Location-Eigenschaft aufweisen:

SELECT *​ FROM DIGITALTWINS WHERE IS_DEFINED(Location)

Diese Abfrage kann sie dabei unterstützen, Zwillinge anhand ihrer tag-Eigenschaften abzurufen, wie unter Hinzufügen von Tags zu digitalen Zwillingen beschrieben. Mit der folgenden Abfrage werden alle Zwillinge abgerufen, die mit dem Tag red markiert wurden:

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

Sie können Zwillinge auch auf der Grundlage des Typs einer Eigenschaft abrufen. Mit der nachstehenden Abfrage werden Zwillinge abgerufen, deren Temperature-Eigenschaft eine Zahl ist:

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

Abfragezuordnungseigenschaften

Wenn eine Eigenschaft vom komplexen Typ Mapist, können Sie die Zuordnungsschlüssel und -werte wie folgt direkt in der Abfrage verwenden:

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

Wenn der Kartenschlüssel mit einem numerischen Zeichen beginnt, müssen Sie den Schlüssel in doppelte eckige Klammern ([[<mapKey>]]) umschließen, um ihn in der Abfrage zu escapen, ähnlich der Strategie zum Abfragen mit reservierten Schlüsselwörtern.

Abfrage nach Modell

Der IS_OF_MODEL-Operator kann verwendet werden, um anhand des Modells des Zwillings zu filtern.

Er berücksichtigt Vererbung und Versionsverwaltung des Modells und wird in true für einen bestimmten Zwilling ausgewertet, wenn der Zwilling eine der folgenden Bedingungen erfüllt:

  • Der Zwilling implementiert das Modell direkt, das für IS_OF_MODEL() bereitgestellt wird, und die Versionsnummer des Modells auf dem Zwilling ist größer oder gleich der Versionsnummer des bereitgestellten Modells.
  • Der Zwilling implementiert ein Modell, das das für IS_OF_MODEL() bereitgestellte Modell erweitert, und die Versionsnummer des erweiterten Modells des Zwillings ist größer oder gleich der Versionsnummer des bereitgestellten Modells.

Wenn Sie z. B. nach Zwillingen des Modells dtmi:example:widget;4 abfragen, gibt die Abfrage alle Zwillinge zurück, die auf Version 4 oder höher des Widgets-Modells basieren, sowie auch Zwillinge, die auf Version 4 oder höher von Modellen basieren, die vom Widget erben.

IS_OF_MODEL kann verschiedene Parameter annehmen, und der Rest dieses Abschnitts beschäftigt sich mit den verschiedenen Überladungsoptionen.

Die einfachste Verwendung von IS_OF_MODEL nimmt nur einen twinTypeName-Parameter entgegen: IS_OF_MODEL(twinTypeName). Hier sehen Sie eine Beispielabfrage, die in diesem Parameter einen Wert übergibt:

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

Um eine zu durchsuchende Zwillingssammlung anzugeben, wenn mehrere vorhanden sind (z. B. bei Verwendung von JOIN), fügen Sie den Parameter twinCollection hinzu: IS_OF_MODEL(twinCollection, twinTypeName). Hier ist eine Beispielabfrage, die einen Wert für diesen Parameter hinzufügt:

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

Um eine genaue Übereinstimmung zu überprüfen, fügen Sie den Parameter exact hinzu: IS_OF_MODEL(twinTypeName, exact). Hier ist eine Beispielabfrage, die einen Wert für diesen Parameter hinzufügt:

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

Sie können auch alle drei Argumente gemeinsam übergeben: IS_OF_MODEL(twinCollection, twinTypeName, exact). Nachfolgend sehen Sie eine Beispielabfrage, in der für alle drei Parameter ein Wert angegeben ist:

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

Abfragen nach Beziehung

Für Abfragen anhand der Beziehungen von digitalen Zwillingen weist die Azure Digital Twins-Abfragesprache eine besondere Syntax auf.

Beziehungen werden in der FROM-Klausel in den Abfragebereich übernommen. Anders als in „klassischen“ SQL-Sprachen sind die einzelnen Ausdrücke in dieser FROM-Klausel keine Tabelle. Stattdessen drückt die FROM-Klausel das entitätsübergreifende Durchlaufen von Beziehungen aus. Zum Durchlaufen von Beziehungen verwendet Azure Digital Twins eine benutzerdefinierte Version von JOIN.

Denken Sie daran, dass im Azure Digital Twins-Modell Beziehungen nicht unabhängig von Zwillingen vorliegen. Dies bedeutet, dass Beziehungen hier nicht unabhängig abgefragt werden können und an einen Zwilling gebunden sein müssen. Um dies zu berücksichtigen, wird das Schlüsselwort RELATED in der JOIN-Klausel verwendet, um den Satz eines bestimmten Beziehungstyps aus der Zwillingssammlung abzurufen. Die Abfrage muss dann mithilfe eines Filters in der WHERE-Klausel angeben, welche bestimmten Zwillinge in der Beziehungsabfrage verwendet werden sollen (unter Verwendung der $dtId-Werte der Zwillinge).

Die folgenden Abschnitte zeigen Beispiele dafür, wie dies aussehen kann.

Grundlegende Beziehungsabfrage

Hier sehen Sie ein Beispiel für eine beziehungsbasierte Abfrage. Mit diesem Codeausschnitt werden alle digitalen Zwillinge mit der ID-Eigenschaft ABC und alle digitalen Zwillinge, die zu diesen digitalen Zwillingen eine contains-Beziehung haben, ausgewählt.

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

Der Typ der Beziehung (im obigen Beispiel contains) wird mithilfe des Felds name der Beziehung aus der zugehörigen DTDL-Definition angegeben.

Hinweis

Der Entwickler muss dieses JOIN nicht mit einem Schlüsselwert in der WHERE-Klausel korrelieren (oder in der JOIN-Definition einen Schlüsselwert angeben). Diese Korrelation wird automatisch vom System berechnet, da die Beziehungseigenschaften die Zielentität direkt identifizieren.

Abfragen nach der Quelle oder dem Ziel einer Beziehung

Sie können die Beziehungsabfragestruktur verwenden, um einen digitalen Zwilling zu identifizieren, der die Quelle oder das Ziel einer Beziehung ist.

Sie können z. B. mit einem Quellzwilling beginnen und seinen Beziehungen folgen, um die Zielzwillinge der Beziehungen zu ermitteln. Mithilfe der nachfolgenden Beispielabfrage werden die Zielzwillinge der feeds-Beziehungen ermittelt, die aus dem Zwilling „source-twin“ stammen.

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

Sie können auch mit dem Ziel der Beziehung beginnen und die Beziehung zurückverfolgen, um den Quellzwilling zu ermitteln. Hier ist ein Beispiel für eine Abfrage, die den Quellzwilling einer feeds-Beziehung zum Zwilling „target-twin“ ermittelt.

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

Abfragen der Eigenschaften einer Beziehung

Ähnlich wie die Eigenschaften digitaler Zwillinge über DTDL beschrieben werden, können Beziehungen ebenfalls über Eigenschaften verfügen. Sie können Zwillinge auf der Grundlage der Eigenschaften ihrer Beziehungen abfragen. Die Azure Digital Twins-Abfragesprache ermöglicht das Filtern und Projizieren von Beziehungen, indem der Beziehung innerhalb der JOIN-Klausel ein Alias zugewiesen wird.

Als Beispiel sei eine servicedBy-Beziehung angenommen, die über die reportedCondition-Eigenschaft verfügt. In der nachstehenden Abfrage erhält diese Beziehung den Alias R, um auf die zugehörige Eigenschaft zu verweisen.

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

Beachten Sie im obigen Beispiel, dass reportedCondition eine Eigenschaft der servicedBy-Beziehung selbst ist, NICHT eines digitalen Zwillings, der über eine servicedBy-Beziehung verfügt.

Abfragen mit mehreren JOINs

Es werden bis zu fünf JOIN-Elemente in einer einzelnen Abfrage unterstützt. Dies ermöglicht es, mehrere Beziehungsebenen gleichzeitig zu durchlaufen.

Um Abfragen für mehrere Beziehungsebenen auszuführen, verwenden Sie eine einzelne FROM-Anweisung gefolgt von N JOIN-Anweisungen, wobei die JOIN-Anweisungen Beziehungen zum Ergebnis einer vorherigen FROM- oder JOIN-Anweisung ausdrücken.

Hier ist ein Beispiel für eine Abfrage mit mehreren Joins, die alle LEDs in den Leuchten der Räume 1 und 2 abruft.

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

Zählen von Elementen

Sie können die Anzahl von Elementen in einem Resultset mit der Select COUNT-Klausel zählen:

SELECT COUNT()
FROM DIGITALTWINS

Fügen Sie eine WHERE-Klausel hinzu, um die Anzahl von Elementen zu zählen, die ein bestimmtes Kriterium erfüllen. Im Folgenden finden Sie einige Beispiele für das Zählen mit einem angewendeten Filter basierend auf dem Typ des Zwillingsmodells (weitere Informationen zu dieser Syntax finden Sie unter Abfragen nach Modell weiter unten):

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

Sie können auch COUNT zusammen mit der JOIN-Klausel verwenden. Nachfolgend sehen Sie eine Abfrage, mit der alle LEDs in den Leuchten der Räume 1 und 2 gezählt werden:

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

Filterergebnisse: Auswählen der obersten Elemente

Mithilfe der Select TOP-Klausel können Sie die verschiedenen obersten Elemente in einer Abfrage auswählen.

SELECT TOP (5)
FROM DIGITALTWINS
WHERE ...

Filterergebnisse: Angeben eines Rückgabesatzes mit Projektionen

Wenn Sie Projektionen in der SELECT-Anweisung verwenden, können Sie auswählen, welche Spalten von einer Abfrage zurückgegeben werden. Projektion wird jetzt sowohl für primitive als auch für komplexe Eigenschaften unterstützt. Weitere Informationen zu Projektionen mit Azure Digital Twins finden Sie in der Referenzdokumentation zur SELECT-Klausel.

Die folgende Beispielabfrage verwendet eine Projektion, um Zwillinge und Beziehungen zurückzugeben. Die folgende Abfrage projiziert die Angaben für Consumer, Factory und Edge aus einem Szenario, in dem eine Factory mit der ID ABC mit dem Consumer durch eine Beziehung von Factory.customer verbunden ist und diese Beziehung als Edge dargestellt wird.

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

Sie können Projektion auch verwenden, um eine Eigenschaft eines Zwillings zurückzugeben. Die folgende Abfrage projiziert die Eigenschaft Name der Consumers, die mit der Factory mit einer ID von ABC durch eine Beziehung von Factory.customer verbunden sind.

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

Sie können Projektion auch verwenden, um eine Eigenschaft einer Beziehung zurückzugeben. Wie im vorhergehenden Beispiel projiziert die folgende Abfrage die Eigenschaft Name der Consumers, die mit der Factory mit einer ID von ABC über eine Beziehung von Factory.customer verbunden sind. Jetzt gibt sie aber auch zwei Eigenschaften dieser Beziehung zurück: prop1 und prop2. Dies geschieht durch Benennen der Beziehung Edge und Erfassen der zugehörigen Eigenschaften.

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

Sie können auch Aliase verwenden, um Abfragen mit Projektion zu vereinfachen.

Mit der folgenden Abfrage werden dieselben Vorgänge wie im vorherigen Beispiel durchgeführt, aber für die Eigenschaftsnamen werden die Aliase consumerName, first, second und factoryArea verwendet.

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'

Hier sehen Sie eine ähnliche Abfrage zum Abrufen derselben Menge wie oben, bei der aber nur die Eigenschaft Consumer.name als consumerName und die vollständige Factory als Zwilling projiziert wird.

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

Erstellen effizienter Abfragen mit dem IN-Operator

Sie können die Anzahl der erforderlichen Abfragen deutlich verringern, indem Sie ein Array aus Zwillingen erstellen und die Abfrage mit dem IN-Operator durchführen.

Stellen Sie sich beispielsweise ein Szenario vor, in dem Gebäude aus Etagen und Etagen aus Räumen bestehen. Um in einem Gebäude nach heißen Räumen zu suchen, besteht eine Möglichkeit darin, diese Schritte durchzuführen.

  1. Etagen im Gebäude basierend auf der contains-Beziehung suchen.

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

  2. Wenn Sie Räume suchen möchten, können Sie eine Abfrage mit einer Sammlung der Etagen im Gebäude (in der nachstehenden Abfrage als Floor bezeichnet) ausführen, anstatt die Etagen einzeln zu überprüfen und jeweils eine JOIN-Abfrage zum Auffinden der Räume auszuführen.

    In der Client-App:

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

    In der Abfrage:

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

Weitere zusammengesetzte Abfragebeispiele

Mithilfe von Kombinationsoperatoren können Sie jeden der oben genannten Abfragetypen kombinieren, um mehr Details in eine einzelne Abfrage einzubeziehen. Es folgen einige weitere Beispiele für zusammengesetzte Abfragen, die mehrere Zwillingsdeskriptortypen gleichzeitig abfragen.

  • Von den Geräten, über die Room 123 verfügt, geben Sie die MxChip-Geräte zurück, die die Rolle des Operators übernehmen
    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'
  • Rufen Sie Zwillinge ab, die eine Beziehung namens Contains mit einem anderen Zwilling aufweisen, der die ID id1 besitzt
    SELECT Room
FROM DIGITALTWINS Room
JOIN Thermostat RELATED Room.Contains
WHERE Thermostat.$dtId = 'id1'
  • Rufen Sie alle Räume dieses Raummodells ab, die in floor11 enthalten sind
    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')

Ausführen von Abfragen mit der API

Nachdem Sie sich für eine Abfragezeichenfolge entschieden haben, führen Sie einen Aufruf der Abfrage-API aus.

Sie können die API direkt aufrufen oder eins der SDKs verwenden, die für Azure Digital Twins verfügbar sind.

Der folgende Codeausschnitt veranschaulicht den .NET (C#) SDK-Aufruf aus einer Client-App:

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

Durch die in diesem Aufruf verwendete Abfrage wird eine Liste mit digitalen Zwillingen zurückgegeben (im obigen Beispiel durch Objekte vom Typ BasicDigitalTwin dargestellt). Der Rückgabetyp Ihrer Daten für die jeweilige Abfrage hängt von den Begriffen ab, die Sie mit der Anweisung SELECT angeben:

  • Bei Abfragen, die mit SELECT * FROM ... beginnen, wird eine Liste mit digitalen Zwillingen zurückgegeben. (Diese können als Objekte vom Typ BasicDigitalTwin oder als andere benutzerdefinierte Typen für digitale Zwillinge serialisiert werden, die Sie ggf. erstellt haben.)
  • Bei Abfragen, die im Format SELECT <A>, <B>, <C> FROM ... beginnen, wird ein Wörterbuch mit den Schlüsseln <A>, <B> und <C> zurückgegeben.
  • Andere Formate von SELECT-Anweisungen können für die Rückgabe benutzerdefinierter Daten erstellt werden. Sie können das Erstellen eigener Klassen erwägen, um benutzerdefinierte Resultsets zu verarbeiten.

Abfrage mit Paging

Abfrageaufrufe unterstützen Paging. Im Folgenden finden Sie ein vollständiges Beispiel mit Verwendung von BasicDigitalTwin als Abfrageergebnistyp mit Fehlerbehandlung und Auslagerung:

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

Nächste Schritte

Erfahren Sie mehr über die Azure Digital Twins-APIs und SDKs, einschließlich der Abfrage-API, die zum Ausführen der Abfragen in diesem Artikel verwendet wird.