Query per dispositivi e moduli gemelli di hub IoT

  • Articolo

I dispositivi gemelli e i moduli gemelli possono contenere oggetti JSON arbitrari come tag e proprietà. L'hub IoT consente di effettuare una query sui dispositivi e i moduli gemelli come singolo documento JSON contenente tutte le informazioni sui dispositivi e i moduli gemelli.

Ecco un dispositivo gemello dell'hub IoT di esempio (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

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

Gli SDK dell'hub IoT 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 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 meno di 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() per 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 di riferimento complete sulle 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 della telemetria:

SELECT properties.reported.telemetryConfig.status AS status,
    COUNT() AS numberOfDevices
  FROM devices
  GROUP BY properties.reported.telemetryConfig.status

Questa query di raggruppamento restituisce un risultato simile all'esempio seguente:

[
    {
        "numberOfDevices": 3,
        "status": "Success"
    },
    {
        "numberOfDevices": 2,
        "status": "Pending"
    },
    {
        "numberOfDevices": 1,
        "status": "Error"
    }
]

In questo esempio, tre dispositivi segnalano che la configurazione è riuscita, 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. 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 sui moduli gemelli

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

Il join tra i dispositivi e le raccolte devices.modules non è consentito. Per eseguire query sui moduli gemelli nei dispositivi, usare i 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 dei dispositivi gemelli

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 risultati nell'ordine di pochi secondi. L'hub IoT punta a fornire bassa latenza per tutte le operazioni. A causa delle condizioni della rete e di altri fattori imprevedibili, non può, tuttavia, garantire una certa latenza.

Un'opzione alternativa alle query con dispositivi gemelli consiste nell'eseguire query su singoli dispositivi gemelli in base all'ID usando l'API REST get gemello. 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.

I confronti sono attualmente supportati solo tra tipi primitivi (non oggetti), ad esempio ... WHERE properties.desired.config = properties.reported.config è supportato solo se tali proprietà hanno valori primitivi.

È consigliabile non eseguire una dipendenza da lastActivityTime disponibile in Proprietà identità dispositivo per query gemelle per qualsiasi scenario. Questo campo non garantisce un misuratore accurato dello stato del dispositivo. Usare invece gli eventi del ciclo di vita del dispositivo IoT per gestire lo stato e le attività del dispositivo. Per altre informazioni su come usare gli eventi hub IoT Lifecycle nella soluzione, visitare React per hub IoT eventi usando Griglia di eventi per attivare le 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 .

Passaggi successivi