Como usar a API REST do IoT Central para consultar dispositivos

  • Artigo

A API REST do IoT Central permite que você desenvolva aplicativos cliente que se integram aos aplicativos do IoT Central. Você pode usar a API REST para consultar dispositivos no seu aplicativo do IoT Central. Veja exemplos de como usar a consulta da API REST:

  • Obter os 10 últimos valores de telemetria relatados por um dispositivo.
  • Localize todos os dispositivos que estão em estado de erro e estão com firmware desatualizado.
  • Tendências de telemetria de dispositivos, médias em janelas de 10 minutos.
  • Obter a versão atual do firmware de todos os dispositivos de termostato.

Este artigo descreve como usar a API /query para consultar dispositivos.

Um dispositivo pode agrupar as propriedades, a telemetria e os comandos aos quais ele dá suporte em componentes e módulos.

Cada chamada à API REST do IoT Central exige um cabeçalho de autorização. Para saber mais, confira Como autenticar e autorizar chamadas à API REST do IoT Central.

Para obter a documentação de referência da API REST do IoT Central, confira Referência da API REST do Azure IoT Central.

Dica

Você pode usar o Postman para experimentar as chamadas à API REST descritas neste artigo. Baixe a coleção do Postman do IoT Central e importe-a para o Postman. Na coleção, você precisará definir variáveis como o subdomínio do aplicativo e o token de administrador.

Para saber como consultar dispositivos usando a interface do usuário do IoT Central, confira Como usar o data explorer para analisar os dados do dispositivo.

Executar uma consulta

Use a seguinte solicitação para executar uma consulta:

POST https://{your app subdomain}.azureiotcentral.com/api/query?api-version=2022-10-31-preview

A consulta está no corpo da solicitação e é semelhante ao exemplo a seguir:

{
  "query": "SELECT $id, $ts, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D)"
}

O valor dtmi:eclipsethreadx:devkit:hlby5jgib2o na cláusula FROM é uma ID de modelo de dispositivo. Para localizar uma ID de modelo de dispositivo, navegue até a página dispositivos no aplicativo IoT Central e passe o mouse sobre um dispositivo que usa o modelo. O cartão inclui a ID do modelo de dispositivo:

Captura de tela que mostra como localizar a ID do modelo de dispositivo na URL da página.

A resposta inclui telemetria de vários dispositivos que compartilham o mesmo modelo de dispositivo. A resposta a essa solicitação é parecida com o seguinte exemplo:

{
  "results": [
    {
      "$id": "sample-003",
      "$ts": "2021-09-10T12:59:52.015Z",
      "temperature": 47.632160152311016,
      "humidity": 49.726422005390816
    },
    {
      "$id": "sample-001",
      "$ts": "2021-09-10T13:01:34.286Z",
      "temperature": 58.898120617808495,
      "humidity": 44.66125772328022
    },
    {
      "$id": "sample-001",
      "$ts": "2021-09-10T13:04:04.96Z",
      "temperature": 52.79601469228174,
      "humidity": 71.5067230188416
    },
    {
      "$id": "sample-002",
      "$ts": "2021-09-10T13:04:36.877Z",
      "temperature": 49.610062789623264,
      "humidity": 52.78538601804491
    }
  ]
}

Sintaxe

A sintaxe de consulta é semelhante à sintaxe de SQL e é composta das seguintes cláusulas:

  • SELECT é necessário e define os dados que você deseja recuperar, como os valores de telemetria do dispositivo.
  • FROM é necessário e identifica o tipo de dispositivo que você está consultando. Essa cláusula especifica a ID do modelo de dispositivo.
  • WHERE é opcional e permite filtrar os resultados.
  • ORDER BY é opcional e permite classificar os resultados.
  • GROUP BY é opcional e permite agregar resultados.

As seções a seguir descrevem essas cláusulas em mais detalhes.

Cláusula SELECT

A cláusula SELECT lista os valores de dados a serem incluídos na saída da consulta e pode incluir os seguintes itens:

  • Telemetria. Use os nomes de telemetria do modelo de dispositivo.
  • $id. A ID do dispositivo.
  • $provisioned. Um valor booliano que mostra se o dispositivo ainda está provisionado.
  • $simulated. Um valor booliano que mostra se o dispositivo é um dispositivo simulado.
  • $ts. O carimbo de data/hora associado a um valor de telemetria.

Se o modelo de dispositivo usar componentes, você referenciará a telemetria definida no componente da seguinte maneira:

{
  "query": "SELECT ComponentName.TelemetryName FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o"
}

Você pode encontrar o nome do componente no modelo de dispositivo:

Captura de tela que mostra como localizar o nome do componente.

Os seguintes limites se aplicam na cláusula SELECT:

  • Não há nenhum operador curinga.
  • Você não pode ter mais de 15 itens na lista de seleção.
  • Uma consulta retorna no máximo 10.000 registros.

Aliases

Use a palavra-chave AS para definir um alias para um item na cláusula SELECT. O alias é usado na saída da consulta. Você também pode usá-lo em outro lugar na consulta. Por exemplo:

{
  "query": "SELECT $id as ID, $ts as timestamp, temperature as t, pressure as p FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D) AND t > 0 AND p > 50"
}

Dica

Você não pode usar outro item na lista de seleção como um alias. Por exemplo, a seguinte não é permitido SELECT id, temp AS id....

O resultado se parece com o seguinte:

{
  "results": [
    {
      "ID": "sample-002",
      "timestamp": "2021-09-10T11:40:29.188Z",
      "t": 40.20355053736378,
      "p": 79.26806508746755
    },
    {
      "ID": "sample-001",
      "timestamp": "2021-09-10T11:43:42.61Z",
      "t": 68.03536237975348,
      "p": 58.33517075380311
    }
  ]
}

INÍCIO

Usar o TOP para limitar o número de resultados que a consulta retorna. Por exemplo, a consulta a seguir retorna os primeiros 10 resultados:

{
    "query": "SELECT TOP 10 $id as ID, $ts as timestamp, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o"
}

Se você não usar TOP, a consulta retornará um máximo de 10 mil resultados.

Para classificar os resultados antes TOP de limitar o número de resultados, usar classificar por.

Cláusula FROM

A cláusula FROM deve conter uma ID de modelo de dispositivo. A cláusula FROM especifica o tipo de dispositivo que você está consultando.

Para localizar uma ID de modelo de dispositivo, navegue até a página dispositivos no aplicativo IoT Central e passe o mouse sobre um dispositivo que usa o modelo. O cartão inclui a ID do modelo de dispositivo:

Captura de tela que mostra como localizar a ID do modelo de dispositivo na página de dispositivos.

Você também pode usar a chamada de API REST Devices-Get para obter a ID do modelo de dispositivo para um dispositivo.

cláusula WHERE

A cláusula WHERE permite que você use valores e janelas de tempo para filtrar os resultados:

Janelas de horas

Para obter a telemetria recebida por seu aplicativo em uma janela de tempo especifica, use WITHIN_WINDOW como parte da cláusula WHERE. Por exemplo, para recuperar a telemetria de temperatura e umidade do último dia, use a seguinte consulta:

{
  "query": "SELECT $id, $ts, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D)"
}

O valor da janela de tempo usa o formato de durações ISO 8601. A tabela a seguir inclui alguns exemplos:

Exemplo Descrição
PT10M Últimos 10 minutos
P1D Um dia atrás
P2DT12H Últimos 2 dias e 12 horas
P1W Semana passada
PT5H Últimas cinco horas
'2021-06-13T13:00:00Z/2021-06-13T15:30:00Z' Intervalo de tempo específico

Comparações de valor

Você pode obter telemetria com base em valores específicos. Por exemplo, a consulta a seguir retorna todas as mensagens em que a temperatura é maior que zero, a pressão é maior que 50 e a ID do dispositivo é um de sample-002 e sample-003:

{
  "query": "SELECT $id, $ts, temperature AS t, pressure AS p FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D) AND t > 0 AND p > 50 AND $id IN ['sample-002', 'sample-003']"
}

Há suporte para os seguintes operadores:

  • Operadores lógicos AND e OR.
  • Operadores de comparação =, !=, >, <, >=, <=, <> e IN.

Observação

O operador IN só funciona com telemetria e $id.

Os seguintes limites se aplicam na cláusula WHERE:

  • Você pode usar um máximo de 10 operadores em uma única consulta.
  • Em uma consulta, a cláusula WHERE só pode conter filtros de metadados de dispositivo e telemetria.
  • Em uma consulta, você pode recuperar até 10.000 registros.

Agregações e cláusula GROUP BY

As funções de agregação permitem calcular valores como média, máximo e mínimo em dados de telemetria dentro de uma janela de tempo. Por exemplo, a consulta a seguir calcula a temperatura média e a umidade do dispositivo sample-001 em janelas de 10 minutos:

{
  "query": "SELECT AVG(temperature), AVG(pressure) FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o WHERE WITHIN_WINDOW(P1D) AND $id='{{DEVICE_ID}}' GROUP BY WINDOW(PT10M)"
}

Os resultados são similares a saída a seguir:

{
    "results": [
        {
            "$ts": "2021-09-14T11:40:00Z",
            "avg_temperature": 49.212146114456104,
            "avg_pressure": 48.590304135023764
        },
        {
            "$ts": "2021-09-14T11:30:00Z",
            "avg_temperature": 52.44844454703927,
            "avg_pressure": 52.25973211022142
        },
        {
            "$ts": "2021-09-14T11:20:00Z",
            "avg_temperature": 50.14626272506926,
            "avg_pressure": 48.98400386898757
        }
    ]
}

Há suporte para as seguintes funções de agregação: SUM, MAX, MIN, COUNT, AVG, FIRST e LAST.

Use GROUP BY WINDOW para especificar o tamanho da janela. Se você não usar GROUP BY WINDOW, a consulta agrega a telemetria nos últimos 30 dias.

Observação

Você só pode agregar valores de telemetria.

Cláusula ORDER BY

A cláusula ORDER BY permite classificar os resultados da consulta por um valor de telemetria, o carimbo de data/hora ou a ID do dispositivo. É possível classificar em ordem crescente ou decrescente. Por exemplo, a consulta a seguir retorna primeiro os resultados mais recentes:

{
  "query": "SELECT $id as ID, $ts as timestamp, temperature, humidity FROM dtmi:eclipsethreadx:devkit:hlby5jgib2o ORDER BY timestamp DESC"
}

Dica

Combinar ORDER BY com TOP para limitar o número de resultados que a consulta retorna após a classificação.

Limites

Os limites atuais para consultas são:

  • Até 15 itens na lista de cláusulas SELECT.
  • Até 10 operações lógicas na cláusula WHERE.
  • O comprimento máximo de uma cadeia de caracteres de consulta é de 350 caracteres.
  • Não é possível usar o curinga (*) na lista de cláusulas SELECT.
  • As consultas podem recuperar até 10.000 registros.

Próximas etapas

Agora que você sabe como consultar dispositivos com a API REST, sugerimos como próxima etapa aprender Como usar a API REST do IoT Central para gerenciar usuários e funções.