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'sini veya SDK'yı kullanarak sorgularınızı yazdıktan sonra nasıl çalıştırabileceğiniz açıklanır.

Başvuru belgeleri

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

• Yan tümce
  • SELECT
  • FROM
  • 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ürecek 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

Yukarıdaki sorguda gösterildiği gibi, meta veri alanı $dtIdkullanılarak dijital ikizin kimliği sorgulanır.

Ayrıca, belirli bir özelliğin tanımlanıp tanımlanmadığını temel alarak ikizleri de alabilirsiniz. Tanımlanmış özelliği olan ikizleri alan bir sorgu aşağıdadır Location :

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. Tüm ikizleri ile redetiketleyen bir sorgu aşağıdadır:

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

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

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

Sorgu Eşlemesi ö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üklerle sorgulama stratejisine benzer şekilde sorguda 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.

Devralma ve model sürümü oluşturmayı dikkate true alır ve ikiz aşağıdaki koşullardan birini karşılıyorsa belirli bir ikiz için olarak değerlendirilir:

• İkiz, için sağlanan IS_OF_MODEL()modeli doğrudan uygular ve ikizdeki modelin sürüm numarası sağlanan modelin sürüm numarasından büyük veya buna eşit
• İ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, modelin dtmi:example:widget;4ikizlerini sorgularsanız, sorgu pencere öğesi modelinin 4 veya üzeri sürümüne göre tüm ikizleri ve pencere öğesinden devralan modellerin 4. veya daha üstünü temel alan 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 olduğunda (örneğin, kullanıldığında) aranacak bir JOIN ikiz koleksiyonu belirtmek için parametresini twinCollection 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

Azure Digital Twins sorgu dilinde dijital ikizleri ilişkilerine göre sorgulamak için kullanılacak özel bir söz dizimi vardır.

İlişkiler, FROM yan tümcesinde sorgu kapsamına çekilir. "Klasik" SQL türü dillerinden farklı olarak yan tümcesindeki FROM her ifade bir tablo değildir; yan FROM tümcesi bir çapraz varlık ilişkisi geçişi ifade eder. Azure Digital Twins, ilişkiler arasında geçiş yapmak için özel bir sürümünü JOINkullanır.

Azure Digital Twins modeli özellikleriyle ilişkilerin ikizlerden bağımsız olarak mevcut olmadığını, yani buradaki ilişkilerin bağımsız olarak sorgulanamayacağını ve bir ikize bağlı olması gerektiğini unutmayın. Bu gerçeği yansıtmak için anahtar sözcüğü RELATED yan tümcesinde JOIN , ikiz koleksiyonundan gelen belirli bir ilişki türü kümesini çekmek için kullanılır. Sorgunun daha sonra ilişki sorgusunda WHERE hangi ikizlerin kullanılacağını (ikizlerin $dtId değerlerini kullanarak) belirtmek için yan tümcesinde 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ığı özelliği olan tüm dijital ikizleri ve bir IDABCcontains ilişki aracılığıyla bu dijital ikizlerle ilgili 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ü (containsyukarıdaki örnekte) DTDL tanımından ilişkinin name alanı kullanılarak belirtilir.

İ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 ikizlerde DTDL aracılığıyla tanımlanan özelliklere benzer şekilde ilişkiler de özelliklere sahip olabilir. İkizleri, ilişkilerinin özelliklerine göre sorgulayabilirsiniz. Azure Digital Twins sorgu dili, yan tümcesindeki ilişkiye bir diğer ad atayarak ilişkilerin JOIN filtrelenmesine ve yansıtılmasına olanak tanır.

Örneğin, özelliği olan bir servicedByreportedCondition ilişkiyi göz önünde bulundurun. Aşağıdaki sorguda, bu ilişkiye özelliğine başvurmak R için bir diğer adı verilir.

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

Yukarıdaki örnekte, ilişkinin kendisinin özelliğinin servicedBy nasıl olduğuna (ilişkisi olan servicedBy bazı dijital ikizlerin DEĞİlDİ) nasıl reportedCondition olduğuna dikkat edin.

Birden çok JOIN içeren sorgu

Tek bir sorguda beş JOINadede kadar sn desteklenir ve bu sayede aynı anda birden çok ilişki düzeyi arasında geçiş yapmanızı 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. İkiz modelin türüne göre uygulanan filtreyle sayma örnekleri aşağıda verilmiştir (bu söz dizimi hakkında daha fazla bilgi için aşağıdaki Modele göre sorgulama bölümüne bakın):

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

Yan tümcesiyle JOIN birlikte de kullanabilirsinizCOUNT. 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

Yan tümcesini kullanarak sorgudaki birkaç "üst" öğeyi Select TOP seçebilirsiniz.

SELECT TOP (5)
FROM DIGITALTWINS
WHERE ...

Sonuçları filtrele: yansıtmalarla dönüş kümesini belirtin

deyimindeki projeksiyonları kullanarak, sorgunun SELECT hangi sütunları döndüreceğini 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, Tüketici, Fabrika ve Edge'i, kimliğine sahip bir Fabrika'nın ABC bir ilişkisi aracılığıyla Tüketici ile ilişkilendirildiği ve bu ilişkinin olarak sunulduğu bir senaryodan Factory.customerprojesini Edgeoluş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, Bir ilişkisi aracılığıyla kimliğiyle Fabrika ile ilgili Tüketicilerin ABCFactory.customerözelliğini projelerName.

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, Factory ile ilgili Tüketiciler özelliğini bir ilişkisi aracılığıyla kimliğiyle ABC projelendiriyorName, ancak şimdi bu ilişkinin prop1 iki özelliğini de döndürüyor ve prop2.Factory.customer Bunu, ilişkiyi Edge adlandırarak ve özelliklerini toplayarak yapar.

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ı , , firstsecondve factoryAreaolarak consumerNameadlandırmaktadı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'

Yukarıdakiyle aynı kümeyi sorgulayan ancak yalnızca özelliğini olarak projeleyen ve fabrikanın Consumer.name tamamını ikiz olarak consumerNameprojeleyen 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 senaryo düşünün. Bina içinde sıcak olan odaları aramak için bu adımları izlemenin bir yolu vardır.

1. İlişkiye göre binadaki zeminleri contains 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 sorgu çalıştırmak yerine, binadaki katların bir koleksiyonuyla sorgulayabilirsiniz (aşağıdaki sorguda Floor olarak adlandırılır).

   İ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

Tek bir sorguya daha fazla ayrıntı eklemek için birleşim işleçlerini kullanarak yukarıdaki sorgu türlerinden herhangi birini birleştirebilirsiniz. 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üne hizmet eden MxChip cihazlarını döndür

  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'
  

• Kimliği olan başka bir ikizle adlı Contains ilişkisi olan ikizleri alma id1

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

• Bu oda modelinin kat tarafından kapsanan tüm odalarını edinin11

  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, yukarıdaki örnekte BasicDigitalTwin nesneleriyle temsil edilen dijital ikizlerin listesini döndürür. Her sorgu için verilerinizin dönüş türü, deyimiyle hangi terimleri belirttiğinize SELECT bağlıdır:

• ile SELECT * FROM ... başlayan sorgular, dijital ikizlerin listesini döndürür (nesneler olarak BasicDigitalTwin serileştirilebilir veya oluşturmuş olabileceğiniz diğer özel dijital ikiz türleri).
• Biçiminde SELECT <A>, <B>, <C> FROM ... başlayan sorgular , <B>ve <C>anahtarlarını <A>içeren bir sözlük döndürür.
• Özel veri döndürmek SELECT için diğer deyim biçimleri 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.