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.
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 (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ı $dtId
kullanılarak dijital ikizin kimliği sorgulanır.
İpucu
Ile başlayan $
meta veri alanlarıyla bir sorgu çalıştırmak için Cloud Shell kullanıyorsanız, Cloud Shell'e 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çış yapmalısınız $
.
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 red
etiketleyen 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;4
ikizlerini 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ü JOIN
kullanı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 ID
ABC
contains
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ü (contains
yukarıdaki örnekte) DTDL tanımından ilişkinin name
alanı kullanılarak belirtilir.
Not
Geliştiricinin bunu JOIN
yan tümcesindeki WHERE
bir anahtar değeriyle ilişkilendirmesi (veya tanım ile satır içinde bir anahtar değeri belirtmesi JOIN
) gerekmez. İ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 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 servicedBy
reportedCondition
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ş JOIN
adede 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.customer
projesini Edge
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, Bir ilişkisi aracılığıyla kimliğiyle Fabrika ile ilgili Tüketicilerin ABC
Factory.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ı , , first
second
ve factoryArea
olarak consumerName
adlandı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 consumerName
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 senaryo düşünün. Bina içinde sıcak olan odaları aramak için bu adımları izlemenin bir yolu vardır.
İlişkiye göre binadaki zeminleri
contains
bulun.SELECT Floor FROM DIGITALTWINS Building JOIN Floor RELATED Building.contains WHERE Building.$dtId = @buildingId
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 almaid1
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 olarakBasicDigitalTwin
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.