Menyiapkan instans dan autentikasi Azure Digital Twins (CLI)
Artikel ini membahas langkah-langkah untuk menyiapkan instans Azure Digital Twins baru, termasuk membuat instans dan menyiapkan autentikasi. Setelah menyelesaikan artikel ini, Anda akan memiliki instans Azure Digital Twins yang siap untuk memulai pemrograman.
Penyiapan penuh untuk instans Azure Digital Twins baru terdiri atas dua bagian:
- Membuat instans
- Menyiapkan izin akses pengguna: Pengguna Azure harus memiliki peran Pemilik Data Azure Digital Twins pada instans Azure Digital Twins untuk dapat mengelolanya dan datanya. Dalam langkah ini, Anda sebagai Pemilik/administrator langganan Azure akan menetapkan peran ini kepada orang yang akan mengelola instans Azure Digital Twins Anda. Ini mungkin diri Anda sendiri atau orang lain di organisasi Anda.
Penting
Untuk menyelesaikan artikel lengkap ini dan menyiapkan instans yang dapat digunakan sepenuhnya, Anda memerlukan izin untuk mengelola sumber daya dan akses pengguna pada langganan Azure. Langkah pertama dapat diselesaikan oleh siapa saja yang dapat membuat sumber daya pada langganan, tetapi langkah kedua memerlukan izin manajemen akses pengguna (atau kerja sama seseorang dengan izin ini). Anda bisa membaca selengkapnya tentang ini di bagian Prasyarat: Izin yang diperlukan untuk langkah izin akses pengguna.
Prasyarat
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.
Menyiapkan sesi CLI
Untuk mulai bekerja dengan Azure Digital Twins di CLI, hal pertama yang harus dilakukan adalah masuk dan mengatur konteks CLI ke langganan Anda untuk sesi ini. Jalankan perintah ini di jendela CLI Anda:
az login
az account set --subscription "<your-Azure-subscription-ID>"
Tip
Anda juga dapat menggunakan nama langganan, bukan ID dalam perintah di atas.
Jika ini pertama kalinya Anda menggunakan langganan ini dengan Azure Digital Twins, jalankan perintah ini untuk mendaftar ke namespace layanan Azure Digital Twins. (Jika Anda tidak yakin, tidak apa-apa untuk menjalankannya lagi bahkan jika Anda pernah melakukannya di masa lalu.)
az provider register --namespace 'Microsoft.DigitalTwins'
Selanjutnya Anda akan menambahkan Ekstensi Microsoft Azure IoT untuk Azure CLI, untuk mengaktifkan perintah untuk berinteraksi dengan Azure Digital Twins dan layanan IoT lainnya. Jalankan perintah ini untuk memastikan Anda memiliki versi terbaru ekstensi:
az extension add --upgrade --name azure-iot
Sekarang Anda siap untuk bekerja dengan Azure Digital Twins di Azure CLI.
Anda dapat memverifikasi ini dengan menjalankan az dt --help sewaktu-waktu untuk melihat daftar perintah Azure Digital Twins tingkat teratas yang tersedia.
Membuat instans Azure Digital Twins
Di bagian ini, Anda akan membuat instans baru Azure Digital Twins menggunakan perintah CLI. Anda harus menyediakan:
- Grup sumber daya tempat instans akan diterapkan. Jika Anda belum memiliki grup sumber daya yang sudah ada, Anda dapat membuatnya sekarang dengan perintah ini:
az group create --location <region> --name <name-for-your-resource-group> - Wilayah untuk penyebaran. Untuk melihat wilayah yang mendukung Azure Digital Twins, buka Produk Azure yang tersedia menurut wilayah.
- Nama untuk instans Anda. Jika langganan Anda memiliki instans Azure Digital Twins lain di wilayah yang sudah menggunakan nama yang ditentukan, Anda akan diminta untuk memilih nama yang berbeda.
Gunakan nilai ini di perintah az dt untuk membuat instans:
az dt create --dt-name <name-for-your-Azure-Digital-Twins-instance> --resource-group <your-resource-group> --location <region>
Ada beberapa parameter opsional yang dapat ditambahkan ke perintah untuk menentukan hal-hal tambahan tentang sumber daya Anda selama pembuatan, termasuk membuat identitas terkelola untuk instans atau mengaktifkan/menonaktifkan akses jaringan publik. Untuk daftar lengkap parameter yang didukung, lihat dokumentasi referensi az dt create .
Membuat instans dengan identitas terkelola
Saat Anda mengaktifkan identitas terkelola pada instans Azure Digital Twins, identitas dibuat untuk identitas tersebut di ID Microsoft Entra. Identitas tersebut kemudian dapat digunakan untuk mengautentikasi ke layanan lain. Anda dapat mengaktifkan identitas terkelola untuk instans Azure Digital Twins saat instans sedang dibuat, atau nanti pada instans yang ada.
Gunakan perintah CLI di bawah ini untuk jenis identitas terkelola yang Anda pilih.
Perintah identitas yang ditetapkan sistem
Untuk membuat instans Azure Digital Twins dengan identitas yang ditetapkan sistem diaktifkan, Anda dapat menambahkan --mi-system-assigned parameter ke az dt create perintah yang digunakan untuk membuat instans. (Untuk informasi selengkapnya tentang perintah pembuatan, lihat dokumentasi referensinya atau instruksi umum untuk menyiapkan instans Azure Digital Twins).
Untuk membuat instans dengan identitas yang ditetapkan sistem, tambahkan --mi-system-assigned parameter seperti ini:
az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-system-assigned
Perintah identitas yang ditetapkan pengguna
Untuk membuat instans dengan identitas yang ditetapkan pengguna, berikan ID identitas yang ditetapkan pengguna yang ada menggunakan --mi-user-assigned parameter , seperti ini:
az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-user-assigned <user-assigned-identity-resource-ID>
Memverifikasi keberhasilan dan mengumpulkan nilai-nilai penting
Jika instans berhasil dibuat, hasilnya di CLI terlihat seperti ini, menghasilkan informasi tentang sumber daya yang telah Anda buat:
Perhatikan hostName,nama,dan resourceGroup instans Azure Digital Twins dari output. Semua nilai ini adalah nilai penting yang mungkin Anda butuhkan saat terus bekerja dengan instans Azure Digital Twins, untuk menyiapkan autentikasi dan sumber daya Azure terkait. Jika pengguna lain akan memprogram terhadap instans, Anda harus berbagi nilai-nilai ini dengan mereka.
Tip
Anda dapat melihat properti ini, bersama dengan semua properti instans Anda, kapan saja dengan menjalankan az dt show --dt-name <your-Azure-Digital-Twins-instance>.
Sekarang Anda memiliki instans Azure Digital Twins yang siap digunakan. Selanjutnya, Anda akan memberikan izin pengguna Azure yang sesuai untuk mengelolanya.
Siapkan izin akses pengguna
Azure Digital Twins menggunakan ID Microsoft Entra untuk kontrol akses berbasis peran (RBAC). Hal ini berarti bahwa sebelum pengguna dapat melakukan panggilan pesawat data ke instans Azure Digital Twins Anda, pengguna tersebut perlu diberi peran dengan izin yang sesuai untuk itu.
Untuk Azure Digital Twins, peran ini adalah Pemilik Data Azure Digital Twins. Anda dapat membaca selengkapnya tentang peran dan keamanan di Solusi Keamanan untuk Azure Digital Twins.
Catatan
Peran ini berbeda dari peran Pemilik ID Microsoft Entra, yang juga dapat ditetapkan pada cakupan instans Azure Digital Twins. Hal ini adalah dua peran manajemen yang berbeda, dan Pemilik tidak memberikan akses ke fitur bidang data yang diberikan dengan APemilik Data Azure Digital Twins.
Bagian ini akan menunjukkan kepada Anda cara membuat penetapan peran untuk pengguna di instans Azure Digital Twins Anda, menggunakan email pengguna tersebut di penyewa Microsoft Entra di langganan Azure Anda. Bergantung pada peran Anda di organisasi, Anda mungkin menyiapkan izin ini untuk diri Anda sendiri, atau menyiapkannya atas nama orang lain yang akan mengelola instans Azure Digital Twins.
Prasyarat: Persyaratan izin
Agar bisa menyelesaikan semua langkah berikut ini, Anda harus memiliki peran dalam langganan yang memiliki izin berikut:
- Membuat dan mengelola sumber daya Azure
- Mengelola akses pengguna ke sumber daya Azure (termasuk memberikan dan mendelegasikan izin)
Peran umum yang memenuhi persyaratan ini adalah Pemilik, Admin akun, atau kombinasi Kontributor dan Administrator Akses Pengguna. Untuk penjelasan lengkap tentang peran dan izin, termasuk izin apa yang disertakan dengan peran lain, kunjungi peran Azure, peran Microsoft Entra, dan peran administrator langganan klasik dalam dokumentasi Azure RBAC.
Untuk melihat peran Anda dalam langganan, kunjungi halaman langganan di portal Azure (Anda bisa menggunakan tautan ini atau mencari Langganan dengan bilah pencarian portal). Cari nama langganan yang Anda gunakan, dan tampilkan peran Anda untuk langganan tersebut di kolom Peran saya:
Jika Anda menemukan bahwa nilainya adalah Kontributor, atau peran lain yang tidak memiliki izin yang diperlukan yang dijelaskan di atas, Anda dapat menghubungi pengguna pada langganan Anda yang memang memiliki izin ini (seperti Pemilik langganan atau admin Akun) dan melanjutkan dengan salah satu cara berikut:
- Minta agar mereka menyelesaikan langkah-langkah penetapan peran atas nama Anda.
- Mintalah agar mereka meningkatkan peran Anda pada langganan sehingga Anda memiliki izin untuk melanjutkan sendiri. Apakah ini tepat tergantung pada organisasi Anda dan peran Anda di dalamnya.
Menetapkan peran
Untuk memberi pengguna izin untuk mengelola instans Azure Digital Twins, Anda harus menetapkan peran Pemilik Data Azure Digital Twins kepada mereka dalam instans.
Gunakan perintah berikut untuk menetapkan peran (harus dijalankan oleh pengguna dengan izin yang memadai dalam langganan Azure). Perintah ini mengharuskan Anda untuk meneruskan nama utama pengguna di akun Microsoft Entra untuk pengguna yang harus diberi peran. Dalam kebanyakan kasus, nilai ini akan cocok dengan email pengguna di akun Microsoft Entra.
az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<Azure-AD-user-principal-name-of-user-to-assign>" --role "Azure Digital Twins Data Owner"
Hasil dari perintah ini adalah informasi output tentang penetapan peran yang telah dibuat untuk pengguna.
Catatan
Jika perintah ini mengembalikan kesalahan yang mengatakan bahwa CLI tidak dapat menemukan perwakilan layanan atau layanan dalam database grafik:
Tetapkan peran menggunakan OBJECT ID pengguna sebagai gantinya. Ini mungkin terjadi untuk pengguna di akun Microsoft pribadi (MSA).
Gunakan halaman portal Azure pengguna Microsoft Entra untuk memilih akun pengguna dan membuka detailnya. Salin ID Objek pengguna:
Kemudian, ulangi perintah daftar penetapan peran menggunakan ID Objek pengguna untuk parameter di assignee atas.
Verifikasi keberhasilan
Salah satu cara untuk memeriksa apakah Anda telah berhasil menyiapkan penetapan peran adalah dengan melihat penetapan peran untuk instans Azure Digital Twins di portal Azure. Buka instans Azure Digital Twins Anda di portal Azure. Untuk sampai ke sana, Anda dapat mencarinya di halaman instans Azure Digital Twins atau mencari namanya di bilah pencarian portal).
Kemudian, lihat semua peran yang ditetapkan di bawah Penetapan Peran kontrol akses (IAM>). Penetapan peran Anda akan muncul dalam daftar.
Sekarang Anda memiliki instans Azure Digital Twins yang siap digunakan, dan telah menetapkan izin untuk mengelolanya.
Mengaktifkan/menonaktifkan identitas terkelola untuk instans
Bagian ini memperlihatkan kepada Anda cara menambahkan identitas terkelola ke instans Azure Digital Twins yang sudah ada. Anda juga dapat menonaktifkan identitas terkelola pada instans yang sudah memilikinya.
Gunakan perintah CLI di bawah ini untuk jenis identitas terkelola yang Anda pilih.
Perintah identitas yang ditetapkan sistem
Perintah untuk mengaktifkan identitas yang ditetapkan sistem untuk instans yang ada adalah perintah yang sama az dt create yang digunakan untuk membuat instans baru dengan identitas yang ditetapkan sistem. Alih-alih memberikan nama baru instans untuk dibuat, Anda dapat memberikan nama instans yang sudah ada. Kemudian, pastikan untuk menambahkan --mi-system-assigned parameter .
az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --mi-system-assigned
Untuk menonaktifkan identitas yang ditetapkan sistem pada instans tempat identitas saat ini diaktifkan, gunakan perintah berikut untuk mengatur --mi-system-assigned ke false.
az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --mi-system-assigned false
Perintah identitas yang ditetapkan pengguna
Untuk mengaktifkan identitas yang ditetapkan pengguna pada instans yang ada, berikan ID identitas yang ditetapkan pengguna yang ada dalam perintah berikut:
az dt identity assign --dt-name <name-of-existing-instance> --resource-group <resource-group> --user <user-assigned-identity-resource-ID>
Untuk menonaktifkan identitas yang ditetapkan pengguna pada instans tempat identitas saat ini diaktifkan, berikan ID identitas dalam perintah berikut:
az dt identity remove --dt-name <name-of-existing-instance> --resource-group <resource-group> --user <user-assigned-identity-resource-ID>
Pertimbangan untuk menonaktifkan identitas terkelola
Penting untuk mempertimbangkan efek yang dapat dimiliki oleh setiap perubahan pada identitas atau perannya pada sumber daya yang menggunakannya. Jika Anda menggunakan identitas terkelola dengan titik akhir Azure Digital Twins atau untuk riwayat data dan identitas dinonaktifkan, atau peran yang diperlukan dihapus darinya, koneksi titik akhir atau riwayat data dapat menjadi tidak dapat diakses dan alur 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.
Langkah berikutnya
Uji panggilan REST API individu pada instans Anda menggunakan perintah Azure Digital Twins CLI:
Atau, lihat cara menyambungkan aplikasi klien ke instans Anda dengan kode autentikasi: