Consultas para dispositivo e módulo gêmeo do Hub IoT

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

Este é 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

Filtre os resultados da consulta usando a cláusula WHERE. Por exemplo, para receber os dispositivos gêmeos em que a marca location.region é 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 os dispositivos gêmeos localizados nos Estados Unidos e configurados para enviar telemetria em menos de cada minuto:

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

Você 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']

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

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

Veja a seção Cláusula WHERE para encontrar a referência completa dos recursos de filtragem.

Também há suporte para o 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 exemplo a seguir:

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

Nesse exemplo, três dispositivos relataram configuração com êxito, dois ainda estão aplicando a configuração e um relatou um erro.

Consultas de projeção permitem que os desenvolvedores retornem apenas as propriedades importantes para eles. Por exemplo, para recuperar a hora da última atividade junto com a ID do dispositivo de todos os dispositivos habilitados que estão desconectados, use a seguinte consulta:

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

O resultado dessa consulta seria semelhante ao exemplo a seguir:

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

Consultas de módulo gêmeo

A consulta de módulos gêmeos é semelhante à consulta de dispositivos gêmeos, mas usando uma coleção ou um namespace diferente, ou seja, em vez de consultar usando devices, é possível consultar usando device.modules:

SELECT * FROM devices.modules

Não permitimos a união de coleções de dispositivos e módulos. Para consultar módulos gêmeos entre dispositivos, use marcas. A consulta a seguir retorna todos os módulos gêmeos em todos os dispositivos com o status de “examinando”:

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

A consulta a seguir retorna todos os módulos gêmeos com o status “examinando”, mas somente para o subconjunto especificado de dispositivos:

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

Limitações da consulta de gêmeos

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

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

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

Recomendamos não usar uma dependência de lastActivityTime encontrada nas propriedades de identidade do dispositivo para consultas de gêmeos 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. Para obter mais informações sobre como usar eventos de ciclo de vida Hub IoT em sua solução, visite Reagir aos eventos do Hub IoT usando a Grade de Eventos para disparar ações.

Próximas etapas

• Entender os conceitos básicos da linguagem de consulta do Hub IoT