Partilhar via

Consultas para dispositivos Hub IoT e módulos duplos

  • Artigo

Os dispositivos duplos e módulos duplos podem conter objetos JSON arbitrários como etiquetas e propriedades. Hub IoT permite-lhe consultar dispositivos duplos e módulos duplos como um único documento JSON que contém todas as informações de duplos.

Segue-se um exemplo de dispositivo duplo do hub IoT (o módulo duplo 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 duplo

Hub IoT expõe os dispositivos duplos como uma coleção de documentos denominada dispositivos. Por exemplo, a consulta mais básica obtém todo o conjunto de dispositivos duplos:

SELECT * FROM devices

Nota

Os SDKs do Azure IoT suportam a paginação de resultados grandes.

Pode agregar os resultados de uma consulta com a cláusula SELECT. Por exemplo, a seguinte consulta obtém uma contagem do número total de dispositivos num hub IoT:

SELECT COUNT() as totalNumberOfDevices FROM devices

Filtre os resultados da consulta com a cláusula WHERE. Por exemplo, para receber dispositivos duplos onde a etiqueta location.region está definida como E.U.A. utilize a seguinte consulta:

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

Crie cláusulas WHERE complexas com operadores booleanos e comparações aritméticas. Por exemplo, a seguinte consulta obtém dispositivos duplos 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

Também pode utilizar constantes de matriz com os operadores IN e NIN (não em). Por exemplo, a seguinte consulta obtém dispositivos duplos que reportam wi-fi ou conectividade com fios:

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

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

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

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

O agrupamento também é suportado. Por exemplo, a seguinte consulta devolve a contagem de dispositivos em cada estado de configuração de telemetria:

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

Esta consulta de agrupamento devolveria um resultado semelhante ao seguinte exemplo:

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

Neste exemplo, três dispositivos reportaram uma configuração com êxito, dois ainda estão a aplicar a configuração e um reportou um erro.

As consultas de projeção permitem que os programadores devolvam apenas as propriedades que lhes interessam. Por exemplo, para obter o último tempo de atividade juntamente com o ID do dispositivo de todos os dispositivos ativados que estão desligados, utilize a seguinte consulta:

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

O resultado dessa consulta terá o seguinte aspeto:

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

Consultas de módulo duplo

A consulta em módulos duplos é semelhante à consulta em dispositivos duplos, mas com uma coleção/espaço de nomes diferente; em vez de a partir de dispositivos, pode consultar a partir de devices.modules:

SELECT * FROM devices.modules

Não permitimos a associação entre as coleções devices e devices.modules. Se quiser consultar módulos duplos em todos os dispositivos, faça-o com base em etiquetas. A seguinte consulta devolve todos os módulos duplos em todos os dispositivos com o estado de análise:

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

A seguinte consulta devolve todos os módulos duplos com o estado de análise, mas apenas no subconjunto especificado dos dispositivos:

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

Limitações de consultas de duplos

Importante

Os resultados da consulta são eventualmente operações consistentes e os atrasos de até 30 minutos devem ser tolerados. Na maioria das instâncias, a consulta dupla devolve resultados na ordem de alguns segundos. Hub IoT se esforça para fornecer baixa latência para todas as operações. No entanto, devido às condições de rede e a outros fatores imprevisíveis, não pode garantir uma determinada latência.

Uma opção alternativa para consultas de duplos é consultar dispositivos duplos individuais por ID com a API REST get twin. Esta API devolve sempre os valores mais recentes e tem limites de limitação mais elevados. Pode emitir a API REST diretamente ou utilizar a funcionalidade equivalente num dos SDKs do Serviço Hub IoT do Azure.

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

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

Recomendamos que não assuma uma dependência do lastActivityTime encontrado nas Propriedades da Identidade do Dispositivo para Consultas Twin para qualquer cenário. Este campo não garante um medidor preciso do estado do dispositivo. Em vez disso, utilize eventos de Ciclo de Vida do Dispositivo IoT para gerir o estado e as atividades do dispositivo. Para obter mais informações sobre como utilizar Hub IoT eventos de Ciclo de Vida na sua solução, visite React para Hub IoT eventos através do Event Grid para acionar ações.

Nota

Evite fazer suposições sobre a latência máxima desta operação. Consulte Soluções de Latência para obter mais informações sobre como criar a sua solução tendo em conta a latência.

Passos seguintes