Mengunggah file dengan IoT Hub
Ada banyak skenario di mana Anda tidak dapat dengan mudah memetakan data perangkat ke dalam pesan perangkat-ke-cloud yang relatif kecil yang diterima IoT Hub. Misalnya, mengirim file media besar seperti video; atau, mengirim batch telemetri besar, baik yang diunggah oleh perangkat yang terhubung secara terputus-putus atau diagregasi dan dikompresi untuk menghemat bandwidth.
Saat perlu mengunggah file besar dari perangkat, Anda masih dapat menggunakan keamanan dan keandalan IoT Hub. Namun, daripada menengahi pesan melalui dirinya sendiri, IoT Hub bertindak sebagai pengirim ke akun penyimpanan Azure terkait. IoT Hub juga dapat memberikan pemberitahuan ke layanan ujung belakang saat perangkat menyelesaikan pengunggahan file.
Jika Anda memerlukan bantuan untuk memutuskan kapan harus menggunakan properti yang dilaporkan, pesan perangkat ke cloud, atau unggahan file, lihat Panduan komunikasi perangkat ke cloud.
Penting
Fungsionalitas pengunggahan file pada perangkat yang menggunakan autentikasi otoritas sertifikat (OS) X.509 berada dalam pratinjau publik, dan mode pratinjau harus diaktifkan. Ini umumnya tersedia di perangkat yang menggunakan autentikasi thumbprint X.509 atau pengesahan sertifikat X.509 dengan Layanan Provisi Perangkat Azure. Untuk mempelajari selengkapnya tentang autentikasi X.509 dengan IoT Hub, lihat Sertifikat X.509 yang didukung.
Gambaran umum pengunggahan file
Hub IoT memfasilitasi pengunggahan file dari perangkat yang terhubung dengan menyediakan URI tanda tangan akses bersama (SAS) berdasarkan per unggahan untuk kontainer blob dan akun penyimpanan Azure yang dikonfigurasi untuk pengunggahan file dari hub. Ada tiga bagian untuk menggunakan unggahan file dengan IoT Hub:
- Mengonfigurasi akun penyimpanan Azure dan kontainer blob di hub IoT Anda.
- Mengunggah file dari perangkat.
- Secara opsional, memberi tahu layanan backend tentang unggahan file yang telah selesai.
Sebelum dapat menggunakan fitur pengunggahan file, Anda harus mengaitkan akun penyimpanan Azure dan kontainer blob dengan hub IoT. Anda juga dapat mengonfigurasi pengaturan yang mengontrol cara IoT Hub mengautentikasi dengan penyimpanan Azure, time-to-live (TTL) URI SAS yang dibagikan hub IoT ke perangkat, dan pemberitahuan pengunggahan file ke layanan ujung belakang Anda. Untuk mempelajari selengkapnya, lihat Mengaitkan akun penyimpanan Azure dengan IoT Hub.
Perangkat mengikuti proses tiga langkah untuk mengunggah file ke kontainer blob terkait:
Perangkat memulai pengunggahan file dengan hub IoT. Perangkat meneruskan nama blob dalam permintaan dan mendapatkan URI SAS serta ID korelasi sebagai gantinya. URI SAS berisi token SAS untuk penyimpanan Azure yang memberikan izin baca-tulis perangkat pada blob yang diminta dalam kontainer blob. Untuk informasi selengkapnya, lihat Perangkat: Menginisialisasi unggahan file.
Perangkat menggunakan URI SAS untuk memanggil API penyimpanan blob Azure dengan aman untuk mengunggah file ke kontainer blob. Untuk informasi selengkapnya, lihat Perangkat: Mengunggah file menggunakan API penyimpanan Azure.
Saat pengunggahan file selesai, perangkat memberi tahu hub IoT tentang status penyelesaian menggunakan ID korelasi yang diterimanya dari IoT Hub saat memulai pengunggahan. Untuk informasi selengkapnya, lihat Perangkat: Memberi tahu IoT Hub tentang unggahan file yang telah selesai.
Layanan ujung belakang dapat berlangganan pemberitahuan pengunggahan file di titik akhir pemberitahuan pengunggahan file yang tersambung layanan hub IoT. Jika Anda mengaktifkan pemberitahuan ini di hub IoT Anda, pemberitahuan tersebut mengirimkannya di titik akhir ini setiap kali perangkat memberi tahu hub bahwa ia menyelesaikan unggahan file. Layanan dapat menggunakan pemberitahuan ini untuk memicu pemrosesan lebih lanjut dari data blob. Untuk informasi selengkapnya, lihat Layanan: Pemberitahuan unggahan file.
Perangkat Azure IoT dan SDK layanan sepenuhnya mendukung unggahan file. Untuk informasi selengkapnya, lihat Unggahan file menggunakan SDK.
Kuota dan batas pengunggahan file
IoT Hub memberlakukan batasan pembatasan pada jumlah pengunggahan file yang dapat dimulai dalam periode tertentu. Ambang didasarkan pada SKU dan jumlah unit hub IoT Anda. Selain itu, setiap perangkat dibatasi hingga 10 pengunggahan file aktif secara bersamaan pada satu waktu. Untuk informasi selengkapnya, lihat kuota dan pembatasan IoT Hub.
Kaitkan akun penyimpanan Azure dengan IoT Hub
Anda harus mengaitkan akun penyimpanan Azure dan kontainer blob dengan hub IoT untuk menggunakan fitur pengunggahan file. Semua unggahan file dari perangkat yang terdaftar di hub IoT Anda masuk ke kontainer ini. Untuk mengonfigurasi akun penyimpanan dan kontainer blob di hub IoT Anda, lihat Mengonfigurasi unggahan file IoT Hub menggunakan portal Azure, Mengonfigurasi unggahan file IoT Hub menggunakan Azure CLI, atau Mengonfigurasi unggahan file IoT Hub menggunakan PowerShell. Anda juga dapat menggunakan API manajemen IoT Hub untuk mengonfigurasi pengunggahan file secara terprogram.
Secara default, Azure IoT Hub menggunakan autentikasi berbasis kunci untuk menghubungkan dan memberi otorisasi dengan Azure Storage. Anda juga dapat mengonfigurasi identitas terkelola yang ditetapkan pengguna atau yang ditetapkan sistem untuk mengautentikasi Azure IoT Hub dengan Azure Storage. Identitas terkelola menyediakan layanan Azure dengan identitas terkelola secara otomatis di Microsoft Entra ID dengan cara yang aman.
Unggahan file tunduk pada pengaturan firewall Azure Storage. Anda perlu memastikan perangkat Anda dapat berkomunikasi dengan penyimpanan Azure sesuai dengan konfigurasi autentikasi Anda.
Ada beberapa pengaturan lain yang mengontrol perilaku pengunggahan file dan pemberitahuan pengunggahan file. Berikut ini bagian daftar semua pengaturan yang tersedia. Bergantung pada apakah Anda menggunakan portal Azure, Azure CLI, PowerShell, atau API manajemen untuk mengonfigurasi unggahan file, beberapa pengaturan ini mungkin tidak tersedia. Pastikan untuk mengatur pengaturan enableFileUploadNotifications jika Anda ingin pemberitahuan dikirim ke layanan ujung belakang saat pengunggahan file selesai.
Pengaturan penyimpanan dan autentikasi IoT Hub
Pengaturan berikut mengaitkan akun penyimpanan dan kontainer dengan hub IoT Anda dan mengontrol cara hub Anda mengautentikasi dengan penyimpanan Azure. Pengaturan ini tidak memengaruhi cara perangkat mengautentikasi dengan penyimpanan Azure. Anda masih perlu menghubungkan perangkat Anda ke penyimpanan menggunakan SAS URI. Saat ini, SAS URI dihasilkan menggunakan string koneksi.
Untuk informasi tentang mengonfigurasi unggahan file untuk menggunakan autentikasi berbasis identitas, lihat Mengonfigurasi unggahan file dengan identitas terkelola.
| Properti | Deskripsi | Rentang dan default |
|---|---|---|
| storageEndpoints.$default.authenticationType | Kontrol cara IoT Hub mengautentikasi dengan penyimpanan Azure. | Nilai yang mungkin adalah keyBased dan identityBased. Default: keyBased. |
| storageEndpoints.$default.connectionString | String koneksi ke akun penyimpanan Azure yang akan digunakan untuk pengunggahan file. | Default: String kosong. |
| storageEndpoints.$default.containerName | Nama kontainer untuk mengunggah file. | Default: String kosong. |
| storageEndpoints.$default.identity | Identitas terkelola yang akan digunakan untuk autentikasi berbasis identitas. | Nilai yang mungkin adalah [system] untuk identitas terkelola yang ditetapkan sistem atau ID sumber daya untuk identitas terkelola yang ditetapkan pengguna. Nilai tidak digunakan untuk autentikasi berbasis kunci. Default: null. |
Pengaturan pengunggahan file
Pengaturan berikut mengontrol pengunggahan file dari perangkat.
| Properti | Deskripsi | Rentang dan default |
|---|---|---|
| storageEndpoints.$default.ttlAsIso8601 | TTL default untuk URI SAS yang dihasilkan oleh IoT Hub. | ISO_8601 interval hingga 48 jam (minimal satu menit). Default: satu jam. |
Pengaturan pemberitahuan pengunggahan file
Pengaturan berikut mengontrol pemberitahuan pengunggahan file ke layanan ujung belakang.
| Properti | Deskripsi | Rentang dan default |
|---|---|---|
| enableFileUploadNotifications | Mengontrol apakah pemberitahuan unggahan file ditulis ke titik akhir pemberitahuan file. | Bool. Default: Palsu. |
| fileNotifications.ttlAsIso8601 | TTL default untuk pemberitahuan unggahan file. | ISO_8601 interval hingga 48 jam (minimal satu menit). Default: satu jam. |
| fileNotifications.lockDuration | Durasi kunci untuk antrean pemberitahuan unggahan file. | 5 hingga 300 detik. Default: 60 detik. |
| fileNotifications.maxDeliveryCount | Jumlah pengiriman maksimum untuk antrean pemberitahuan unggahan file. | 1 hingga 100. Default: 10. |
Unggahan file menggunakan SDK
Panduan penggunaan berikut memberikan instruksi langkah demi langkah yang lengkap untuk mengunggah file menggunakan perangkat IoT Azure dan SDK layanan. Panduan menunjukkan kepada Anda cara menggunakan portal Azure untuk mengaitkan akun penyimpanan dengan hub IoT. Panduan ini juga berisi cuplikan kode atau merujuk ke sampel yang memandu Anda melalui unggahan.
| Panduan | Contoh SDK perangkat | Contoh SDK layanan |
|---|---|---|
| .NET | Ya | Ya |
| Java | Ya | Ya |
| Node.js | Ya | Ya |
| Python | Ya | Tidak (tidak didukung) |
Catatan
SDK perangkat C menggunakan satu panggilan pada klien perangkat untuk melakukan pengunggahan file. Untuk informasi selengkapnya, lihat IoTHubDeviceClient_UploadToBlobAsync() dan IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync(). Fungsi-fungsi ini melakukan semua aspek pengunggahan file dalam satu panggilan: memulai unggahan, mengunggah file ke penyimpanan Azure, dan memberi tahu IoT Hub saat selesai. Interaksi ini berarti bahwa, selain protokol apa pun yang digunakan perangkat untuk berkomunikasi dengan IoT Hub, perangkat juga harus dapat berkomunikasi melalui HTTPS dengan penyimpanan Azure karena fungsi ini melakukan panggilan ke API penyimpanan Azure.
Perangkat: Menginisialisasi pengunggahan file
Perangkat memanggil REST API Buat URI SAS Pengunggahan File atau API yang setara di salah satu SDK perangkat untuk memulai pengunggahan file.
Protokol yang didukung: HTTPS
Titik akhir: {iot hub}.azure-devices.net/devices/{deviceId}/files
Metode: POST
{
"blobName":"myfile.txt"
}
| Properti | Deskripsi |
|---|---|
| blobName | Nama blob untuk menghasilkan URI SAS. |
IoT Hub merespons dengan ID korelasi dan elemen URI SAS yang dapat digunakan perangkat untuk mengautentikasi dengan penyimpanan Azure. Respons ini tunduk pada batas pembatasan dan batas pengunggahan per perangkat dari hub IoT target.
{
"correlationId":"MjAyMTA3MzAwNjIxXzBiNjgwOGVkLWZjNzQtN...MzYzLWRlZmI4OWQxMzdmNF9teWZpbGUudHh0X3ZlcjIuMA==",
"hostName":"contosostorageaccount.blob.core.windows.net",
"containerName":"device-upload-container",
"blobName":"mydevice/myfile.txt",
"sasToken":"?sv=2018-03-28&sr=b&sig=mBLiODhpKXBs0y9RVzwk1S...l1X9qAfDuyg%3D&se=2021-07-30T06%3A11%3A10Z&sp=rw"
}
| Properti | Deskripsi |
|---|---|
| correlationId | Pengidentifikasi untuk perangkat yang akan digunakan saat mengirim pemberitahuan lengkap pengunggahan file ke IoT Hub. |
| hostName | Nama host akun penyimpanan Azure untuk akun penyimpanan yang dikonfigurasi di hub IoT |
| containerName | Nama kontainer blob yang dikonfigurasi di hub IoT. |
| blobName | Lokasi tempat blob akan disimpan dalam kontainer. Nama dalam format berikut: {device ID of the device making the request}/{blobName in the request} |
| sasToken | Token SAS yang memberikan akses baca-tulis pada blob dengan penyimpanan Azure. Token dibuat dan ditandatangani oleh IoT Hub. |
Saat menerima respons, perangkat:
Menyimpan ID korelasi untuk disertakan dalam pemberitahuan lengkap pengunggahan file ke hub IoT saat pengunggahan selesai.
Menggunakan properti lain untuk membuat URI SAS untuk blob yang digunakan untuk mengautentikasi dengan penyimpanan Azure. URI SAS berisi URI sumber daya untuk blob yang diminta dan token SAS. Bentuknya sebagai berikut:
https://{hostName}/{containerName}/{blobName}{sasToken}(PropertisasTokendalam respons berisi karakter awalan '?'.) Tanda kurung kurawal tidak disertakan.Misalnya, untuk nilai yang dikembalikan dalam sampel sebelumnya, URI SAS adalah,
https://contosostorageaccount.blob.core.windows.net/device-upload-container/mydevice/myfile.txt?sv=2018-03-28&sr=b&sig=mBLiODhpKXBs0y9RVzwk1S...l1X9qAfDuyg%3D&se=2021-07-30T06%3A11%3A10Z&sp=rwUntuk informasi selengkapnya tentang URI SAS dan token SAS, lihat Membuat SAS layanan di dokumentasi penyimpanan Azure.
Perangkat: Mengunggah file menggunakan API penyimpanan Azure
Perangkat menggunakan REST API Azure Blob Storage atau API SDK penyimpanan Azure yang setara untuk mengunggah file ke blob di penyimpanan Azure.
Protokol yang didukung: HTTPS
Contoh berikut menunjukkan permintaan Letakkan Blob untuk membuat atau memperbarui blob blok kecil. Perhatikan bahwa URI yang digunakan untuk permintaan ini adalah URI SAS yang ditampilkan oleh IoT Hub di bagian sebelumnya. Header x-ms-blob-type menunjukkan bahwa permintaan ini adalah untuk blob blok. Jika permintaan berhasil, penyimpanan Azure menampilkan 201 Created.
PUT https://contosostorageaccount.blob.core.windows.net/device-upload-container/mydevice/myfile.txt?sv=2018-03-28&sr=b&sig=mBLiODhpKXBs0y9RVzwk1S...l1X9qAfDuyg%3D&se=2021-07-30T06%3A11%3A10Z&sp=rw HTTP/1.1
Content-Length: 11
Content-Type: text/plain; charset=UTF-8
Host: contosostorageaccount.blob.core.windows.net
x-ms-blob-type: BlockBlob
hello world
Bekerja dengan API penyimpanan Azure berada di luar cakupan artikel ini. Selain REST API penyimpanan Blob Azure yang ditautkan sebelumnya di bagian ini, Anda dapat menjelajahi dokumentasi berikut untuk membantu Anda memulai:
Untuk mempelajari selengkapnya tentang bekerja dengan blob di penyimpanan Azure, lihat dokumentasi Azure Blob Storage.
Untuk informasi tentang menggunakan SDK klien penyimpanan Azure guna mengunggah blob, lihat Referensi API Azure Blob Storage.
Perangkat: Memberi tahu IoT Hub tentang pengunggahan file yang selesai
Perangkat memanggil REST API Perbarui Status Pengunggahan File atau API yang setara di salah satu SDK perangkat saat pengunggahan file selesai. Perangkat harus memperbarui status pengunggahan file dengan IoT Hub terlepas dari apakah pengunggahan berhasil atau gagal.
Protokol yang didukung: HTTPS
Titik akhir: {iot hub}.azure-devices.net/devices/{deviceId}/files/notifications
Metode: POST
{
"correlationId": "MjAyMTA3MzAwNjIxXzBiNjgwOGVkLWZjNzQtN...MzYzLWRlZmI4OWQxMzdmNF9teWZpbGUudHh0X3ZlcjIuMA==",
"isSuccess": true,
"statusCode": 200,
"statusDescription": "File uploaded successfully"
}
| Properti | Deskripsi |
|---|---|
| correlationId | ID korelasi yang diterima dalam permintaan URI SAS awal. |
| isSuccess | Boolean yang menunjukkan apakah pengunggahan file berhasil. |
| statusCode | Bilangan bulat yang mewakili kode status pengunggahan file. Biasanya tiga digit; misalnya, 200 atau 201. |
| statusDescription | Deskripsi status pengunggahan file. |
Saat menerima pemberitahuan lengkap pengunggahan file dari perangkat, IoT Hub:
Memicu pemberitahuan pengunggahan file ke layanan ujung belakang jika pemberitahuan pengunggahan file dikonfigurasi.
Melepaskan sumber daya yang terkait dengan pengunggahan file. Jika IoT Hub tidak menerima pemberitahuan, IoT Hub mempertahankan sumber daya hingga sas URI time-to-live (TTL) yang terkait dengan unggahan kedaluwarsa.
Layanan: Pemberitahuan pengunggahan file
Jika pemberitahuan unggahan file diaktifkan di hub IoT Anda, hub Anda menghasilkan pesan pemberitahuan untuk layanan backend saat menerima pemberitahuan dari perangkat bahwa unggahan file selesai. IoT Hub mengirimkan pemberitahuan pengunggahan file ini melalui titik akhir yang tersambung ke layanan. Semantik yang diterima untuk pemberitahuan unggahan file sama dengan untuk pesan cloud ke perangkat dan memiliki siklus hidup pesan yang sama. SDK layanan mengekspos API untuk menangani pemberitahuan pengunggahan file.
Protokol yang didukung AMQP, AMQP-WS
Titik akhir: {iot hub}.azure-devices.net/messages/servicebound/fileuploadnotifications
Metode GET
Setiap pesan yang diambil dari titik akhir pemberitahuan pengunggahan file adalah baris JSON:
{
"deviceId":"mydevice",
"blobUri":"https://contosostorageaccount.blob.core.windows.net/device-upload-container/mydevice/myfile.txt",
"blobName":"mydevice/myfile.txt",
"lastUpdatedTime":"2021-07-31T00:26:50+00:00",
"blobSizeInBytes":11,
"enqueuedTimeUtc":"2021-07-31T00:26:51.5134008Z"
}
| Properti | Deskripsi |
|---|---|
| enqueuedTimeUtc | Tanda waktu menunjukkan kapan pemberitahuan dibuat. |
| deviceId | ID Perangkat dari perangkat yang mengunggah file. |
| blobUri | URI file yang diunggah. |
| blobName | Nama file yang diunggah. Nama dalam format berikut: {device ID of the device}/{name of the blob} |
| lastUpdatedTime | Tanda waktu yang menunjukkan kapan file terakhir diperbarui. |
| blobSizeInBytes | Bilangan bulat yang mewakili ukuran file yang diunggah dalam byte. |
Layanan dapat menggunakan pemberitahuan untuk mengelola pengunggahan. Misalnya, layanan dapat memicu pemrosesan data blob mereka sendiri, memicu pemrosesan data blob menggunakan layanan Azure lainnya, atau mencatat pemberitahuan pengunggahan file untuk ditinjau nanti.