Linguagem de consulta do Hub IoT do dispositivo e módulos duplos, tarefas e encaminhamento de mensagens

Artigo
06/13/2024

O Hub IoT fornece uma poderosa linguagem semelhante ao SQL para recuperar informações sobre gêmeos de dispositivos, gêmeos de módulos, trabalhos e roteamento de mensagens. Este artigo apresenta:

Uma introdução aos principais recursos da linguagem de consulta do Hub IoT, e
A descrição detalhada da língua. Para obter detalhes sobre o idioma de consulta para roteamento de mensagens, consulte consultas em roteamento de mensagens.

Para obter exemplos específicos, consulte Consultas para gêmeos de dispositivo e módulo ou Consultas para trabalhos.

Nota

Alguns dos recursos mencionados neste artigo, como mensagens de nuvem para dispositivo, gêmeos de dispositivo e gerenciamento de dispositivos, estão disponíveis apenas na camada padrão do Hub IoT. Para obter mais informações sobre as camadas básica e padrão/gratuita do Hub IoT, consulte Escolha a camada certa do Hub IoT para sua solução.

Executar consultas do Hub IoT

Você pode executar consultas em seu hub IoT diretamente no portal do Azure.

Entre no portal do Azure e navegue até seu hub IoT.
Selecione Consultas na seção Gerenciamento de dispositivos do menu de navegação.
Introduza a sua consulta na caixa de texto e selecione Executar consulta.

Você também pode executar consultas em seus aplicativos usando os SDKs e APIs de serviço do Azure IoT.

Por exemplo, código implementando consultas do Hub IoT, consulte a seção Exemplos de consulta com os SDKs de serviço.

Para obter links para páginas de referência e exemplos do SDK, consulte SDKs do Azure IoT.

Noções básicas de uma consulta do Hub IoT

Cada consulta do Hub IoT consiste em cláusulas SELECT e FROM, com cláusulas opcionais WHERE e GROUP BY.

As consultas são executadas em uma coleção de documentos JSON, por exemplo, gêmeos de dispositivo. A cláusula FROM indica a coleção de documentos a ser iterada ( devices, devices.modules ou devices.jobs).

Em seguida, o filtro na cláusula WHERE é aplicado. Com agregações, os resultados desta etapa são agrupados conforme especificado na cláusula GROUP BY. Para cada grupo, uma linha é gerada conforme especificado na cláusula SELECT.

SELECT <select_list>
  FROM <from_specification>
  [WHERE <filter_condition>]
  [GROUP BY <group_specification>]

Cláusula SELECT

A cláusula SELECT <select_list> é necessária em todas as consultas do Hub IoT. Ele especifica quais valores são recuperados da consulta. Ele especifica os valores JSON a serem usados para gerar novos objetos JSON. Para cada elemento do subconjunto filtrado (e opcionalmente agrupado) da coleção FROM, a fase de projeção gera um novo objeto JSON. Este objeto é construído com os valores especificados na cláusula SELECT.

Por exemplo:

Retornar todos os valores
```
SELECT *
```
Retornar propriedades específicas
```
SELECT DeviceID, LastActivityTime
```
Agregar os resultados de uma consulta para retornar uma contagem
```
SELECT COUNT() as TotalNumber
```

Atualmente, cláusulas de seleção diferentes de SELECT são suportadas apenas em consultas agregadas em gêmeos de dispositivo.

A sintaxe a seguir é a gramática da cláusula SELECT:

SELECT [TOP <max number>] <projection list>

<projection_list> ::=
    '*'
    | <projection_element> AS alias [, <projection_element> AS alias]+

<projection_element> :==
    attribute_name
    | <projection_element> '.' attribute_name
    | <aggregate>

<aggregate> :==
    count()
    | avg(<projection_element>)
    | sum(<projection_element>)
    | min(<projection_element>)
    | max(<projection_element>)

Attribute_name refere-se a qualquer propriedade do documento JSON na coleção FROM.

Cláusula FROM

A cláusula FROM <from_specification> é necessária em todas as consultas do ioT Hub. Deve ser um de três valores:

dispositivos para consultar gêmeos de dispositivo
devices.modules para consultar gêmeos de módulo
devices.jobs consultar detalhes do trabalho por dispositivo

Por exemplo:

Recuperar todos os gêmeos de dispositivo
```
SELECT * FROM devices
```

Cláusula WHERE

A cláusula WHERE <filter_condition> é opcional. Ele especifica uma ou mais condições que os documentos JSON na coleção FROM devem satisfazer para serem incluídos como parte do resultado. Qualquer documento JSON deve avaliar as condições especificadas como "true" para ser incluído no resultado.

Por exemplo:

Recuperar todos os trabalhos destinados a um dispositivo específico

SELECT * FROM devices.jobs
  WHERE devices.jobs.deviceId = 'myDeviceId'

As condições permitidas são descritas na seção expressões e condições .

Cláusula GROUP BY

A cláusula GROUP BY <group_specification> é opcional. Esta cláusula é executada após o filtro especificado na cláusula WHERE e antes da projeção especificada na cláusula SELECT. Ele agrupa documentos com base no valor de um atributo. Esses grupos são usados para gerar valores agregados conforme especificado na cláusula SELECT.

Por exemplo:

Retornar a contagem de dispositivos que estão relatando 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

Atualmente, a cláusula GROUP BY só é suportada ao consultar gêmeos de dispositivo.

Atenção

O termo group é atualmente tratado como uma palavra-chave especial em consultas. Caso você use group como nome do seu estabelecimento, considere cercá-lo com colchetes duplos para evitar erros, por exemplo, SELECT * FROM devices WHERE tags.[[group]].name = 'some_value'.

A sintaxe formal para GROUP BY é:

GROUP BY <group_by_element>
<group_by_element> :==
    attribute_name
    | < group_by_element > '.' attribute_name

Attribute_name refere-se a qualquer propriedade do documento JSON na coleção FROM.

Paginação dos resultados da consulta

Um objeto de consulta é instanciado com um tamanho máximo de página menor ou igual a 100 registros. Para obter várias páginas, chame o nextAsTwin no Node.js SDK ou GetNextAsTwinAsync no método .Net SDK várias vezes. Um objeto de consulta pode expor vários valores Next, dependendo da opção de desserialização exigida pela consulta. Por exemplo, um objeto de consulta pode retornar objetos gêmeos de dispositivo ou de trabalho, ou JSON simples ao usar projeções.

Expressões e condições

Em alto nível, uma expressão:

Avalia como uma instância de um tipo JSON (como Boolean, number, string, array ou object).
É definido pela manipulação de dados provenientes do documento JSON do dispositivo e constantes usando operadores e funções incorporadas.

Condições são expressões que avaliam para um booleano. Qualquer constante diferente de Boolean true é considerada como falsa. Esta regra inclui null, undefined, qualquer objeto ou instância de matriz, qualquer string e o Boolean false.

A sintaxe das expressões é:

<expression> ::=
    <constant> |
    attribute_name |
    <function_call> |
    <expression> binary_operator <expression> |
    <create_array_expression> |
    '(' <expression> ')'

<function_call> ::=
    <function_name> '(' expression ')'

<constant> ::=
    <undefined_constant>
    | <null_constant>
    | <number_constant>
    | <string_constant>
    | <array_constant>

<undefined_constant> ::= undefined
<null_constant> ::= null
<number_constant> ::= decimal_literal | hexadecimal_literal
<string_constant> ::= string_literal
<array_constant> ::= '[' <constant> [, <constant>]+ ']'

Para entender o que significa cada símbolo na sintaxe das expressões, consulte a tabela a seguir:

Símbolo	Definição
attribute_name	Qualquer propriedade do documento JSON na coleção FROM .
binary_operator	Qualquer operador binário listado na seção Operadores .
function_name	Qualquer função listada na seção Funções .
decimal_literal	Um flutuador expresso em notação decimal.
hexadecimal_literal	Número expresso pela cadeia «0x» seguida de uma cadeia de algarismos hexadecimais.
string_literal	Cadeias de caracteres Unicode representadas por uma sequência de zero ou mais caracteres Unicode ou sequências de escape. Os literais de cadeia de caracteres são colocados entre aspas simples ou duplas. Escapes permitidos: `\'`, `\"`, `\\`, `\uXXXX` para caracteres Unicode definidos por quatro dígitos hexadecimais.

Operadores

Os seguintes operadores são suportados:

Família	Operadores
Aritmético	+, -, *, /, %
Lógico	E, OU, NÃO
Comparação	=, !=, <, >, <=, >=, <>

Funções

Ao consultar gêmeos e trabalhos, a única função suportada é:

Function	Description
IS_DEFINED(propriedade)	Retorna um Boolean indicando se a propriedade recebeu um valor (incluindo `null`).

Em condições de rotas, as seguintes funções matemáticas são suportadas:

Function	Description
ABS(x)	Devolve o valor absoluto (positivo) da expressão numérica especificada.
EXP(x)	Devolve o valor exponencial da expressão numérica especificada (e^x).
POTÊNCIA (x,y)	Retorna o valor da expressão especificada para a potência especificada (x^y).
QUADRADO(x)	Devolve o quadrado do valor numérico especificado.
TETO (x)	Retorna o menor valor inteiro maior ou igual à expressão numérica especificada.
PAVIMENTO(x)	Retorna o maior inteiro menor ou igual à expressão numérica especificada.
SINAL(x)	Devolve o sinal positivo (+1), zero (0) ou negativo (-1) da expressão numérica especificada.
SQRT(x)	Retorna a raiz quadrada do valor numérico especificado.

Em condições de rotas, as seguintes funções de verificação de tipo e fundição são suportadas:

Function	Description
AS_NUMBER	Converte a cadeia de caracteres de entrada em um número. `noop` se a entrada for um número; `Undefined` se string não representar um número.
IS_ARRAY	Retorna um valor booleano que indica se o tipo da expressão especificada é uma matriz.
IS_BOOL	Retorna um valor booleano que indica se o tipo da expressão especificada é booleano.
IS_DEFINED	Retorna um Boolean indicando se a propriedade recebeu um valor. Esta função é suportada apenas quando o valor é um tipo primitivo. Os tipos primitivos incluem string, booleano, numérico ou `null`. DateTime, tipos de objeto e matrizes não são suportados.
IS_NULL	Retorna um valor booleano indicando se o tipo da expressão especificada é null.
IS_NUMBER	Retorna um valor booleano que indica se o tipo da expressão especificada é um número.
IS_OBJECT	Retorna um valor booleano indicando se o tipo da expressão especificada é um objeto JSON.
IS_PRIMITIVE	Retorna um valor booleano que indica se o tipo da expressão especificada é uma primitiva (string, booleana, numérica ou `null`).
IS_STRING	Retorna um valor booleano que indica se o tipo da expressão especificada é uma cadeia de caracteres.

Em condições de rotas, as seguintes funções de cadeia de caracteres são suportadas:

Function	Description
CONCAT(x, y, ...)	Retorna uma cadeia de caracteres que é o resultado da concatenação de dois ou mais valores de cadeia de caracteres.
COMPRIMENTO (x)	Retorna o número de caracteres da expressão de cadeia de caracteres especificada.
INFERIOR (x)	Retorna uma expressão de cadeia de caracteres depois de converter dados de caracteres maiúsculos em minúsculas.
SUPERIOR (x)	Retorna uma expressão de cadeia de caracteres depois de converter dados de caracteres minúsculos em maiúsculas.
SUBSTRING(string, start [, length])	Retorna parte de uma expressão de cadeia de caracteres começando na posição baseada em zero do caractere especificado e continua até o comprimento especificado ou até o final da cadeia de caracteres.
INDEX_OF(string, fragmento)	Retorna a posição inicial da primeira ocorrência da segunda expressão de cadeia de caracteres dentro da primeira expressão de cadeia de caracteres especificada, ou -1 se a cadeia de caracteres não for encontrada.
STARTSWITH(x, y)	Retorna um booleano indicando se a primeira expressão de cadeia de caracteres começa com a segunda.
ENDSWITH(x, y)	Retorna um Boolean indicando se a primeira expressão de cadeia de caracteres termina com a segunda.
CONTÉM(x,y)	Retorna um Boolean indicando se a primeira expressão de cadeia de caracteres contém a segunda.

Exemplos de consulta com os SDKs de serviço

Exemplo de C#

A funcionalidade de consulta é exposta pelo SDK do serviço C# na classe RegistryManager.

Aqui está um exemplo de uma consulta simples:

var query = registryManager.CreateQuery("SELECT * FROM devices", 100);
while (query.HasMoreResults)
{
    var page = await query.GetNextAsTwinAsync();
    foreach (var twin in page)
    {
        // do work on twin object
    }
}

O objeto de consulta é instanciado com os parâmetros mencionados na seção paginação de resultados da consulta. Várias páginas são recuperadas chamando os métodos GetNextAsTwinAsync várias vezes.

Node.js exemplo

A funcionalidade de consulta é exposta pelo SDK do serviço IoT do Azure para Node.js no objeto Registry .

Aqui está um exemplo de uma consulta simples:

var query = registry.createQuery('SELECT * FROM devices', 100);
var onResults = function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        // Do something with the results
        results.forEach(function(twin) {
            console.log(twin.deviceId);
        });

        if (query.hasMoreResults) {
            query.nextAsTwin(onResults);
        }
    }
};
query.nextAsTwin(onResults);

O objeto de consulta é instanciado com os parâmetros mencionados na seção paginação de resultados da consulta. Várias páginas são recuperadas chamando o método nextAsTwin várias vezes.

Próximos passos

Saiba mais sobre o roteamento de mensagens com base nas propriedades ou no corpo da mensagem com a sintaxe de consulta de roteamento de mensagens do Hub IoT.
Obtenha exemplos específicos de Consultas para gêmeos de dispositivo e módulo ou Consultas para trabalhos.

Partilhar via

Linguagem de consulta do Hub IoT do dispositivo e módulos duplos, tarefas e encaminhamento de mensagens

Executar consultas do Hub IoT

Noções básicas de uma consulta do Hub IoT

Cláusula SELECT

Cláusula FROM

Cláusula WHERE

Cláusula GROUP BY

Expressões e condições

Operadores

Funções

Exemplos de consulta com os SDKs de serviço

Exemplo de C#

Node.js exemplo

Próximos passos

Comentários

Recursos adicionais