Kueri grafik kembar Azure Digital Twins

Artikel ini menawarkan contoh kueri dan instruksi untuk menggunakan bahasa kueri Azure Digital Twins untuk meminta informasi pada grafik kembar Anda. (Untuk pengenalan bahasa kueri, lihat Bahasa kueri.)

Artikel berisi kueri sampel yang menggambarkan struktur bahasa kueri dan operasi kueri umum untuk kembar digital. Ini juga menjelaskan cara menjalankan kueri setelah Anda menulisnya, menggunakan Azure Digital Twins Query API atau SDK.

Catatan

Jika Anda menjalankan contoh kueri di bawah ini dengan API atau panggilan SDK, Anda harus mengembun teks kueri ke dalam satu baris.

Dokumentasi rujukan

Referensi bahasa kueri dapat ditemukan di Referensi di daftar isi kiri untuk dokumentasi Azure Digital Twins. Anda juga dapat langsung masuk ke bagian referensi menggunakan tautan di bawah ini:

• Klausul
  • PILIH
  • DARI
  • PERTANDINGAN
  • IKUTI
  • DI MANA
• Fungsi
• Operator
• Kata Kunci yang Dicadangkan

Tampilkan semua kembar digital

Berikut adalah kueri dasar yang akan menampilkan daftar semua kembar digital dalam instans:

SELECT * FROM DIGITALTWINS

Kueri menurut properti

Dapatkan kembar digital berdasarkan properti (termasuk ID dan metadata):

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

Seperti yang diperlihatkan dalam kueri di atas, ID kembar digital dikueri menggunakan bidang metadata $dtId.

Tip

Jika Anda menggunakan Cloud Shell untuk menjalankan kueri dengan bidang metadata yang dimulai dengan $, Anda harus menghindari $ dengan garis miring terbalik untuk memberi tahu Cloud Shell bahwa itu bukan variabel dan harus digunakan sebagai harfiah dalam teks kueri.

Anda juga bisa mendapatkan anak kembar berdasarkan apakah properti tertentu didefinisikan. Berikut adalah kueri yang mendapatkan kembar yang memiliki properti yang ditentukan Location :

SELECT *​ FROM DIGITALTWINS WHERE IS_DEFINED(Location)

Kueri ini dapat membantu Anda mendapatkan kembar berdasarkan propertinya tag , seperti yang dijelaskan dalam Menambahkan tag ke kembar digital. Berikut adalah kueri yang membuat semua kembar ditandai dengan red:

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

Anda juga bisa mendapatkan anak kembar berdasarkan jenis properti. Berikut adalah kueri yang mendapatkan kembar yang propertinya Temperature adalah angka:

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

Properti Peta Kueri

Jika properti berjenis Mapkompleks , Anda bisa menggunakan kunci dan nilai peta secara langsung dalam kueri, seperti ini:

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

Jika kunci peta dimulai dengan karakter numerik, Anda harus membungkus kunci dalam tanda kurung siku ganda ([[<mapKey>]]) untuk menghindarinya dalam kueri, mirip dengan strategi untuk mengkueri dengan kata kunci yang dipesan.

Kueri menurut model

Operator IS_OF_MODEL dapat digunakan untuk memfilter berdasarkan model kembar.

Ini mempertimbangkan pewarisan dan penerapan versi model, dan mengevaluasi untuk kembaran true tertentu jika kembar memenuhi salah satu kondisi ini:

• Kembar langsung mengimplementasikan model yang disediakan untuk IS_OF_MODEL(), dan nomor versi model pada kembar lebih besar dari atau sama dengan nomor versi model yang disediakan
• Kembar mengimplementasikan model yang memperluas model yang disediakan untuk IS_OF_MODEL(), dan nomor versi model yang diperluas kembar lebih besar dari atau sama dengan nomor versi model yang disediakan

Jadi misalnya, jika Anda meminta kembar model dtmi:example:widget;4, kueri akan mengembalikan semua kembar berdasarkan versi 4 atau lebih besar dari model widget, dan juga kembar berdasarkan versi 4 atau lebih besar dari model apa pun yang mewarisi dari widget.

IS_OF_MODEL dapat mengambil beberapa parameter yang berbeda, dan bagian ini lainnya didedikasikan untuk berbagai opsi kelebihan beban.

Penggunaan paling sederhana IS_OF_MODEL hanya membutuhkan twinTypeName parameter: IS_OF_MODEL(twinTypeName). Berikut adalah contoh kueri yang meneruskan nilai dalam parameter ini:

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

Untuk menentukan koleksi kembar yang akan dicari saat ada lebih dari satu (seperti saat JOIN digunakan), tambahkan parameter twinCollection: IS_OF_MODEL(twinCollection, twinTypeName). Berikut adalah contoh kueri yang menambahkan nilai untuk parameter ini:

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

Untuk melakukan kecocokan persis, tambahkan exact parameter: IS_OF_MODEL(twinTypeName, exact). Berikut adalah contoh kueri yang menambahkan nilai untuk parameter ini:

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

Anda juga dapat menyampaikan ketiga argumen bersama-sama: IS_OF_MODEL(twinCollection, twinTypeName, exact). Berikut adalah contoh kueri yang menentukan nilai untuk ketiga parameter:

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

Kueri menurut hubungan

Saat mengkueri berdasarkan hubungan kembar digital, bahasa kueri Azure Digital Twins memiliki sintaks khusus.

Hubungan ditarik ke dalam lingkup kueri dalam klausa FROM. Tidak seperti dalam bahasa jenis SQL "klasik", setiap ekspresi dalam klausul FROM bukanlah tabel; melainkan, klausul FROM mengungkapkan traversal hubungan lintas entitas. Untuk melintasi hubungan, Azure Digital Twins menggunakan versi kustom dari JOIN.

Ingatlah bahwa dengan kemampuan model Azure Digital Twins, hubungan tidak ada secara independen dari kembar, artinya hubungan di sini tidak dapat dikuerikan secara independen dan harus diikat ke kembar. Untuk mencerminkan fakta ini, kata kunci RELATED digunakan dalam klausul JOIN untuk menarik serangkaian jenis hubungan tertentu yang berasal dari kumpulan kembar. Kueri kemudian harus memfilter dalam klausul WHERE, untuk menunjukkan kembar spesifik mana yang akan digunakan dalam kueri hubungan (menggunakan nilai $dtId kembar).

Bagian berikut ini memberikan contoh seperti apa tampilan ini.

Kueri hubungan dasar

Berikut adalah sampel kueri berbasis hubungan. Cuplikan kode ini memilih semua kembar digital dengan ID properti ABC, dan semua kembar digital yang terkait dengan kembar digital ini melalui contains hubungan.

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

Jenis hubungan (contains dalam contoh di atas) ditunjukkan menggunakan bidang hubungan dari definisi DTDL-nyaname.

Catatan

Pengembang tidak perlu mengkorelasikan JOIN ini dengan nilai kunci dalam klausa WHERE (atau tentukan nilai kunci sejajar dengan definisi JOIN). Korelasi ini dihitung secara otomatis oleh sistem, karena properti hubungan itu sendiri mengidentifikasi entitas target.

Kueri menurut sumber atau target hubungan

Anda bisa menggunakan struktur kueri hubungan untuk mengidentifikasi kembaran digital yang menjadi sumber atau target hubungan.

Misalnya, Anda dapat memulai dengan kembaran sumber dan mengikuti hubungannya untuk menemukan kembar target hubungannya. Berikut adalah contoh kueri yang menemukan kembar target hubungan feeds yang berasal dari kembar sumber kembar.

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

Anda juga dapat memulai dengan target hubungan dan melacak hubungan kembali untuk menemukan kembar sumber. Berikut adalah contoh kueri yang menemukan kembar feeds sumber hubungan dengan kembar target-kembar.

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

Mengkueri properti hubungan

Demikian pula dengan cara kembar digital memiliki properti yang dijelaskan melalui DTDL, hubungan juga dapat memiliki properti. Anda dapat meminta kembar berdasarkan sifat hubungan mereka. Bahasa kueri Azure Digital Twins memungkinkan pemfilteran dan proyeksi hubungan, dengan menetapkan alias ke hubungan dalam klausa JOIN.

Sebagai contoh, pertimbangkan servicedBy hubungan yang memiliki reportedCondition properti . Dalam kueri di bawah ini, hubungan ini diberi alias R untuk mereferensikan propertinya.

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

Dalam contoh di atas, perhatikan bagaimana reportedCondition adalah properti dari hubungan itu servicedBy sendiri (BUKAN dari beberapa kembar digital yang memiliki servicedBy hubungan).

Kueri dengan beberapa JOIN

Hingga lima JOIN didukung dalam satu kueri, yang memungkinkan Anda melintasi beberapa tingkat hubungan sekaligus.

Untuk mengkueri beberapa tingkat hubungan, gunakan satu pernyataan FROM yang diikuti oleh pernyataan JOIN N, di mana pernyataan JOIN menyatakan hubungan pada hasil dari pernyataan FROM atau JOIN sebelumnya.

Berikut adalah contoh kueri multi-gabungan, yang mendapatkan semua bola lampu yang terdapat di panel lampu di ruang 1 dan 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']

Menghitung item

Anda bisa menghitung jumlah item dalam kumpulan hasil menggunakan klausa Select COUNT:

SELECT COUNT()
FROM DIGITALTWINS

Tambahkan klausa WHERE untuk menghitung jumlah item yang memenuhi kriteria tertentu. Berikut adalah beberapa contoh penghitungan dengan filter terapan berdasarkan tipe model kembar (untuk informasi selengkapnya tentang sintaks ini, lihat Kueri menurut model di bawah):

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

Anda juga dapat menggunakan COUNT bersama dengan klausa JOIN. Berikut adalah kueri yang menghitung semua bola lampu yang terdapat di panel lampu kamar 1 dan 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']

Hasil filter: pilih item teratas

Anda dapat memilih beberapa item "atas" dalam kueri menggunakan klausa Select TOP.

SELECT TOP (5)
FROM DIGITALTWINS
WHERE ...

Hasil filter: tentukan kembalian set dengan proyeksi

Dengan menggunakan proyeksi dalam pernyataan SELECT, Anda bisa memilih kolom mana yang akan dikembalikan kueri. Proyeksi sekarang didukung untuk properti primitif dan properti kompleks. Untuk informasi selengkapnya tentang proyeksi dengan Azure Digital Twins, lihat PILIH dokumentasi referensi klausa.

Berikut adalah contoh kueri yang menggunakan proyeksi untuk menampilkan kembar dan hubungan. Kueri berikut memproyeksikan Konsumen, Pabrik, dan Edge dari skenario di mana Pabrik dengan ID ABC terkait dengan Konsumen melalui hubungan Factory.customer, dan hubungan tersebut disajikan sebagai Edge.

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

Anda juga dapat menggunakan proyeksi untuk mengembalikan properti kembar. Kueri berikut memproyeksikan Name properti Konsumen yang terkait dengan Pabrik dengan ID ABC melalui hubungan Factory.customer.

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

Anda juga dapat menggunakan proyeksi untuk mengembalikan properti hubungan. Seperti dalam contoh sebelumnya, kueri berikut memproyeksikan Name properti Konsumen yang terkait dengan Pabrik dengan ID ABC melalui hubungan Factory.customer; tetapi sekarang juga mengembalikan dua properti hubungan itu, prop1 dan prop2. Ini dilakukan dengan menamai hubungan Edge dan mengumpulkan propertinya.

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

Anda juga dapat menggunakan alias untuk menyederhanakan kueri dengan proyeksi.

Kueri berikut ini melakukan operasi yang sama seperti contoh sebelumnya, tetapi alias nama properti menjadi consumerName, first, second, dan 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'

Berikut adalah kueri serupa yang mengkueri set yang sama seperti di atas, tetapi hanya memproyeksikan Consumer.name properti sebagai consumerName, dan memproyeksikan Factory lengkap sebagai kembar.

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

Membangun kueri yang efisien dengan operator IN

Anda dapat secara signifikan mengurangi jumlah kueri yang Anda butuhkan dengan membuat array kembar dan kueri dengan operator IN.

Misalnya, pertimbangkan skenario di mana Bangunan berisi Lantai dan Lantai berisi Kamar. Untuk mencari kamar di dalam gedung yang panas, salah satu caranya adalah dengan mengikuti langkah-langkah ini.

1. Temukan lantai di gedung berdasarkan hubungan contains.

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

2. Untuk menemukan ruang, alih-alih mempertimbangkan lantai satu per satu dan menjalankan kueri JOIN untuk menemukan ruangan untuk masing-masing ruangan, Anda dapat meminta dengan koleksi lantai di gedung (bernama Lantai dalam kueri di bawah).

   Aplikasi dalam klien:

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

   Dalam kueri:

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

Contoh kueri gabungan lainnya

Anda bisa menggabungkan salah satu tipe kueri di atas menggunakan operator kombinasi untuk menyertakan detail selengkapnya dalam satu kueri. Berikut adalah beberapa contoh kueri majemuk lainnya yang mengkueri lebih dari satu jenis pendeskripsi kembar sekaligus.

• Dari perangkat yang dimiliki Ruang 123, kembalikan perangkat MxChip yang melayani peran Operator

  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'
  

• Dapatkan kembar yang memiliki hubungan bernama Contains dengan kembar lain yang memiliki ID id1

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

• Dapatkan semua kamar model kamar ini yang terkandung oleh lantai11

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

Jalankan kueri dengan API

Setelah Anda memutuskan string kueri, Anda menjalankannya dengan melakukan panggilan ke API Kueri.

Anda dapat menghubungi API secara langsung, atau menggunakan salah satu SDK yang tersedia untuk Azure Digital Twins.

Cuplikan kode berikut mengilustrasikan panggilan .NET (C#) SDK dari aplikasi klien:

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

Kueri yang digunakan dalam panggilan ini mengembalikan daftar kembar digital, yang diwakili contoh di atas dengan objek BasicDigitalTwin. Tipe pengembalian data Anda untuk setiap kueri akan bergantung pada istilah apa yang Anda tentukan dengan pernyataan SELECT:

• Kueri yang dimulai dengan SELECT * FROM ... akan mengembalikan daftar kembar digital (yang dapat diserialisasikan sebagai BasicDigitalTwin objek, atau jenis kembar digital kustom lainnya yang mungkin telah Anda buat).
• Kueri yang dimulai dalam format SELECT <A>, <B>, <C> FROM ... akan mengembalikan kamus dengan kunci <A>, <B>, dan <C>.
• Format pernyataan SELECT lain dapat dibuat untuk mengembalikan data kustom. Anda dapat mempertimbangkan untuk membuat kelas Anda sendiri untuk menangani tataan hasil yang disesuaikan.

Kueri dengan halaman

Panggilan kueri mendukung halaman. Berikut adalah contoh lengkap menggunakan BasicDigitalTwin sebagai jenis hasil kueri dengan penanganan kesalahan dan penomoran:

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

Langkah berikutnya

Pelajari selengkapnya tentang API dan SDK Azure Digital Twins, termasuk API Kueri yang digunakan untuk menjalankan kueri dari artikel ini.