Partilhar via

IoT Hub query language for device and module twins, jobs, and message routing

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. For more information about query language for message routing, see IoT Hub message routing query syntax.

For specific examples, see Queries for IoT Hub device and module twins or Queries for IoT Hub jobs.

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 e o tamanho certos 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.

  1. Entre no portal do Azure e navegue até seu hub IoT.
  2. Selecione Consultas na seção Gerenciamento de dispositivos do menu de navegação.
  3. 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.

For example code implementing IoT Hub queries, see the Query examples with the service SDKs section.

For links to SDK reference pages and samples, see Azure IoT Hub SDKs.

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.

Queries are run on a collection of JSON documents, for example device twins. 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

Currently, selection clauses different than SELECT are only supported in aggregate queries on device twins.

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.

FROM clause

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

  • devices to query device twins
  • devices.modules to query module twins
  • devices.jobs to query job per-device details

Por exemplo:

  • Retrieve all device twins

    SELECT * FROM devices

WHERE clause

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:

  • Retrieve all jobs that target a specific device

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

The allowed conditions are described in the Expressions and conditions section.

GROUP BY clause

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 a relatar 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

Currently, the GROUP BY clause is only supported when querying device twins.

Atenção

O termo group é atualmente tratado como uma palavra-chave especial em consultas. In case, you use group as your property name, consider surrounding it with double brackets to avoid errors, as shown in this example: 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 que ou igual a 100 registos. To obtain multiple pages, call the nextAsTwin on Node.js SDK or GetNextAsTwinAsync on .NET SDK method multiple times. Um objeto de consulta pode expor vários valores Next, dependendo da opção de desserialização exigida pela consulta. For example, a query object can return device twin or job objects, or plain JSON when using projections.

Expressões e condições

At a high level, an expression:

  • Evaluates to an instance of a JSON type (such as Boolean, number, string, array, or object).
  • É definido pela manipulação de dados provenientes do documento JSON do dispositivo e constantes usando operadores e funções incorporadas.

Conditions are expressions that evaluate to a Boolean. 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
nome_do_atributo Qualquer propriedade do documento JSON na coleção FROM .
operador binário Qualquer operador binário listado na seção Operadores .
function_name Qualquer função listada na seção Funções .
decimal_literal Um número flutuante 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. String literals are enclosed in single quotes or double quotes. Escapes permitidos: \', \", \\, \uXXXX para caracteres Unicode definidos por quatro dígitos hexadecimais.

Operadores

Os seguintes operadores são suportados:

Família Operadores
Arithmetic +, -, *, /, %
Lógico AND, OR, NOT
Comparação =, !=, <, >, <=, >=, <>

Funções

When querying twins and jobs the only supported function is:

Function Descrição
IS_DEFINED(property) Returns a Boolean indicating if the property is assigned a value (including null).

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

Function Descrição
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).
SQUARE(x) Devolve o quadrado do valor numérico especificado.
CEILING(x) Retorna o menor valor inteiro maior ou igual à expressão numérica especificada.
FLOOR(x) Retorna o maior inteiro menor ou igual à expressão numérica especificada.
SIGN(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.

In routes conditions, the following type checking and casting functions are supported:

Function Descrição
AS_NUMBER Converte a cadeia de caracteres de entrada em um número. noop if input is a number; Undefined if string doesn't represent a number.
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 Returns a Boolean indicating if the property is a value. Esta função é suportada apenas quando o valor é um tipo primitivo. Os tipos primitivos incluem string, booleano, numérico ou null. DateTime, object types, and arrays aren't supported.
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 Descrição
CONCAT(x, y, ...) Retorna uma cadeia de caracteres que é o resultado da concatenação de dois ou mais valores de cadeia de caracteres.
LENGTH(x) Retorna o número de caracteres da expressão de cadeia de caracteres especificada.
LOWER(x) Retorna uma expressão de cadeia de caracteres depois de converter dados de caracteres maiúsculos em minúsculas.
UPPER(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, fragment) 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.
STARTS_WITH(x, y) Retorna um booleano indicando se a primeira expressão de cadeia de caracteres começa com a segunda.
ENDS_WITH(x, y) Retorna um Boolean indicando se a primeira expressão de cadeia de caracteres termina com a segunda.
CONTAINS(x,y) Retorna um Boolean indicando se a primeira expressão de cadeia de caracteres contém a segunda.

Query examples with the service SDKs

Exemplo de C#

The query functionality is exposed by the Azure IoT Hub service SDK for .NET in the RegistryManager class.

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
    }
}

The query object is instantiated with the parameters mentioned in the Query results pagination section. Várias páginas são recuperadas chamando os métodos GetNextAsTwinAsync várias vezes.

Node.js exemplo

The query functionality is exposed by the Azure IoT Hub service SDK for Node.js in the Registry object.

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);

The query object is instantiated with the parameters mentioned in the Query results pagination section. Várias páginas são recuperadas chamando o método nextAsTwin várias vezes.

Próximos passos

  • Last updated on