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

gêmeos de dispositivo e gêmeos de módulo podem conter objetos JSON arbitrários como tags e propriedades. O Hub IoT permite consultar as réplicas de dispositivo e as réplicas de módulo como um único documento JSON que contém todas as informações dessas réplicas.

Aqui está um exemplo de dispositivo de hub IoT twin (módulo twin 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 gêmeas de dispositivo

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

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 réplicas de dispositivos onde a etiqueta location.region está definida como US, utilize a seguinte consulta:

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

Crie cláusulas WHERE complexas usando operadores booleanos e comparações aritméticas. Por exemplo, a consulta seguinte obtém réplicas de dispositivos localizados nos EUA e configurados para enviar telemetria com frequência inferior a um 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 gêmeos de dispositivo que relatam conectividade com ou sem fio:

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

Muitas vezes, é necessário identificar todos os gêmeos de dispositivos que contêm uma propriedade específica. O Hub IoT suporta a função is_defined() para esta finalidade. Por exemplo, a consulta a seguir recupera gêmeos de dispositivo que definem a propriedade connectivity:

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

Consulte a secção da cláusula WHERE para obter a referência completa das capacidades de filtragem.

O agrupamento também é suportado. 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"
    }
]

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 devolvam apenas as propriedades que lhes interessam. Por exemplo, para recuperar a última hora da 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 gêmeas do módulo

Consultar em gêmeos de módulo é semelhante a consultar em gêmeos de dispositivo, mas usando uma coleção/namespace diferente; Em vez de dispositivos, você consulta a partir de devices.modules:

SELECT * FROM devices.modules

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

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

A consulta a seguir retorna todos os gêmeos de módulo com o status de varredura, mas somente no subconjunto especificado de dispositivos:

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

Limitações de consultas gêmeas

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

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

Atualmente, as comparações são suportadas apenas entre tipos primitivos (sem objetos), por exemplo, ... WHERE properties.desired.config = properties.reported.config é suportada apenas se essas propriedades tiverem valores primitivos.

Recomendamos não depender lastActivityTime das encontradas em Propriedades de identidade de dispositivo para consultas gêmeas para qualquer cenário. Este campo não garante um indicador preciso do estado do dispositivo. Em vez disso, use os 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 do Ciclo de Vida do Hub IoT em sua solução, visite Reagir a eventos do Hub IoT usando a Grade de Eventos para acionar ações.

Próximos passos

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