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, com a API de Consulta do Azure Digital Twins ou um SDK.

Nota

Se estiver a executar as consultas de exemplo abaixo com uma chamada API ou 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:

• Cláusulas
  • SELECT
  • FROM
  • CORRESP
  • ADERIR
  • WHERE
• Funções
• Operadores
• Palavras-chave Reservadas

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 Cloud Shell saber que 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 com 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. Eis uma consulta que obtém todas as etiquetas de 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)

Propriedades do Mapa de Consulta

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

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

Se a chave de mapa começar com um caráter numérico, terá de moldar a chave entre parênteses retos duplos ([[<mapKey>]]) para escapar à mesma na consulta, semelhante à estratégia de consulta com palavras-chave reservadas.

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 duplo se o duplo cumprir qualquer uma destas condições:

• O duplo implementa diretamente o modelo fornecido em IS_OF_MODEL()e o número da versão do modelo no duplo duplo é maior ou igual ao número da 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 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 de 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 é utilizada uma JOIN ), 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 associadas 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.

Consultar 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 de destino das relações. Eis um exemplo de uma consulta que localiza os duplos-alvo das feeds relações provenientes do duplo 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 na 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, observe como reportedCondition é uma propriedade da servicedBy própria relação (NÃO de um duplo digital que tenha uma servicedBy relação).

Consultar com vários JOINs

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

Para consultar em vários 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 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

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. Seguem-se alguns exemplos de contagem com um filtro aplicado com base no tipo de modelo duplo (para obter mais informações sobre esta sintaxe, veja 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 "principais" 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 instrução SELECT , 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 de 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 alia 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 consultar com o IN operador.

Por exemplo, considere um cenário em que os 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 (denominado 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 consulta composta

Pode combinar qualquer um dos tipos de consulta acima através de operadores de combinação para incluir mais detalhes numa única consulta. Eis 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 que tenham uma relação com Contains outro 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 piso11

  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 para a 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 devolução dos seus dados para cada consulta dependerá dos termos que especificar com a SELECT instrução:

• As consultas que começam por SELECT * FROM ... devolverão 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 ... devolverão 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

A consulta chama a paginação de suporte. 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 que é utilizada para executar as consultas a partir deste artigo.