Frågor för IoT Hub-enheter och modultvillingar

Enhetstvillingar och modultvillingar kan innehålla godtyckliga JSON-objekt som både taggar och egenskaper. Med IoT Hub kan du fråga enhetstvillingar och modultvillingar som ett enda JSON-dokument som innehåller all tvillinginformation.

Här är ett exempel på en IoT Hub-enhetstvilling (modultvillingen skulle vara liknande bara med en parameter för 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
        }
    }
}

Sökfrågor för enhetstvillingar

IoT Hub gör enhetstvillingarna tillgängliga som en samling dokument med namnet enheter. Den mest grundläggande frågan hämtar till exempel hela uppsättningen enhetstvillingar:

SELECT * FROM devices

Du kan aggregera resultatet av en fråga med hjälp av SELECT-satsen. Till exempel ger följande fråga en räkning av det totala antalet enheter i en IoT-hubb:

SELECT COUNT() as totalNumberOfDevices FROM devices

Filtrera frågeresultat med hjälp av WHERE-satsen. Om du till exempel vill ta emot enhetstvillingar där taggen location.region är inställd på USA, använd följande fråga:

SELECT * FROM devices
WHERE tags.location.region = 'US'

Skapa komplexa WHERE-satser med hjälp av booleska operatorer och aritmetiska jämförelser. Följande fråga hämtar till exempel enhetstvillingar som finns i USA och som är konfigurerade för att skicka telemetri med kortare intervall än varje minut:

SELECT * FROM devices
  WHERE tags.location.region = 'US'
    AND properties.reported.telemetryConfig.sendFrequencyInSecs >= 60

Du kan också använda matriskonstanter med operatorerna IN och NIN (inte i). Följande fråga hämtar till exempel enhetstvillingar som rapporterar antingen WiFi eller kabelansluten anslutning.

SELECT * FROM devices
  WHERE properties.reported.connectivity IN ['wired', 'wifi']

Det är ofta nödvändigt att identifiera alla enhetstvillingar som innehåller en specifik egenskap. IoT Hub stöder funktionen is_defined() för detta ändamål. Följande fråga hämtar till exempel enhetstvillingar som definierar egenskapen connectivity:

SELECT * FROM devices
  WHERE is_defined(properties.reported.connectivity)

Se avsnittet WHERE-satsen för en fullständig referens för filtreringsförmågorna.

Gruppering stöds också. Följande fråga returnerar till exempel antalet enheter i varje telemetrikonfigurationsstatus:

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

Den här grupperingsfrågan returnerar ett resultat som liknar följande exempel:

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

I det här exemplet rapporterade tre enheter att konfigurationen lyckades, två tillämpar fortfarande konfigurationen och en rapporterade ett fel.

Projektionsfrågor gör det möjligt för utvecklare att endast returnera de egenskaper de bryr sig om. Om du till exempel vill hämta den senaste aktivitetstiden tillsammans med enhets-ID:t för alla aktiverade enheter som är frånkopplade använder du följande fråga:

SELECT DeviceId, LastActivityTime FROM devices WHERE status = 'enabled' AND connectionState = 'Disconnected'

Resultatet av frågan skulle se ut som i följande exempel:

[
  {
    "deviceId": "AZ3166Device",
    "lastActivityTime": "2021-05-07T00:50:38.0543092Z"
  }
]

Frågor för modultvillingar

Att frågeställa om modultvillingar liknar frågeställningen om enhetstvillingar, men använder en annan samling/namnrymd. I stället för att använda enheter, frågar du i devices.modules.

SELECT * FROM devices.modules

Vi tillåter inte koppling mellan samlingarna devices och devices.modules. Om du vill ställa frågor till modultvillingar över flera enheter gör du det baserat på taggar. Följande fråga returnerar alla modultvillingar på alla enheter med skanningsstatus:

SELECT * FROM devices.modules WHERE properties.reported.status = 'scanning'

Följande fråga returnerar alla modultvillingar med genomsökningsstatus, men endast på den angivna delmängden av enheter:

SELECT * FROM devices.modules
  WHERE properties.reported.status = 'scanning'
  AND deviceId IN ['device1', 'device2']

Begränsningar för tvillingfrågor

Ett alternativ till tvillingfrågor är att fråga enskilda enhetstvillingar efter ID med hjälp av hämta tvilling-REST API. Det här API:et returnerar alltid de senaste värdena och har högre begränsningsgränser. Du kan utfärda REST-API:et direkt eller använda motsvarande funktioner i någon av Azure IoT Hub Service SDK:er.

Frågeuttryck kan innehålla högst 8 192 tecken.

För närvarande stöds jämförelser endast mellan primitiva typer (inga objekt), till exempel ... WHERE properties.desired.config = properties.reported.config stöds endast om dessa egenskaper har primitiva värden.

Vi rekommenderar att du inte är beroende lastActivityTime av att hittas i Enhetsidentitetsegenskaper för tvillingfrågor för något scenario. Det här fältet garanterar inte en korrekt bedömning av enhetens status. Använd i stället IoT-enhetslivscykelhändelser för att hantera enhetstillstånd och aktiviteter. Mer information om hur du använder IoT Hub-livscykelhändelser i din lösning finns i Reagera på IoT Hub-händelser genom att använda Event Grid för att utlösa åtgärder.

Nästa steg

• Förstå grunderna i frågespråket IoT Hub