Come usare l'API REST IoT Central per eseguire query sui dispositivi

L'API REST di IoT Central consente di sviluppare applicazioni client integrate con le applicazioni IoT Central. È possibile usare l'API REST per eseguire query sui dispositivi nell'applicazione IoT Central. Di seguito sono riportati esempi di come usare l'API REST di query:

• Ottenere gli ultimi 10 valori di telemetria segnalati da un dispositivo.
• Trovare tutti i dispositivi che si trovano in uno stato di errore e hanno firmware obsoleto.
• Tendenze dei dati di telemetria dai dispositivi, mediamente in finestre di 10 minuti.
• Ottenere la versione corrente del firmware di tutti i dispositivi termostato.

Questo articolo descrive come usare l'API /query per eseguire query sui dispositivi.

Un dispositivo può raggruppare le proprietà, i dati di telemetria e i comandi supportati in componenti e moduli.

Ogni chiamata API REST di IoT Central richiede un'intestazione di autorizzazione. Per altre informazioni, vedere Come autenticare e autorizzare le chiamate API REST IoT Central.

Per la documentazione di riferimento per l'API REST di IoT Central, vedere Informazioni di riferimento sull'API REST di Azure IoT Central.

Per informazioni su come eseguire query sui dispositivi usando l'interfaccia utente di IoT Central, vedere Come usare Esplora dati per analizzare i dati dei dispositivi.

Eseguire una query

Usare la richiesta seguente per eseguire una query:

POST https://{your app subdomain}.azureiotcentral.com/api/query?api-version=2022-10-31-preview

La query si trova nel corpo della richiesta e ha un aspetto simile all'esempio seguente:

{
  "query": "SELECT $id, $ts, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D)"
}

Il dtmi:eclipsethreadx:devkit:hlby5jgib2o valore nella FROM clausola è un ID modello di dispositivo. Per trovare un ID modello di dispositivo, passare alla pagina Dispositivi nell'applicazione IoT Central e passare il puntatore del mouse su un dispositivo che usa il modello. La scheda include l'ID modello di dispositivo:

La risposta include dati di telemetria da più dispositivi che condividono lo stesso modello di dispositivo. La risposta a questa richiesta è simile all'esempio seguente:

{
  "results": [
    {
      "$id": "sample-003",
      "$ts": "2021-09-10T12:59:52.015Z",
      "temperature": 47.632160152311016,
      "humidity": 49.726422005390816
    },
    {
      "$id": "sample-001",
      "$ts": "2021-09-10T13:01:34.286Z",
      "temperature": 58.898120617808495,
      "humidity": 44.66125772328022
    },
    {
      "$id": "sample-001",
      "$ts": "2021-09-10T13:04:04.96Z",
      "temperature": 52.79601469228174,
      "humidity": 71.5067230188416
    },
    {
      "$id": "sample-002",
      "$ts": "2021-09-10T13:04:36.877Z",
      "temperature": 49.610062789623264,
      "humidity": 52.78538601804491
    }
  ]
}

Sintassi

La sintassi della query è simile alla sintassi SQL ed è costituita dalle clausole seguenti:

• SELECT è obbligatorio e definisce i dati da recuperare, ad esempio i valori di telemetria del dispositivo.
• FROM è obbligatorio e identifica il tipo di dispositivo su cui si sta eseguendo una query. Questa clausola specifica l'ID modello di dispositivo.
• WHERE è facoltativo e consente di filtrare i risultati.
• ORDER BY è facoltativo e consente di ordinare i risultati.
• GROUP BY è facoltativo e consente di aggregare i risultati.

Le sezioni seguenti descrivono queste clausole in modo più dettagliato.

Clausola SELECT

La SELECT clausola elenca i valori dei dati da includere nell'output della query e può includere gli elementi seguenti:

• Telemetria. Usare i nomi di telemetria del modello di dispositivo.
• $id. ID del dispositivo.
• $provisioned. Valore booleano che indica se è ancora stato effettuato il provisioning del dispositivo.
• $simulated. Valore booleano che indica se il dispositivo è un dispositivo simulato.
• $ts. Timestamp associato a un valore di telemetria.

Se il modello di dispositivo usa componenti, si fa riferimento ai dati di telemetria definiti nel componente come indicato di seguito:

{
  "query": "SELECT ComponentName.TelemetryName FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o"
}

È possibile trovare il nome del componente nel modello di dispositivo:

Nella clausola si applicano SELECT i limiti seguenti:

• Non esiste alcun operatore con caratteri jolly.
• Non è possibile avere più di 15 elementi nell'elenco di selezione.
• Una query restituisce un massimo di 10.000 record.

Alias

Usare la AS parola chiave per definire un alias per un elemento nella SELECT clausola . L'alias viene usato nell'output della query. È anche possibile usarlo altrove nella query. Ad esempio:

{
  "query": "SELECT $id as ID, $ts as timestamp, temperature as t, pressure as p FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D) AND t > 0 AND p > 50"
}

Il risultato è simile all'output seguente:

{
  "results": [
    {
      "ID": "sample-002",
      "timestamp": "2021-09-10T11:40:29.188Z",
      "t": 40.20355053736378,
      "p": 79.26806508746755
    },
    {
      "ID": "sample-001",
      "timestamp": "2021-09-10T11:43:42.61Z",
      "t": 68.03536237975348,
      "p": 58.33517075380311
    }
  ]
}

TOP

TOP Usare per limitare il numero di risultati restituiti dalla query. Ad esempio, la query seguente restituisce i primi 10 risultati:

{
    "query": "SELECT TOP 10 $id as ID, $ts as timestamp, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o"
}

Se non si usa TOP, la query restituisce un massimo di 10.000 risultati.

Per ordinare i risultati prima TOP di limitare il numero di risultati, usare ORDER BY.

Clausola FROM

La FROM clausola deve contenere un ID modello di dispositivo. La FROM clausola specifica il tipo di dispositivo su cui si sta eseguendo una query.

Per trovare un ID modello di dispositivo, passare alla pagina Dispositivi nell'applicazione IoT Central e passare il puntatore del mouse su un dispositivo che usa il modello. La scheda include l'ID modello di dispositivo:

È anche possibile usare la chiamata all'API REST Devices - Get per ottenere l'ID modello di dispositivo per un dispositivo.

Clausola WHERE

La WHERE clausola consente di usare valori e finestre temporali per filtrare i risultati:

Intervalli di tempo

Per ottenere i dati di telemetria ricevuti dall'applicazione all'interno di un intervallo di tempo specificato, usare WITHIN_WINDOW come parte della WHERE clausola . Ad esempio, per recuperare i dati di telemetria relativi a temperatura e umidità per l'ultimo giorno, usare la query seguente:

{
  "query": "SELECT $id, $ts, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D)"
}

Il valore dell'intervallo di tempo usa il formato durata ISO 8601. La tabella seguente include alcuni esempi:

Confronti di valori

È possibile ottenere dati di telemetria in base a valori specifici. Ad esempio, la query seguente restituisce tutti i messaggi in cui la temperatura è maggiore di zero, la pressione è maggiore di 50 e l'ID dispositivo è uno dei campioni-002 e sample-003:

{
  "query": "SELECT $id, $ts, temperature AS t, pressure AS p FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D) AND t > 0 AND p > 50 AND $id IN ['sample-002', 'sample-003']"
}

Sono supportati gli operatori seguenti:

• Operatori logici AND e OR.
• Operatori =di confronto , , !=<>, >=, <=, <>, e .IN

Nella clausola si applicano WHERE i limiti seguenti:

• È possibile usare un massimo di 10 operatori in una singola query.
• In una query la WHERE clausola può contenere solo i dati di telemetria e i filtri dei metadati del dispositivo.
• In una query è possibile recuperare fino a 10.000 record.

Aggregazioni e clausola GROUP BY

Le funzioni di aggregazione consentono di calcolare valori come media, massima e minima sui dati di telemetria all'interno di un intervallo di tempo. Ad esempio, la query seguente calcola la temperatura media e l'umidità del dispositivo sample-001 in finestre di 10 minuti:

{
  "query": "SELECT AVG(temperature), AVG(pressure) FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D) AND $id='{{DEVICE_ID}}' GROUP BY WINDOW(PT10M)"
}

I risultati sono simili all'output seguente:

{
    "results": [
        {
            "$ts": "2021-09-14T11:40:00Z",
            "avg_temperature": 49.212146114456104,
            "avg_pressure": 48.590304135023764
        },
        {
            "$ts": "2021-09-14T11:30:00Z",
            "avg_temperature": 52.44844454703927,
            "avg_pressure": 52.25973211022142
        },
        {
            "$ts": "2021-09-14T11:20:00Z",
            "avg_temperature": 50.14626272506926,
            "avg_pressure": 48.98400386898757
        }
    ]
}

Sono supportate le funzioni di aggregazione seguenti: SUM, MAXMIN, , AVGCOUNT, FIRST, e LAST.

Usare GROUP BY WINDOW per specificare le dimensioni della finestra. Se non si usa GROUP BY WINDOW, la query aggrega i dati di telemetria negli ultimi 30 giorni.

Clausola ORDER BY

La ORDER BY clausola consente di ordinare i risultati della query in base a un valore di telemetria, al timestamp o all'ID dispositivo. È possibile ordinare in ordine crescente o decrescente. Ad esempio, la query seguente restituisce prima i risultati più recenti:

{
  "query": "SELECT $id as ID, $ts as timestamp, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o ORDER BY timestamp DESC"
}

Limiti

I limiti correnti per le query sono:

• Non più di 15 elementi nell'elenco delle SELECT clausole.
• Nella clausola non sono presenti più di 10 operazioni WHERE logiche.
• La lunghezza massima di una stringa di query è di 350 caratteri.
• Non è possibile usare il carattere jolly (*) nell'elenco di SELECT clausole.
• Le query possono recuperare fino a 10.000 record.

Passaggi successivi

Dopo aver appreso come eseguire query sui dispositivi con l'API REST, un passaggio successivo consigliato consiste nell'apprendere come usare l'API REST di IoT Central per gestire utenti e ruoli.