Cara memigrasikan hub IoT secara otomatis menggunakan Azure CLI

  • Artikel

Gunakan Azure CLI untuk memigrasikan hub IoT ke wilayah baru, tingkat baru, atau konfigurasi baru.

Langkah-langkah dalam artikel ini berguna jika Anda ingin:

  • Tingkatkan dari tingkat gratis ke IoT hub tingkat dasar atau standar.
  • Memindahkan hub IoT ke wilayah baru.
  • Ekspor informasi status hub IoT untuk memiliki sebagai cadangan.
  • Tingkatkan jumlah partisi untuk hub IoT.
  • Siapkan hub untuk pengembangan, bukan produksi, lingkungan.

Membandingkan langkah-langkah migrasi otomatis dan manual

Hasil artikel ini mirip dengan Cara memigrasikan hub Azure IoT menggunakan templat Azure Resource Manager, tetapi dengan proses yang berbeda. Sebelum memulai, putuskan proses mana yang tepat untuk skenario Anda.

  • Proses Azure CLI (artikel ini):

    • Memigrasikan registri perangkat Anda, informasi perutean dan titik akhir Anda, dan detail konfigurasi lainnya seperti penyebaran IoT Edge atau konfigurasi manajemen perangkat otomatis.
    • Lebih mudah untuk memigrasikan sejumlah kecil perangkat (misalnya, hingga 10.000).
    • Tidak memerlukan akun Azure Storage.
    • Mengumpulkan string koneksi untuk perutean dan titik akhir pengunggahan file dan menyertakannya dalam output templat ARM.

  • Proses manual:

    • Memigrasikan registri perangkat Anda serta informasi perutean dan titik akhir Anda. Anda harus membuat ulang detail konfigurasi lain secara manual di hub IoT baru.
    • Lebih cepat untuk memigrasikan sejumlah besar perangkat (misalnya, lebih dari 100.000).
    • Menggunakan akun Azure Storage untuk mentransfer registri perangkat.
    • Scrub string koneksi untuk perutean dan titik akhir pengunggahan file dari output templat ARM, dan Anda perlu menambahkannya kembali secara manual.

Prasyarat

  • Azure CLI

    Fitur yang dijelaskan dalam artikel ini memerlukan versi 0.20.0 atau yang lebih baru dari ekstensi azure-iot . Untuk memeriksa versi ekstensi Anda, jalankan az --version. Untuk memperbarui ekstensi Anda, jalankan az extension update --name azure-iot.

    Jika Anda masih memiliki ekstensi azure-cli-iot-ext warisan yang terinstal, hapus ekstensi tersebut sebelum menambahkan ekstensi azure-iot .

Status hub IoT

Ketika kita berbicara tentang memigrasikan status hub IoT, kita mengacu pada kombinasi tiga aspek:

  • Sumber daya Azure Resource Manager (ARM). Aspek ini adalah segala sesuatu yang dapat didefinisikan dalam templat sumber daya, dan merupakan informasi yang sama dengan yang akan Anda dapatkan jika Anda mengekspor templat sumber daya dari hub IoT Anda di portal Azure. Informasi yang diambil sebagai bagian dari aspek Azure Resource Manager meliputi:

    • Waktu retensi hub peristiwa bawaan
    • Sertifikat
    • Properti cloud-ke-perangkat
    • Menonaktifkan SAS perangkat
    • Menonaktifkan autentikasi lokal
    • Aktifkan pemberitahuan unggahan file
    • Titik akhir penyimpanan unggahan file
    • Identities
      • Identitas yang ditetapkan pengguna
      • Identitas yang ditetapkan sistem (diaktifkan atau dinonaktifkan)
    • Seperangkat aturan jaringan
    • Perutean
      • Titik akhir kustom
      • Rute fallback
      • Rute
    • Tag

  • Konfigurasi. Aspek ini ditujukan untuk aspek hub IoT yang tidak diwakili dalam templat ARM. Secara khusus, aspek ini mencakup konfigurasi manajemen perangkat otomatis dan penyebaran IoT Edge.

  • Perangkat. Aspek ini mewakili informasi dalam registri perangkat Anda, yang meliputi:

    • Identitas perangkat dan kembar
    • Identitas modul dan kembar

Properti atau konfigurasi IoT Hub apa pun yang tidak tercantum di sini mungkin tidak diekspor atau diimpor dengan benar.

Mengekspor status hub IoT

Gunakan perintah ekspor status hub az iot untuk mengekspor status hub IoT ke file JSON.

Jika Anda ingin menjalankan langkah-langkah ekspor dan impor dalam satu perintah, lihat bagian nanti di artikel ini untuk Memigrasikan hub IoT.

Saat mengekspor status hub IoT, Anda dapat memilih aspek mana yang akan diekspor.

Parameter Detail
--aspects Aspek status untuk diekspor. Tentukan satu atau beberapa nilai yang diterima: arm, konfigurasi, atau perangkat. Jika parameter ini dibiarkan, maka ketiga aspek diekspor.
--state-file -f Jalur ke file tempat informasi status ditulis.
--replace -r Jika parameter ini disertakan, maka perintah ekspor menimpa konten file status.
--hub-name -n
atau
--login -l		 Nama hub IoT asal (-n) atau string koneksi untuk hub IoT asal (-l). Jika keduanya disediakan, maka string koneksi akan diprioritaskan.
--resource-group -g Nama grup sumber daya untuk hub IoT asal.

Contoh berikut mengekspor semua aspek status hub IoT ke file bernama myHub-state:

az iot hub state export --hub-name myHub --state-file ./myHub-state.json

Contoh berikut hanya mengekspor perangkat dan azure Resource Manager aspek status hub IoT, dan menimpa konten file yang ada:

az iot hub state export --hub-name myHub --state-file ./myHub-state.json --aspects arm devices --replace

Mengekspor titik akhir

Jika Anda memilih untuk mengekspor aspek Azure Resource Manager hub IoT, perintah ekspor mengambil string koneksi untuk titik akhir apa pun yang memiliki autentikasi berbasis kunci dan menyertakannya dalam templat ARM output.

Perintah ekspor juga memeriksa semua titik akhir untuk memverifikasi bahwa sumber daya yang terhubung dengannya masih ada. Jika tidak, maka titik akhir tersebut dan rute apa pun yang menggunakan titik akhir tersebut tidak diekspor.

Mengimpor status hub IoT

Gunakan perintah impor status hub az iot untuk mengimpor informasi status dari file yang diekspor ke hub IoT baru atau yang sudah ada.

Jika Anda ingin menjalankan langkah-langkah ekspor dan impor dalam satu perintah, lihat bagian nanti di artikel ini untuk Memigrasikan hub IoT.

Parameter Detail
--aspects Aspek status yang akan diimpor. Tentukan satu atau beberapa nilai yang diterima: arm, konfigurasi, atau perangkat. Jika parameter ini dibiarkan, ketiga aspek tersebut akan diimpor.
--state-file -f Jalur ke file status yang diekspor.
--replace -r Jika parameter ini disertakan, perintah impor akan menghapus status hub tujuan saat ini.
--hub-name -n
atau
--login -l		 Nama hub IoT tujuan (-n) atau string koneksi untuk hub IoT tujuan (-l). Jika keduanya disediakan, maka string koneksi akan diprioritaskan.
--resource-group -g Nama grup sumber daya untuk hub IoT tujuan.

Contoh berikut mengimpor semua aspek ke hub IoT baru, yang dibuat jika belum ada:

az iot hub state import --hub-name myNewHub --state-file ./myHub-state.json

Contoh berikut hanya mengimpor aspek perangkat dan konfigurasi ke hub IoT baru, yang harus sudah ada, dan menimpa perangkat dan konfigurasi yang ada:

az iot hub state import --hub-name myNewHub --state-file ./myHub-state.json --aspects devices configurations --replace

Membuat hub IoT baru dengan impor status

Anda dapat menggunakan az iot hub state import perintah untuk membuat hub IoT baru atau menulis ke hub IoT yang ada.

Jika Anda ingin membuat IoT Hub baru, maka Anda harus menyertakan arm aspek dalam perintah impor. Jika arm tidak disertakan dalam perintah, dan hub tujuan tidak ada, maka perintah impor gagal.

Jika hub tujuan tidak ada, maka --resource-group parameter juga diperlukan untuk perintah impor.

Memperbarui hub IoT yang ada dengan impor status

Jika hub IoT tujuan sudah ada, maka arm aspeknya tidak diperlukan untuk az iot hub state import perintah . Jika Anda menyertakan aspek , arm semua properti sumber daya akan ditimpa kecuali untuk properti berikut yang tidak dapat diubah setelah pembuatan hub:

  • Lokasi
  • SKU
  • Jumlah partisi Azure Event Hubs bawaan
  • Residensi data
  • Fitur

--resource-group Jika ditentukan dalam perintah impor dan berbeda dari grup sumber daya hub IoT saat ini, maka perintah gagal karena mencoba membuat hub baru dengan nama yang sama dengan yang sudah ada.

Jika Anda menyertakan --replace bendera dalam perintah impor, maka aspek hub IoT berikut dihapus dari hub tujuan sebelum status hub diunggah:

  • ARM: Setiap sertifikat yang diunggah di hub tujuan akan dihapus. Jika sertifikat ada, perlu etag untuk diperbarui.
  • Perangkat: Semua perangkat dan modul, tepi dan non-edge, dihapus.
  • Konfigurasi: Semua konfigurasi ADM dan penyebaran IoT Edge dihapus.

Memigrasikan hub IoT

Gunakan perintah az iot hub state migrate untuk memigrasikan status satu hub IoT ke hub IoT baru atau yang sudah ada.

Perintah ini membungkus langkah-langkah ekspor dan impor ke dalam satu perintah, tetapi tidak memiliki file output. Semua panduan dan batasan yang dijelaskan dalam status Ekspor hub IoT dan Impor status bagian hub IoT juga berlaku untuk state migrate perintah.

Jika Anda memigrasikan registri perangkat dengan banyak perangkat (misalnya, beberapa ratus atau beberapa ribu), Anda mungkin merasa lebih mudah dan lebih cepat untuk menjalankan perintah ekspor dan impor secara terpisah daripada menjalankan perintah migrasi.

Parameter Detail
--aspects Aspek status untuk bermigrasi. Tentukan satu atau beberapa nilai yang diterima: arm, konfigurasi, atau perangkat. Jika parameter ini dibiarkan, ketiga aspek tersebut akan dimigrasikan.
--replace -r Jika parameter ini disertakan, perintah migrasi akan menghapus status hub tujuan saat ini.
--destination-hub --dh
atau
--destination-hub-login --dl		 Nama hub IoT tujuan (--dh) atau string koneksi untuk hub IoT tujuan (--dl). Jika keduanya disediakan, maka string koneksi akan diprioritaskan.
--destination-resource-group --dg Nama grup sumber daya untuk hub IoT tujuan. Grup sumber daya tujuan diperlukan jika hub tujuan tidak ada.
--origin-hub --oh
atau
--origin-hub-login --ol		 Nama hub IoT asal (--oh) atau string koneksi untuk hub IoT asal (--ol). Jika keduanya disediakan, maka string koneksi akan diprioritaskan. Gunakan string koneksi untuk menghindari harus masuk ke sesi Azure CLI.
--origin-resource-group --og Nama grup sumber daya untuk hub IoT asal.

Contoh berikut memigrasikan semua aspek hub asal ke hub tujuan, yang dibuat jika tidak ada:

az iot hub state migrate --origin-hub myHub --origin-resource-group myGroup  --destination-hub myNewHub --destination-resource-group myNewGroup

Memecahkan masalah migrasi

Jika Anda tidak dapat mengekspor atau mengimpor perangkat atau konfigurasi, periksa apakah Anda memiliki akses ke properti tersebut. Salah satu cara untuk memverifikasi akses Anda adalah dengan menjalankan az iot hub device-identity list perintah atau az iot hub configuration list .

az iot hub state migrate Jika perintah gagal, coba jalankan perintah ekspor dan impor secara terpisah. Kedua perintah menghasilkan fungsionalitas yang sama dengan perintah migrasi saja, tetapi dengan menjalankannya secara terpisah Anda dapat meninjau file status yang dibuat dari perintah ekspor.

Langkah berikutnya

Untuk informasi selengkapnya tentang melakukan operasi massal terhadap registri identitas di hub IoT, lihat Mengimpor dan mengekspor identitas perangkat IoT Hub.