Como utilizar a API REST do IoT Central para consultar dispositivos

  • Artigo

A API REST do IoT Central permite desenvolver aplicativos cliente que se integram aos aplicativos do IoT Central. Você pode usar a API REST para consultar dispositivos em seu aplicativo IoT Central. A seguir estão exemplos de como você pode usar a API REST de consulta:

  • Obtenha os últimos 10 valores de telemetria relatados por um dispositivo.
  • Encontre todos os dispositivos que estão em um estado de erro e têm firmware desatualizado.
  • Tendências de telemetria dos dispositivos, em média em janelas de 10 minutos.
  • Obtenha a versão de firmware atual de todos os seus dispositivos de termostato.

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

Um dispositivo pode agrupar as propriedades, telemetria e comandos que suporta em componentes e módulos.

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

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

Gorjeta

Você pode usar o Postman para experimentar as chamadas de API REST descritas neste artigo. Faça o download da coleção IoT Central Postman 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, consulte Como usar o explorador de dados para analisar 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 se parece com o exemplo a seguir:

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

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

Captura de ecrã que mostra como encontrar o ID do modelo de dispositivo no 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 se parece com o exemplo a seguir:

{
  "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 SQL e é composta pelas 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 está a consultar. Esta cláusula especifica o ID do modelo de dispositivo.
  • WHERE é opcional e permite filtrar os resultados.
  • ORDER BY é opcional e permite-lhe ordenar os resultados.
  • GROUP BY é opcional e permite agregar resultados.

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

Cláusula SELECT

A SELECT cláusula 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. O ID do dispositivo.
  • $provisioned. Um valor booleano que mostra se o dispositivo ainda está provisionado.
  • $simulated. Um valor booleano 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 usa componentes, você faz referência à 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.

Aplicam-se os SELECT seguintes limites na cláusula:

  • Não há operador curinga.
  • Não é possível ter mais de 15 itens na lista de seleção.
  • Uma consulta retorna um máximo de 10.000 registros.

Aliases

Use a AS palavra-chave para definir um alias para um item na SELECT cláusula. 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"
}

Gorjeta

Não é possível usar outro item na lista de seleção como um alias. Por exemplo, o seguinte não é permitido SELECT id, temp AS id....

O resultado é semelhante à seguinte saída:

{
  "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

Use o TOP para limitar o número de resultados retornados pela consulta. 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 TOPo , a consulta retornará um máximo de 10.000 resultados.

Para classificar os resultados antes TOP de limitar o número de resultados, use ORDER BY.

Cláusula FROM

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

Para encontrar um ID de modelo de dispositivo, navegue até a página Dispositivos em seu aplicativo IoT Central e passe o mouse sobre um dispositivo que usa o modelo. O cartão inclui o ID do modelo do dispositivo:

Captura de ecrã que mostra como encontrar o ID do modelo de dispositivo na página de dispositivos.

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

Cláusula WHERE

A WHERE cláusula permite usar valores e janelas de tempo para filtrar os resultados:

Janelas temporais

Para obter telemetria recebida pelo seu aplicativo dentro de uma janela de tempo especificada, use WITHIN_WINDOW como parte da WHERE cláusula. 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 Description
PT10M Últimos 10 minutos
P1D Dia passado
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 valores

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 é uma das amostras-002 e amostra-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']"
}

Os seguintes operadores são suportados:

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

Nota

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

Aplicam-se os WHERE seguintes limites na cláusula:

  • Você pode usar um máximo de 10 operadores em uma única consulta.
  • Em uma consulta, a cláusula só pode conter filtros de telemetria WHERE e metadados do dispositivo.
  • 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 se parecem com a seguinte saída:

{
    "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
        }
    ]
}

As seguintes funções de agregação são suportadas: SUM, MAX, MIN, COUNT, AVG, e FIRSTLAST.

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

Nota

Só é possível agregar valores de telemetria.

Cláusula ORDER BY

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

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

Gorjeta

Combine 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:

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

Próximos passos

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