Linguagem de consulta do Hub IoT para dispositivos e módulos gêmeos, trabalhos e roteamento de mensagens

O Hub IoT oferece uma linguagem avançada semelhante à SQL para recuperação de informações relacionadas a dispositivos gêmeos, módulos gêmeos, trabalhos e roteamento de mensagens. Este artigo apresenta:

• Uma introdução aos principais recursos da linguagem de consulta do Hub IoT e
• Uma descrição mais detalhada da linguagem. Para obter detalhes sobre a linguagem de consulta do roteamento de mensagens, confira consultas no roteamento de mensagens.

Para obter exemplos específicos, consulte Consultas para dispositivos e módulos gêmeos ou Consultas para trabalhos.

Executar consultas Hub IoT

Você pode executar consultas no Hub IoT diretamente no portal do Azure.

1. Entre no Portal do Azure e navegue até o Hub IoT.
2. Selecione Consultas na seção Gerenciamento de dispositivos do menu de navegação.
3. Insira sua consulta na caixa de texto e selecione Executar consulta.

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

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

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

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

Todas as consultas de Hub IoT são compostas por cláusulas SELECT e FROM, com cláusulas WHERE e GROUP BY opcionais.

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

Em seguida, o filtro na cláusula WHERE é aplicado. Com agregações, os resultados dessa 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 cada consulta Hub IoT. Ela especifica quais valores são recuperados da consulta. Ela especifica os valores JSON a serem usado 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. Esse 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
  

No momento, as cláusulas de seleção diferentes de SELECT* têm suporte apenas em consultas de agregação em dispositivos gêmeos.

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 Hub IoT. Deve ser um dos três valores:

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

Por exemplo:

• Recuperar todos os dispositivos gêmeos

  SELECT * FROM devices
  

cláusula WHERE

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

Por exemplo:

• Recuperar todos os trabalhos direcionados 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. Essa cláusula é executada após o filtro especificado na cláusula WHERE e antes da projeção especificada no SELECT. Ela 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
  

No momento, a cláusula GROUP BY tem suporte apenas ao consultar dispositivos gêmeos.

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 de 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 método nextAsTwin em Node.js SDK ou GetNextAsTwinAsync no SDK do .Net 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 dispositivos gêmeos ou objetos de trabalho ou JSON simples ao usar projeções.

Expressões e condições

Em um alto nível, uma expressão:

• Avalia para uma instância de um tipo JSON (por exemplo, booliano, número, cadeia de caracteres, matriz ou objeto).
• É definida pela manipulação de dados provenientes do documento JSON de dispositivo e constantes usando as funções e operadores internos.

Condições são expressões que retornam um valor booliano. Qualquer constante diferente do Booliano verdadeiro é considerada como falso. Essa regra inclui nulo, indefinido, qualquer instância de matriz ou objeto, qualquer cadeia de caracteres e o booleano falso.

A sintaxe de 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 de expressões, consulte a tabela a seguir:

Operadores

Há suporte para os seguintes operadores:

Funções

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

Em condições de rotas, há suporte para as seguintes funções matemáticas:

Em condições de rotas, há suporte para as seguintes funções de verificação de tipo e conversão de tipo:

Em condições de rotas, há suporte para as seguintes funções de cadeias de caracteres:

Exemplos de consulta com os SDKs de serviço

Exemplo de C#

A funcionalidade da consulta é exposta pelo SDK do serviço de 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. Em seguida, várias páginas são recuperadas chamando os métodos GetNextAsTwinAsync várias vezes.

Exemplo do Node.js

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óximas etapas

• Saiba mais sobre como encaminhar mensagens com base nas propriedades da mensagem ou no corpo da mensagem, confira a sintaxe de consulta de encaminhamento de mensagens do Hub IoT.
• Obtenha exemplos específicos de Consultas para dispositivos e módulos gêmeos ou Consultas para trabalhos.