Membuat titik akhir di Azure Digital Twins

Artikel ini menjelaskan cara membuat titik akhir untuk peristiwa Azure Digital Twin menggunakan portal Azure atau Azure CLI. Anda juga dapat mengelola titik akhir dengan API sarana kontrol DigitalTwinsEndpoint.

Merutekan pemberitahuan peristiwa dari Azure Digital Twins ke layanan hilir atau sumber daya komputasi yang terhubung adalah proses dua langkah: membuat titik akhir, lalu membuat rute peristiwa untuk mengirim data ke titik akhir tersebut. Artikel ini membahas langkah pertama, menyiapkan titik akhir yang dapat menerima peristiwa. Nantinya, Anda dapat membuat rute peristiwa yang menentukan peristiwa mana yang dihasilkan oleh Azure Digital Twins yang dikirimkan ke titik akhir mana.

Prasyarat

• Anda akan memerlukan akun Azure, yang dapat disiapkan secara gratis

• Anda akan memerlukan instans Azure Digital Twins di langganan Azure Anda. Jika Anda belum memiliki instans, Anda dapat membuat instans menggunakan langkah-langkah dalam Menyiapkan instans dan autentikasi. Miliki nilai berikut dari penyetelan yang berguna untuk digunakan nanti di artikel ini:

  • Nama Instans
  • Grup sumber daya

  Anda dapat menemukan detail ini di portal Microsoft Azure setelah menyiapkan instans Anda.

  

Selanjutnya, ikuti instruksi di bawah ini jika Anda ingin menggunakan Azure CLI saat mengikuti panduan ini.

Persiapkan lingkungan Anda untuk Azure CLI

• Gunakan lingkungan Bash di Azure Cloud Shell. Untuk informasi selengkapnya, lihat Mulai Cepat untuk Bash di Azure Cloud Shell.

  

• Jika Anda lebih suka menjalankan perintah referensi CLI secara lokal, instal Azure CLI. Jika Anda menjalankan Windows atau macOS, pertimbangkan untuk menjalankan Azure CLI dalam kontainer Docker. Untuk informasi lebih lanjut, lihat Cara menjalankan Azure CLI di kontainer Docker.

  • Jika Anda menggunakan instalasi lokal, masuk ke Azure CLI dengan menggunakan perintah login az. Untuk menyelesaikan proses autentikasi, ikuti langkah-langkah yang ditampilkan di terminal Anda. Untuk opsi masuk lainnya, lihat Masuk dengan Azure CLI.

  • Saat Anda diminta, instal ekstensi Azure CLI pada penggunaan pertama. Untuk informasi selengkapnya tentang ekstensi, lihat Menggunakan ekstensi dengan Azure CLI.

  • Jalankan versi az untuk menemukan versi dan pustaka dependen yang diinstal. Untuk meningkatkan ke versi terbaru, jalankan peningkatan az.

Membuat sumber daya yang diperlukan

Layanan ini adalah jenis titik akhir yang didukung yang dapat Anda buat untuk instans Anda:

• Topik Event Grid
  • Untuk titik akhir Event Grid, hanya topik Event Grid yang didukung. Domain Event Grid tidak didukung sebagai titik akhir.
• Hub Event Hubs
• Topik Service Bus

Untuk menautkan titik akhir ke Azure Digital Twins, topik Event Grid, hub peristiwa, atau topik Bus Layanan yang Anda gunakan untuk titik akhir harus sudah ada.

Gunakan bagan berikut untuk melihat sumber daya apa yang harus disiapkan sebelum membuat titik akhir Anda.

Jenis titik akhir	Sumber daya yang diperlukan (ditautkan ke instruksi pembuatan)
Titik akhir Azure Event Grid	Topik Event Grid *skema event harus berupa Event Grid Schema atau Cloud Event Schema v1.0
Titik akhir Azure Event Hubs	Namespace layanan Azure Event Hubs pusat aktivitas (Opsional) aturan otorisasi untuk autentikasi berbasis kunci
Titik akhir Microsoft Azure Service Bus	Namespace layanan Microsoft Azure Service Bus Topik Service Bus (Opsional) aturan otorisasi untuk autentikasi berbasis kunci

Membuat titik akhir

Setelah membuat sumber daya titik akhir, Anda dapat menggunakannya untuk titik akhir Azure Digital Twins.

Portal

Untuk membuat titik akhir baru, buka halaman instans Anda di portal Microsoft Azure (Anda dapat menemukan instans dengan memasukkan namanya ke bilah pencarian portal).

1. Dari menu instans, pilihTitik Akhir. Lalu dari halaman Titik Akhir yang mengikuti, pilih + Buat titik akhir. Melakukannya akan membuka halaman Buat titik akhir, tempat Anda akan mengisi bidang dalam langkah-langkah berikut.

   

2. Masukkan Nama untuk titik akhir Anda dan pilih jenis Titik Akhir.

3. Lengkapi detail lain yang diperlukan untuk jenis titik akhir Anda, termasuk langganan Anda dan sumber daya titik akhir yang dijelaskan sebelumnya.

   1. Untuk Azure Event Hubs dan titik akhir Bus Layanan saja, Anda harus memilih jenis Autentikasi. Anda dapat menggunakan autentikasi berbasis kunci dengan aturan otorisasi yang telah dibuat sebelumnya, atau identitas terkelola yang ditetapkan sistem atau ditetapkan pengguna. Untuk informasi selengkapnya tentang menggunakan opsi autentikasi identitas, lihat Opsi titik akhir: Autentikasi berbasis identitas.

   

4. Selesaikan pembuatan titik akhir Anda dengan memilih Simpan.

Setelah membuat titik akhir, Anda bisa memverifikasi bahwa titik akhir berhasil dibuat dengan memeriksa ikon pemberitahuan di bilah portal Microsoft Azure teratas:

Jika pembuatan titik akhir gagal, amati pesan kesalahan dan coba lagi setelah beberapa menit.

Anda juga bisa melihat titik akhir yang dibuat kembali di halaman Titik akhir untuk instans Azure Digital Twins Anda.

Sekarang topik Event Grid, pusat aktivitas, atau topik Bus Layanan tersedia sebagai titik akhir di Azure Digital Twins, dengan nama yang Anda pilih untuk titik akhir. Anda biasanya akan menggunakan nama tersebut sebagai target rute peristiwa, yang dapat Anda buat di Membuat rute dan filter.

CLI

Contoh berikut menunjukkan cara membuat titik akhir menggunakan perintah buat titik akhir az dt untuk CLI Azure Digital Twins. Ganti tempat penampung dalam perintah dengan detail sumber daya Anda sendiri.

Untuk membuat titik akhir Event Grid:

az dt endpoint create eventgrid --endpoint-name <Event-Grid-endpoint-name> --eventgrid-resource-group <Event-Grid-resource-group-name> --eventgrid-topic <your-Event-Grid-topic-name> --dt-name <your-Azure-Digital-Twins-instance-name>

Untuk membuat titik akhir Azure Event Hubs (autentikasi berbasis kunci):

az dt endpoint create eventhub --endpoint-name <Event-Hub-endpoint-name> --eventhub-resource-group <Event-Hub-resource-group> --eventhub-namespace <Event-Hub-namespace> --eventhub <Event-Hub-name> --eventhub-policy <Event-Hub-policy> --dt-name <your-Azure-Digital-Twins-instance-name>

Untuk membuat titik akhir topik Microsoft Azure Service Bus (autentikasi berbasis kunci):

az dt endpoint create servicebus --endpoint-name <Service-Bus-endpoint-name> --servicebus-resource-group <Service-Bus-resource-group-name> --servicebus-namespace <Service-Bus-namespace> --servicebus-topic <Service-Bus-topic-name> --servicebus-policy <Service-Bus-topic-policy> --dt-name <your-Azure-Digital-Twins-instance-name>

Setelah berhasil menjalankan perintah ini, topik Event Grid, pusat aktivitas, atau topik Bus Layanan akan tersedia sebagai titik akhir di Azure Digital Twins, dengan nama yang Anda berikan dengan --endpoint-name argumen . Anda biasanya akan menggunakan nama tersebut sebagai target rute peristiwa, yang dapat Anda buat di Membuat rute dan filter.

Opsi titik akhir: Autentikasi berbasis identitas

Bagian ini menjelaskan cara menggunakan identitas terkelola untuk instans Azure Digital Twins saat meneruskan peristiwa ke tujuan perutean yang didukung. Menyiapkan identitas terkelola tidak diperlukan untuk perutean, tetapi dapat membantu instans mengakses sumber daya yang dilindungi Microsoft Entra lainnya dengan mudah, seperti Azure Event Hubs, tujuan Bus Layanan, dan Kontainer Azure Storage. Identitas terkelola dapat ditetapkan sistem atau ditetapkan pengguna.

Sisa bagian ini berjalan melalui tiga langkah untuk menyiapkan titik akhir dengan identitas terkelola.

1. Aktifkan identitas terkelola untuk instans

Gunakan tab di bawah ini untuk instruksi yang cocok dengan pengalaman pilihan Anda.

Portal

Pertama, pastikan Anda telah mengaktifkan identitas terkelola untuk instans Azure Digital Twins Anda.

Selain itu, pastikan Anda memiliki peran Pemilik Data Azure Digital Twins pada instans. Anda dapat menemukan instruksi di Menyiapkan izin akses pengguna.

CLI

Pertama, pastikan Anda telah mengaktifkan identitas terkelola untuk instans Azure Digital Twins Anda.

Selain itu, pastikan Anda memiliki peran Pemilik Data Azure Digital Twins pada instans. Anda dapat menemukan instruksi di Menyiapkan izin akses pengguna.

2. Tetapkan peran Azure ke identitas

Setelah identitas terkelola dibuat untuk instans Azure Digital Twins, Anda harus menetapkan peran yang sesuai untuk mengautentikasi dengan berbagai jenis titik akhir untuk merutekan peristiwa ke tujuan yang didukung. Bagian ini menjelaskan opsi peran dan cara menetapkannya ke identitas terkelola.

Penting

Pastikan untuk menyelesaikan langkah ini. Tanpa itu, identitas tidak akan dapat mengakses titik akhir dan peristiwa Anda tidak akan dikirimkan.

Berikut adalah peran minimum yang diperlukan identitas Azure Digital Twins Anda untuk mengakses titik akhir, tergantung pada jenis tujuan. Peran dengan izin yang lebih tinggi (seperti peran Pemilik Data) juga akan berfungsi.

Tujuan	Peran Azure
Azure Event Hubs	Azure Service Bus Data Sender
Azure Service Bus	Azure Service Bus Data Sender
Kontainer penyimpanan Azure	Data blob penyimpanan kontributor

Gunakan tab di bawah ini untuk menetapkan peran menggunakan pengalaman pilihan Anda.

Portal

Untuk menetapkan peran ke identitas, mulailah dengan membuka portal Microsoft Azure di browser.

1. Navigasikan ke sumber daya titik akhir Anda (hub peristiwa, topik Azure Service Bus, atau kontainer penyimpanan) dengan mencari namanya di bilah pencarian portal.

2. Pilih Kontrol akses (IAM).

3. Pilih Tambahkan>Tambahkan penetapan peran untuk membuka halaman Tambahkan penetapan peran.

4. Tetapkan peran yang diinginkan ke identitas terkelola instans Azure Digital Twins Anda, menggunakan informasi di bawah ini. Untuk langkah-langkah mendetail, lihat Menetapkan peran Azure menggunakan portal Azure.

   Pengaturan	Nilai
   Peran	Pilih peran yang diinginkan dari opsi.
   Tetapkan akses ke	Identitas terkelola
   Anggota	Pilih identitas terkelola yang ditetapkan pengguna atau yang ditetapkan sistem dari instans Azure Digital Twins Anda yang sedang ditetapkan perannya. Identitas yang ditetapkan pengguna akan memiliki nama yang Anda pilih saat membuat identitas, dan identitas yang ditetapkan sistem akan memiliki nama yang cocok dengan nama instans Azure Digital Twins Anda.

   

CLI

Anda dapat menambahkan parameter --scopes ke perintah az dt create untuk menetapkan identitas ke satu atau beberapa cakupan dengan peran tertentu. Perintah dengan parameter ini dapat digunakan saat pertama kali membuat instans, atau kemudian dengan meneruskan nama instans yang sudah ada.

Berikut adalah contoh yang membuat instans dengan identitas terkelola yang ditetapkan sistem, dan menetapkan identitas tersebut peran kustom yang disebut MyCustomRole di pusat aktivitas.

az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-system-assigned --scopes "/subscriptions/<subscription ID>/resourceGroups/<resource-group>/providers/Microsoft.EventHub/namespaces/<Event-Hubs-namespace>/eventhubs/<event-hub-name>" --role MyCustomRole

Untuk contoh penetapan peran lainnya dengan perintah ini, lihat dokumentasi referensi az dt create.

Anda juga dapat menggunakan grup perintah penetapan peran az untuk membuat dan mengelola peran. Perintah ini dapat digunakan untuk mendukung skenario lain ketika Anda tidak ingin mengelompokkan penetapan peran dengan perintah buat.

3. Buat titik akhir dengan autentikasi berbasis identitas

Setelah menyiapkan identitas terkelola untuk instans Azure Digital Twins Anda dan menetapkan peran yang sesuai, Anda dapat membuat titik akhir yang menggunakan identitas untuk autentikasi. Opsi ini hanya tersedia untuk Azure Event Hubs dan titik akhir jenis Bus Layanan (tidak didukung untuk Event Grid).

Catatan

Anda tidak bisa mengedit titik akhir yang telah dibuat dengan identitas berbasis kunci untuk berubah menjadi autentikasi berbasis identitas. Anda harus memilih jenis autentikasi ketika titik akhir pertama kali dibuat.

Gunakan tab di bawah ini untuk membuat titik akhir menggunakan pengalaman pilihan Anda.

Portal

Mulai ikuti instruksi umum untuk membuat titik akhir Azure Digital Twins.

Saat Anda sampai ke langkah menyelesaikan detail yang diperlukan untuk jenis titik akhir Anda, pilih Ditetapkan sistem atau Ditetapkan pengguna (pratinjau) untuk jenis Autentikasi.

Selesaikan pengaturan titik akhir Anda dan pilih Simpan.

CLI

Identitas terkelola ditambahkan ke titik akhir dengan menambahkan parameter ke az dt endpoint create perintah yang digunakan untuk membuat titik akhir. (Untuk informasi selengkapnya tentang perintah ini, lihat dokumentasi referensinya atau instruksi umum untuk membuat titik akhir Azure Digital Twins.).

Gunakan perintah CLI di bawah ini untuk jenis identitas terkelola yang Anda pilih.

Perintah identitas yang ditetapkan sistem

Untuk membuat titik akhir yang menggunakan autentikasi yang ditetapkan sistem, tentukan IdentityBased jenis autentikasi dengan --auth-type parameter . Contoh di bawah menggambarkan fungsionalitas ini untuk titik akhir Azure Event Hubs.

az dt endpoint create eventhub --endpoint-name <endpoint-name> --eventhub-resource-group <eventhub-resource-group> --eventhub-namespace <eventhub-namespace> --eventhub <eventhub-name> --dt-name <instance-name> --auth-type IdentityBased

Perintah identitas yang ditetapkan pengguna

Untuk membuat titik akhir yang menggunakan autentikasi identitas yang ditetapkan pengguna, tentukan ID sumber daya identitas yang ditetapkan pengguna dengan --user parameter . Contoh di bawah menggambarkan fungsionalitas ini untuk titik akhir Azure Event Hubs.

az dt endpoint create eventhub --endpoint-name <endpoint-name> --eventhub-resource-group <eventhub-resource-group> --eventhub-namespace <eventhub-namespace> --eventhub <eventhub-name> --dt-name <instance-name> --user <user-assigned-identity-resource-ID>

Pertimbangan untuk menonaktifkan identitas terkelola

Karena identitas dikelola secara terpisah dari titik akhir yang menggunakannya, penting untuk mempertimbangkan efek yang dapat dilakukan oleh setiap perubahan pada identitas atau perannya pada titik akhir di instans Azure Digital Twins Anda. Jika identitas dinonaktifkan, atau peran yang diperlukan untuk titik akhir dihapus darinya, titik akhir dapat menjadi tidak dapat diakses dan aliran peristiwa akan terganggu.

Untuk terus menggunakan titik akhir yang telah disiapkan dengan identitas terkelola yang sekarang telah dinonaktifkan, Anda harus menghapus titik akhir dan membuatnya kembali dengan jenis autentikasi yang berbeda. Mungkin perlu waktu hingga satu jam agar acara dapat melanjutkan pengiriman ke titik akhir setelah perubahan ini.

Opsi titik akhir: Dead-lettering

Ketika titik akhir tidak dapat mengirimkan peristiwa dalam jangka waktu tertentu atau setelah mencoba mengirimkan peristiwa beberapa kali, itu dapat mengirim peristiwa yang tidak terkirim ke akun penyimpanan. Proses ini dikenal sebagai surat gagal.

Anda dapat menyiapkan sumber daya penyimpanan yang diperlukan menggunakan portal Microsoft Azure atau CLI Azure Digital Twins. Namun, untuk membuat titik akhir dengan dead-lettering diaktifkan, Anda harus menggunakan Azure Digital Twins CLI atau API sarana kontrol.

Untuk mempelajari selengkapnya tentang dead-lettering, lihat Titik akhir dan rute peristiwa. Untuk petunjuk tentang cara mengatur titik akhir dengan surat gagal, lanjutkan melalui seluruh bagian ini.

Menyiapkan sumber daya penyimpanan

Sebelum mengatur lokasi surat gagal, Anda harus memiliki akun penyimpanan dengan kontainer yang telah disiapkan dalam akun Azure Anda.

Anda memberikan URI untuk kontainer ini saat membuat titik akhir nanti. Lokasi surat gagal akan disediakan ke titik akhir sebagai URI kontainer dengan token SAS. Token itu membutuhkan izin write untuk kontainer tujuan dalam akun penyimpanan. Surat mati SAS URI yang sepenuhnya terbentuk akan dalam format: https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>.

Ikuti langkah-langkah di bawah ini untuk menyiapkan sumber daya penyimpanan ini di akun Azure Anda, untuk bersiap menyiapkan sambungan titik akhir di bagian berikutnya.

1. Ikuti langkah-langkah dalam Membuat akun penyimpanan untuk membuat akun penyimpanan di langganan Azure Anda. Catat nama akun penyimpanan untuk digunakan nanti.
2. Ikuti langkah-langkah dalam Membuat kontainer untuk membuat kontainer dalam akun penyimpanan baru. Catat nama kontainer untuk digunakan nanti.

Membuat token SAS

Selanjutnya, buat token SAS untuk akun penyimpanan Anda yang dapat digunakan titik akhir untuk mengaksesnya.

Portal

1. Mulailah dengan menavigasi ke akun penyimpanan Anda di portal Microsoft Azure (Anda dapat menemukannya berdasarkan nama dengan bilah pencarian portal).

2. Di halaman akun penyimpanan, pilih tautan Tanda tangan akses bersama di bilah navigasi kiri untuk mulai menyiapkan token SAS.

   

3. Pada halaman Tanda tangan akses bersama, di bawah Layanan yang diizinkan dan Jenis sumber daya yang diizinkan, pilih pengaturan apa pun yang Anda inginkan. Anda harus memilih setidaknya satu kotak di setiap kategori. Di bawah Izin yang diizinkan, pilih Tulis (Anda juga bisa memilih izin lain jika menginginkannya).

4. Atur nilai apa pun yang Anda inginkan untuk pengaturan yang tersisa.

5. Setelah selesai, pilih tombol Hasilkan SAS dan string koneksi untuk menghasilkan token SAS.

   

6. Melakukannya akan menghasilkan beberapa nilai SAS dan string koneksi di bagian bawah halaman yang sama, di bawah pilihan pengaturan. Gulir ke bawah untuk menampilkan nilai, dan gunakan ikon Salin ke clipboard untuk menyalin nilai token SAS. Simpan untuk digunakan nanti.

   

CLI

1. Ambil kunci akun penyimpanan Anda menggunakan perintah berikut dan salin nilai untuk salah satu kunci Anda:

   az storage account keys list --account-name <storage-account-name>
   

2. Pilih tanggal kedaluwarsa dan hasilkan token SAS untuk akun penyimpanan Anda menggunakan perintah berikut:

   az storage account generate-sas --account-name <storage-account-name> --account-key <storage-account-key> --expiry <expiration-date> --services bfqt --resource-types o --permissions w
   

   Output dari perintah ini adalah token SAS. Salin nilai token SAS untuk digunakan nanti.

   Catatan

   Perintah ini mencakup layanan "blob", "file", "antrean", dan tabel; jenis sumber daya "objek"; dan mengizinkan izin "tulis".

   Untuk mengetahui informasi lebih lanjut tentang perintah az storage account generate-sas dan parameternya, lihat referensi Azure CLI.

Membuat titik akhir surat gagal

Portal

Untuk membuat titik akhir dengan dead-lettering diaktifkan, Anda harus menggunakan perintah CLI atau API sarana kontrol untuk membuat titik akhir Anda, bukan portal Azure.

Untuk instruksi tentang cara membuat jenis titik akhir ini dengan Azure CLI, beralihlah ke tab CLI untuk bagian ini.

CLI

Untuk membuat titik akhir yang mengaktifkan dead-lettering, tambahkan --deadletter-sas-uri parameter ke perintah az dt endpoint create yang membuat titik akhir.

Nilai untuk parameter adalah huruf mati SAS URI yang terdiri dari nama akun penyimpanan, nama kontainer, dan token SAS yang Anda kumpulkan di bagian sebelumnya. Parameter ini membuat titik akhir dengan autentikasi berbasis kunci. Berikut tampilan parameternya:

--deadletter-sas-uri https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>

Tip

Untuk membuat titik akhir surat mati dengan autentikasi berbasis identitas, tambahkan parameter dead-letter dari bagian ini dan parameter identitas terkelola yang sesuai ke perintah yang sama.

Anda juga dapat membuat titik akhir surat mati menggunakan API sarana kontrol Azure Digital Twins alih-alih CLI. Untuk melakukannya, lihat dokumentasi DigitalTwinsEndpoint untuk melihat cara menyusun permintaan dan menambahkan parameter surat mati.

Skema penyimpanan pesan

Setelah titik akhir dengan surat gagal disiapkan, pesan bersurat gagal mati akan disimpan dalam format berikut di akun penyimpanan Anda:

<container>/<endpoint-name>/<year>/<month>/<day>/<hour>/<event-ID>.json

Pesan surat gagal akan cocok dengan skema peristiwa asli yang dimaksudkan untuk dikirimkan ke titik akhir asli Anda.

Berikut adalah contoh pesan surat mati untuk pemberitahuan buat kembar:

{
  "specversion": "1.0",
  "id": "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "Microsoft.DigitalTwins.Twin.Create",
  "source": "<your-instance>.api.<your-region>.da.azuredigitaltwins-test.net",
  "data": {
    "$dtId": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "$etag": "W/\"xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx\"",
    "TwinData": "some sample",
    "$metadata": {
      "$model": "dtmi:test:deadlettermodel;1",
      "room": {
        "lastUpdateTime": "2020-10-14T01:11:49.3576659Z"
      }
    }
  },
  "subject": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "time": "2020-10-14T01:11:49.3667224Z",
  "datacontenttype": "application/json",
  "traceparent": "00-889a9094ba22b9419dd9d8b3bfe1a301-f6564945cb20e94a-01"
}

Langkah berikutnya

Untuk benar-benar mengirim data dari Azure Digital Twins ke titik akhir, Anda harus menentukan rute peristiwa. Rute-rute ini memungkinkan pengembang menghubungkan aliran peristiwa, ke seluruh sistem dan ke layanan hilir. Satu rute harus memungkinkan beberapa pemberitahuan dan jenis peristiwa dipilih. Lanjutkan untuk membuat rute peristiwa ke titik akhir Anda di Membuat rute dan filter.