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

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}

Mengambil rincian akun penyimpanan Anda

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

Untuk mengonfigurasi pengunggahan file dari perangkat, Anda memerlukan string koneksi untuk akun Azure Storage. Akun penyimpanannya harus berada di langganan yang sama dengan hub IoT Anda. Anda juga memerlukan nama kontainer blob di akun penyimpanannya. Gunakan perintah berikut untuk mengambil kunci akun penyimpanan Anda:

az storage account show-connection-string --name {your storage account name} \
  --resource-group {your storage account resource group}

String koneksi akan mirip dengan output berikut:

{
  "connectionString": "DefaultEndpointsProtocol=https;EndpointSuffix=core.windows.net;AccountName={your storage account name};AccountKey={your storage account key}"
}

Catat nilai connectionString. Anda akan membutuhkannya dalam langkah-langkah berikut.

Anda dapat menggunakan kontainer blob yang sudah ada untuk unggahan file Anda atau membuat yang baru:

  • Untuk membuat daftar kontainer blob yang ada di akun penyimpanan Anda, gunakan perintah berikut:

    az storage container list --connection-string "{your storage account connection string}"

  • Untuk membuat kontainer blob yang ada di akun penyimpanan Anda, gunakan perintah berikut:

    az storage container create --name {container name} \
  --connection-string "{your storage account connection string}"

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. Default adalah autentikasi berbasis kunci; Namun, identitas terkelola yang ditugaskan sistem dan pengguna juga dapat digunakan. Identitas terkelola menyediakan layanan Azure dengan identitas yang dikelola secara otomatis di ID Microsoft Entra dengan cara yang aman. Untuk mempelajari cara mengonfigurasi identitas terkelola di IoT hub dan akun Azure Storage Anda, lihat dukungan IoT Hub untuk identitas terkelola. Setelah dikonfigurasi, Anda dapat mengatur salah satu identitas terkelola untuk digunakan untuk autentikasi dengan penyimpanan Azure.

    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 IoT hub dan memberikannya peran RBAC yang sesuai 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 terkelola harus dikonfigurasi pada IoT hub dan diberikan peran RBAC 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