Bagikan melalui

Mengonfigurasi pengunggahan file IoT Hub menggunakan Azure CLI

  • Artikel

Artikel ini menunjukkan cara mengonfigurasi pengunggahan file di IoT hub menggunakan Azure CLI.

Untuk menggunakan fungsionalitas pengunggahan file di IoT Hub, Anda harus terlebih dahulu mengaitkan akun penyimpanan Azure dengan IoT Hub Anda. Azure IoT Hub secara otomatis menghasilkan URI SAS dengan izin tulis ke kontainer blon ini untuk digunakan perangkat saat mereka mengunggah file. Selain akun penyimpanan dan kontainer blob, Anda dapat mengatur waktu hidup untuk URI SAS dan jenis autentikasi yang digunakan IoT Hub dengan penyimpanan Azure. Anda juga dapat mengonfigurasi pengaturan untuk pemberitahuan pengunggahan file opsional yang dapat dikirimkan IoT Hub ke layanan ujung belakang.

Prasyarat

  • Akun Azure aktif. Jika Anda tidak memiliki akun, Anda dapat membuat akun gratis hanya dalam beberapa menit.

  • IoT Hub di langganan Azure Anda. Jika belum memiliki hub, Anda dapat mengikuti langkah-langkah di Membuat IoT hub.

  • Akun Azure Storage dengan kontainer blob. Jika Anda tidak memiliki akun Azure Storage, Anda bisa menggunakan Azure CLI untuk membuatnya. Untuk informasi selengkapnya, lihat Membuat akun penyimpanan.

Catatan

Artikel ini menggunakan versi terbaru ekstensi Azure IoT, yang disebut azure-iot. Versi warisan disebut azure-cli-iot-ext. Anda seharusnya hanya memiliki satu versi yang terinstal pada satu waktu. Anda bisa menggunakan perintah az extension list untuk memvalidasi ekstensi yang saat ini terinstal.

Gunakan az extension remove --name azure-cli-iot-ext untuk menghapus versi lama ekstensi.

Gunakan az extension add --name azure-iot untuk menambahkan versi baru ekstensi.

Untuk melihat ekstensi apa yang telah Anda instal, gunakan az extension list.

Masuk dan atur akun Azure Anda

Masuklah ke akun Azure Anda dan pilih langganan Anda. Jika menggunakan Azure Cloud Shell, Anda seharusnya sudah masuk; namun, Anda mungkin masih perlu memilih langganan Azure jika memiliki beberapa langganan.

  1. Pada perintah, jalankan perintah login:

    az login

    Ikuti instruksinya untuk mengautentikasi menggunakan kode dan masuk ke akun Azure Anda melalui browser web.

  2. Jika Anda memiliki beberapa langganan Azure, maka masuk ke Azure akan memberi Anda akses ke semua akun Azure yang terkait dengan informasi masuk Anda. Gunakan perintah berikut ini untuk mencantumkan akun Azure yang tersedia untuk Anda gunakan:

    az account list

    Gunakan perintah berikut untuk memilih langganan yang ingin Anda gunakan guna menjalankan perintah untuk membuat loT hub IoT Anda. Anda dapat menggunakan nama atau ID langganan dari output perintah sebelumnya:

    az account set --subscription {your subscription name or id}

Mengonfigurasi akses akun penyimpanan

Langkah-langkah berikut mengasumsikan bahwa Anda membuat akun penyimpanan menggunakan model penyebaran Resource Managerdan bukan model penyebaran Klasik tersebut.

Untuk mengonfigurasi unggahan file dari perangkat, Anda perlu memberikan izin akses hub IoT ke akun Azure Storage. Akun penyimpanannya harus berada di langganan yang sama dengan hub IoT Anda. Anda juga memerlukan nama kontainer blob di akun penyimpanannya.

Anda dapat menggunakan autentikasi berbasis kunci atau berbasis identitas untuk memberikan izin akses. Microsoft merekomendasikan autentikasi berbasis identitas sebagai opsi yang lebih aman.

Autentikasi berbasis kunci

Untuk autentikasi berbasis kunci, berikan string koneksi untuk akun penyimpanan Anda. Gunakan perintah az storage account show-connection-string untuk mengambil kunci akun penyimpanan Anda.

Catat nilai connectionString. string koneksi terlihat mirip dengan output berikut:

{
  "connectionString": "DefaultEndpointsProtocol=https;EndpointSuffix=core.windows.net;AccountName={your_storage_account_name};AccountKey={your_storage_account_key}"
}

Autentikasi berbasis identitas

Anda dapat menggunakan identitas terkelola yang ditetapkan sistem atau identitas terkelola yang ditetapkan pengguna untuk autentikasi berbasis identitas. Untuk informasi selengkapnya, lihat Dukungan IoT Hub untuk identitas terkelola.

Gunakan perintah az role assignment create untuk menetapkan peran ke identitas terkelola Anda. Untuk informasi selengkapnya, lihat Menetapkan peran Azure untuk akses ke data blob.

Mengonfigurasi IoT hub Anda

Anda sekarang dapat mengonfigurasi hub IoT Anda untuk mengaktifkan kemampuan untuk mengunggah file ke hub IoT menggunakan rincian akun penyimpanan Anda.

Konfigurasinya memerlukan nilai berikut:

  • Kontainer penyimpanan: Kontainer blob di akun penyimpanan Azure di langganan Azure Anda saat ini untuk dikaitkan dengan hub IoT Anda. Anda telah mengambil informasi akun penyimpanan yang diperlukan di bagian sebelumnya. Azure IoT Hub secara otomatis menghasilkan URI SAS dengan izin tulis ke kontainer blon ini untuk digunakan perangkat saat mereka mengunggah file.

  • Terima pemberitahuan untuk file yang diunggah: Aktifkan atau nonaktifkan pemberitahuan pengunggahan file.

  • SAS TTL: Pengaturan ini adalah waktu aktif dari URI SAS yang dikembalikan ke perangkat oleh IoT Hub. Diatur ke satu jam secara default.

  • Pengaturan pemberitahuan file default TTL: Waktu hidup dari pemberitahuan pengunggahan file sebelum kedaluwarsa. Diatur ke satu hari secara default.

  • Jumlah pengiriman maksimum pemberitahuan file: Berapa kali IoT Hub mencoba mengirimkan pemberitahuan pengunggahan file. Diatur ke 10 secara default.

  • Durasi kunci pemberitahuan file: Durasi kunci untuk antrian pemberitahuan file. Atur ke 60 detik secara default.

  • Jenis autentikasi: Jenis autentikasi untuk IoT Hub untuk digunakan dengan Azure Storage. Pengaturan ini menentukan bagaimana IoT hub Anda mengautentikasi dan mengotorisasi dengan Azure Storage. Defaultnya adalah autentikasi berbasis kunci; namun, opsi autentikasi identitas terkelola yang ditetapkan sistem atau ditetapkan pengguna disarankan. Identitas terkelola menyediakan layanan Azure dengan identitas terkelola secara otomatis di Microsoft Entra ID dengan cara yang aman.

    Catatan

    Pengaturan jenis autentikasi mengonfigurasi cara IoT hub Anda mengautentikasi dengan akun Azure Storage. Perangkat selalu mengautentikasi dengan Azure Storage menggunakan URI SAS yang mereka dapatkan dari IoT hub.

Perintah berikut menunjukkan cara mengonfigurasi pengaturan pengunggahan file di IoT hub Anda. Perintah ini ditampilkan secara terpisah untuk kejelasan, tetapi biasanya, Anda akan mengeluarkan satu perintah dengan semua parameter yang diperlukan untuk skenario Anda. Sertakan kutipan di mana mereka muncul di baris perintah. Jangan sertakan kurung kurawal. Detail lebih lanjut tentang setiap parameter dapat ditemukan di dokumentasi Azure CLI untuk perintah pembaruan az iot hub.

Perintah berikut mengonfigurasi akun penyimpanan dan kontainer blob.

az iot hub update --name {your iot hub name} \
    --fileupload-storage-connectionstring "{your storage account connection string}" \
    --fileupload-storage-container-name "{your container name}"

Perintah berikut mengatur waktu hidup URI SAS ke default (satu jam).

az iot hub update --name {your iot hub name} \
    --fileupload-sas-ttl 1

Perintah berikut mengaktifkan pemberitahuan file dan mengatur properti pemberitahuan file ke nilai defaultnya. (Waktu pemberitahuan pengunggahan file diatur ke satu jam dan durasi penguncian diatur ke 60 detik.)

az iot hub update --name {your iot hub name} \
    --fileupload-notifications true  \
    --fileupload-notification-max-delivery-count 10 \
    --fileupload-notification-ttl 1 \
    --fileupload-notification-lock-duration 60

Perintah berikut mengonfigurasi autentikasi berbasis kunci:

az iot hub update --name {your iot hub name} \
    --fileupload-storage-auth-type keyBased

Perintah berikut mengonfigurasi autentikasi menggunakan identitas terkelola yang ditetapkan oleh sistem IoT hub. Sebelum dapat menjalankan perintah ini, Anda perlu mengaktifkan identitas terkelola yang ditetapkan sistem untuk hub IoT Anda dan memberinya peran kontrol akses berbasis peran yang benar di akun Azure Storage Anda. Untuk mempelajari caranya, lihat dukungan IoT Hub untuk identitas terkelola.

az iot hub update --name {your iot hub name} \
    --fileupload-storage-auth-type identityBased \
    --fileupload-storage-identity [system]

Perintah berikut mengambil identitas terkelola yang ditetapkan pengguna yang dikonfigurasi di IoT hub Anda dan mengonfigurasi autentikasi dengan salah satunya. Sebelum Anda dapat menggunakan identitas terkelola yang ditetapkan pengguna untuk mengautentikasi, identitas tersebut harus dikonfigurasi di hub IoT Anda dan diberikan peran kontrol akses berbasis peran yang sesuai di akun Azure Storage Anda. Untuk detail dan langkah lebih lanjut, lihat dukungan IoT Hub untuk identitas terkelola.

Untuk mengueri identitas terkelola yang ditetakan pengguna di IoT hub Anda, gunakan perintah tampilkan identitas az iot hub.

az iot hub identity show --name {your iot hub name} --query userAssignedIdentities

Perintah menampilkan kumpulan identitas terkelola yang ditetapkan pengguna yang dikonfigurasi di IoT hub Anda. Output berikut menunjukkan kumpulan yang berisi identitas terkelola yang ditetapkan pengguna tunggal.

{
  "/subscriptions/{your subscription ID}/resourcegroups/{your resource group}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{your user-assigned managed identity name}": 
  {
    "clientId": "<client ID GUID>",
    "principalId": "<principal ID GUID>"
  }
}

Perintah berikut mengonfigurasi autentikasi untuk menggunakan identitas yang ditetapkan pengguna di atas.

az iot hub update --name {your iot hub name} \
    --fileupload-storage-auth-type identityBased \
    --fileupload-storage-identity  "/subscriptions/{your subscription ID}/resourcegroups/{your resource group}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{your user-assigned managed identity name}"

Anda dapat meninjau pengaturan pada IoT hub Anda menggunakan perintah berikut:

az iot hub show --name {your iot hub name}

Untuk hanya meninjau pengaturan pengunggahan file, gunakan perintah berikut:

az iot hub show --name {your iot hub name}
    --query '[properties.storageEndpoints, properties.enableFileUploadNotifications, properties.messagingEndpoints.fileNotifications]'

Untuk sebagian besar situasi, menggunakan parameter bernama dalam perintah Azure CLI adalah yang paling mudah; namun, Anda juga dapat mengkonfigurasi pengaturan pengunggahan file dengan parameter --set. Perintah berikut dapat membantu Anda memahami caranya.

az iot hub update --name {your iot hub name} \
  --set properties.storageEndpoints.'$default'.connectionString="{your storage account connection string}"

az iot hub update --name {your iot hub name} \
  --set properties.storageEndpoints.'$default'.containerName="{your storage container name}"

az iot hub update --name {your iot hub name} \
  --set properties.storageEndpoints.'$default'.sasTtlAsIso8601=PT1H0M0S

az iot hub update --name {your iot hub name} \
  --set properties.enableFileUploadNotifications=true

az iot hub update --name {your iot hub name} \
  --set properties.messagingEndpoints.fileNotifications.maxDeliveryCount=10

az iot hub update --name {your iot hub name} \
  --set properties.messagingEndpoints.fileNotifications.ttlAsIso8601=PT1H0M0S

Langkah berikutnya