Compartir vía

Consultas para dispositivos y módulos gemelos de IoT Hub

  • Artículo

Los dispositivos gemelos y los módulos gemelos pueden contener objetos JSON arbitrarios en forma de etiquetas y propiedades. IoT Hub permite consultar dispositivos gemelos y módulos gemelos como un solo documento JSON que contiene toda la información sobre ellos.

Este es un dispositivo gemelo de IoT Hub de ejemplo (el módulo gemelo sería similar, pero con un parámetro para 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
        }
    }
}

Consultas de dispositivos gemelos

IoT Hub expone los dispositivos gemelos como una colección de documentos denominada devices. Por ejemplo, la consulta más básica recupera el conjunto completo de dispositivos gemelos:

SELECT * FROM devices

Nota

Los SDK IoT de Azure admiten la paginación de resultados de gran tamaño.

Puede agregar los resultados de una consulta con la cláusula SELECT. Por ejemplo, la consulta siguiente obtiene un recuento del número total de dispositivos existentes en un centro de IoT:

SELECT COUNT() as totalNumberOfDevices FROM devices

Filtre los resultados de la consulta con la cláusula WHERE. Por ejemplo, para recibir los dispositivos gemelos en los que la etiqueta location.region se estableció en US, use la consulta siguiente:

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

Cree cláusulas WHERE complejas mediante operadores booleanos y comparaciones aritméticas. Por ejemplo, la consulta siguiente recupera los dispositivos gemelos ubicados en la región denominada "US" y que se han configurado para enviar datos de telemetría en intervalos inferiores a un minuto:

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

También puede usar constantes de matriz con los operadores IN ("en") y NIN ("no en"). Por ejemplo, la consulta siguiente recupera dispositivos gemelos que informan de conectividad WiFi o con cable:

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

A menudo, es necesario identificar todos los dispositivos gemelos que contienen una propiedad concreta. IoT Hub admite la función is_defined() para esta finalidad. Por ejemplo, la consulta siguiente recupera dispositivos gemelos que definen la propiedad connectivity:

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

Consulte la sección Cláusula WHERE para obtener la referencia completa de las funcionalidades de filtrado.

También se admite la agrupación. Por ejemplo, la consulta siguiente devuelve el número de dispositivos en cada estado de configuración de telemetría:

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

Esta consulta de agrupación devolverá un resultado similar al ejemplo siguiente:

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

En este ejemplo, puede ver que tres dispositivos notificaron una configuración correcta, dos de ellos todavía están aplicándola y uno de ellos ha notificado un error.

Las consultas de proyección permiten a los desarrolladores devolver solo las propiedades que les interesen. Por ejemplo, para recuperar la hora de la última actividad junto con el id. de dispositivo de todos los dispositivos habilitados que están desconectados, use la consulta siguiente:

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

El resultado de esa consulta sería similar al ejemplo siguiente:

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

Consultas de módulo gemelo

Las consultas en los módulos gemelos son parecidas a las consultas en los dispositivos gemelos, pero usan un espacio de nombres o colección diferentes porque, en lugar de realizar la consulta desde devices, se realiza desde devices.modules:

SELECT * FROM devices.modules

No se permite la unión entre las colecciones devices y devices.modules. Si quiere consultar módulos gemelos entre dispositivos, hágalo en función de etiquetas. La consulta siguiente devuelve todos los módulos gemelos entre todos los dispositivos con el estado de exploración:

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

La consulta siguiente devuelve todos los módulos gemelos con el estado de exploración, pero solo en el subconjunto de dispositivos especificado:

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

Limitaciones de la consulta de gemelos

Importante

Los resultados de las consultas son operaciones con coherencia final y deben tolerarse retrasos de hasta 30 minutos. En la mayoría de los casos, una consulta de gemelos devuelve resultados en pocos segundos. IoT Hub se esfuerza por proporcionar una latencia baja para todas las operaciones. Pero debido a las condiciones de la red y otros factores impredecibles no puede garantizar una determinada latencia.

Una opción alternativa a las consultas de gemelos es consultar dispositivos gemelos individuales por identificador mediante la API REST Get Twin. Esta API siempre devuelve los últimos valores y tiene límites restrictivos más altos. Puede emitir la API de REST directamente o usar la funcionalidad equivalente en uno de los SDK del servicio Azure IoT Hub.

Las expresiones de consulta pueden tener una longitud máxima de 8192 caracteres.

Actualmente, las comparaciones solo se admiten entre tipos primitivos (no objetos), por ejemplo ... WHERE properties.desired.config = properties.reported.config solo se admite si esas propiedades tienen valores primitivos.

Se recomienda no tomar una dependencia de lastActivityTime, que se encuentra en las propiedades de identidad del dispositivo, para las consultas gemelas de ningún escenario. Este campo no garantiza un medidor preciso del estado del dispositivo. En su lugar, use eventos del ciclo de vida del dispositivo IoT para administrar el estado y las actividades del dispositivo. Para obtener más información sobre cómo usar eventos del ciclo de vida de IoT Hub en la solución, consulte Reacción a eventos de IoT Hub usando Event Grid para desencadenar acciones.

Nota:

Evitar realizar suposiciones sobre la latencia máxima de esta operación. Consulte Soluciones de latencia para obtener más información sobre cómo crear la solución teniendo en cuenta la latencia.

Pasos siguientes