Azure Digital Twins ikiz grafiğini sorgulama

Bu makalede, bilgi için ikiz grafınızısorgulamak için Azure Digital Twins sorgu dilini kullanmaya yönelik sorgu örnekleri ve yönergeler sunulmaktadır. (Sorgu diline giriş için bkz. Sorgu dili.)

Makale, dijital ikizler için sorgu dili yapısını ve yaygın sorgu işlemlerini gösteren örnek sorgular içerir. Ayrıca, Azure Digital Twins Sorgu API'si veya SDKkullanarak sorgularınızı yazdıktan sonra nasıl çalıştırabileceğiniz açıklanır.

Not

Aşağıdaki örnek sorguları bir API veya SDK çağrısıyla çalıştırırsanız, sorgu metnini tek bir satırda daraltmanız gerekir.

Başvuru belgeleri

Sorgu Dili Başvurusu, Azure Digital Twins belgelerinin sol taraftaki içindekiler tablosunda Reference bölümünde bulunabilir. Aşağıdaki bağlantıları kullanarak doğrudan başvuru bölümlerine de gidebilirsiniz:

• Maddeler
  • SELECT
  • KİMDEN
  • MAÇ
  • BİRLEŞTİRMEK
  • WHERE
• İşlevler
• İşleçler
• Ayrılmış anahtar sözcükler

Tüm dijital ikizleri göster

Örnekteki tüm dijital ikizlerin listesini döndüren temel sorgu aşağıdadır:

SELECT * FROM DIGITALTWINS

Özelliğe göre sorgulama

Özelliklere göre (kimlik ve meta veriler dahil) dijital ikizleri edinin:

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

Önceki sorguda gösterildiği gibi, $dtIdmeta veri alanı kullanılarak dijital ikizin kimliği sorgulanır.

Tavsiye

$ile başlayan metaveri alanlarıyla bir sorgu çalıştırmak için Cloud Shell kullanıyorsanız, Cloud Shell'e bunun bir değişken olmadığını ve sorgu metninde sabit bir değer olarak kullanılması gerektiğini bildirmek için $ karakterini ters eğik çizgiyle kaçış yapmalısınız.

Ayrıca, belirli bir özelliğin tanımlanıp tanımlanmadığını temel alarak ikizleri de alabilirsiniz. İşte tanımlanmış bir özelliği olan ikizleri alan bir sorguLocation:

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(Location)

Bu sorgu, dijital ikizlere tag etiket ekleme bölümünde açıklandığı gibi özelliklerine göre ikizleri almanıza yardımcı olabilir. İşte red ile etiketlenmiş tüm ikizleri getiren bir sorgu:

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

Bir özelliğin türüne göre ikizler de alabilirsiniz. Özelliği sayı olan Temperature ikizleri alan bir sorgu aşağıdadır:

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

Sorgu Haritası özellikleri

Bir özellik karmaşık türdeyse Map, eşleme anahtarlarını ve değerlerini doğrudan sorguda kullanabilirsiniz, örneğin:

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

Eşleme anahtarı sayısal bir karakterle başlıyorsa, anahtarı ayrılmış anahtar sözcüklerlesorgulama stratejisine benzer şekilde sorgudan kaçmak için çift köşeli ayraç ([[<mapKey>]]) içine sarmalamanız gerekir.

Modele göre sorgulama

IS_OF_MODEL İşleç, ikizin modeline göre filtrelemek için kullanılabilir.

Miras ve model sürümlendirmeyi dikkate alır ve ikiz aşağıdaki koşullardan birini karşılıyorsa, belirli bir ikiz için olarak değerlendirilir.

• İkiz, sağlanan modeli IS_OF_MODEL() doğrudan uygular ve ikizdeki modelin sürüm numarası, sağlanan modelin sürüm numarasından büyük ya da eşittir.
• İkiz, sağlanan modeli 'ye IS_OF_MODEL()genişleten bir model uygular ve ikizin genişletilmiş model sürüm numarası, sağlanan modelin sürüm numarasından büyük veya buna eşit

Örneğin, dtmi:example:widget;4modelinin ikizlerini sorgularsanız, sorgu, pencere öğesi modelinin 4 veya daha yüksek bir sürümüne dayanan tüm ikizleri ve ayrıca pencere öğesinden devralan herhangi bir modelin 4 veya daha üstü sürümüne dayanan ikizleri döndürür.

IS_OF_MODEL birkaç farklı parametre alabilir ve bu bölümün geri kalanı farklı aşırı yükleme seçeneklerine ayrılmıştır.

en basit kullanımı IS_OF_MODEL yalnızca bir twinTypeName parametre alır: IS_OF_MODEL(twinTypeName). Bu parametrede bir değer geçiren bir sorgu örneği aşağıda verilmiştir:

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

Birden fazla ikiz koleksiyonu olduğunda (örneğin, bir JOIN kullanıldığında), aranacak ikiz koleksiyonu belirtmek için twinCollection parametresini ekleyin: IS_OF_MODEL(twinCollection, twinTypeName). Bu parametre için değer ekleyen bir sorgu örneği aşağıda verilmişti:

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

Tam eşleşme yapmak için parametresini exact ekleyin: IS_OF_MODEL(twinTypeName, exact). Bu parametre için değer ekleyen bir sorgu örneği aşağıda verilmişti:

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

Ayrıca üç bağımsız değişkeni de birlikte geçirebilirsiniz: IS_OF_MODEL(twinCollection, twinTypeName, exact). Üç parametre için de bir değer belirten bir sorgu örneği aşağıda verilmiştir:

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

İlişkiye göre sorgulama

Dijital ikizlerin ilişkilerini temel alarak sorgulamak için Azure Digital Twins sorgu dili özel bir söz dizimi sağlar.

İlişkiler, FROM yan tümcesinde sorgu kapsamına çekilir. "Klasik SQL türü dillerindeki gibi değil, FROM tümcesindeki her ifade bir tablo değil; bunun yerine FROM tümcesi, çapraz varlık ilişkisi geçişini ifade eder." Azure Digital Twins, ilişkiler arasında geçiş yapmak için JOIN'in özel bir sürümünü kullanır.

Azure Digital Twins modeli özellikleriyle ilişkilerin ikizlerden bağımsız olarak var olamayacağını hatırlayın. Sonuçta ilişkiler bağımsız olarak sorgulanamaz ve bir ikize bağlı olmalıdır. Bu gerçeği yansıtmak için, RELATED anahtar sözcüğü, JOIN yan tümcesinde, ikiz koleksiyonundan gelen belirli bir ilişki türü kümesini çekmek için kullanılır. Ardından sorgunun, ilişki sorgusunda hangi ikizlerin kullanılacağını (ikizlerin $dtId değerlerini kullanarak) belirtmek için WHERE koşulunda filtrelemesi gerekir.

Aşağıdaki bölümlerde bunun nasıl göründüğüne ilişkin örnekler verilmiştir.

Temel ilişki sorgusu

İşte ilişki tabanlı örnek bir sorgu. Bu kod parçacığı, ID özelliğine sahip tüm dijital ikizleri ve contains ilişkisi aracılığıyla bu dijital ikizlerle ilgili olan tüm dijital ikizleri seçer.

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

İlişkinin türü (önceki örnektecontains), DTDL tanımıilişkinin name alanı kullanılarak belirtilir.

Not

Geliştiricinin bu JOIN ile WHERE yan tümcesindeki bir anahtar değer arasında bir ilişki kurmasına (ya da JOIN tanımında metin içinde bir anahtar değeri belirtmesine) gerek yoktur. İlişki özellikleri hedef varlığı tanımladıkça sistem bu bağıntıyı otomatik olarak hesaplar.

İlişkinin kaynağına veya hedeflerine göre sorgulama

İlişkinin kaynağı veya hedefi olan bir dijital ikizi tanımlamak için ilişki sorgu yapısını kullanabilirsiniz.

Örneğin, bir kaynak ikiz ile başlayıp ilişkilerini izleyerek ilişkilerin hedef ikizlerini bulabilirsiniz. burada, ikiz kaynak ikizinden gelen ilişkilerin hedef ikizlerini feeds bulan bir sorgu örneği verilmiştir.

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

Ayrıca, ilişkinin hedefiyle başlayabilir ve kaynak ikizini bulmak için ilişkiyi geri izleyebilirsiniz. Burada, ikiz hedef ikizine ilişkinin kaynak ikizini bulan bir feeds sorgu örneği verilmiş.

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

Bir ilişkinin özelliklerini sorgulama

Dijital ikizlerin DTDL aracılığıyla açıklanan özelliklere sahip olması gibi ilişkiler de özelliklere sahip olabilir. İkizleri, ilişkilerinin özelliklerine göre sorgulayabilirsiniz. Azure Digital Twins sorgu dili, JOIN cümlesi içindeki ilişkiye bir diğer ad atayarak ilişkilerin filtrelenmesine ve yansıtılmasına olanak tanır.

Örneğin, servicedBy üzerinde bir reportedCondition özelliği olan bir ilişkiyi göz önünde bulundurun. Aşağıdaki sorguda, bu ilişkiye özelliğine atıfta bulunmak için R takma adı verilir.

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

Önceki örnekte, reportedCondition'nin servicedBy ilişkisinin kendisinin bir özelliği olduğuna dikkat edin (bazı servicedBy ilişkisi olan dijital ikizin DEĞİLDİR).

Birden çok JOIN içeren sorgu

Tek bir sorguda beş JOIN adede kadar desteklenir, bu da aynı anda birden fazla ilişki seviyesini geçmenizi sağlar.

Birden çok ilişki düzeyini sorgulamak için tek FROM bir deyim ve ardından N JOIN deyimleri kullanın; burada JOIN deyimler önceki FROM veya JOIN deyimin sonucuyla ilişkileri ifade eder.

Burada, 1 ve 2. odalardaki ışık panellerinde bulunan tüm ampulleri alan çoklu birleşim sorgusu örneği verilmiştir.

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']

Öğeleri sayma

Yan tümcesini kullanarak Select COUNT bir sonuç kümesindeki öğe sayısını sayabilirsiniz:

SELECT COUNT()
FROM DIGITALTWINS

Belirli bir WHERE ölçüte uyan öğe sayısını saymak için bir yan tümce ekleyin. Aşağıdaki örneklerde, ikiz modelinin türüne göre uygulanan filtreyle sayma gösterilmektedir. Bu söz dizimi hakkında daha fazla bilgi için bkz. modele göre sorgulama.

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

COUNT ifadesini JOIN maddesiyle birlikte de kullanabilirsiniz. 1. ve 2. odaların ışık panellerinde bulunan tüm ampulleri sayan bir sorgu aşağıdadır:

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']

Sonuçları filtrele: en çok kullanılan öğeleri seçin

Sorgudaki birkaç "en üst" öğeyi yan tümcesini kullanarak Select TOP seçebilirsiniz.

SELECT TOP (5)
FROM DIGITALTWINS
WHERE ...

Sonuçları filtrele: projeksiyonlar kullanarak dönüş kümesini belirtin

SELECT deyimindeki projeksiyonları kullanarak, sorgunun döndürdüğü sütunları seçebilirsiniz. Projeksiyon artık hem ilkel hem de karmaşık özellikler için desteklenmektedir. Azure Digital Twins ile projeksiyonlar hakkında daha fazla bilgi için SELECT yan tümcesi başvuru belgelerine bakın.

burada ikizleri ve ilişkileri döndürmek için projeksiyon kullanan bir sorgu örneği verilmiştir. Aşağıdaki sorgu, bir Factory.customer ilişkisi aracılığıyla ABC kimliğine sahip olan bir Fabrika'nın Tüketici ile ve bu ilişki de Edge olarak sunulduğu bir senaryodan Tüketici, Fabrika ve Edge'in projeksiyonunu oluşturur.

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

Bir ikizin özelliğini döndürmek için projeksiyonu da kullanabilirsiniz. Aşağıdaki sorgu, kimliği ABC olan Fabrika ile Factory.customer ilişkisi aracılığıyla ilişkili Tüketicilerin Name özelliğini projelendirir.

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

Bir ilişkinin özelliğini döndürmek için projeksiyonu da kullanabilirsiniz. Önceki örnekte olduğu gibi, aşağıdaki sorgu, kimliği ABC olan Factory ile ilişkili Tüketiciler'in Name özelliğini, Factory.customer ilişkisi aracılığıyla projelendiriyor; ancak şimdi bu ilişkinin prop1 ve prop2 olmak üzere iki özelliğini de döndürüyor. Sorgu, Edge adlı ilişkiyi kullanarak ve özelliklerini toplayarak bu iki özelliği döndürür.

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

Projeksiyonla sorguları basitleştirmek için diğer adları da kullanabilirsiniz.

Aşağıdaki sorgu, önceki örnekle aynı işlemleri yapar, ancak özellik adlarını consumerName, first, second ve factoryArea olarak adlandırır.

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'

Önceki sorguyla aynı kümeyi sorgulayan ancak yalnızca Consumer.name özelliğini consumerNameolarak projeleyen ve tüm Factory'yi ikiz olarak projeleyen benzer bir sorgu aşağıda gösterilmiştir.

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

IN işleciyle verimli sorgular oluşturma

bir dizi ikiz oluşturup işleciyle IN sorgulayarak ihtiyacınız olan sorgu sayısını önemli ölçüde azaltabilirsiniz.

Örneğin, Binaların Katları ve Katların Odaları içerdiği bir senaryoyu düşünün. Bina içinde sıcak olan odaları aramak için bu adımları izlemenin bir yolu vardır.

1. Binadaki katları contains ilişkisine göre bulun.

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

2. Odaları bulmak için, katları tek tek düşünmek ve her birinin odalarını bulmak için bir JOIN sorgusu çalıştırmak yerine, binadaki katların bir koleksiyonuyla sorgulayabilirsiniz (aşağıdaki sorguda Floor adlı).

   İstemci uygulamasında:

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

   Sorguda:

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

Diğer bileşik sorgu örnekleri

Daha önce açıklanan sorgu türlerinden herhangi birini birleşim işleçlerini kullanarak birleştirerek tek bir sorguya daha fazla ayrıntı ekleyebilirsiniz. Bir kerede birden fazla ikiz tanımlayıcı türünü sorgulayan bileşik sorgulara ilişkin diğer bazı örnekler aşağıda verilmiştir.

• Room 123'ün sahip olduğu cihazlardan, Operatör rolünü üstlenen MxChip cihazlarını geri verin

  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'
  

• id1 kimliğine sahip başka bir ikizle Contains adlı ilişkisi bulunan ikizleri alın

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

• Bu oda modelinin kat11 tarafından kapsanan tüm odalarını edinin.

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

API ile sorgu çalıştırma

Bir sorgu dizesine karar verdikten sonra, Sorgu API'sine bir çağrı yaparak bu dizeyi yürütürsiniz.

API'yi doğrudan çağırabilir veya Azure Digital Twins için kullanılabilen SDK'lardan birini kullanabilirsiniz.

Aşağıdaki kod parçacığı, bir istemci uygulamasından gelen .NET (C#) SDK çağrısını gösterir:

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

Bu çağrıda kullanılan sorgu, önceki örneğin BasicDigitalTwin nesneleriyle temsil ettiği dijital ikizlerin listesini döndürür. Her sorgu için verilerinizin dönüş türü, SELECT deyimiyle hangi terimleri belirttiğinize bağlıdır:

• SELECT * FROM ... ile başlayan sorgular, dijital ikizlerin listesini döndürür (BasicDigitalTwin nesneler veya oluşturabileceğiniz diğer özel dijital ikiz türleri olarak seri hale getirilebilir).
• biçiminde başlayan sorgular SELECT <A>, <B>, <C> FROM ...<A>, <B>ve <C>anahtarlarıyla bir sözlük döndürür.
• Özel veri döndürmek için başka deyim biçimleri SELECT oluşturulabilir. Özelleştirilmiş sonuç kümelerini işlemek için kendi sınıflarınızı oluşturmayı düşünebilirsiniz.

Sayfalama ile sorgulama

Sorgu çağrıları sayfalandırmayı destekler. Burada hata işleme ve sayfalama ile sorgu sonuç türü olarak kullanan BasicDigitalTwin tam bir örnek verilmiştir:

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

Sonraki adımlar

Bu makaledeki sorguları çalıştırmak için kullanılan Sorgu API'si de dahil olmak üzere Azure Digital Twins API'leri ve SDK'ları hakkında daha fazla bilgi edinin.