Query per dispositivi e moduli gemelli dell'hub IoT

I dispositivi gemelli e i moduli gemelli possono contenere oggetti JSON arbitrari come tag e proprietà. L'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 sui dispositivi gemelli

L'hub IoT espone i dispositivi gemelli come raccolta di documenti denominata dispositivi. Ad esempio, la query più semplice recupera l'intero set di dispositivi gemelli:

SELECT * FROM devices

È 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 tag location.region è 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 usare costanti di matrice 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. L'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 .

Il raggruppamento è supportato anche. 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à di cui si preoccupano. 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é dai dispositivi, 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 analisi:

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

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 8192 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 accettare una dipendenza da lastActivityTime disponibile in Proprietà identità dispositivo per query gemelli per 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 altre informazioni su come usare gli eventi del ciclo di vita dell'hub IoT nella soluzione, vedere React to IoT Hub events by using Event Grid (React to IoT Hub Events events by using Event Grid) per attivare le azioni.

Passaggi successivi

• Comprendere le nozioni di base del linguaggio di query dell'hub IoT