Eseguire query sul grafico gemelli digitali di Azure

Questo articolo offre esempi di query e istruzioni per l'uso del linguaggio di query di Gemelli digitali di Azure per eseguire query sul grafico gemello per informazioni. Per un'introduzione al linguaggio di query, vedere Linguaggio di query.

L'articolo contiene query di esempio che illustrano la struttura del linguaggio di query e le operazioni di query comuni per gemelli digitali. Descrive anche come eseguire le query dopo averle scritte usando l'API Query gemelli digitali di Azure o un SDK.

Nota

Se si eseguono le query di esempio seguenti con una chiamata API o SDK, è necessario condensare il testo della query in una singola riga.

Documentazione di riferimento

Il riferimento al linguaggio di query è disponibile in Riferimento nel sommario sinistro per la documentazione di Gemelli digitali di Azure. È anche possibile passare direttamente alle sezioni di riferimento usando i collegamenti seguenti:

• Clausole
  • SELECT
  • FROM
  • MATCH
  • JOIN
  • WHERE
• Funzioni
• Operatori
• Parole chiave riservate

Visualizzare tutti i gemelli digitali

Ecco la query di base che restituirà un elenco di tutti i gemelli digitali nell'istanza:

SELECT * FROM DIGITALTWINS

Query in base a proprietà

Ottenere gemelli digitali in base alle proprietà (inclusi ID e metadati):

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

Come illustrato nella query precedente, viene eseguita una query sull'ID di un gemello digitale usando il campo dei metadati $dtId.

Suggerimento

Se si usa Cloud Shell per eseguire una query con campi di metadati che iniziano con $, è consigliabile eseguire l'escape $ con una barra rovesciata per consentire Cloud Shell sapere che non è una variabile e deve essere utilizzata come valore letterale nel testo della query.

È anche possibile ottenere i gemelli in base alla definizione di una determinata proprietà. Ecco una query che ottiene gemelli con una proprietà definita Location :

SELECT *​ FROM DIGITALTWINS WHERE IS_DEFINED(Location)

Questa query consente di ottenere gemelli in base alle relative tag proprietà, come descritto in Aggiungere tag ai gemelli digitali. Ecco una query che ottiene tutti i gemelli contrassegnati con red:

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

È anche possibile ottenere gemelli in base al tipo di una proprietà. Ecco una query che ottiene gemelli la cui Temperature proprietà è un numero:

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

Proprietà mappa query

Se una proprietà è del tipo Mapcomplesso , è possibile usare le chiavi e i valori della mappa direttamente nella query, come illustrato di seguito:

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

Se la chiave della mappa inizia con un carattere numerico, è necessario eseguire il wrapping della chiave in parentesi quadre doppie ([[<mapKey>]]) per eseguirne l'escape nella query, simile alla strategia per l'esecuzione di query con parole chiave riservate.

Query in base al modello

L'operatore IS_OF_MODEL può essere usato per filtrare in base al modello del gemello.

Considera l'ereditarietà e il controllo delle versioni del modello e restituisce per true un determinato gemello se il gemello soddisfa una di queste condizioni:

• Il gemello implementa direttamente il modello fornito a IS_OF_MODEL()e il numero di versione del modello nel gemello è maggiore o uguale al numero di versione del modello fornito
• Il gemello implementa un modello che estende il modello fornito a IS_OF_MODEL()e il numero di versione estesa del gemello è maggiore o uguale al numero di versione del modello fornito

Ad esempio, se si esegue una query per gemelli del modello dtmi:example:widget;4, la query restituirà tutti i gemelli in base alla versione 4 o successiva del modello di widget e anche gemelli in base alla versione 4 o successiva di tutti i modelli che ereditano dal widget.

IS_OF_MODEL può accettare diversi parametri e la parte restante di questa sezione è dedicata alle diverse opzioni di overload.

L'uso più semplice di IS_OF_MODEL accetta solo un twinTypeName parametro: IS_OF_MODEL(twinTypeName). Ecco un esempio di query che passa un valore in questo parametro:

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

Per specificare una raccolta gemella da cercare quando è presente più di una (ad esempio quando viene usato un JOIN oggetto), aggiungere il twinCollection parametro : IS_OF_MODEL(twinCollection, twinTypeName). Ecco un esempio di query che aggiunge un valore per questo parametro:

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

Per eseguire una corrispondenza esatta, aggiungere il exact parametro : IS_OF_MODEL(twinTypeName, exact). Ecco un esempio di query che aggiunge un valore per questo parametro:

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

È anche possibile passare tutti e tre gli argomenti: IS_OF_MODEL(twinCollection, twinTypeName, exact). Ecco un esempio di query che specifica un valore per tutti e tre i parametri:

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

Query in base alla relazione

Quando si esegue una query in base alle relazioni dei gemelli digitali, il linguaggio di query di Gemelli digitali di Azure presenta una sintassi speciale.

Il pull delle relazioni viene eseguito nell'ambito della query nella clausola FROM. A differenza dei linguaggi di tipo SQL "classico", ogni espressione nella FROM clausola non è una tabella. Invece, la FROM clausola esprime un attraversamento tra entità. Per attraversare le relazioni, Gemelli digitali di Azure usa una versione personalizzata di JOIN.

Si ricordi che con le funzionalità del modello di Gemelli digitali di Azure, le relazioni non esistono indipendentemente dai gemelli, ovvero che le relazioni qui non possono essere eseguite query in modo indipendente e devono essere associate a un gemello. Per riflettere questo fatto, la parola chiave RELATED viene usata nella clausola per eseguire il pull nel JOIN set di un determinato tipo di relazione proveniente dall'insieme gemello. La query deve quindi filtrare nella WHERE clausola, per indicare quali gemelli specifici usare nella query di relazione (usando i valori dei $dtId gemelli).

Le sezioni seguenti forniscono esempi di ciò che sembra.

Query di relazione di base

Ecco una query basata su relazioni di esempio. Questo frammento di codice seleziona tutti i gemelli digitali con una ID proprietà di ABCe tutti i gemelli digitali correlati a questi gemelli digitali tramite una contains relazione.

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

Il tipo della relazione (contains nell'esempio precedente) è indicato usando il campo della name relazione dalla definizione DTDL.

Nota

Lo sviluppatore non deve correlarlo JOIN con un valore chiave nella WHERE clausola (o specificare un valore chiave inline con la JOIN definizione). Questa correlazione viene calcolata automaticamente dal sistema, perché le proprietà della relazione identificano l'entità di destinazione.

Query in base all'origine o alla destinazione di una relazione

È possibile usare la struttura di query di relazione per identificare un gemello digitale che rappresenta l'origine o la destinazione di una relazione.

Ad esempio, è possibile iniziare con un gemello di origine e seguire le relative relazioni per trovare i gemelli di destinazione delle relazioni. Ecco un esempio di query che trova i gemelli di destinazione delle feeds relazioni provenienti dal gemello.

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

È anche possibile iniziare con la destinazione della relazione e tracciare nuovamente la relazione per trovare il gemello di origine. Ecco un esempio di query che trova il gemello di origine di una feeds relazione con il gemello.

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

Eseguire una query sulle proprietà di una relazione

Così come i gemelli digitali hanno proprietà descritte tramite DTDL, anche le relazioni possono avere proprietà. È possibile eseguire una query sui gemelli in base alle proprietà delle relazioni. Il linguaggio di query di Gemelli digitali di Azure consente il filtro e la proiezione delle relazioni assegnando un alias alla relazione all'interno della JOIN clausola.

Si consideri, ad esempio, una servicedBy relazione con una reportedCondition proprietà. Nella query seguente questa relazione viene assegnato un alias di R per fare riferimento alla relativa proprietà.

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

Nell'esempio servicedBy precedente si noti come reportedCondition è una proprietà della relazione stessa (NOT di un gemello digitale con una servicedBy relazione).

Eseguire query con più JOIN

Fino a cinque JOINs sono supportati in una singola query, che consente di attraversare più livelli di relazioni contemporaneamente.

Per eseguire una query su più livelli di relazioni, usare un'unica FROM istruzione seguita da istruzioni NJOIN, in cui le JOIN istruzioni esprimono le relazioni sul risultato di un'istruzione o JOIN precedenteFROM.

Ecco un esempio di query multi-join, che ottiene tutte le lampadine contenute nei pannelli di luce nelle camere 1 e 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']

Conteggio degli elementi

È possibile contare il numero di elementi in un set di risultati usando la Select COUNT clausola:

SELECT COUNT()
FROM DIGITALTWINS

Aggiungere una WHERE clausola per contare il numero di elementi che soddisfano determinati criteri. Ecco alcuni esempi di conteggio con un filtro applicato in base al tipo di modello gemello (per altre informazioni su questa sintassi, vedere Query by model seguente):

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

È anche possibile usare COUNT insieme alla JOIN clausola . Ecco una query che conta tutte le lampadine contenute nei pannelli di luce delle camere 1 e 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']

Filtra i risultati: selezionare gli elementi principali

È possibile selezionare i diversi elementi "top" in una query usando la Select TOP clausola .

SELECT TOP (5)
FROM DIGITALTWINS
WHERE ...

Risultati del filtro: specificare set restituito con proiezioni

Usando le proiezioni nell'istruzione SELECT , è possibile scegliere quali colonne restituiranno una query. La proiezione è ora supportata per le proprietà primitive e complesse. Per altre informazioni sulle proiezioni con Gemelli digitali di Azure, vedere la documentazione di riferimento sulla clausola SELECT.

Ecco un esempio di query che usa la proiezione per restituire gemelli e relazioni. La query seguente proietta Consumer, Factory e Edge da uno scenario in cui una factory con un ID di ABC è correlata al Consumer tramite una relazione di Factory.customere tale relazione viene presentata come Edge.

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

È anche possibile usare la proiezione per restituire una proprietà di un gemello. La query seguente proietta la Name proprietà dei consumer correlati alla factory con un ID di ABC tramite una relazione di Factory.customer.

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

È anche possibile usare la proiezione per restituire una proprietà di una relazione. Come nell'esempio precedente, la query seguente proietta la Name proprietà di Consumer correlati alla factory con un ID di ABC tramite una relazione di Factory.customer, ma ora restituisce anche due proprietà di tale relazione prop1 e prop2. A tale scopo, assegnare un nome alla relazione Edge e raccogliere le relative proprietà.

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

È anche possibile usare alias per semplificare le query con la proiezione.

La query seguente esegue le stesse operazioni dell'esempio precedente, ma esegue l'alias dei nomi delle proprietà in consumerName, first, seconde 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'

Ecco una query simile che esegue una query sullo stesso set di cui sopra, ma proietta solo la Consumer.name proprietà come consumerNamee proietta la factory completa come un gemello.

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

Creare query efficienti con l'operatore IN

È possibile ridurre significativamente il numero di query necessarie creando una matrice di gemelli ed eseguendo query con l'operatore IN .

Si consideri ad esempio uno scenario in cui gli edifici contengono pavimenti e pavimenti contengono stanze. Per cercare le stanze all'interno di un edificio che sono calde, un modo consiste nel seguire questi passaggi.

1. Trovare pavimenti nell'edificio in base alla contains relazione.

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

2. Per trovare le stanze, invece di considerare i piani uno per uno ed eseguire una JOIN query per trovare le stanze per ognuna, è possibile eseguire una query con una raccolta dei piani nell'edificio (denominato Floor nella query seguente).

   Nell'app client:

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

   Nella query:

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

Altri esempi di query composte

È possibile combinare uno dei tipi di query precedenti usando operatori di combinazione per includere più dettagli in una singola query. Ecco alcuni altri esempi di query composte che eseguono una query per più tipi di descrittore gemello contemporaneamente.

• Dai dispositivi che Room 123 ha, restituire i dispositivi MxChip che svolgono il ruolo di Operator

  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'
  

• Ottenere i gemelli che hanno una relazione denominata Contains con un altro gemello che ha un ID di id1

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

• Ottenere tutte le camere di questo modello di stanza che sono contenute da floor11

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

Eseguire query con l'API

Dopo aver deciso una stringa di query, eseguirla eseguendo una chiamata all'API Query.

È possibile chiamare direttamente l'API oppure usare uno degli SDK disponibili per Gemelli digitali di Azure.

Il frammento di codice seguente illustra la chiamata dell'SDK .NET (C#) da un'app client:

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

La query usata in questa chiamata restituisce un elenco di gemelli digitali, che l'esempio precedente rappresenta con oggetti BasicDigitalTwin . Il tipo restituito dei dati per ogni query dipende dai termini specificati con l'istruzione SELECT :

• Le query che iniziano con SELECT * FROM ... restituiranno un elenco di gemelli digitali (che possono essere serializzati come BasicDigitalTwin oggetti o altri tipi di gemelli digitali personalizzati che potrebbero essere stati creati).
• Le query che iniziano nel formato SELECT <A>, <B>, <C> FROM ... restituiranno un dizionario con chiavi <A>, <B>e <C>.
• È possibile creare altri formati di SELECT istruzioni per restituire dati personalizzati. È possibile creare classi personalizzate per gestire set di risultati personalizzati.

Query con paging

Le chiamate di query supportano il paging. Ecco un esempio completo che usa BasicDigitalTwin come tipo di risultato della query con gestione degli errori e paging:

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

Passaggi successivi

Altre informazioni sulle API e sugli SDK di Gemelli digitali di Azure, inclusa l'API query usata per eseguire le query di questo articolo.