Abfragen für IoT Hub-Geräte- und -Modulzwillinge

  • Artikel

Gerätezwillinge und Modulzwillinge können beliebige JSON-Objekte als Tags und Eigenschaften enthalten. In IoT Hub können Sie Geräte- und Modulzwillinge als einzelnes JSON-Dokument abfragen, das alle Informationen zum Zwilling enthält.

Hier ist ein Beispiel für einen IoT Hub-Gerätezwilling (ein Modulzwilling wäre ähnlich, nur 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ätezwillingabfragen

IoT Hub macht die Gerätezwillinge als eine Dokumentensammlung namens Geräte verfügbar. Beispielsweise ruft die einfachste Abfrage die gesamte Menge von Gerätezwillingen ab:

SELECT * FROM devices

Hinweis

Azure IoT SDKs unterstützen die seitenweise Ausgabe von umfangreichen Ergebnissen.

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

SELECT COUNT() as totalNumberOfDevices FROM devices

Filtern Sie Abfrageergebnisse mithilfe der WHERE-Klausel. Beispielsweise können Sie mithilfe der folgenden Abfrage Gerätezwillinge erhalten, bei denen das Tag location.region auf US festgelegt ist:

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

Erstellen Sie komplexe WHERE-Klauseln mithilfe von booleschen Operatoren und arithmetischen Vergleichen. Beispielsweise ruft die folgende Abfrage Gerätezwillinge in den USA ab, die so konfiguriert wurden, dass sie Telemetriedaten seltener als jede Minute 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 (not in) verwenden. Die folgende Abfrage ruft beispielsweise Gerätezwillinge ab, die entweder WLAN- oder kabelgebundene Konnektivität melden:

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

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

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

Die vollständige Referenz zu den Filtermöglichkeiten finden Sie im Abschnitt zur WHERE-Klausel.

Gruppierung wird ebenfalls unterstützt. Mit der folgenden Abfrage beispielsweise wird die Anzahl von Geräten mit dem jeweiligen Status für die Telemetriekonfiguration zurückgegeben:

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

Diese Gruppierungsabfrage würde ein ähnliches Ergebnis wie im folgenden Beispiel zurückgegeben:

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

In diesem Beispiel meldeten drei Geräte eine erfolgreiche Konfiguration, zwei wenden die Konfiguration noch an und ein Gerät hat einen Fehler gemeldet.

Mithilfe von Projektionsabfragen können Entwickler nur die interessierenden Eigenschaften zurückgeben. Um beispielsweise den Zeitpunkt der letzten Aktivität zusammen mit der Geräte-ID aller aktivierten Geräte abzurufen, 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"
  }
]

Modulzwillingsabfragen

Das Abfragen von Modulzwillingen ähnelt dem Abfragen von Gerätezwillingen. Allerdings wird hierbei eine andere Sammlung bzw. ein anderer Namespace verwendet. Sie führen die Abfrage nicht über devices, sondern über device.modules durch:

SELECT * FROM devices.modules

Eine Verknüpfung zwischen den Sammlungen „devices“ und „devices.modules“ ist nicht zulässig. Wenn Sie Modulzwillinge geräteübergreifend abfragen möchten, müssen dazu Tags verwendet werden. Die folgende Abfrage gibt alle Modulzwillinge auf allen Geräten mit dem Scanstatus zurück:

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

Die folgende Abfrage gibt alle Modulzwillinge mit dem Scanstatus zurück, aber nur für die angegebene Teilmenge von Geräten:

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

Einschränkungen für Zwillingsabfragen

Wichtig

Abfrageergebnisse sind letztendlich konsistente Vorgänge, und Verzögerungen von bis zu 30 Minuten sollten toleriert werden. In den meisten Fällen gibt die Zwillingsabfrage Ergebnisse innerhalb von wenigen 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 Option zu Zwillingsabfragen ist das Abfragen von einzelnen Gerätezwillingen nach ID mithilfe der REST-API zum Abrufen von Zwillingen. Diese API gibt immer die aktuellen Werte zurück und weist höhere Einschränkungsgrenzwerte auf. Sie können die REST-API direkt aufrufen oder die entsprechende Funktion in einem der Azure IoT Hub-Dienst-SDKs verwenden.

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

Derzeit werden Vergleiche nur zwischen primitiven Typen (keine Objekte) unterstützt. ... WHERE properties.desired.config = properties.reported.config wird beispielsweise nur unterstützt, wenn diese Eigenschaften über primitive Werte verfügen.

Wir empfehlen, keine Abhängigkeit von „lastActivityTime“ zu nutzen, die unter „Geräteidentitätseigenschaften für Zwillingsabfragen“ für jedes beliebige Szenario aufgeführt wird. Dieses Feld garantiert keine genaue Messung des Gerätestatus. Verwenden Sie stattdessen Ereignisse des Lebenszyklus von IoT-Geräten, um den Gerätestatus und Aktivitäten zu verwalten. Weitere Informationen zur Verwendung von Ereignissen des Lebenszyklus von IoT-Geräten in Ihrer Lösung finden Sie unter Reagieren auf IoT Hub-Ereignisse mithilfe von Event Grid zum Auslösen von Aktionen.

Hinweis

Vermeiden Sie es, Annahmen zur maximalen Wartezeit dieses Vorgangs zu treffen. Weitere Informationen zum Erstellen Ihrer Lösung unter Berücksichtigung der Wartezeit finden Sie unter Latency Solutions (Lösungen bei Wartezeit).

Nächste Schritte