Consultar o gráfico duplo do Azure Digital Twins

Este artigo oferece exemplos de consulta e instruções para utilizar a linguagem de consulta do Azure Digital Twins para consultar o gráfico duplo para obter informações. (Para obter 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 duplos digitais. Também descreve como executar as suas consultas depois de as ter escrito, utilizando a API de Consulta do Azure Digital Twins ou um SDK.

Nota

Se estiver a executar as consultas de exemplo abaixo com uma API ou uma chamada SDK, terá de condensar o texto da consulta numa única linha.

Documentação de referência

A referência da linguagem de consulta pode ser encontrada em Referência no índice esquerdo da documentação do Azure Digital Twins. Também pode aceder diretamente às secções de referência com as ligações abaixo:

Mostrar todos os duplos digitais

Eis a consulta básica que irá devolver uma lista de todos os duplos digitais na instância:

SELECT * FROM DIGITALTWINS

Consultar por propriedade

Obter duplos 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

Conforme mostrado na consulta acima, o ID de um duplo digital é consultado com o campo $dtIdde metadados .

Dica

Se estiver a utilizar Cloud Shell para executar uma consulta com campos de metadados que comecem por $, deve escapar ao $ com uma barra invertida para informar Cloud Shell não é uma variável e deve ser consumido como literal no texto da consulta.

Também pode obter duplos com base na definição de uma determinada propriedade. Eis uma consulta que obtém duplos que têm uma propriedade definida Location :

SELECT *​ FROM DIGITALTWINS WHERE IS_DEFINED(Location)

Esta consulta pode ajudá-lo a obter duplos pelas respetivas tag propriedades, conforme descrito em Adicionar etiquetas a duplos digitais. Segue-se uma consulta que identifica todos os duplos com red:

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

Também pode obter duplos com base no tipo de propriedade. Eis uma consulta que obtém duplos cuja Temperature propriedade é um número:

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

Dica

Se uma propriedade for do tipo Map, pode utilizar as chaves de mapa e os valores diretamente na consulta, da seguinte forma:

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

Consultar por modelo

O IS_OF_MODEL operador pode ser utilizado para filtrar com base no modelo do duplo.

Considera a herança e o controlo de versões de modelos e avalia como true para um determinado duplo se o duplo cumprir qualquer uma destas condições:

  • O duplo implementa diretamente o modelo fornecido para IS_OF_MODEL()e o número da versão do modelo no duplo é maior ou igual ao número de versão do modelo fornecido
  • O duplo implementa um modelo que expande o modelo fornecido para IS_OF_MODEL()e o número de versão de modelo expandido do duplo é maior ou igual ao número da versão do modelo fornecido

Por exemplo, se consultar duplos do modelo dtmi:example:widget;4, a consulta devolverá todos os duplos com base na versão 4 ou superior do modelo widget e também duplos com base na versão 4 ou superior de quaisquer modelos que herdem do widget.

IS_OF_MODEL pode utilizar vários parâmetros diferentes e o resto desta secção é dedicado às diferentes opções de sobrecarga.

A utilização mais simples do IS_OF_MODEL utiliza apenas um twinTypeName parâmetro: IS_OF_MODEL(twinTypeName). Eis um exemplo de consulta que transmite um valor neste parâmetro:

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

Para especificar uma coleção de duplos para procurar quando existir mais do que uma (como quando uma JOIN é utilizada), adicione o twinCollection parâmetro: IS_OF_MODEL(twinCollection, twinTypeName). Eis um exemplo de consulta que adiciona um valor para este 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). Eis um exemplo de consulta que adiciona um valor para este parâmetro:

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

Também pode transmitir os três argumentos em conjunto: IS_OF_MODEL(twinCollection, twinTypeName, exact). Eis um exemplo de consulta que especifica um valor para os três parâmetros:

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

Consultar 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; em vez disso, a FROM cláusula expressa um percurso de relação entre entidades. Para percorrer relações, o Azure Digital Twins utiliza uma versão personalizada do JOIN.

Lembre-se de que, com as capacidades do modelo do Azure Digital Twins, as relações não existem independentemente dos duplos, o que significa que as relações aqui não podem ser consultadas de forma independente e têm de estar ligadas a um duplo. Para refletir este facto, a palavra-chave RELATED é utilizada na JOIN cláusula para solicitar o conjunto de um determinado tipo de relação proveniente da coleção de duplos. Em seguida, a consulta tem de filtrar na WHERE cláusula, para indicar quais os duplos específicos a utilizar na consulta de relação (utilizando os valores dos $dtId duplos).

As secções seguintes dão exemplos do aspeto deste aspeto.

Consulta de relação básica

Eis uma consulta baseada em relações de exemplo. Este fragmento de código seleciona todos os duplos digitais com uma ID propriedade de ABCe todos os duplos digitais relacionados com estes duplos digitais através de uma contains relação.

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

O tipo da relação (contains no exemplo acima) é indicado através do campo da name relação a partir da respetiva definição de DTDL.

Nota

O programador não precisa de correlacionar isto JOIN com um valor chave na WHERE cláusula (ou especificar um valor de chave inline 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

Pode utilizar a estrutura de consulta de relação para identificar um duplo digital que seja a origem ou o destino de uma relação.

Por exemplo, pode começar com um duplo de origem e seguir as respetivas relações para encontrar os duplos-alvo das relações. Eis um exemplo de uma consulta que localiza os duplos-alvo das feeds relações provenientes do duplo-duplo.

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

Também pode começar com o destino da relação e rastrear a relação de volta para encontrar o duplo de origem. Eis um exemplo de uma consulta que localiza o duplo de origem de uma feeds relação com o duplo-duplo-duplo.

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 do Azure Digital Twins permite filtrar e projeção de relações ao atribuir um alias à relação dentro da JOIN cláusula.

Por exemplo, considere uma servicedBy relação que tenha uma reportedCondition propriedade. Na consulta abaixo, esta relação recebe um alias de R para referenciar a respetiva 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, tenha em atenção como reportedCondition é uma propriedade da servicedBy própria relação (NÃO de algum duplo digital que tenha uma servicedBy relação).

Consulta com vários JOINs

Até cinco JOINs são suportados numa única consulta, o que lhe permite percorrer vários níveis de relações ao mesmo tempo.

Para consultar em múltiplos níveis de relações, utilize uma única FROM instrução seguida de instruções NJOIN, em que as JOIN instruções expressam relações no resultado de uma instrução ou JOIN anteriorFROM.

Eis um exemplo de uma consulta multi-associação, que obtém todas as lâmpadas contidas nos painéis claros 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

Pode contar o número de itens num conjunto de resultados com a Select COUNT cláusula:

SELECT COUNT()
FROM DIGITALTWINS

Adicione uma WHERE cláusula para contar o número de itens que cumprem determinados critérios. Eis alguns exemplos de contagem com um filtro aplicado com base no tipo de modelo duplo (para obter mais informações sobre esta sintaxe, consulte Consultar 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

Também pode utilizar COUNT juntamente com a JOIN cláusula. Eis uma consulta que conta todas as lâmpadas contidas nos painéis claros 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: selecione os itens principais

Pode selecionar os vários itens "top" numa consulta com a Select TOP cláusula .

SELECT TOP (5)
FROM DIGITALTWINS
WHERE ...

Filtrar resultados: especifique o conjunto de devoluções com projeções

Ao utilizar projeções na SELECT instrução, pode escolher as colunas que uma consulta irá devolver. A projeção é agora suportada para propriedades primitivas e complexas. Para obter mais informações sobre projeções com o Azure Digital Twins, veja a documentação de referência da cláusula SELECT.

Eis um exemplo de uma consulta que utiliza a projeção para devolver duplos e relações. A consulta seguinte projeta o Consumidor, Fábrica e Edge a partir de um cenário em que uma Fábrica com um ID ABC está relacionada com o Consumidor através de 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'

Também pode utilizar a projeção para devolver uma propriedade de um duplo. A consulta seguinte projeta a Name propriedade dos Consumidores que estão relacionados com a Fábrica com um 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'

Também pode utilizar a projeção para devolver uma propriedade de uma relação. Tal como no exemplo anterior, a seguinte consulta projeta a Name propriedade dos Consumidores relacionados com a Fábrica com um ID de através de ABC uma relação de Factory.customer; mas agora também devolve duas propriedades dessa relação, prop1 e prop2. Fá-lo ao atribuir um nome à relação Edge e ao recolher as respetivas propriedades.

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

Também pode utilizar aliases para simplificar as consultas com projeção.

A consulta seguinte faz as mesmas operações que o exemplo anterior, mas alias os nomes das propriedades para consumerName, first, seconde 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'

Eis uma consulta semelhante que consulta o mesmo conjunto que acima, mas projeta apenas a Consumer.name propriedade como consumerNamee projeta a Fábrica completa como um duplo.

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

Criar consultas eficientes com o operador IN

Pode reduzir significativamente o número de consultas de que precisa ao criar uma matriz de duplos e ao consultar com o IN operador.

Por exemplo, considere um cenário em que Edifícios contêm Pisos e Pisos contêm Salas. Para procurar salas dentro de um edifício frequente, uma forma é seguir estes passos.

  1. Encontre pisos 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 salas, em vez de considerar os pisos um a um e executar uma JOIN consulta para encontrar as salas para cada uma, pode consultar com uma coleção dos pisos do edifício (com o nome Piso na consulta abaixo).

    Na aplicação cliente:

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

    Na 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

Pode combinar qualquer um dos tipos de consulta acima através de operadores de combinação para incluir mais detalhes numa única consulta. Seguem-se outros exemplos de consultas compostas que consultam mais do que um tipo de descritor duplo ao mesmo tempo.

  • Fora dos dispositivos que a Sala 123 tem, devolva os dispositivos MxChip que servem a função 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 duplos com uma relação denominada Contains com outro duplo duplo com um ID de id1
    SELECT Room
    FROM DIGITALTWINS Room
    JOIN Thermostat RELATED Room.Contains
    WHERE Thermostat.$dtId = 'id1'
    
  • Obter todas as salas deste modelo de sala que estão contidas no piso 11
    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 consulta, execute-a ao efetuar uma chamada à API de Consulta.

Pode chamar a API diretamente ou utilizar um dos SDKs disponíveis para o Azure Digital Twins.

O fragmento de código seguinte ilustra a chamada do SDK .NET (C#) a partir de uma aplicação cliente:

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

A consulta utilizada nesta chamada devolve uma lista de duplos digitais, que o exemplo acima representa com objetos BasicDigitalTwin . O tipo de retorno dos seus dados para cada consulta dependerá dos termos que especificar com a SELECT instrução :

  • As consultas que começam com SELECT * FROM ... irão devolver uma lista de duplos digitais (que podem ser serializados como BasicDigitalTwin objetos ou outros tipos de duplos digitais personalizados que possa ter criado).
  • As consultas que começam no formato SELECT <A>, <B>, <C> FROM ... irão devolver um dicionário com as chaves <A>, <B>e <C>.
  • Podem ser criados outros formatos de SELECT instruções para devolver dados personalizados. Pode considerar criar as suas próprias classes para processar conjuntos de resultados personalizados.

Consulta com paginação

As chamadas de consulta suportam a paginação. Eis um exemplo completo que utiliza BasicDigitalTwin como tipo de resultado de consulta com processamento 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;
}

Passos seguintes

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