Mengunggah file dengan IoT Hub

  • Artikel

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 telah dikonfigurasi sebelumnya dengan hub. Ada tiga bagian untuk menggunakan unggahan file dengan IoT Hub: pra-konfigurasi akun penyimpanan Azure dan kontainer blob di hub IoT Anda, mengunggah file dari perangkat, dan, 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:

  1. 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.

  2. 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.

  3. 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 telah mengaktifkan pemberitahuan ini di hub IoT, pemberitahuan akan mengirimkannya di titik akhir ini setiap kali perangkat memberi tahu hub bahwa telah menyelesaikan pengunggahan file. Layanan dapat menggunakan pemberitahuan ini untuk memicu pemrosesan lebih lanjut dari data blob. Untuk informasi selengkapnya, lihat Layanan: Pemberitahuan unggahan file.

Pengunggahan file didukung sepenuhnya oleh perangkat IoT Azure dan SDK layanan. 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 pengunggahan file dari perangkat yang terdaftar dengan hub IoT Anda akan 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.

Jika menggunakan portal, Anda dapat membuat akun penyimpanan dan kontainer selama konfigurasi. Jika tidak, untuk membuat akun penyimpanan, lihat Membuat akun penyimpanan di dokumentasi penyimpanan Azure. Setelah memiliki akun penyimpanan, Anda dapat melihat cara membuat kontainer blob di mulai cepat Azure Blob Storage. 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 yang dikelola secara otomatis di ID Microsoft Entra dengan cara yang aman. Untuk mempelajari cara mengonfigurasi identitas terkelola, lihat bagian Mengonfigurasi unggahan file dengan identitas terkelola dari dukungan IoT Hub untuk identitas terkelola.

Unggahan file tunduk pada pengaturan firewall Azure Storage. Berdasarkan konfigurasi autentikasi, Anda harus memastikan perangkat Anda dapat berkomunikasi dengan penyimpanan Azure.

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 Microsoft Azure, Azure CLI, PowerShell, atau API manajemen untuk mengonfigurasi pengunggahan 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 Hub Iot

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. Perangkat selalu mengautentikasi dengan token SAS yang disajikan dalam URI SAS yang diambil dari IoT Hub.

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} (Properti sasToken dalam 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=rw

    Untuk 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 akan 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.

Langkah berikutnya