Bagikan melalui

Tutorial: Membuat grafik Azure Digital Twins menggunakan aplikasi klien sampel

Dalam tutorial ini, Anda membangun grafik di Azure Digital Twins menggunakan model, kembar, 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 operasi penting Azure Digital Twins seperti mengunggah model, membuat dan memodifikasi kembar digital, 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 kembaran digital
  • 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.

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

Cuplikan layar repositori digital-twins-samples di GitHub, yang menyoroti langkah-langkah untuk mengunduhnya sebagai zip.

Tindakan ini 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 berhasil menyelesaikan setiap langkah.

Setelah Anda menyiapkan instance, catat nama host dari instance tersebut. Anda dapat menemukan nama host di portal Microsoft Azure.

Konfigurasikan proyek contoh

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 Azure.Identity dari pustaka) untuk mengautentikasi dengan instans Azure Digital Twins saat Anda menjalankan sampel di komputer lokal Anda. DefaultAzureCredential adalah salah satu dari banyak opsi autentikasi. Untuk informasi selengkapnya tentang berbagai cara aplikasi klien dapat mengautentikasi dengan Azure Digital Twins, lihat Menulis kode autentikasi aplikasi.

Dengan DefaultAzureCredential, contoh mencari kredensial di lingkungan lokal Anda, misalnya masuk ke 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 Masuk, sampel kode akan mengautentikasi Anda secara otomatis saat dijalankan.

Jalankan proyek sampel

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

dotnet run

Proyek mulai berjalan, melakukan autentikasi, dan menunggu perintah.

Berikut adalah cuplikan layar tampilan konsol proyek:

Cuplikan layar pesan selamat datang dari aplikasi baris perintah.

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 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 memungkinkan untuk mendefinisikan perintah pada kembar digital. 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 HumidityHumidityLevel (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 mengunggah model, Anda dapat membuat instans kembar 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 mencetak informasi lengkap untuk semua model yang diunggah ke instans Azure Digital Twins Anda. Carilah model ruangan yang telah diedit dalam hasil.

    Cuplikan layar hasil dari GetModels, memperlihatkan model Room yang diperbarui.

Jaga agar aplikasi konsol tetap berjalan untuk langkah berikutnya.

Kesalahan

Aplikasi sampel juga menangani kesalahan dari layanan.

Untuk menguji penanganan kesalahan ini, jalankan CreateModels ulang perintah untuk mencoba memuat ulang model Ruangan yang sudah Anda unggah:

CreateModels Room

Karena model tidak dapat ditimpa, perintah ini sekarang 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 kembaran digital

Sekarang setelah beberapa model diunggah ke instans Azure Digital Twins, Anda dapat membuat kembar digital berdasarkan definisi model. Kembar digital mewakili entitas dalam lingkungan bisnis Anda—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 sedang berjalan untuk membuat beberapa kembaran, 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 menunjukkan bahwa kembar berhasil dibuat.

    Cuplikan layar memperlihatkan kutipan dari hasil perintah CreateDigitalTwin, yang mencakup floor0, floor1, room0, dan room1.

  2. Anda dapat memverifikasi bahwa twins telah dibuat dengan menjalankan perintah Query. Perintah ini menanyakan semua digital twin yang terdapat dalam instans Azure Digital Twins Anda. Cari room0, room1, floor0, dan floor1 yang sejenis 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 kembar digital

Anda juga dapat mengubah properti kembar yang 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

    Hasil keluaran harus menunjukkan bahwa objek kembar telah berhasil diperbarui.

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

    GetDigitalTwin room0

    Hasilnya akan mencerminkan nama yang diperbarui.

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 jenis hubungan contains dari setiap kembaran Lantai ke ruang yang sesuai yang dikandungnya.

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

  1. Jalankan perintah berikut untuk menambahkan hubungan antara setiap kembaran Floor yang Anda buat sebelumnya dengan 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 Floor model juga didefinisikan dengan dua properti string, ownershipUser dan ownershipDepartment, sehingga Anda dapat memberikan argumen dengan nilai awal untuk properti-properti ini ketika Anda membuat hubungan. Berikut adalah versi alternatif dari perintah sebelumnya yang Anda gunakan 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:

    Cuplikan layar kutipan dari hasil perintah CreateRelationship, yang mencakup relationship0 dan 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 ada di setiap ruangan (melihat hubungan dari sisi "sebaliknya"): 
      GetIncomingRelationships room0
GetIncomingRelationships room1
    • Untuk mencari hubungan ini satu per satu, berdasarkan ID. 
      GetRelationship floor0 relationship0
GetRelationship floor1 relationship1

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

Diagram menampilkan grafik konseptual. floor0 tersambung melalui relationship0 ke room0, dan floor1 tersambung melalui relationship1 ke room1.

Meminta grafik kembar untuk menjawab pertanyaan tentang lingkungan

Fitur utama Azure Digital Twins adalah kemampuan untuk menjalankan kueri pada grafik kembar 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:

    Cuplikan layar yang menunjukkan sebagian hasil dari kueri kembar, termasuk room0 dan floor1.

    Tip

    Dalam proyek sampel, perintah Query tanpa argumen lain 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 yang 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 kembaran dari jenis tertentu, untuk mendapatkan informasi yang lebih spesifik tentang apa yang direpresentasikan. Hasil dari ini menunjukkan kamar0 dan kamar1, tetapi tidak menunjukkan lantai0 atau lantai1 (karena mereka lantai, bukan kamar).

    Cuplikan layar hasil dari kueri model, hanya memperlihatkan room0 dan room1.

  3. Apa saja ruangan yang ada di lantai 0? (kueri berdasarkan hubungan)

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

    Anda dapat melakukan kueri berdasarkan hubungan dalam graf Anda, untuk mendapatkan informasi tentang bagaimana kembar digital terhubung atau menyaring kueri Anda ke wilayah tertentu. Hanya ruangan 0 yang ada di lantai0, jadi ruangan itu adalah satu-satunya ruangan yang muncul dalam hasil.

    Cuplikan layar hasil dari kueri hubungan, memperlihatkan room0.

  4. Apa saja anak-anak kembar di area 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.

    Cuplikan layar hasil dari kueri properti, hanya memperlihatkan room1.

  5. Ruangan apa saja di lantai 0 yang suhunya 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 kembar lebih spesifik. Hasilnya sekarang hanya mencakup ruangan dengan suhu di atas 75 yang berada di lantai 0—yang dalam hal ini, tidak ada satu pun ruangan. Set hasil kosong.

    Cuplikan layar hasil dari kueri gabungan, tidak memperlihatkan hasil.

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, twins, dan relasinya, Anda dapat menggunakan perintah DeleteAllTwins dan DeleteAllModels dari aplikasi sampel untuk menghapus twins 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, kembar digital, dan hubungan untuk membentuk graf. 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:

Menghubungkan solusi end-to-end

  • Last updated on