Consultar o gráfico de gêmeos do Azure Digital Twins

Este artigo oferece exemplos de consulta e instruções para usar a linguagem de consulta do Azure Digital Twins para consultar seu gráfico gêmeo para obter informações. (Para uma introdução à linguagem de consulta, consulte Linguagem de consulta.)

O artigo contém consultas de exemplo que ilustram a estrutura da linguagem de consulta e as operações de consulta comuns para gêmeos digitais. Ele também descreve como executar suas consultas depois de escrevê-las, usando a API de Consulta de Gêmeos Digitais do Azure ou um SDK.

Nota

Se você estiver executando as consultas de exemplo abaixo com uma chamada de API ou SDK, precisará condensar o texto da consulta em uma única linha.

Documentação de referência

A referência de linguagem de consulta pode ser encontrada em Referência no sumário esquerdo da documentação dos Gêmeos Digitais do Azure. Você também pode ir diretamente para as seções de referência usando os links abaixo:

• Cláusulas
  • SELECT
  • DE
  • CORRESPONDÊNCIA
  • ADERIR
  • EM QUE
• Funções
• Operadores
• Palavras-chave reservadas

Mostrar todos os gêmeos digitais

Aqui está a consulta básica que retornará uma lista de todos os gêmeos digitais na instância:

SELECT * FROM DIGITALTWINS

Consulta por propriedade

Obtenha gêmeos digitais por propriedades (incluindo ID e metadados):

SELECT  *
FROM DIGITALTWINS T  
WHERE T.firmwareVersion = '1.1'
AND T.$dtId in ['123', '456']
AND T.Temperature = 70

Como mostrado na consulta acima, o ID de um gêmeo digital é consultado usando o campo $dtIdde metadados .

Gorjeta

Se você estiver usando o Cloud Shell para executar uma consulta com campos de metadados que começam com $, você deve escapar com $ uma barra invertida para que o Cloud Shell saiba que não é uma variável e deve ser consumido como um literal no texto da consulta.

Você também pode obter gêmeos com base na definição de uma determinada propriedade. Aqui está uma consulta que obtém gêmeos que têm uma propriedade definida Location :

SELECT *​ FROM DIGITALTWINS WHERE IS_DEFINED(Location)

Esta consulta pode ajudá-lo a obter gémeos pelas suas tag propriedades, conforme descrito em Adicionar etiquetas a gémeos digitais. Aqui está uma consulta que faz com que todos os gêmeos sejam marcados com red:

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

Você também pode obter gêmeos com base no tipo de propriedade. Aqui está uma consulta que obtém gêmeos cuja Temperature propriedade é um número:

SELECT * FROM DIGITALTWINS​ T WHERE IS_NUMBER(T.Temperature)

Propriedades do Mapa de Consulta

Se uma propriedade for do tipo Mapcomplexo, você poderá usar as chaves e os valores do mapa diretamente na consulta, da seguinte forma:

SELECT * FROM DIGITALTWINS​ T WHERE T.<propertyName>.<mapKey> = '<mapValue>'

Se a chave do mapa começar com um caractere numérico, você precisará envolver a chave entre colchetes duplos ([[<mapKey>]]) para escapar dela na consulta, semelhante à estratégia para consultar com palavras-chave reservadas.

Consulta por modelo

O IS_OF_MODEL operador pode ser usado para filtrar com base no modelo do gêmeo.

Ele considera a herança e o versionamento do modelo, e avalia para um determinado gêmeo se o gêmeo atende a true qualquer uma destas condições:

• O gêmeo implementa diretamente o modelo fornecido ao IS_OF_MODEL(), e o número da versão do modelo no gêmeo é maior ou igual ao número da versão do modelo fornecido
• O gêmeo implementa um modelo que estende o modelo fornecido para IS_OF_MODEL(), e o número de versão estendida do modelo do gêmeo é maior ou igual ao número da versão do modelo fornecido

Assim, por exemplo, se você consultar gêmeos do modelo dtmi:example:widget;4, a consulta retornará todos os gêmeos baseados na versão 4 ou superior do modelo de widget, e também gêmeos baseados na versão 4 ou superior de quaisquer modelos que herdam do widget.

IS_OF_MODEL pode tomar vários parâmetros diferentes, e o resto desta seção é dedicada às suas diferentes opções de sobrecarga.

O uso mais simples de IS_OF_MODEL leva apenas um twinTypeName parâmetro: IS_OF_MODEL(twinTypeName). Aqui está um exemplo de consulta que passa um valor neste parâmetro:

SELECT * FROM DIGITALTWINS WHERE IS_OF_MODEL('dtmi:example:thing;1')

Para especificar uma coleção de gêmeos para pesquisar quando houver mais de uma (como quando uma JOIN é usada), adicione o twinCollection parâmetro: IS_OF_MODEL(twinCollection, twinTypeName). Aqui está um exemplo de consulta que adiciona um valor para esse parâmetro:

SELECT * FROM DIGITALTWINS DT WHERE IS_OF_MODEL(DT, 'dtmi:example:thing;1')

Para fazer uma correspondência exata, adicione o exact parâmetro: IS_OF_MODEL(twinTypeName, exact). Aqui está um exemplo de consulta que adiciona um valor para esse parâmetro:

SELECT * FROM DIGITALTWINS WHERE IS_OF_MODEL('dtmi:example:thing;1', exact)

Você também pode passar os três argumentos juntos: IS_OF_MODEL(twinCollection, twinTypeName, exact). Aqui está um exemplo de consulta especificando um valor para todos os três parâmetros:

SELECT * FROM DIGITALTWINS DT WHERE IS_OF_MODEL(DT, 'dtmi:example:thing;1', exact)

Consulta por relação

Ao fazer a consulta com base em relações de duplos digitais, a linguagem de consulta do Azure Digital Twins tem uma sintaxe especial.

As relações são solicitadas para o âmbito de pesquisa na cláusula FROM. Ao contrário das linguagens "clássicas" do tipo SQL, cada expressão na FROM cláusula não é uma tabela, mas sim uma travessia FROM de relacionamento entre entidades. Para atravessar relações, o Azure Digital Twins usa uma versão personalizada do JOIN.

Lembre-se de que, com os recursos do modelo de Gêmeos Digitais do Azure, os relacionamentos não existem independentemente dos gêmeos, o que significa que os relacionamentos aqui não podem ser consultados de forma independente e devem ser vinculados a um gêmeo. Para refletir esse fato, a JOIN palavra-chave RELATED é usada na cláusula para puxar o conjunto de um determinado tipo de relação proveniente da coleção gêmea. A consulta deve então filtrar na WHERE cláusula, para indicar quais gêmeos específicos usar na consulta de relacionamento (usando os valores dos $dtId gêmeos).

As seções a seguir dão exemplos de como isso se parece.

Consulta de relacionamento básica

Aqui está um exemplo de consulta baseada em relacionamento. Este trecho de código seleciona todos os gêmeos digitais com uma ID propriedade de , e todos os gêmeos digitais relacionados a esses gêmeos digitais por meio de ABCum contains relacionamento.

SELECT T, CT
FROM DIGITALTWINS T
JOIN CT RELATED T.contains
WHERE T.$dtId = 'ABC'

O tipo de relação (contains no exemplo acima) é indicado usando o campo da name relação a partir de sua definição DTDL.

Nota

O desenvolvedor não precisa correlacionar isso JOIN com um valor de chave na WHERE cláusula (ou especificar um valor de chave em linha com a JOIN definição). Esta correlação é calculada automaticamente pelo sistema, uma vez que as próprias propriedades de relação identificam a entidade de destino.

Consulta pela origem ou destino de uma relação

Você pode usar a estrutura de consulta de relacionamento para identificar um gêmeo digital que é a origem ou o destino de um relacionamento.

Por exemplo, você pode começar com um gêmeo fonte e seguir seus relacionamentos para encontrar os gêmeos alvo dos relacionamentos. Aqui está um exemplo de uma consulta que encontra os gêmeos alvo dos feeds relacionamentos provenientes do gêmeo fonte-gêmeo.

SELECT target 
FROM DIGITALTWINS source 
JOIN target RELATED source.feeds 
WHERE source.$dtId = 'source-twin'

Você também pode começar com o alvo do relacionamento e rastrear o relacionamento de volta para encontrar o gêmeo de origem. Aqui está um exemplo de uma consulta que encontra o gêmeo de origem de uma feeds relação com o gêmeo-alvo gêmeo.

SELECT source 
FROM DIGITALTWINS source 
JOIN target RELATED source.feeds 
WHERE target.$dtId = 'target-twin'

Consultar as propriedades de uma relação

Da mesma forma que os duplos digitais têm propriedades descritas através de DTDL, as relações também podem ter propriedades. Pode consultar duplos com base nas propriedades das suas relações. A linguagem de consulta dos Gêmeos Digitais do Azure permite filtrar e projetar relações, atribuindo um alias à relação dentro da JOIN cláusula.

Como exemplo, considere uma servicedBy relação que tenha uma reportedCondition propriedade. Na consulta abaixo, essa relação recebe um alias de R para fazer referência à sua propriedade.

SELECT T, SBT, R
FROM DIGITALTWINS T
JOIN SBT RELATED T.servicedBy R
WHERE T.$dtId = 'ABC'
AND R.reportedCondition = 'clean'

No exemplo acima, observe como reportedCondition é uma propriedade da relação em si (NÃO de algum gêmeo servicedBy digital que tenha uma servicedBy relação).

Consulta com várias JOINs

Até cinco JOINs são suportados em uma única consulta, o que permite que você percorra vários níveis de relacionamentos ao mesmo tempo.

Para consultar em vários níveis de relações, use uma única FROM instrução seguida por N JOIN instruções, onde as instruções expressam JOIN relações sobre o resultado de uma instrução anterior FROM ou JOIN .

Aqui está um exemplo de uma consulta multi-junção, que obtém todas as lâmpadas contidas nos painéis de luz nas salas 1 e 2.

SELECT LightBulb
FROM DIGITALTWINS Room
JOIN LightPanel RELATED Room.contains
JOIN LightBulb RELATED LightPanel.contains
WHERE IS_OF_MODEL(LightPanel, 'dtmi:contoso:com:lightpanel;1')
AND IS_OF_MODEL(LightBulb, 'dtmi:contoso:com:lightbulb ;1')
AND Room.$dtId IN ['room1', 'room2']

Contar itens

Você pode contar o número de itens em um conjunto de resultados usando a Select COUNT cláusula:

SELECT COUNT()
FROM DIGITALTWINS

Adicione uma WHERE cláusula para contar o número de itens que atendem a um determinado critério. Aqui estão alguns exemplos de contagem com um filtro aplicado com base no tipo de modelo gêmeo (para obter mais informações sobre essa sintaxe, consulte Consulta por modelo abaixo):

SELECT COUNT()
FROM DIGITALTWINS
WHERE IS_OF_MODEL('dtmi:sample:Room;1')

SELECT COUNT()
FROM DIGITALTWINS c
WHERE IS_OF_MODEL('dtmi:sample:Room;1') AND c.Capacity > 20

Você também pode usar COUNT junto com a JOIN cláusula. Aqui está uma consulta que conta todas as lâmpadas contidas nos painéis de luz das salas 1 e 2:

SELECT COUNT()  
FROM DIGITALTWINS Room  
JOIN LightPanel RELATED Room.contains  
JOIN LightBulb RELATED LightPanel.contains  
WHERE IS_OF_MODEL(LightPanel, 'dtmi:contoso:com:lightpanel;1')  
AND IS_OF_MODEL(LightBulb, 'dtmi:contoso:com:lightbulb;1')  
AND Room.$dtId IN ['room1', 'room2']

Filtrar resultados: selecionar itens principais

Você pode selecionar os vários itens "superiores" em uma consulta usando a Select TOP cláusula.

SELECT TOP (5)
FROM DIGITALTWINS
WHERE ...

Filtrar resultados: especificar conjunto de retorno com projeções

Usando projeções na SELECT instrução, você pode escolher quais colunas uma consulta retornará. A projeção agora é suportada para propriedades primitivas e complexas. Para obter mais informações sobre projeções com o Azure Digital Twins, consulte a documentação de referência da cláusula SELECT.

Aqui está um exemplo de uma consulta que usa projeção para retornar gêmeos e relacionamentos. A consulta a seguir projeta o Consumidor, a Fábrica e a Borda de um cenário em que uma Fábrica com uma ID de está relacionada ao Consumidor por meio de ABC uma relação de Factory.customer, e essa relação é apresentada como o Edge.

SELECT Consumer, Factory, Edge
FROM DIGITALTWINS Factory
JOIN Consumer RELATED Factory.customer Edge
WHERE Factory.$dtId = 'ABC'

Você também pode usar a projeção para retornar uma propriedade de um gêmeo. A consulta a seguir projeta a Name propriedade dos Consumidores que estão relacionados à Fábrica com uma ID de através de ABC uma relação de Factory.customer.

SELECT Consumer.name
FROM DIGITALTWINS Factory
JOIN Consumer RELATED Factory.customer Edge
WHERE Factory.$dtId = 'ABC'

Você também pode usar projeção para retornar uma propriedade de um relacionamento. Como no exemplo anterior, a consulta a seguir projeta a Name propriedade dos Consumidores relacionada à Fábrica com uma ID de através de ABC uma relação de Factory.customer, mas agora também retorna duas propriedades dessa relação prop1 e prop2. Ele faz isso nomeando a relação Edge e reunindo suas propriedades.

SELECT Consumer.name, Edge.prop1, Edge.prop2, Factory.area
FROM DIGITALTWINS Factory
JOIN Consumer RELATED Factory.customer Edge
WHERE Factory.$dtId = 'ABC'

Você também pode usar aliases para simplificar consultas com projeção.

A consulta a seguir faz as mesmas operações que o exemplo anterior, mas aliasa os nomes de propriedade para consumerName, first, second, e factoryArea.

SELECT Consumer.name AS consumerName, Edge.prop1 AS first, Edge.prop2 AS second, Factory.area AS factoryArea
FROM DIGITALTWINS Factory
JOIN Consumer RELATED Factory.customer Edge
WHERE Factory.$dtId = 'ABC'

Aqui está uma consulta semelhante que consulta o mesmo conjunto acima, mas projeta apenas a Consumer.name propriedade como consumerName, e projeta a fábrica completa como um gêmeo.

SELECT Consumer.name AS consumerName, Factory
FROM DIGITALTWINS Factory
JOIN Consumer RELATED Factory.customer Edge
WHERE Factory.$dtId = 'ABC'

Crie consultas eficientes com o operador IN

Você pode reduzir significativamente o número de consultas necessárias criando uma matriz de gêmeos e consultando com o IN operador.

Por exemplo, considere um cenário em que Edifícios contêm Pisos e Pisos contêm Quartos. Para procurar quartos dentro de um edifício que estejam quentes, uma maneira é seguir estes passos.

1. Encontre andares no edifício com base na contains relação.

   SELECT Floor
   FROM DIGITALTWINS Building
   JOIN Floor RELATED Building.contains
   WHERE Building.$dtId = @buildingId
   

2. Para encontrar quartos, em vez de considerar os andares um a um e executar uma JOIN consulta para encontrar os quartos para cada um, você pode consultar com uma coleção dos andares do edifício (chamado Andar na consulta abaixo).

   No aplicativo cliente:

   var floors = "['floor1','floor2', ..'floorn']"; 
   

   Em consulta:

   SELECT Room
   FROM DIGITALTWINS Floor
   JOIN Room RELATED Floor.contains
   WHERE Floor.$dtId IN ['floor1','floor2', ..'floorn']
   AND Room. Temperature > 72
   AND IS_OF_MODEL(Room, 'dtmi:com:contoso:Room;1')
   

Outros exemplos de consultas compostas

Você pode combinar qualquer um dos tipos de consulta acima usando operadores de combinação para incluir mais detalhes em uma única consulta. Aqui estão alguns outros exemplos de consultas compostas que consultam mais de um tipo de descritor gêmeo ao mesmo tempo.

• Dos dispositivos que a Sala 123 possui, devolva os dispositivos MxChip que cumprem o papel de Operador

  SELECT device
  FROM DIGITALTWINS space
  JOIN device RELATED space.has
  WHERE space.$dtid = 'Room 123'
  AND device.$metadata.model = 'dtmi:contoso:com:DigitalTwins:MxChip:3'
  AND has.role = 'Operator'
  

• Obter gêmeos que têm um relacionamento nomeado Contains com outro gêmeo que tem um ID de id1

  SELECT Room
  FROM DIGITALTWINS Room
  JOIN Thermostat RELATED Room.Contains
  WHERE Thermostat.$dtId = 'id1'
  

• Obtenha todos os quartos deste modelo de quarto que estão contidos por andar11

  SELECT Room
  FROM DIGITALTWINS Floor
  JOIN Room RELATED Floor.Contains
  WHERE Floor.$dtId = 'floor11'
  AND IS_OF_MODEL(Room, 'dtmi:contoso:com:DigitalTwins:Room;1')
  

Executar consultas com a API

Depois de decidir sobre uma cadeia de caracteres de consulta, execute-a fazendo uma chamada para a API de consulta.

Você pode chamar a API diretamente ou usar um dos SDKs disponíveis para Gêmeos Digitais do Azure.

O trecho de código a seguir ilustra a chamada do SDK .NET (C#) de um aplicativo cliente:

// Run a query for all twins   
string query = "SELECT * FROM DIGITALTWINS";
AsyncPageable<BasicDigitalTwin> result = client.QueryAsync<BasicDigitalTwin>(query);

A consulta usada nesta chamada retorna uma lista de gêmeos digitais, que o exemplo acima representa com objetos BasicDigitalTwin . O tipo de retorno de seus dados para cada consulta dependerá dos termos especificados com a SELECT instrução:

• As consultas que começam com SELECT * FROM ... retornarão uma lista de gêmeos digitais (que podem ser serializados como BasicDigitalTwin objetos ou outros tipos de gêmeos digitais personalizados que você pode ter criado).
• As consultas que começam no formato SELECT <A>, <B>, <C> FROM ... retornarão um dicionário com as teclas <A>, <B>e <C>.
• Outros formatos de SELECT instruções podem ser criados para retornar dados personalizados. Você pode considerar a criação de suas próprias classes para lidar com conjuntos de resultados personalizados.

Consulta com paginação

As chamadas de consulta suportam paginação. Aqui está um exemplo completo usando BasicDigitalTwin como tipo de resultado de consulta com manipulação de erros e paginação:

AsyncPageable<BasicDigitalTwin> result = client.QueryAsync<BasicDigitalTwin>("Select * From DigitalTwins");
try
{
    await foreach (BasicDigitalTwin twin in result)
    {
        // You can include your own logic to print the result
        // The logic below prints the twin's ID and contents
        Console.WriteLine($"Twin ID: {twin.Id} \nTwin data");
        foreach (KeyValuePair<string, object> kvp in twin.Contents)
        {
            Console.WriteLine($"{kvp.Key}  {kvp.Value}");
        }
    }
}
catch (RequestFailedException ex)
{
    Console.WriteLine($"Error {ex.Status}, {ex.ErrorCode}, {ex.Message}");
    throw;
}

Próximos passos

Saiba mais sobre as APIs e SDKs do Azure Digital Twins, incluindo a API de Consulta usada para executar as consultas deste artigo.