Azure Digital Twins ikiz grafını sorgulama

  • Makale

Bu makalede, bilgi için ikiz grafınızı sorgulamak üzere 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 de açıklanır.

Not

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

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:

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 dijital ikizleri alın (kimlik ve meta veriler dahil):

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, dijital ikizin kimliği meta veri alanı $dtIdkullanılarak sorgulanır.

İpucu

ile başlayan $meta veri alanlarıyla bir sorgu çalıştırmak için Cloud Shell kullanıyorsanız, Cloud Shell değişken olmadığını ve sorgu metninde değişmez değer olarak kullanılması gerektiğini bildirmek için ters eğik çizgiyle kaçış karakteri kullanmanız gerekir$.

Ayrıca belirli bir özelliğin tanımlanıp tanımlanmadığına bağlı olarak ikizleri de alabilirsiniz. Tanımlı özelliğe sahip ikizleri alan bir sorgu aşağıdadır Location :

SELECT *​ FROM DIGITALTWINS WHERE IS_DEFINED(Location)

Bu sorgu, Dijital ikizlere etiket ekleme bölümünde açıklandığı gibi ikizleri tagözelliklerine göre almanıza yardımcı olabilir. Tüm ikizleri ile redetiketleyen bir sorgu aşağıdadır:

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

Ayrıca 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 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>'

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

Modele göre sorgulama

İşleç, IS_OF_MODEL 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 ikiz üzerindeki modelin sürüm numarası, sağlanan modelin sürüm numarasından büyük veya buna eşit
  • İkiz, sağlanan modeli ile 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

Bu nedenle örneğin, modelin dtmi:example:widget;4ikizlerini sorgularsanız sorgu, pencere öğesi modelinin 4 veya daha sonraki bir sürümüne göre tüm ikizleri ve pencere öğesinden devralan modellerin 4. veya daha sonraki bir sürümü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 parametredeki bir değeri 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ştir:

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ştir:

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 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ündeki dillerden farklı olarak yan tümcesindeki FROM her ifade bir tablo değildir; bunun yerine 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 olguyu yansıtmak için, ikiz koleksiyonundan gelen belirli bir ilişki türü kümesini çekmek için yan tümcesinde anahtar sözcüğü RELATED kullanılır JOIN . Sorgunun, ilişki sorgusunda WHERE hangi ikizlerin kullanılacağını (ikizlerin $dtId değerlerini kullanarak) belirtmek için yan tümcesinde filtreleme yapması gerekir.

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

Temel ilişki sorgusu

İlişki tabanlı örnek bir sorgu aşağıda verilmiştır. Bu kod parçacığı özelliğine sahip 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ındaki ilişki name alanı kullanılarak belirtilir.

Not

Geliştiricinin bunu JOIN yan tümcedeki WHERE bir anahtar değeriyle ilişkilendirmesi gerekmez (veya tanımla JOIN satır içinde bir anahtar değeri belirtin). İlişki özellikleri hedef varlığı tanımladığından bu bağıntı sistem tarafından otomatik olarak hesaplanır.

İ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 ikizle başlayıp ilişkileri takip ederek ilişkilerin hedef ikizlerini bulabilirsiniz. Aşağıda, 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. Aşağıda, ikiz hedef ikizine ilişkin bir ilişkinin kaynak ikizini bulan bir feeds sorgu örneği verilmiştir.

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ümcesi içindeki JOIN ilişkiye bir diğer ad atayarak ilişkilerin filtrelenmesine ve yansıtılmasına olanak tanır.

Örneğin, özelliği olan bir servicedByreportedCondition ilişkiyi düşünün. 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 özelliğinin servicedBy nasıl reportedCondition olduğuna dikkat edin (ilişkisi olan servicedBy bazı dijital ikizlerin DEĞİlDİ).

Birden çok JOIN ile sorgulama

Tek bir sorguda beş JOINadede kadar sn desteklenir ve bu sayede aynı anda birden çok ilişki düzeyinde dolaşmanız sağlanır.

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 bir sonuç kümesindeki Select COUNT öğ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 işlemine ilişkin bazı örnekler 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']

Filtre sonuçları: en çok kullanılan öğeleri seçme

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

SELECT TOP (5)
FROM DIGITALTWINS
WHERE ...

Sonuçları filtrele: yansıtmalarla dönüş kümesi belirtme

Deyimdeki 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.

aşağıda ikizleri ve ilişkileri döndürmek için projeksiyon kullanan bir sorgu örneği verilmiştir. Aşağıdaki sorgu, Consumer, Factory ve Edge'i, kimliğine sahip bir Fabrika'nın ABC bir ilişkisi aracılığıyla Tüketici ile ilişkili olduğu ve bu ilişkinin olarak sunulduğu bir senaryodan Factory.customerprojelendiriyor Edge.

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

İkizin bir özelliğini döndürmek için projeksiyonu da kullanabilirsiniz. Aşağıdaki sorgu, Factory ile ilişkili Olan Tüketicilerin özelliğini bir ilişkisi aracılığıyla kimliğiyle ABC projelendiriyor.NameFactory.customer

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, Fabrika 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'

Aşağıda yukarıdakiyle aynı kümeyi sorgulayan, ancak yalnızca olarak özelliğini ve fabrikanın Consumer.name tamamını ikiz olarak consumerNameprojeleyen benzer bir sorgu bulunmaktadır.

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 binada zeminler 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 katlardan oluşan bir koleksiyonla 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

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. Burada, aynı anda birden fazla tür ikiz tanımlayıcısı sorgulayan bileşik sorguların diğer örnekleri 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 bir ilişkiye sahip ikizleri alma id1
    SELECT Room
FROM DIGITALTWINS Room
JOIN Thermostat RELATED Room.Contains
WHERE Thermostat.$dtId = 'id1'
  • Bu oda modelinin floor11 içindeki tüm odalarını alın
    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 yapılan .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 seri hale getirilebilir 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 için diğer 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.

Disk belleği ile sorgulama

Sorgu çağrıları sayfalandırmayı destekler. Hata işleme ve sayfalama ile sorgu sonuç türü olarak kullanan BasicDigitalTwin tam bir örnek aşağıda 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.