Bagikan melalui

Tutorial: Membuat grafik Azure Digital Twins menggunakan aplikasi klien sampel

  • Artikel

Dalam tutorial ini, Anda akan membuat grafik di Azure Digital Twins menggunakan model, twin, dan hubungan. Alat untuk tutorial ini adalah aplikasi klien baris perintah sampel untuk berinteraksi dengan instans Azure Digital Twins. Aplikasi klien mirip dengan yang ditulis dalam Mengodekan aplikasi klien.

Anda dapat menggunakan sampel ini untuk melakukan tindakan penting Azure Digital Twins seperti mengunggah model, membuat dan memodifikasi twin, dan membuat hubungan. Anda juga dapat melihat kode sampel untuk mempelajari API Azure Digital Twins, dan berlatih menerapkan perintah Anda sendiri dengan memodifikasi proyek sampel sesuai keinginan Anda.

Dalam tutorial ini, Anda akan...

  • Memodelkan lingkungan
  • Membuat digital twin
  • Menambahkan hubungan untuk membentuk grafik
  • Meng-kueri grafik untuk menjawab pertanyaan

Prasyarat

Sebelum memulai tutorial ini, mulailah dengan prasyarat ini:

  • Jika Anda tidak memiliki langganan Azure, buat akun gratis sebelum Anda memulai.
  • Tutorial ini menggunakan .NET. Anda dapat mengunduh versi terbaru .NET SDK untuk beberapa platform dari Unduh .NET.

Kemudian, lanjutkan melalui sisa bagian ini untuk menyiapkan prasyarat yang tersisa.

Mendapatkan sumber daya sampel

Tutorial tersebut digerakkan oleh proyek sampel ujung ke ujung Azure Digital Twins yang ditulis dalam C#. Dapatkan proyek sampel di komputer Anda dengan menavigasi ke tautan sampel, dan memilih tombol Telusuri kode di bawah judul.

Ini akan membawa Anda ke repositori GitHub untuk sampel, yang dapat Anda unduh sebagai .zip dengan memilih tombol Kode diikuti dengan Unduh ZIP.

Screenshot of the digital-twins-samples repo on GitHub, highlighting the steps to download it as a zip.

Ini akan mengunduh folder .zip ke komputer Anda sebagai digital-twins-samples-main.zip. Buka zip folder dan ekstrak file.

Menyiapkan instans Azure Digital Twins

Untuk bekerja dengan Azure Digital Twins dalam artikel ini, Anda memerlukan instans Azure Digital Twins dan izin yang diperlukan untuk menggunakannya. Jika Anda sudah menyiapkan instans Azure Digital Twins, Anda dapat menggunakan instans tersebut dan melompat ke bagian berikutnya. Jika tidak, ikuti instruksi dalam Menyiapkan instans dan autentikasi. Instruksi berisi informasi untuk membantu Anda memverifikasi bahwa Anda telah menyelesaikan setiap langkah dengan sukses.

Setelah Anda menyiapkan instans, catat nama host instans. Anda dapat menemukan nama host di portal Microsoft Azure.

Mengonfigurasi proyek sampel

Selanjutnya, siapkan sampel aplikasi klien yang akan berinteraksi dengan instans Azure Digital Twins Anda.

Navigasikan di komputer Anda ke folder yang Anda unduh sebelumnya dari sampel end-to-end Azure Digital Twins (dan unzip jika Anda belum melakukannya).

Setelah berada di dalam folder, navigasikan ke digital-twins-samples-main\AdtSampleApp\SampleClientApp dan buka file appsettings.json . File JSON ini berisi variabel konfigurasi yang diperlukan untuk menjalankan proyek.

Di isi file, ubah instanceUrl ke URL nama host instans Azure Digital Twins Anda (dengan menambahkan https:// di depan nama host, seperti yang ditunjukkan di bawah).

{
  "instanceUrl": "https://<your-Azure-Digital-Twins-instance-host-name>"
}

Simpan dan tutup file.

Siapkan kredensial Azure lokal

Sampel ini menggunakan DefaultAzureCredential (bagian dari pustaka Azure.Identity) untuk mengautentikasi pengguna dengan instans Azure Digital Twins saat Anda menjalankannya di komputer lokal Anda. Untuk informasi selengkapnya tentang berbagai cara aplikasi klien dapat mengautentikasi dengan Azure Digital Twins, lihat Menulis kode autentikasi aplikasi.

Dengan DefaultAzureCredential, sampel akan mencari kredensial di lingkungan lokal Anda, seperti masuk Azure di Azure CLI lokal atau di Visual Studio atau Visual Studio Code. Untuk alasan ini, Anda harus masuk ke Azure secara lokal melalui salah satu mekanisme ini untuk menyiapkan kredensial untuk sampel tersebut.

Jika Anda menggunakan Visual Studio atau Visual Studio Code untuk menjalankan sampel kode, pastikan Anda masuk ke editor tersebut dengan kredensial Azure yang sama dengan yang ingin Anda gunakan untuk mengakses instans Azure Digital Twins Anda. Jika Anda menggunakan jendela CLI lokal, jalankan az login perintah untuk masuk ke akun Azure Anda. Setelah ini, saat menjalankan sampel kode, Anda harus diautentikasi secara otomatis.

Jalankan proyek sampel

Setelah aplikasi dan autentikasi disiapkan, buka jendela konsol lokal yang akan Anda gunakan untuk menjalankan proyek. Navigasikan di konsol ke folder digital-twins-samples-main\AdtSampleApp\SampleClientApp , dan jalankan proyek dengan perintah dotnet ini:

dotnet run

Proyek akan mulai berjalan, melakukan autentikasi, dan menunggu perintah.

Berikut adalah cuplikan layar tampilan konsol proyek:

Screenshot of the welcome message from the command-line app.

Tip

Untuk daftar semua perintah yang mungkin anda gunakan dengan proyek ini, masukkan help di konsol proyek dan tekan return/kembali.

Setelah mengonfirmasi bahwa aplikasi berhasil berjalan, Anda dapat berhenti menjalankan proyek. Anda akan menjalankannya lagi nanti dalam tutorial.

Memodelkan lingkungan fisik dengan DTDL

Sekarang setelah instans Azure Digital Twins dan aplikasi sampel disiapkan, Anda dapat mulai membangun grafik skenario.

Langkah pertama dalam membuat solusi Azure Digital Twins adalah mendefinisikan model kembar untuk lingkungan Anda.

Model mirip dengan kelas dalam bahasa pemrograman berorientasi objek; mereka adalah templat yang ditentukan pengguna yang dapat Anda buat untuk membuat kembar digital. Model untuk Azure Digital Twins ditulis dalam bahasa seperti JSON yang disebut Digital Twins Definition Language (DTDL), dan mendefinisikan jenis kembar dalam hal properti, hubungan, dan komponennya.

Catatan

DTDL juga dapat menentukan perintah pada digital twins. Namun, perintah saat ini tidak didukung di layanan Azure Digital Twins.

Di folder proyek sampel yang Anda unduh sebelumnya, navigasikan ke folder digital-twins-samples-main\AdtSampleApp\SampleClientApp\Models . Folder ini memuat model sampel.

Buka Room.json untuk pengeditan, dan buat perubahan berikut pada kode:

  1. Perbarui nomor versi, untuk menunjukkan bahwa Anda menyediakan versi yang lebih baru dari model ini. Lakukan ini dengan mengubah 1 di akhir nilai @id menjadi 2. Nomor apa pun yang lebih besar dari nomor versi saat ini juga akan berfungsi.

  2. Mengedit properti. Ubah nama properti menjadi Humidity HumidityLevel (atau sesuatu yang berbeda jika Anda mau. Jika Anda menggunakan sesuatu yang berbeda dari HumidityLevel, ingat apa yang Anda gunakan dan terus menggunakannya alih-alih HumidityLevel di seluruh tutorial).

  3. Menambahkan properti. Di bawah properti HumidityLevel dengan akhir pada baris 15, tempel kode berikut untuk menambahkan properti RoomName ke ruangan:

    ,{
  "@type": "Property",
  "name": "RoomName",
  "schema": "string"
}

  4. Tambahkan hubungan. Di bawah RoomName properti yang baru saja Anda tambahkan, tempelkan kode berikut untuk menambahkan kemampuan jenis kembar ini untuk membentuk contains hubungan dengan kembar lainnya:

    ,{
  "@type": "Relationship",
  "name": "contains"
}

Ketika Anda selesai, model yang diperbarui harus cocok dengan ini:

{
    "@id": "dtmi:example:Room;2",
    "@type": "Interface",
    "displayName": "Room",
    "contents": [
      {
        "@type": "Property",
        "name": "Temperature",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "HumidityLevel",
        "schema": "double"
      }
      ,{
        "@type": "Property",
        "name": "RoomName",
        "schema": "string"
      }
      ,{
        "@type": "Relationship",
        "name": "contains"
      }
    ],
    "@context": "dtmi:dtdl:context;3"
  }

Pastikan untuk menyimpan file sebelum melanjutkan.

Mengunggah model ke Azure Digital Twins

Setelah mendesain model, Anda perlu mengunggahnya ke instans Azure Digital Twins Anda. Ini akan mengonfigurasi instans layanan Azure Digital Twins Anda dengan kosakata domain kustom Anda sendiri. Setelah Anda mengunggah model, Anda dapat membuat instans kembaran yang menggunakannya.

  1. Kembali ke jendela konsol Anda yang terbuka untuk folder digital-twins-samples-main\AdtSampleApp\SampleClientApp , dan jalankan aplikasi konsol lagi dengan dotnet run.

  2. Di jendela konsol proyek, jalankan perintah berikut untuk mengunggah model Room yang diperbarui, serta model Floor yang juga akan Anda gunakan di bagian berikutnya untuk membuat berbagai jenis kembaran.

    CreateModels Room Floor

    Outputnya akan menunjukkan bahwa model berhasil dibuat.

  3. Verifikasi model yang dibuat dengan menjalankan perintah GetModels true. Perintah ini akan mencetak informasi lengkap untuk semua model yang telah diunggah ke instans Azure Digital Twins Anda. Mencari model Ruangan yang telah diedit di hasil:

    Screenshot of the result from GetModels, showing the updated Room model.

Jaga agar aplikasi konsol tetap berjalan untuk langkah berikutnya.

Kesalahan

Aplikasi sampel juga menangani kesalahan dari layanan.

Untuk menguji ini, jalankan CreateModels ulang perintah untuk mencoba mengunggah ulang model Ruangan yang telah Anda unggah:

CreateModels Room

Karena model tidak dapat ditimpa, perintah ini sekarang akan mengembalikan kesalahan layanan yang menunjukkan bahwa beberapa ID model yang Anda coba buat sudah ada.

Untuk detail tentang cara menghapus model yang sudah ada, lihat Mengelola model DTDL.

Membuat digital twin

Setelah beberapa model diunggah ke instans Azure Digital Twins, Anda dapat membuat digital twins berdasarkan definisi model. Digital Twin mewakili entitas dalam lingkungan bisnis Anda—hal-hal seperti sensor di peternakan, ruangan di gedung, atau lampu pada mobil.

Untuk membuat digital twin, Anda menggunakan perintah CreateDigitalTwin. Anda harus mereferensikan model yang dijadikan dasar twin, serta memiliki opsi untuk dapat menentukan nilai awal properti apa pun dalam model. Anda tidak harus meneruskan informasi hubungan apa pun di tahap ini.

  1. Jalankan kode ini di konsol proyek yang berjalan untuk membuat beberapa twin, berdasarkan model Room yang Anda perbarui sebelumnya dan model Floor. Ingat bahwa Room memiliki tiga properti, sehingga Anda dapat menyediakan argumen dengan nilai awal untuk properti ini. (Menginisialisasi nilai properti bersifat opsional secara umum, tetapi diperlukan untuk tutorial ini.)

    CreateDigitalTwin dtmi:example:Room;2 room0 RoomName string Room0 Temperature double 70 HumidityLevel double 30
CreateDigitalTwin dtmi:example:Room;2 room1 RoomName string Room1 Temperature double 80 HumidityLevel double 60
CreateDigitalTwin dtmi:example:Floor;1 floor0
CreateDigitalTwin dtmi:example:Floor;1 floor1

    Output dari perintah ini akan menunjukkan bahwa twin berhasil dibuat.

    Screenshot showing an excerpt from the result of the CreateDigitalTwin commands, which includes floor0, floor1, room0, and room1.

  2. Anda dapat memverifikasi bahwa twin telah dibuat dengan menjalankan perintah Query. Perintah ini meng-kueri instans Azure Digital Twins Anda untuk semua digital twin yang dikandungnya. Cari twin room0, room1, floor0, dan floor1 dalam hasil.

Catatan

Setelah mengubah data di grafik Anda, terdapat kemungkinan latensi hingga 10 detik sebelum perubahan tersebut tercermin dalam kueri.

API DigitalTwins mencerminkan perubahan secara langsung, jadi jika Anda memerlukan respons instan, gunakan permintaan API (DigitalTwins GetById) atau panggilan SDK (GetDigitalTwin) untuk mendapatkan data kembar, alih-alih kueri.

Memodifikasi digital twin

Anda juga dapat memodifikasi properti twin yang telah Anda buat.

Catatan

REST API yang mendasarinya menggunakan format JSON Patch untuk menentukan pembaruan pada twin. Aplikasi baris perintah juga menggunakan format ini, untuk memberikan pengalaman yang lebih nyata dengan yang diharapkan oleh API yang mendasarinya.

  1. Jalankan perintah ini untuk mengubah RoomName room0 dari "Room0" menjadi "PresidentialSuite":

    UpdateDigitalTwin room0 add /RoomName string PresidentialSuite

    Outputnya akan menunjukkan bahwa twin telah berhasil diperbarui.

  2. Anda dapat memverifikasi bahwa pembaruan berhasil dengan menjalankan perintah ini untuk melihat informasi room0:

    GetDigitalTwin room0

    Outputnya{i>

Membuat grafik dengan menambahkan hubungan

Selanjutnya, Anda dapat membuat beberapa hubungan antara kembar ini, untuk menghubungkannya ke grafik kembar. Grafik twin digunakan untuk mewakili seluruh lingkungan.

Jenis hubungan yang dapat Anda buat dari satu twin ke twin lainnya ditentukan dalam model yang telah Anda unggah sebelumnya. Definisi model untuk Lantai menentukan bahwa lantai dapat memiliki jenis hubungan yang disebut contains, yang memungkinkan untuk membuat containshubungan -type dari setiap twin Lantai ke ruang yang sesuai yang dikandungnya.

Untuk menambahkan hubungan, gunakan perintah CreateRelationship. Tentukan twin asal hubungan, jenis hubungan, dan twin yang disambungkan dengan hubungan tersebut. Terakhir, berikan ID yang unik bagi hubungan.

  1. Jalankan perintah berikut untuk menambahkan contains hubungan dari setiap twin Lantai yang Anda buat sebelumnya ke kembaran Ruangan yang sesuai. Hubungan tersebut diberi nama hubungan0 dan hubungan1.

    CreateRelationship floor0 contains room0 relationship0
CreateRelationship floor1 contains room1 relationship1

    Tip

    Hubungan contains dalam model Lantai juga didefinisikan dengan dua properti string, ownershipUser dan ownershipDepartment, sehingga Anda juga dapat memberikan argumen dengan nilai awal untuk ini saat Anda membuat hubungan. Berikut adalah versi alternatif dari perintah di atas untuk membuat relationship0 yang juga menentukan nilai awal untuk properti ini:

    CreateRelationship floor0 contains room0 relationship0 ownershipUser string MyUser ownershipDepartment string myDepartment

    Output dari perintah ini menegaskan bahwa hubungan telah berhasil dibuat:

    Screenshot of an excerpt from the result of the CreateRelationship commands, which includes relationship0 and relationship1.

  2. Anda dapat memverifikasi hubungan dengan salah satu perintah berikut, yang akan mencetak hubungan di instans Azure Digital Twins Anda.

    • Untuk melihat semua hubungan yang berasal dari setiap lantai (melihat hubungan dari satu sisi): 
      GetRelationships floor0
GetRelationships floor1
    • Untuk melihat semua hubungan yang tiba di setiap ruangan (melihat hubungan dari sisi "lainnya"): 
      GetIncomingRelationships room0
GetIncomingRelationships room1
    • Untuk mencari hubungan ini satu per satu, menurut ID: 
      GetRelationship floor0 relationship0
GetRelationship floor1 relationship1

Twin dan hubungan yang telah Anda siapkan dalam tutorial ini membentuk grafik konseptual berikut:

A diagram showing a conceptual graph. floor0 is connected via relationship0 to room0, and floor1 is connected via relationship1 to room1.

Meng-kueri grafik twin untuk menjawab pertanyaan lingkungan

Fitur utama Azure Digital Twins adalah kemampuan untuk mengkueri grafik twin Anda dengan mudah dan efisien untuk menjawab pertanyaan tentang lingkungan Anda.

Catatan

Setelah mengubah data di grafik Anda, terdapat kemungkinan latensi hingga 10 detik sebelum perubahan tersebut tercermin dalam kueri.

API DigitalTwins mencerminkan perubahan secara langsung, jadi jika Anda memerlukan respons instan, gunakan permintaan API (DigitalTwins GetById) atau panggilan SDK (GetDigitalTwin) untuk mendapatkan data kembar, alih-alih kueri.

Jalankan perintah berikut di konsol proyek yang sedang berjalan untuk menjawab beberapa pertanyaan tentang lingkungan sampel.

  1. Apa saja entitas dari lingkungan saya yang diwakili di Azure Digital Twins? (kueri semua)

    Query

    Langkah ini memungkinkan Anda melihat sekilas lingkungan Anda, dan memastikan semuanya diwakili seperti yang Anda inginkan dalam Azure Digital Twins. Hasil dari perintah ini adalah output yang berisi setiap kembaran digital dengan detailnya. Berikut adalah kutipannya:

    Screenshot showing a partial result from the twin query, including room0 and floor1.

    Tip

    Dalam proyek sampel, perintah Query tanpa argumen tambahan setara dengan Query SELECT * FROM DIGITALTWINS. Untuk meng-kueri semua twin dalam instans Anda menggunakan API Kueri atau perintah CLI, gunakan kueri yang lebih panjang (yang lebih lengkap).

  2. Apa saja ruangan di ada di lingkungan saya? (kueri berdasarkan model)

    Query SELECT * FROM DIGITALTWINS T WHERE IS_OF_MODEL(T, 'dtmi:example:Room;2')

    Anda bisa membatasi kueri Anda untuk twin dari jenis tertentu, untuk mendapatkan informasi yang lebih spesifik tentang apa yang diwakili. Hasil dari ini menunjukkan kamar0 dan kamar1, tetapi tidak menunjukkan lantai0 atau lantai1 (karena mereka lantai, bukan kamar).

    Screenshot of the result from the model query, showing only room0 and room1.

  3. Apa saja ruangan/room yang ada di floor0? (kueri berdasarkan hubungan)

    Query SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.$dtId = 'floor0'

    Anda bisa meng-kueri berdasarkan hubungan dalam grafik Anda, untuk mendapatkan informasi tentang bagaimana twin terhubung atau membatasi kueri Anda ke area tertentu. Hanya ruangan 0 yang ada di lantai0, jadi ruangan itu adalah satu-satunya ruangan yang muncul dalam hasil.

    Screenshot of the result from the relationship query, showing room0.

  4. Apa saja twin di lingkungan saya dengan suhu di atas 75? (kueri berdasarkan properti)

    Query SELECT * FROM DigitalTwins T WHERE T.Temperature > 75

    Anda dapat meng-kueri grafik berdasarkan properti untuk menjawab berbagai pertanyaan, termasuk menemukan outlier di lingkungan Anda yang mungkin perlu diperhatikan. Operator perbandingan lainnya (<,>, =, atau !=) juga didukung. ruangan 1 muncul dalam hasil di sini, karena memiliki suhu 80.

    Screenshot of the result from the property query, showing only room1.

  5. Ruangan/room apa saja di floor0 yang bersuhu di atas 75? (kueri gabungan)

    Query SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.$dtId = 'floor0' AND IS_OF_MODEL(room, 'dtmi:example:Room;2') AND room.Temperature > 75

    Anda juga dapat menggabungkan kueri yang lebih lama seperti yang Anda lakukan di SQL, menggunakan operator kombinasi seperti AND, OR, NOT. Kueri ini menggunakan AND untuk membuat kueri sebelumnya tentang suhu twin lebih spesifik. Hasilnya sekarang hanya mencakup ruangan dengan suhu di atas 75 yang berada di floor0—yang dalam hal ini, tidak ada satu ruangan pun. Set hasil kosong.

    Screenshot of the result from the compound query, showing no results.

Sekarang setelah Anda menjalankan beberapa kueri pada skenario yang Anda siapkan, tutorial selesai. Berhenti menjalankan proyek dan tutup jendela konsol.

Membersihkan sumber daya

Setelah menyelesaikan tutorial ini, Anda dapat memilih sumber daya mana yang ingin Anda hapus, tergantung pada apa yang ingin Anda lakukan selanjutnya.

  • Jika Anda berencana untuk melanjutkan ke tutorial berikutnya, Anda dapat menyimpan sumber daya yang Anda siapkan di sini untuk terus menggunakan instans Azure Digital Twins ini dan aplikasi sampel yang dikonfigurasi untuk tutorial berikutnya

  • Jika Anda ingin terus menggunakan instans Azure Digital Twins, tetapi menghapus semua model, kembar, dan hubungannya, Anda dapat menggunakan aplikasi DeleteAllTwins sampel dan DeleteAllModels perintah untuk menghapus kembar dan model dalam instans Anda.

  • Jika Anda tidak memerlukan sumber daya apa pun yang Anda buat dalam tutorial ini, Anda dapat menghapus instans Azure Digital Twins dan semua sumber daya lainnya dari artikel ini dengan perintah az group delete CLI. Tindakan ini menghapus semua sumber daya Azure dalam grup sumber daya, serta grup sumber daya itu sendiri.

    Penting

    Penghapusan grup sumber daya tidak bisa dipulihkan. Grup sumber daya dan semua sumber daya yang tercakup di dalamnya akan dihapus secara permanen. Pastikan Anda tidak menghapus grup atau sumber daya yang salah secara tidak sengaja.

    Buka Azure Cloud Shell atau jendela CLI lokal, dan jalankan perintah berikut untuk menghapus grup sumber daya dan semua yang ada di dalamnya.

    az group delete --name <your-resource-group>

Anda mungkin juga ingin menghapus folder proyek yang diunduh dari komputer lokal Anda.

Langkah berikutnya

Dalam tutorial ini, Anda memulai Azure Digital Twins dengan membuat grafik dalam instans Anda menggunakan aplikasi klien sampel. Anda membuat model, digital twin, dan hubungan untuk membentuk grafik. Anda juga menjalankan beberapa kueri pada grafik, untuk mendapatkan gambaran tentang jenis pertanyaan apa yang dapat dijawab oleh Azure Digital Twins tentang lingkungan.

Lanjutkan ke tutorial berikutnya untuk menggabungkan Azure Digital Twins dengan layanan Azure lainnya untuk menyelesaikan skenario end-to-end berbasis data:

Koneksi solusi end-to-end