Linguagem de consulta do Hub IoT do dispositivo e módulos duplos, tarefas e encaminhamento de mensagens
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, LastActivityTimeAgregar 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.
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários