Dela via

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

  • Artikel

Enhetstvillingar och modultvillingar kan innehålla godtyckliga JSON-objekt som både taggar och egenskaper. 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 likna 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
        }
    }
}

Frågor för enhetstvillingar

IoT Hub exponerar enhetstvillingarna som en dokumentsamling som kallas enheter. Den mest grundläggande frågan hämtar till exempel hela uppsättningen enhetstvillingar:

SELECT * FROM devices

Anteckning

Azure IoT SDK:er stöder växling av stora resultat.

Du kan aggregera resultatet av en fråga med hjälp av SELECT-satsen. Följande fråga hämtar till exempel ett antal 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änder du 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 konfigureras för att skicka telemetri mindre än varje minut:

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

Du kan också använda matriskonstanter med IN - och NIN-operatorerna (inte i). Följande fråga hämtar till exempel enhetstvillingar som rapporterar wi-fi 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 connectivity egenskapen:

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

I avsnittet WHERE-sats finns en fullständig referens för filtreringsfunktionerna.

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 att utvecklare bara kan returnera de egenskaper som 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åga efter modultvillingar liknar att fråga efter enhetstvillingar, men att använda en annan samling/namnrymd. i stället för från enheter frågar du från devices.modules:

SELECT * FROM devices.modules

Vi tillåter inte anslutning mellan samlingar av enheter och enheter.modules. Om du vill köra frågor mot modultvillingar mellan enheter gör du det baserat på taggar. Följande fråga returnerar alla modultvillingar på alla enheter med genomsökningsstatus:

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

Viktigt

Frågeresultat är så småningom konsekventa åtgärder och fördröjningar på upp till 30 minuter bör tolereras. I de flesta fall returnerar tvillingfrågan resultat i några sekunders ordning. IoT Hub strävar efter att ge låg svarstid för alla åtgärder. Men på grund av nätverksförhållanden och andra oförutsägbara faktorer kan det inte garantera en viss svarstid.

Ett alternativ till tvillingfrågor är att fråga enskilda enhetstvillingar efter ID med hjälp av REST-API:et get twin. 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 ha en maximal längd på 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 använder ett beroende av lastActivityTime som finns i Egenskaper för enhetsidentitet för tvillingfrågor för något scenario. Det här fältet garanterar inte en korrekt mätare av enhetsstatus. 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 React för att IoT Hub händelser med hjälp av Event Grid för att utlösa åtgärder.

Anteckning

Undvik att göra några antaganden om den maximala svarstiden för den här åtgärden. Mer information om hur du skapar din lösning med hänsyn till svarstid finns i Svarstidslösningar .

Nästa steg