Teilen über

Abfragen für IoT Hub-Geräte- und Modul-Twins

Geräte-Zwillinge und Modul-Zwillinge können beliebige JSON-Objekte als Tags und Eigenschaften enthalten. Mit IoT Hub können Sie Geräte-Twins und Modul-Twins als einzelnes JSON-Dokument abfragen, das alle Twin-Informationen enthält.

Hier ist ein Beispiel für ioT Hub-Gerät Twin (Modul-Twin wäre ähnlich mit einem 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
        }
    }
}

Geräte-Twin-Abfragen

IoT Hub macht die Geräte twins als Dokumentsammlung verfügbar, die als Geräte bezeichnet wird. Die grundlegendste Abfrage ruft beispielsweise den gesamten Satz von Geräte twins ab:

SELECT * FROM devices

Hinweis

Azure IoT-SDKs unterstützen das Paging großer Ergebnisse.

Sie können die Ergebnisse einer Abfrage mithilfe der SELECT-Klausel aggregieren. Die folgende Abfrage ruft beispielsweise die Gesamtzahl der Geräte in einem IoT-Hub ab:

SELECT COUNT() as totalNumberOfDevices FROM devices

Filterabfrageergebnisse mithilfe der WHERE-Klausel. Um beispielsweise Geräte-Twins zu empfangen, bei denen das Tag "location.region " auf "USA " festgelegt ist, verwenden Sie die folgende Abfrage:

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

Erstellen Sie komplexe WHERE-Klauseln mithilfe boolescher Operatoren und arithmetischer Vergleiche. Die folgende Abfrage ruft beispielsweise Geräte-Zwillinge in den USA ab und konfiguriert, um Telemetrie weniger als jede Minute zu senden:

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

Sie können auch Arraykonstanten mit den Operatoren IN und NIN (nicht in) verwenden. Die folgende Abfrage ruft beispielsweise Geräte-Zwillinge ab, die entweder WLAN oder kabelgebundene Konnektivität melden:

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

Es ist häufig erforderlich, alle Geräte twins zu identifizieren, die eine bestimmte Eigenschaft enthalten. IoT Hub unterstützt die Funktion is_defined() zu diesem Zweck. Die folgende Abfrage ruft beispielsweise Geräte twins ab, die die connectivity Eigenschaft definieren:

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

Im ABSCHNITT WHERE-Klausel finden Sie den vollständigen Verweis auf die Filterfunktionen.

Die Gruppierung wird ebenfalls unterstützt. Die folgende Abfrage gibt beispielsweise die Anzahl der Geräte in jedem Telemetriekonfigurationsstatus zurück:

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

Diese Gruppierungsabfrage würde ein Ergebnis wie im folgenden Beispiel zurückgeben:

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

In diesem Beispiel meldeten drei Geräte eine erfolgreiche Konfiguration, zwei werden weiterhin auf die Konfiguration angewendet, und eine hat einen Fehler gemeldet.

Projektionsabfragen ermöglichen Entwicklern, nur die Eigenschaften zurückzugeben, die sie interessieren. Wenn Sie beispielsweise die letzte Aktivitätszeit zusammen mit der Geräte-ID aller aktivierten Geräte abrufen möchten, die getrennt sind, verwenden Sie die folgende Abfrage:

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

Das Ergebnis dieser Abfrage würde wie im folgenden Beispiel aussehen:

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

Modul-Twin-Abfragen

Das Abfragen von Modul-Twins ähnelt der Abfrage auf Geräte-Twins, aber die Verwendung einer anderen Sammlung/eines anderen Namespaces; statt von Geräten abfragen Sie von "devices.modules":

SELECT * FROM devices.modules

Die Verknüpfung zwischen geräten und geräte.modules-Sammlungen ist nicht zulässig. Wenn Sie Modul-Zwillinge auf allen Geräten abfragen möchten, verwenden Sie sie basierend auf Tags. Die folgende Abfrage gibt alle Modul-Zwillinge auf allen Geräten mit dem Scanstatus zurück:

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

Die folgende Abfrage gibt alle Modul twins mit dem Scanstatus zurück, aber nur auf der angegebenen Teilmenge der Geräte:

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

Twin-Abfragebeschränkungen

Von Bedeutung

Abfrageergebnisse sind schließlich konsistente Vorgänge und Verzögerungen von bis zu 30 Minuten sollten toleriert werden. In den meisten Fällen gibt twin query ergebnisse in der Reihenfolge von ein paar Sekunden zurück. IoT Hub sorgt bei allen Vorgängen für eine möglichst niedrige Latenz. Abhängig von den Netzwerkbedingungen und aufgrund weiterer unvorhersehbarer Faktoren kann eine maximale Wartezeit jedoch nicht garantiert werden.

Eine Alternative zu Twin-Abfragen ist das Abfragen einzelner Geräte twins nach ID mithilfe der get twin REST-API. Diese API gibt immer die neuesten Werte zurück und weist höhere Einschränkungsgrenzwerte auf. Sie können die REST-API direkt ausstellen oder die entsprechende Funktionalität in einem der Azure IoT Hub Service SDKs verwenden.

Abfrageausdrücke können maximal 8192 Zeichen lang sein.

Derzeit werden Vergleiche nur zwischen primitiven Typen (keine Objekte) unterstützt, z ... WHERE properties.desired.config = properties.reported.config . B. nur, wenn diese Eigenschaften grundtypwerte aufweisen.

Es wird empfohlen, für jedes Szenario keine Abhängigkeit lastActivityTime von den Geräteidentitätseigenschaften für Twin-Abfragen zu verwenden. Dieses Feld garantiert keine genaue Messung des Gerätestatus. Verwenden Sie stattdessen IoT Device Lifecycle-Ereignisse, um den Gerätestatus und Aktivitäten zu verwalten. Weitere Informationen zur Verwendung von IoT Hub Lifecycle-Ereignissen in Ihrer Lösung finden Sie unter React zu IoT Hub-Ereignissen, indem Sie Event Grid verwenden, um Aktionen auszulösen.

Hinweis

Vermeiden Sie annahmen über die maximale Latenz dieses Vorgangs. Weitere Informationen zum Erstellen Ihrer Lösung unter Berücksichtigung der Latenz finden Sie unter "Latenzlösungen ".

Nächste Schritte

  • Last updated on