Tutorial: Menyebarkan Pratinjau Azure Digital Twins dan mengonfigurasi grafik spasial

Artikel
01/10/2020

Penting

Versi baru layanan Azure Digital Twins telah dirilis. Mengingat kemampuan layanan baru yang diperluas, layanan Azure Digital Twins asli (dijelaskan dalam set dokumentasi ini) telah dihentikan.

Untuk melihat dokumentasi layanan baru, kunjungi Dokumentasi Azure Digital Twins aktif.

Anda dapat menggunakan layanan Pratinjau Azure Digital Twins untuk menyatukan orang, tempat, dan perangkat dalam sistem spasial yang koheren. Rangkaian tutorial ini menunjukkan cara menggunakan Azure Digital Twins untuk mendeteksi hunian kamar dengan kondisi suhu dan kualitas udara yang optimal.

Tutorial ini akan memandu Anda melalui aplikasi konsol .NET untuk membangun skenario gedung kantor. Bangunan ini memiliki beberapa lantai dan kamar di setiap lantai. Kamar berisi perangkat dengan sensor terpasang yang mendeteksi gerakan, suhu sekitar, dan kualitas udara.

Anda akan mempelajari cara mereplikasi area fisik dan entitas dalam bangunan sebagai objek digital dengan menggunakan layanan Azure Digital Twins. Anda akan mensimulasikan peristiwa perangkat dengan menggunakan aplikasi konsol lain. Kemudian, Anda akan mempelajari cara memantau peristiwa yang berasal dari area fisik dan entitas ini mendekati real time.

Administrator kantor dapat menggunakan informasi ini untuk membantu karyawan yang bekerja di gedung ini untuk memesan ruang rapat dengan kondisi optimal. Manajer fasilitas kantor dapat menggunakan penyiapan Anda untuk mendapatkan tren penggunaan ruangan, dan untuk memantau kondisi kerja untuk tujuan pemeliharaan.

Dalam tutorial pertama dari seri ini, Anda mempelajari cara:

Menyebarkan Digital Twins.
Berikan izin ke aplikasi Anda.
Ubah aplikasi sampel Digital Twins.
Memprovisikan bangunan Anda.

Tutorial ini menggunakan dan memodifikasi sampel yang sama dengan mulai cepat untuk menemukan kamar yang tersedia , untuk cakupan konsep yang lebih rinci dan mendalam.

Prasyarat

Langganan Azure. Jika Anda tidak memiliki akun Azure, buat akun gratis.
The .NET Core SDK. Sampel Azure Digital Twins yang digunakan dalam tutorial ini ditulis dalam C#. Pastikan untuk menginstal .NET Core SDK versi 2.1.403 atau yang lebih baru pada komputer pengembangan Anda untuk membangun dan menjalankan sampel. Periksa apakah versi yang tepat diinstal pada komputer Anda dengan menjalankan dotnet --version di jendela perintah.
Visual Studio Code untuk menjelajahi kode sampel.

Menyebarkan Digital Twins

Gunakan langkah-langkah di bagian ini untuk membuat instans baru layanan Azure Digital Twins. Hanya satu instans yang dapat dibuat per langganan. Lewati ke bagian berikutnya jika Anda sudah menjalankannya.

Masuk ke portal Microsoft Azure.
Pilih bilah sisi beranda, lalu + Buat sumber daya.
Cari Digital Twins, dan pilih Digital Twins.

Atau, pilih Internet of Things, dan pilih Digital Twins (pratinjau).
Pilih Buat untuk memulai proses penyebaran.
Di panel Digital Twins , masukkan informasi berikut ini:
- Nama Sumber Daya: Buat nama unik untuk instans Digital Twins Anda.
- Langganan: Pilih langganan yang ingin Anda gunakan untuk membuat instans Digital Twins ini.
- Grup sumber daya: Pilih atau buat grup sumber daya untuk instans Digital Twins.
- Lokasi: Pilih lokasi terdekat dengan perangkat Anda.
Tinjau informasi Digital Twins Anda, lalu pilih Buat. Instans Digital Twins Anda mungkin memerlukan waktu beberapa menit untuk dibuat. Anda bisa memantau kemajuannya di panel Pemberitahuan.
Buka panel Gambaran Umum instans Digital Twins Anda. Perhatikan tautan di bawah API Manajemen. URL API Manajemen diformat sebagai:
```
https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swagger
```
URL ini membawa Anda ke dokumentasi REST API Azure Digital Twins yang berlaku untuk instans Anda. Baca Cara menggunakan Azure Digital Twins Swagger untuk mempelajari cara membaca dan menggunakan dokumentasi API ini. Salin dan ubah URL API Manajemen ke format ini:
```
https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/
```
Aplikasi Anda akan menggunakan URL yang dimodifikasi sebagai URL dasar untuk mengakses instans Anda. Salin URL yang dimodifikasi ini ke file sementara. Anda akan membutuhkan ini di bagian berikutnya.

Memberikan izin ke aplikasi Anda

Digital Twins menggunakan Azure Active Directory (Azure AD) untuk mengontrol akses baca/tulis ke layanan. Aplikasi apa pun yang perlu terhubung dengan instans Digital Twins Anda harus didaftarkan ke Azure AD. Langkah-langkah di bagian ini menunjukkan cara mendaftarkan aplikasi sampel Anda.

Jika sudah memiliki pendaftaran aplikasi, Anda dapat menggunakannya kembali untuk sampel Anda. Namun, telusuri bagian ini untuk memastikan pendaftaran aplikasi Anda dikonfigurasi dengan benar.

Catatan

Bagian ini menyediakan instruksi untuk pendaftaran aplikasi Azure AD.

Di portal Azure, buka Azure Active Directory dari menu kiri yang dapat diperluas, lalu buka panel Pendaftaran aplikasi.
Pilih tombol + Pendaftaran baru .
Berikan nama yang mudah diingat untuk pendaftaran aplikasi ini di kotak Nama .
1. Di bawah bagian Alihkan URI (opsional) , masukkan https://microsoft.com di kotak teks.
2. Verifikasi akun dan penyewa mana yang didukung oleh aplikasi Azure Active Directory Anda.
3. Pilih Daftar.
Bilah Autentikasi menentukan pengaturan konfigurasi autentikasi penting.
1. Tambahkan URI Pengalihan dan konfigurasikan Token Akses dengan memilih + Tambahkan platform.
2. Pilih Ya untuk menentukan bahwa aplikasi adalah klien publik.
3. Verifikasi akun dan penyewa mana yang didukung oleh aplikasi Azure Active Directory Anda.
Setelah memilih platform yang sesuai, konfigurasikan URI Pengalihan dan Token Akses Anda di panel samping di sebelah kanan antarmuka pengguna.
1. URI Pengalihan harus cocok dengan alamat yang diberikan oleh permintaan autentikasi:
  - Untuk aplikasi yang dihosting di lingkungan pengembangan lokal, pilih Klien publik (seluler & desktop) . Memastikan untuk mengatur klien publik ke Ya.
  - Untuk Aplikasi Satu Hahalaman yang dihosting di Azure App Service, pilih Web.
2. Menentukan apakah URL Keluar sudah sesuai.
3. Mengaktifkan aliran hibah implisit dengan mencentang Token akses atau token ID.
Klik Konfigurasikan, lalu Simpan.
Buka panel Gambaran Umum aplikasi terdaftar Anda, dan salin nilai entitas berikut ke file sementara. Anda akan menggunakan nilai-nilai ini untuk mengonfigurasi aplikasi sampel Anda di bagian berikut.
- ID aplikasi (klien)
- ID direktori (tenant)
Buka panel izin API untuk pendaftaran aplikasi Anda. Pilih tombol + Tambahkan izin . Di panel Minta izin API , pilih tab API yang digunakan organisasi saya , lalu cari salah satu hal berikut ini:
1. Azure Digital Twins. Pilih AZURE Digital Twins API.
2. Atau, cari Azure Smart Spaces Service. Pilih Azure Smart Spaces Service API.
Penting

Nama dan ID API Azure AD yang akan muncul tergantung pada penyewa Anda:
- Penyewa pengujian dan akun pelanggan harus mencari Azure Digital Twins.
- Akun Microsoft lainnya harus mencari Azure Smart Spaces Service.
Salah satu API akan muncul sebagai Azure Digital Twins di panel izin Request API yang sama setelah dipilih. Pilih opsi drop-down Baca , lalu pilih kotak centang Baca.Tulis . Pilih tombol Tambahkan izin akses.
Bergantung pada pengaturan organisasi, Anda mungkin perlu mengambil langkah tambahan untuk memberikan akses admin ke API ini. Hubungi administrator Anda untuk informasi lebih lanjut. Setelah akses admin disetujui, kolom Admin Diperlukan Persetujuan di panel izin API akan menampilkan izin Anda.

Verifikasi bahwa Azure Digital Twins muncul.

Mengonfigurasi sampel Digital Twins

Bagian ini memanding Anda melalui aplikasi Azure Digital Twins yang berkomunikasi dengan REST API Digital Twins.

Unduh sampel

Jika Anda sudah memiliki sampel yang diunduh untuk mulai cepat untuk menemukan ruang yang tersedia, Anda dapat melewati langkah-langkah ini.

Unduh sampel Digital Twins .NET.
Ekstrak isi folder zip pada komputer Anda.

Menjelajahi sampel

Di folder sampel yang diekstrak, buka file digital-twins-samples-csharp\digital-twins-samples.code-workspace di Visual Studio Code. Ini berisi dua proyek:

Anda dapat menggunakan sampel provisi occupancy-quickstart untuk mengonfigurasi dan menyediakan grafik kecerdasan spasial. Grafik ini adalah gambar digital ruang fisik Anda dan sumber daya di dalamnya. Ini menggunakan model objek, yang mendefinisikan objek untuk bangunan pintar. Untuk daftar lengkap objek Digital Twins dan REST API, kunjungi dokumentasi REST API ini atau URL API Manajemen yang dibuat untuk instans Anda.

Untuk menjelajahi sampel untuk memahami caranya berkomunikasi dengan instans Digital Twins Anda, Anda dapat mulai dengan folder src\actions . File dalam folder ini mengimplementasikan perintah yang akan Anda gunakan dalam tutorial ini:
- File provisionSample.cs menunjukkan cara memprovisikan grafik spasial Anda.
- File getSpaces.cs mendapatkan informasi tentang ruang yang disediakan.
- File getAvailableAndFreshSpaces.cs mendapatkan hasil fungsi kustom yang disebut fungsi yang ditentukan pengguna.
- File createEndpoints.cs membuat titik akhir untuk berinteraksi dengan layanan lain.
Sampel simulasi konektivitas perangkat mensimulasikan data sensor dan mengirimkannya ke hub IoT yang disediakan untuk instans Digital Twins Anda. Anda akan menggunakan sampel ini dalam tutorial berikutnya setelah memprovisikan grafik spasial Anda. Pengidentifikasi sensor dan perangkat yang Anda gunakan untuk mengonfigurasi sampel ini harus sama dengan apa yang akan Anda gunakan untuk memprovisikan grafik Anda.

Mengonfigurasi sampel provisi

Buka jendela perintah dan buka sampel yang diunduh. Jalankan perintah berikut:
```
cd occupancy-quickstart/src
```
Pulihkan dependensi ke proyek sampel dengan menjalankan perintah ini:
```
dotnet restore
```
Di Visual Studio Code, buka file appSettings.json di proyek occupancy-quickstart. Perbarui nilai berikut ini:
- ClientId: Masukkan ID aplikasi pendaftaran aplikasi Azure AD Anda. Anda mencatat ID ini di bagian tempat Anda mengatur izin aplikasi.
- Penyewa: Masukkan ID direktori penyewa Azure AD Anda. Anda juga mencatat ID ini di bagian tempat Anda mengatur izin aplikasi.
- BaseUrl: Masukkan URL instans Digital Twins Anda. Untuk mendapatkan URL ini, ganti tempat penampung di URL ini dengan nilai untuk instans Anda: https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/. Anda juga bisa mendapatkan URL ini dengan memodifikasi URL API Manajemen dari bagian penyebaran. Ganti swagger/ dengan api/v1.0/.
Tinjau daftar fitur Digital Twins yang dapat Anda jelajahi dengan menggunakan sampel. Jalankan perintah berikut:
```
dotnet run
```

Memahami proses provisi

Bagian ini memperlihatkan bagaimana sampel memprovisikan grafik spasial bangunan.

Di Visual Studio Code, telusuri folder occupancy-quickstart\src\actions dan buka file provisionSample.cs. Perhatikan fungsi berikut:

public static async Task<IEnumerable<ProvisionResults.Space>> ProvisionSample(HttpClient httpClient, ILogger logger)
{
    IEnumerable<SpaceDescription> spaceCreateDescriptions;
    using (var r = new StreamReader("actions/provisionSample.yaml"))
    {
        spaceCreateDescriptions = await GetProvisionSampleTopology(r);
    }

    var results = await CreateSpaces(httpClient, logger, spaceCreateDescriptions, Guid.Empty);

    Console.WriteLine($"Completed Provisioning: {JsonConvert.SerializeObject(results, Formatting.Indented)}");

    return results;
}

Fungsi ini menggunakan provisionSample.yaml di folder yang sama. Buka file ini, dan perhatikan hierarki gedung kantor: Tempat, Lantai, Area, dan Kamar. Salah satu ruang fisik ini dapat berisi perangkat dan sensor. Setiap entri memiliki yang telah ditentukan typesebelumnya —misalnya, Lantai, Ruangan.

File yaml sampel menunjukkan grafik spasial Default yang menggunakan model objek Digital Twins. Model ini menyediakan nama generik untuk sebagian besar jenis. Nama generik cukup untuk sebuah bangunan. Contohnya adalah Suhu untuk SensorDataType, dan Peta untuk SpaceBlobType. Contoh jenis spasi adalah Ruangan dengan subjenis FocusRoom, ConferenceRoom, dan sebagainya.

Jika Anda harus membuat grafik spasial untuk tempat jenis yang berbeda, seperti pabrik, Anda mungkin memerlukan model objek yang berbeda. Anda dapat mengetahui model mana yang tersedia untuk digunakan dengan menjalankan perintah dotnet run GetOntologies pada baris perintah untuk sampel provisi.

Untuk informasi selengkapnya tentang grafik spasial dan model objek, baca Memahami model objek Digital Twins dan grafik kecerdasan spasial.

Mengubah contoh grafik spasial

File provisionSample.yaml berisi simpul berikut:

sumber daya: Simpul resources membuat sumber daya Azure IoT Hub untuk berkomunikasi dengan perangkat dalam penyiapan Anda. Hub IoT di simpul akar grafik Anda dapat berkomunikasi dengan semua perangkat dan sensor dalam grafik Anda.
spasi: Dalam model objek Digital Twins, spaces mewakili lokasi fisik. Setiap ruang memiliki Type—misalnya, Wilayah, Tempat, atau Pelanggan—dan yang ramah Name. Spasi dapat dimiliki oleh spasi lain, membuat struktur hierarkis. File provisionSample.yaml memiliki grafik spasial bangunan imajiner. Perhatikan bersarangnya ruang logis jenis Floor dalam Venue, Area di lantai, dan Room simpul di suatu area.
perangkat: Spasi dapat berisi devices, yang merupakan entitas fisik atau virtual yang mengelola sejumlah sensor. Misalnya, perangkat mungkin ponsel pengguna, pod sensor Raspberry Pi, atau gateway. Di bangunan imajiner dalam sampel Anda, perhatikan bagaimana ruangan bernama Focus Room berisi perangkat Raspberry Pi 3 A1 . Setiap simpul perangkat diidentifikasi oleh yang unik hardwareId, yang dikodekan secara permanen dalam sampel. Untuk mengonfigurasi sampel ini untuk produksi aktual, ganti ini dengan nilai dari penyiapan Anda.
sensor: Perangkat dapat berisi beberapa sensors. Mereka dapat mendeteksi dan merekam perubahan fisik seperti suhu, gerakan, dan tingkat baterai. Setiap simpul sensor diidentifikasi secara unik oleh hardwareId, dikodekan secara permanen di sini. Untuk aplikasi aktual, ganti ini dengan menggunakan pengidentifikasi unik sensor dalam penyiapan Anda. File provisionSample.yaml memiliki dua sensor untuk merekam Gerakan dan KarbonDioksida. Tambahkan sensor lain untuk merekam Suhu, dengan menambahkan baris berikut, di bawah garis untuk sensor KarbonDioksida. Ini disediakan dalam provisionSample.yaml sebagai baris yang dikomentari. Anda dapat membatalkan komentar dengan menghapus # karakter di bagian depan setiap baris.
```
        - dataType: Temperature
          hardwareId: SAMPLE_SENSOR_TEMPERATURE
```
Catatan

Pastikan tombol dataType dan hardwareId selaras dengan pernyataan di atas cuplikan ini. Pastikan juga bahwa editor Anda tidak mengganti spasi dengan tab.

Simpan dan tutup file provisionSample.yaml. Dalam tutorial berikutnya, Anda akan menambahkan informasi selengkapnya ke file ini, lalu memprovisikan pembuatan sampel Azure Digital Twins Anda.

Tip

Anda dapat melihat dan mengubah grafik spasial Menggunakan Penampil Grafik Azure Digital Twins.

Membersihkan sumber daya

Jika Anda ingin berhenti menjelajahi Azure Digital Twins pada saat ini, jangan ragu untuk menghapus sumber daya yang dibuat dalam tutorial ini:

Dari menu sebelah kiri di portal Azure, pilih Semua sumber daya, pilih grup sumber daya Digital Twins Anda, dan pilih Hapus.

Tip

Jika Anda mengalami masalah saat menghapus instans Digital Twins, pembaruan layanan telah diluncurkan dengan perbaikan. Silakan coba lagi menghapus instans Anda.
Jika perlu, hapus aplikasi sampel di komputer kerja Anda.

Langkah berikutnya

Untuk mempelajari cara menerapkan logika kustom untuk memantau kondisi di pembuatan sampel Anda, buka tutorial berikutnya dalam seri:

Tutorial: Memprovisikan bangunan Anda dan memantau kondisi kerja