Consultas para dispositivos e módulos gêmeos do Hub IoT

Dispositivos gêmeos e módulos gêmeos podem conter objetos JSON arbitrários como marcas e propriedades. O Hub IoT permite consultar dispositivos gêmeos e módulos gêmeos como um único documento JSON que contém todas as informações de gêmeos.

Aqui está um exemplo de dispositivo gêmeo do hub IoT (o módulo gêmeo seria semelhante apenas com um 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 dispositivo gêmeo

O Hub IoT expõe os dispositivos gêmeos como uma coleção de documentos chamada dispositivos. Por exemplo, a consulta mais básica recupera todo o conjunto de dispositivos gêmeos:

SELECT * FROM devices

Você pode agregar os resultados de uma consulta usando a cláusula SELECT. Por exemplo, a consulta a seguir obtém uma contagem do número total de dispositivos em um hub IoT:

SELECT COUNT() as totalNumberOfDevices FROM devices

Filtrar os resultados da consulta usando a cláusula WHERE. Por exemplo, para receber dispositivos gêmeos em que a marca location.region está definida como EUA , use a seguinte consulta:

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

Crie cláusulas WHERE complexas usando operadores boolianos e comparações aritméticas. Por exemplo, a consulta a seguir recupera dispositivos gêmeos localizados nos EUA e configurados para enviar telemetria menos de cada minuto:

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

Você também pode usar constantes de matriz com os operadores IN e NIN (não in). Por exemplo, a consulta a seguir recupera dispositivos gêmeos que relatam conectividade wi-fi ou com fio:

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

Geralmente, é necessário identificar todos os dispositivos gêmeos que contêm uma propriedade específica. O Hub IoT dá suporte à função is_defined() para essa finalidade. Por exemplo, a consulta a seguir recupera dispositivos gêmeos que definem a connectivity propriedade:

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

Consulte a seção cláusula WHERE para obter a referência completa dos recursos de filtragem.

Também há suporte para agrupamento. Por exemplo, a consulta a seguir retorna a contagem de dispositivos em cada status de configuração de telemetria:

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

Essa consulta de agrupamento retornaria um resultado semelhante ao seguinte exemplo:

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

Neste exemplo, três dispositivos relataram configuração bem-sucedida, dois ainda estão aplicando a configuração e um relatou um erro.

As consultas de projeção permitem que os desenvolvedores retornem apenas as propriedades com as quais se preocupam. Por exemplo, para recuperar o tempo da última atividade junto com a ID do dispositivo de todos os dispositivos habilitados desconectados, use a seguinte consulta:

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

O resultado dessa consulta se pareceria com o seguinte exemplo:

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

Consultas do módulo gêmeo

A consulta em módulos gêmeos é semelhante à consulta em dispositivos gêmeos, mas usando uma coleção/namespace diferente; em vez de dispositivos, você consulta devices.modules:

SELECT * FROM devices.modules

Não permitimos a junção entre os dispositivos e as coleções devices.modules. Se você quiser consultar módulos gêmeos entre dispositivos, faça isso com base em marcas. A consulta a seguir retorna todos os módulos gêmeos em todos os dispositivos com o status de verificação:

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

A consulta a seguir retorna todos os módulos gêmeos com o status de verificação, mas somente no subconjunto especificado dos dispositivos:

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

Limitações de consulta de gêmeos

Uma opção alternativa para consultas de gêmeo é consultar dispositivos gêmeos individuais por ID usando a API REST get twin. Essa API sempre retorna os valores mais recentes e tem limites de limitação mais altos. Você pode emitir a API REST diretamente ou usar a funcionalidade equivalente em um dos SDKs de Serviço do Hub IoT do Azure.

As expressões de consulta podem ter um comprimento máximo de 8.192 caracteres.

Atualmente, há suporte para comparações somente entre tipos primitivos (sem objetos), por exemplo ... WHERE properties.desired.config = properties.reported.config , só há suporte se essas propriedades tiverem valores primitivos.

É recomendável não usar uma dependência encontrada nas lastActivityTime Propriedades de Identidade do Dispositivo para Consultas Gêmeas para qualquer cenário. Esse campo não garante um medidor preciso do status do dispositivo. Em vez disso, use eventos do Ciclo de Vida do Dispositivo IoT para gerenciar o estado e as atividades do dispositivo. Mais informações sobre como usar eventos do Ciclo de Vida do Hub IoT em sua solução, visite eventos do React ao Hub IoT usando a Grade de Eventos para disparar ações.

Próximas etapas

• Entender as noções básicas da linguagem de consulta do Hub IoT