Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Hub IoT offre un linguaggio avanzato simile a SQL per recuperare informazioni relative ai gemelli dei dispositivi, gemelli dei moduli, job e all'instradamento dei messaggi. Questo articolo contiene:
- Introduzione alle principali funzionalità del linguaggio di query hub IoT.
- Descrizione dettagliata della lingua. Per altre informazioni sul linguaggio di query per il routing dei messaggi, vedere hub IoT sintassi delle query di routing dei messaggi.
Per esempi specifici, vedere Queries for hub IoT device and module twins o Queries for hub IoT jobs.
Nota
Alcune delle funzionalità indicate in questo articolo, come la messaggistica da cloud a dispositivo, i dispositivi gemelli e la gestione dei dispositivi, sono disponibili solo nel livello Standard dell'hub IoT. Per altre informazioni sui livelli di hub IoT di base e standard/gratuiti, vedere Scegliere il livello e le dimensioni dell'hub IoT corretti per la soluzione.
Eseguire interrogazioni Hub IoT
È possibile eseguire query sull'hub IoT direttamente nel portale di Azure.
- Accedere al portale di Azure e passare all'hub IoT.
- Selezionare Query nella sezione di Gestione dispositivi del menu di spostamento.
- Immettere la query nella casella di testo e selezionare Esegui query.
È anche possibile eseguire query all'interno delle applicazioni usando gli SDK del servizio Azure IoT e le API del servizio.
Per un esempio di codice che implementa le query per l'hub IoT, consultare la sezione Esempi di query con i kit di sviluppo software del servizio.
Per i collegamenti alle pagine di riferimento e agli esempi dell'SDK, vedere hub IoT di Azure SDK.
Nozioni di base di una query dell'hub IoT
Ogni query dell'hub IoT è costituita da una clausola SELECT e da una clausola FROM e dalle clausole facoltative WHERE e GROUP BY.
Le query vengono eseguite in una raccolta di documenti JSON, ad esempio dispositivi gemelli. La clausola FROM indica l'insieme di documenti su cui eseguire l'iterazione (dispositivi, devices.modules o devices.jobs).
Viene quindi applicato il filtro nella clausola WHERE. Con le aggregazioni, i risultati di questo passaggio vengono raggruppati come specificato nella clausola GROUP BY. Per ogni gruppo, viene generata una riga come specificato nella clausola SELECT.
SELECT <select_list>
FROM <from_specification>
[WHERE <filter_condition>]
[GROUP BY <group_specification>]
Clausola SELECT
La clausola SELECT <select_list> è necessaria in ogni query di hub IoT. Specifica i valori recuperati dalla query. Specifica i valori JSON da usare per generare nuovi oggetti JSON.
Per ogni elemento del subset filtrato (e facoltativamente raggruppato) della raccolta FROM, la fase di proiezione genera un nuovo oggetto JSON, Questo oggetto è costruito con i valori specificati nella clausola SELECT.
Ad esempio:
Restituisce tutti i valori
SELECT *Restituire proprietà specifiche
SELECT DeviceID, LastActivityTimeAggregare i risultati di una query per restituire un conteggio
SELECT COUNT() as TotalNumber
Attualmente, le clausole di selezione diverse da SELECT sono supportate solo nelle query di aggregazione nei dispositivi gemelli.
La sintassi seguente è la grammatica della clausola SELECT:
SELECT [TOP <max number>] <projection list>
<projection_list> ::=
'*'
| <projection_element> AS alias [, <projection_element> AS alias]+
<projection_element> :==
attribute_name
| <projection_element> '.' attribute_name
| <aggregate>
<aggregate> :==
count()
| avg(<projection_element>)
| sum(<projection_element>)
| min(<projection_element>)
| max(<projection_element>)
Attribute_name fa riferimento a qualsiasi proprietà del documento JSON nella raccolta FROM.
Clausola FROM
La FROM <from_specification> clausola è necessaria in ogni query dell'hub ioT. Deve essere uno dei tre valori seguenti:
- dispositivi per eseguire query sui dispositivi gemelli
- devices.modules per eseguire query sui moduli gemelli
- devices.jobs per interrogare i dettagli del lavoro per dispositivo
Ad esempio:
Recuperare tutti i dispositivi gemelli
SELECT * FROM devices
Clausola WHERE
La WHERE <filter_condition> clausola è facoltativa. e specifica una o più condizioni che i documenti JSON della raccolta FROM devono soddisfare per essere inclusi come parte del risultato. Qualsiasi documento JSON deve valutare le condizioni specificate a true per essere incluso nel risultato.
Ad esempio:
Recuperare tutti i processi destinati a un dispositivo specifico
SELECT * FROM devices.jobs WHERE devices.jobs.deviceId = 'myDeviceId'
Le condizioni consentite sono descritte nella sezione Espressioni e condizioni .
Clausola GROUP BY
La GROUP BY <group_specification> clausola è facoltativa. Questa clausola viene eseguita dopo il filtro specificato nella clausola WHERE e prima della proiezione specificata in SELECT. Raggruppa i documenti in base al valore di un attributo. Questi gruppi vengono usati per generare valori aggregati come specificato nella clausola SELECT.
Ad esempio:
Restituisce il numero di dispositivi che segnalano ogni stato di configurazione dei dati di telemetria
SELECT properties.reported.telemetryConfig.status AS status, COUNT() AS numberOfDevices FROM devices GROUP BY properties.reported.telemetryConfig.status
Attualmente la clausola GROUP BY è supportata solo quando si effettua una query sui dispositivi gemelli.
Attenzione
Il termine gruppo è attualmente considerato come una parola chiave speciale nelle query. Se si usa group come nome della proprietà, è consigliabile racchiuderlo tra parentesi doppie per evitare errori, come illustrato in questo esempio: SELECT * FROM devices WHERE tags.[[group]].name = 'some_value'.
La sintassi formale di GROUP BY è:
GROUP BY <group_by_element>
<group_by_element> :==
attribute_name
| < group_by_element > '.' attribute_name
Attribute_name fa riferimento a qualsiasi proprietà del documento JSON nella raccolta FROM.
Paginazione dei risultati delle query
Viene creata un'istanza di un oggetto query con dimensione massima di pagina minore o uguale a 100 record. Per ottenere più pagine, chiamare nextAsTwin su Node.js SDK o GetNextAsTwinAsync nel metodo SDK .NET più volte. Un oggetto query può esporre più valori Next, a seconda dell'opzione di deserializzazione richiesta dalla query. Ad esempio, un oggetto query può restituire oggetti "device twin" o "job", oppure JSON normale quando si usano le proiezioni.
Espressioni e condizioni
In generale, un'espressione:
- Restituisce un'istanza di un tipo JSON, ad esempio un valore booleano, un numero, una stringa, un array o un oggetto.
- Viene definita modificando i dati provenienti dalle costanti e dal documento JSON dei dispositivi, che usano funzioni e operatori predefiniti.
Le condizioni sono espressioni che restituiscono un valore booleano. Qualsiasi costante diversa dal valore booleano true viene considerata come false. Questa regola include null, undefined, qualsiasi istanza di oggetto o di matrice, qualsiasi stringa e il valore booleano false.
La sintassi delle espressioni è:
<expression> ::=
<constant> |
attribute_name |
<function_call> |
<expression> binary_operator <expression> |
<create_array_expression> |
'(' <expression> ')'
<function_call> ::=
<function_name> '(' expression ')'
<constant> ::=
<undefined_constant>
| <null_constant>
| <number_constant>
| <string_constant>
| <array_constant>
<undefined_constant> ::= undefined
<null_constant> ::= null
<number_constant> ::= decimal_literal | hexadecimal_literal
<string_constant> ::= string_literal
<array_constant> ::= '[' <constant> [, <constant>]+ ']'
Per informazioni sul significato di ogni simbolo nella sintassi delle espressioni, fare riferimento alla tabella seguente:
| Simbolo | Definizione |
|---|---|
| nome_attributo | Proprietà del documento JSON nella raccolta FROM. |
| operatore_binario | Operatore binario elencato nella sezione Operatori. |
| function_name | Funzioni elencate nella sezione Funzioni. |
| letterale_decimale | Numero in virgola mobile espresso in notazione decimale. |
| hexadecimal_literal | Numero espresso dalla stringa '0x' seguito da una stringa di cifre esadecimali. |
| string_literal | Stringhe Unicode rappresentate da una sequenza di zero o più caratteri Unicode o sequenze di escape. I valori letterali stringa sono racchiusi tra virgolette singole o virgolette doppie. Escape consentiti: \', \", \\, \uXXXX per i caratteri Unicode definiti da quattro cifre esadecimali. |
Operatori
Sono supportati gli operatori seguenti:
| Famiglia | Operatori |
|---|---|
| Aritmetica | +, -, *, /, % |
| Logico | E, O, NON |
| Confronto | =, !=, <, >, <=, >=, <> |
Funzioni
Quando si eseguono query su gemelli e sui lavori, l'unica funzione supportata è:
| Funzione | Descrizione |
|---|---|
| IS_DEFINED(proprietà) | Restituisce un valore booleano che indica se alla proprietà è assegnato un valore (incluso null). |
Nelle condizioni di route, sono supportate le funzioni matematiche seguenti:
| Funzione | Descrizione |
|---|---|
| Valore Assoluto (ABS)(x) | Restituisce il valore assoluto (positivo) dell'espressione numerica specificata. |
| EXP(x) | Restituisce il valore esponente dell'espressione numerica specificata (e^x). |
| POTENZA(x,y) | Restituisce il valore dell'espressione specificata alla potenza specificata (x^y). |
| SQUARE(x) | Restituisce il quadrato del valore numerico specificato. |
| CEILING(x) | Restituisce il più piccolo valore integer maggiore di o uguale all'espressione numerica specificata. |
| FLOOR(x) | Restituisce l'intero maggiore che risulta minore o uguale all'espressione numerica specificata. |
| SEGNO(x) | Restituisce il segno positivo (+1), zero (0) o negativo (-1) dell'espressione numerica specificata. |
| SQRT(x) | Restituisce la radice quadrata del valore numerico specificato. |
Nelle condizioni di route, sono supportate le seguenti funzioni di controllo del tipo e di conversione:
| Funzione | Descrizione |
|---|---|
| AS_NUMBER | Converte la stringa di input in un numero.
noop se l'input è un numero; Undefined se la stringa non rappresenta un numero. |
| IS_ARRAY | Restituisce un valore booleano che indica se il tipo di espressione specificata è una matrice. |
| IS_BOOL | Restituisce un valore booleano che indica se il tipo di espressione specificata è un valore booleano. |
| IS_DEFINED | Restituisce un valore booleano che indica se la proprietà è un valore. Questa funzione è supportata solo quando il valore è un tipo primitivo. I tipi primitivi includono string, Boolean, numeric o null. DateTime, tipi di oggetto e matrici non sono supportati. |
| IS_NULL | Restituisce un valore booleano che indica se il tipo di espressione specificata è nulla. |
| IS_NUMBER | Restituisce un valore booleano che indica se il tipo di espressione specificata è un numero. |
| IS_OBJECT | Restituisce un valore booleano che indica se il tipo di espressione specificata è un oggetto JSON. |
| IS_PRIMITIVE | Restituisce un valore booleano che indica se il tipo dell'espressione specificata è primitivo (stringa, valore booleano, numerico o null). |
| IS_STRING | Restituisce un valore booleano che indica se il tipo di espressione specificata è una stringa. |
Nelle condizioni di route, sono supportate le funzioni di stringa seguenti:
| Funzione | Descrizione |
|---|---|
| CONCAT(x, y, ...) | Restituisce una stringa che rappresenta il risultato della concatenazione di due o più valori di stringa. |
| LENGTH(x) | Restituisce il numero di caratteri dell'espressione stringa specificata. |
| LOWER(x) | Restituisce un'espressione stringa dopo la conversione di dati in caratteri maiuscoli in caratteri minuscoli. |
| UPPER(x) | Restituisce un'espressione stringa dopo aver convertito i caratteri minuscoli in caratteri maiuscoli. |
| SUBSTRING (stringa, avvio [, lunghezza]) | Restituisce parte di un'espressione stringa a partire dalla posizione in base al carattere zero specificata e continua fino alla lunghezza specificata o alla fine della stringa. |
| INDEX_OF(stringa, frammento) | Restituisce la posizione iniziale della prima occorrenza della seconda espressione stringa all'interno della prima espressione stringa specificata oppure -1 se la stringa non viene trovata. |
| STARTS_WITH(x, y) | Restituisce un valore booleano che indica se la prima espressione stringa inizia con il secondo. |
| ENDS_WITH(x, y) | Restituisce un valore booleano che indica se la prima espressione stringa termina con il secondo. |
| CONTAINS(x,y) | Restituisce un valore booleano che indica se la prima espressione stringa contiene il secondo. |
Esempi di query con gli SDK del servizio
Esempio in C#
La funzionalità di query viene esposta dall'SDK del servizio hub IoT di Azure per .NET nella classe RegistryManager.
Di seguito è riportato un esempio di query semplice:
var query = registryManager.CreateQuery("SELECT * FROM devices", 100);
while (query.HasMoreResults)
{
var page = await query.GetNextAsTwinAsync();
foreach (var twin in page)
{
// do work on twin object
}
}
L'oggetto query viene istanziato con i parametri indicati nella sezione Paginazione risultati query. Più pagine vengono recuperate chiamando più volte i GetNextAsTwinAsync metodi.
Esempio di Node. js
La funzionalità di query viene esposta dall'SDK del servizio hub IoT di Azure per Node.js nell'oggetto Registry.
Di seguito è riportato un esempio di query semplice:
var query = registry.createQuery('SELECT * FROM devices', 100);
var onResults = function(err, results) {
if (err) {
console.error('Failed to fetch the results: ' + err.message);
} else {
// Do something with the results
results.forEach(function(twin) {
console.log(twin.deviceId);
});
if (query.hasMoreResults) {
query.nextAsTwin(onResults);
}
}
};
query.nextAsTwin(onResults);
L'oggetto della query viene istanziato con i parametri indicati nella sezione Paginazione risultati query. Più pagine vengono recuperate chiamando il nextAsTwin metodo più volte.
Query per dispositivi e moduli gemelli di hub IoT
I dispositivi gemelli e i moduli gemelli possono contenere oggetti JSON arbitrari come tag e proprietà. hub IoT consente di eseguire query su dispositivi gemelli e moduli gemelli come singolo documento JSON contenente tutte le informazioni sui dispositivi gemelli.
Ecco un esempio di dispositivo gemello dell'hub IoT (il modulo gemello sarà simile a quello di un parametro per moduleId):
{
"deviceId": "myDeviceId",
"etag": "AAAAAAAAAAc=",
"status": "enabled",
"statusUpdateTime": "0001-01-01T00:00:00",
"connectionState": "Disconnected",
"lastActivityTime": "0001-01-01T00:00:00",
"cloudToDeviceMessageCount": 0,
"authenticationType": "sas",
"x509Thumbprint": {
"primaryThumbprint": null,
"secondaryThumbprint": null
},
"version": 2,
"tags": {
"location": {
"region": "US",
"plant": "Redmond43"
}
},
"properties": {
"desired": {
"telemetryConfig": {
"configId": "db00ebf5-eeeb-42be-86a1-458cccb69e57",
"sendFrequencyInSecs": 300
},
"$metadata": {
...
},
"$version": 4
},
"reported": {
"connectivity": {
"type": "cellular"
},
"telemetryConfig": {
"configId": "db00ebf5-eeeb-42be-86a1-458cccb69e57",
"sendFrequencyInSecs": 300,
"status": "Success"
},
"$metadata": {
...
},
"$version": 7
}
}
}
Query del dispositivo gemello
hub IoT espone i dispositivi gemelli come raccolta di documenti denominata devices. Ad esempio, la query più semplice recupera l'intero set di dispositivi gemelli:
SELECT * FROM devices
Nota
Azure IoT SDK supportano il paging di risultati di grandi dimensioni.
È possibile aggregare i risultati di una query usando la clausola SELECT. Ad esempio, la query seguente ottiene un conteggio del numero totale di dispositivi in un hub IoT:
SELECT COUNT() as totalNumberOfDevices FROM devices
Filtrare i risultati della query usando la clausola WHERE. Ad esempio, per ricevere dispositivi gemelli in cui il location.region tag è impostato su US , usare la query seguente:
SELECT * FROM devices
WHERE tags.location.region = 'US'
Creare clausole WHERE complesse usando operatori booleani e confronti aritmetici. Ad esempio, la query seguente recupera i dispositivi gemelli situati negli Stati Uniti e configurati per inviare dati di telemetria inferiori a ogni minuto:
SELECT * FROM devices
WHERE tags.location.region = 'US'
AND properties.reported.telemetryConfig.sendFrequencyInSecs >= 60
È anche possibile utilizzare le costanti di array con gli operatori IN e NIN (non in). Ad esempio, la query seguente recupera i dispositivi gemelli che segnalano la connettività Wi-Fi o cablata:
SELECT * FROM devices
WHERE properties.reported.connectivity IN ['wired', 'wifi']
Spesso è necessario identificare tutti i dispositivi gemelli che contengono una proprietà specifica. hub IoT supporta la funzione is_defined() a questo scopo. Ad esempio, la query seguente recupera i dispositivi gemelli che definiscono la connectivity proprietà :
SELECT * FROM devices
WHERE is_defined(properties.reported.connectivity)
Per informazioni sul riferimento completo delle funzionalità di filtro, vedere la sezione clausola WHERE .
Anche il raggruppamento è supportato. Ad esempio, la query seguente restituisce il numero di dispositivi in ogni stato di configurazione dei dati di telemetria:
SELECT properties.reported.telemetryConfig.status AS status,
COUNT() AS numberOfDevices
FROM devices
GROUP BY properties.reported.telemetryConfig.status
Questa query di raggruppamento restituirà un risultato simile all'esempio seguente:
[
{
"numberOfDevices": 3,
"status": "Success"
},
{
"numberOfDevices": 2,
"status": "Pending"
},
{
"numberOfDevices": 1,
"status": "Error"
}
]
In questo esempio tre dispositivi hanno segnalato la corretta configurazione, due stanno ancora applicando la configurazione e uno ha segnalato un errore.
Le query di proiezione consentono agli sviluppatori di restituire solo le proprietà che interessano loro. Ad esempio, per recuperare l'ora dell'ultima attività insieme all'ID dispositivo di tutti i dispositivi abilitati disconnessi, usare la query seguente:
SELECT DeviceId, LastActivityTime FROM devices WHERE status = 'enabled' AND connectionState = 'Disconnected'
Il risultato della query sarà simile all'esempio seguente:
[
{
"deviceId": "AZ3166Device",
"lastActivityTime": "2021-05-07T00:50:38.0543092Z"
}
]
Query del modulo gemello
L'esecuzione di query sui moduli gemelli è simile all'esecuzione di query sui dispositivi gemelli, ma l'uso di una raccolta/spazio dei nomi diverso; anziché da devices, eseguire una query da devices.modules:
SELECT * FROM devices.modules
Non è consentito unire i dispositivi e le raccolte devices.modules. Se si vogliono eseguire query sui moduli gemelli tra dispositivi, è possibile farlo in base ai tag. La query seguente restituisce tutti i moduli gemelli in tutti i dispositivi con lo stato di scansione.
SELECT * FROM devices.modules WHERE properties.reported.status = 'scanning'
La query seguente restituisce tutti i moduli gemelli con lo stato di analisi, ma solo nel subset specificato di dispositivi:
SELECT * FROM devices.modules
WHERE properties.reported.status = 'scanning'
AND deviceId IN ['device1', 'device2']
Limitazioni delle query gemelle
Importante
I risultati delle query sono infine operazioni coerenti e devono essere tollerati ritardi fino a 30 minuti. Nella maggior parte dei casi, la query gemella restituisce i risultati nell'ordine di pochi secondi. L'hub IoT punta a fornire bassa latenza per tutte le operazioni. Tuttavia, a causa delle condizioni della rete e di altri fattori imprevedibili, non può garantire una certa latenza.
Un'opzione alternativa alle query dei dispositivi gemelli consiste nell'eseguire query su singoli dispositivi gemelli in base all'ID usando l'API REST get twin. Questa API restituisce sempre i valori più recenti e presenta limiti di limitazione più elevati. È possibile eseguire direttamente l'API REST o usare la funzionalità equivalente in uno degli SDK del servizio hub IoT di Azure.
Le espressioni di query possono avere una lunghezza massima di 8.192 caratteri.
Attualmente, i confronti sono supportati solo tra tipi primitivi (nessun oggetto), ad esempio ... WHERE properties.desired.config = properties.reported.config è supportato solo se tali proprietà hanno valori primitivi.
È consigliabile non fare affidamento su lastActivityTime trovato nelle Proprietà di Identità del Dispositivo per le query dei gemelli in qualsiasi scenario. Questo campo non garantisce un misuratore accurato dello stato del dispositivo. Usare invece gli eventi del ciclo di vita dei dispositivi IoT per gestire lo stato e le attività del dispositivo. Per informazioni su come usare gli eventi del ciclo di vita di hub IoT nella soluzione, vedere Reagire agli eventi di hub IoT usando Event Grid per attivare azioni.
Nota
Evitare di fare ipotesi sulla latenza massima di questa operazione. Per altre informazioni su come creare la soluzione tenendo conto della latenza, vedere Soluzioni di latenza .
Query per le attività di hub IoT
Job consentono di eseguire operazioni su set di dispositivi. Ogni gemello del dispositivo contiene le informazioni dei lavori destinati a esso in una raccolta denominata jobs. hub IoT consente di eseguire query sui processi come singolo documento JSON contenente tutte le informazioni sui dispositivi gemelli.
Ecco un dispositivo gemello dell'hub IoT di esempio che fa parte di un processo denominato myJobId:
{
"deviceId": "myDeviceId",
"etag": "AAAAAAAAAAc=",
"tags": {
...
},
"properties": {
...
},
"jobs": [
{
"deviceId": "myDeviceId",
"jobId": "myJobId",
"jobType": "scheduleUpdateTwin",
"status": "completed",
"startTimeUtc": "2016-09-29T18:18:52.7418462",
"endTimeUtc": "2016-09-29T18:20:52.7418462",
"createdDateTimeUtc": "2016-09-29T18:18:56.7787107Z",
"lastUpdatedDateTimeUtc": "2016-09-29T18:18:56.8894408Z",
"outcome": {
"deviceMethodResponse": null
}
},
...
]
}
Attualmente, questa raccolta è queryabile come devices.jobs nel linguaggio di query hub IoT.
Importante
Attualmente, la proprietà jobs non viene restituita durante l'esecuzione di query sui dispositivi gemelli. Ovvero, le query che contengono FROM devices. È possibile accedere alla proprietà "jobs" direttamente con le query usando FROM devices.jobs.
Ad esempio, la query seguente restituisce tutti i processi (passati e pianificati) che influiscono su un singolo dispositivo:
SELECT * FROM devices.jobs
WHERE devices.jobs.deviceId = 'myDeviceId'
Si noti che questa query fornisce lo stato specifico del dispositivo (ed eventualmente la risposta al metodo diretto) di ogni processo restituito.
È anche possibile filtrare con condizioni booleane arbitrarie su tutte le proprietà dell'oggetto nell'insieme devices.jobs .
Ad esempio, la query seguente recupera tutti i processi di aggiornamento dei dispositivi gemelli completati creati dopo settembre 2016 per un dispositivo specifico:
SELECT * FROM devices.jobs
WHERE devices.jobs.deviceId = 'myDeviceId'
AND devices.jobs.jobType = 'scheduleUpdateTwin'
AND devices.jobs.status = 'completed'
AND devices.jobs.createdTimeUtc > '2016-09-01'
È anche possibile recuperare i risultati per dispositivo di un singolo processo.
SELECT * FROM devices.jobs
WHERE devices.jobs.jobId = 'myJobId'
Limitazioni delle query dei lavori
Le espressioni di query possono avere una lunghezza massima di 8.192 caratteri.
Attualmente, le query su devices.jobs non supportano:
- Le proiezioni, pertanto, sono possibili solo
SELECT *. - Condizioni che fanno riferimento, oltre alle proprietà dell'attività, anche al dispositivo gemello (vedere la sezione precedente).
- Aggregazioni, ad esempio count, avg e group by.
Contenuti correlati
- Informazioni sul routing dei messaggi in base alle proprietà del messaggio o al corpo del messaggio con la sintassi di query del routing dei messaggi di hub IoT.