Bagikan melalui

Mengunggah file dari perangkat Anda ke cloud dengan Azure IoT Hub (.NET)

  • Artikel

Artikel ini menunjukkan cara mengunggah file kemampuan IoT Hub mengunggah file ke penyimpanan blob Azure, menggunakan perangkat Azure IoT .NET dan SDK layanan.

Mulai cepat Mengirimkan telemetri dari perangkat ke hub IoT dan artikel Mengirim pesan cloud-ke-perangkat dengan IoT Hub menunjukkan fungsionalitas dasar olahpesan perangkat-ke-cloud dan cloud-ke-perangkat IoT Hub. Artikel Mengonfigurasi Perutean Pesan dengan IoT Hub menunjukkan cara untuk menyimpan pesan perangkat-ke-cloud secara andal dalam penyimpanan blob Microsoft Azure. Namun, dalam beberapa skenario Anda tidak dapat dengan mudah memetakan data yang dikirim perangkat Anda ke pesan perangkat ke cloud yang relatif kecil yang diterima IoT Hub. Contohnya:

  • Video
  • File besar yang berisi gambar
  • Data getaran yang diambil sampelnya pada frekuensi tinggi
  • Beberapa bentuk data yang diproses sebelumnya

File tersebut biasanya diproses secara batch di cloud menggunakan alat seperti Azure Data Factory atau tumpukan Hadoop. Saat Anda perlu mengunggah file dari perangkat, Anda masih dapat menggunakan keamanan dan keandalan IoT Hub. Artikel ini menunjukkan cara.

Di akhir artikel ini, Anda menjalankan dua aplikasi konsol .NET:

  • FileUploadSample. Aplikasi perangkat ini mengunggah file ke penyimpanan menggunakan SAS URI yang disediakan oleh hub IoT Anda. Sampel ini berasal dari repositori Azure IoT C# SDK yang Anda unduh di prasyarat.

  • ReadFileUploadNotification. Aplikasi layanan ini menerima pemberitahuan pengunggahan file dari hub IoT Anda. Anda membuat aplikasi ini.

Catatan

IoT Hub mendukung banyak platform dan bahasa perangkat, (termasuk C, Java, Python, dan JavaScript) melalui Azure IoT device SDK. Lihat Azure IoT Developer Center untuk mempelajari cara menghubungkan perangkat Anda ke Azure IoT Hub.

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.

Prasyarat

  • Hub IoT. Membuat satu dengan CLI atau portal Azure.

  • Perangkat yang terdaftar. Daftarkan perangkat di portal Azure.

  • Aplikasi sampel yang Anda jalankan dalam artikel ini ditulis menggunakan C# dengan .NET Core.

    Unduh .NET Core SDK untuk beberapa platform dari .NET.

    Anda dapat memverifikasi versi .NET Core SDK Anda saat ini di komputer pengembangan Anda menggunakan perintah berikut:

    dotnet --version

  • Unduh Azure IoT C# SDK dari Unduh sampel dan ekstrak arsip ZIP.

  • Port 8883 harus terbuka di firewall Anda. Sampel dalam artikel ini menggunakan protokol MQTT, yang berkomunikasi melalui port 8883. Port ini dapat diblokir di beberapa lingkungan jaringan perusahaan dan pendidikan. Untuk informasi selengkapnya dan cara mengatasi masalah ini, lihat Menyambungkan ke Azure IoT Hub (MQTT).

Mengaitkan akun Microsoft Azure Storage dengan IoT Hub

Untuk mengunggah file dari perangkat, Anda harus memiliki akun Azure Storage dan kontainer Azure Blob Storage yang terkait dengan hub IoT Anda. Setelah Anda mengaitkan akun penyimpanan dan kontainer dengan hub IoT, hub IoT Anda dapat menyediakan elemen URI SAS saat diminta oleh perangkat. Perangkat kemudian dapat menggunakan elemen ini untuk membangun URI SAS yang digunakan untuk melakukan autentikasi dengan Azure Storage dan mengunggah file ke kontainer blob.

Untuk mengaitkan akun Azure Storage dengan hub IoT Anda:

  1. Di bagian Pengaturan Hub, pilih Unggah file di panel kiri IoT hub Anda.

    Cuplikan layar yang menunjukkan pilih pengaturan pengunggahan file tertentu dari portal.

  2. Di panel Unggahan file, pilih Kontainer Azure Storage. Untuk artikel ini, sebaiknya akun penyimpanan dan IoT Hub Anda berada di wilayah yang sama.

    • Jika Anda sudah memiliki akun penyimpanan yang ingin digunakan, pilih dari daftar.

    • Pilih +Akun Storage untuk membuat akun penyimpanan. Masukkan nama akun penyimpanan dan pastikan Lokasi diatur ke wilayah yang sama dengan hub IoT Anda, lalu pilih OK. Akun baru dibuat dalam grup sumber daya yang sama dengan hub IoT Anda. Saat penyebaran selesai, pilih akun penyimpanan dari daftar.

    Setelah akun penyimpanan dipilih, panel Kontainer akan terbuka.

  3. Di halaman Kontainer, pilih kontainer blob.

    • Jika Anda sudah memiliki kontainer blob yang ingin digunakan, pilih dari daftar dan klik Pilih.

    • Pilih + Kontainer untuk membuat kontainer blob baru. Masukkan nama kontainer baru. Untuk tujuan artikel ini, Anda dapat membiarkan semua bidang lainnya dengan opsi default-nya. Pilih Buat. Setelah penyebaran selesai, pilih kontainer dari daftar dan klik Pilih.

  4. Kembali ke panel Unggahan file, pastikan bahwa pemberitahuan file diatur ke Aktif. Anda dapat membiarkan pengaturan lainnya dengan opsi default-nya. Pilih Simpan dan tunggu hingga pengaturan selesai sebelum berpindah ke bagian selanjutnya.

    Cuplikan layar yang menunjukkan konfirmasi pengaturan pengunggahan file di portal.

Untuk petunjuk yang lebih mendetail tentang cara membuat akun Azure Storage, lihat Membuat akun penyimpanan. Untuk petunjuk selengkapnya tentang cara mengaitkan akun penyimpanan dan kontainer blob dengan hub IoT, lihat Mengonfigurasi unggahan file menggunakan portal Azure.

Mengunggah file dari aplikasi perangkat

Dalam artikel ini, Anda menggunakan sampel dari repositori Azure IoT C# SDK yang Anda unduh sebelumnya sebagai aplikasi perangkat. Anda dapat membuka file di bawah ini menggunakan Visual Studio, Visual Studio Code, atau editor teks pilihan Anda.

Sampel terletak di azure-iot-sdk-csharp/iothub/device/samples/getting started/FileUploadSample di folder tempat Anda mengekstrak Azure IoT C# SDK.

Periksa kode di FileUpLoadSample.cs. File ini berisi logika sampel utama. Setelah membuat klien perangkat IoT Hub, maka akan mengikuti prosedur tiga bagian standar untuk mengunggah file dari perangkat:

  1. Kode ini memanggil metode GetFileUploadSasUriAsync pada klien perangkat untuk mendapatkan SAS URI dari hub IoT:

    var fileUploadSasUriRequest = new FileUploadSasUriRequest
{
    BlobName = fileName
};

// Lines removed for clarity

FileUploadSasUriResponse sasUri = await _deviceClient.GetFileUploadSasUriAsync(fileUploadSasUriRequest);
Uri uploadUri = sasUri.GetBlobUri();

  2. Kode menggunakan SAS URI untuk mengunggah file ke penyimpanan Azure. Dalam sampel ini, menggunakan SAS URI untuk membuat klien blob blok penyimpanan Azure dan mengunggah file:

    var blockBlobClient = new BlockBlobClient(uploadUri);
await blockBlobClient.UploadAsync(fileStreamSource, new BlobUploadOptions());

  3. Kode tersebut memberi tahu hub IoT bahwa pengunggahan telah selesai. Kode ini memberi tahu hub IoT bahwa kode ini dapat merilis sumber daya yang terkait dengan unggahan (SAS URI). Jika pemberitahuan unggahan file diaktifkan, hub IoT akan mengirim pesan pemberitahuan ke layanan backend.

    var successfulFileUploadCompletionNotification = new FileUploadCompletionNotification
{
    // Mandatory. Must be the same value as the correlation id returned in the sas uri response
    CorrelationId = sasUri.CorrelationId,

    // Mandatory. Will be present when service client receives this file upload notification
    IsSuccess = true,

    // Optional, user defined status code. Will be present when service client receives this file upload notification
    StatusCode = 200,

    // Optional, user-defined status description. Will be present when service client receives this file upload notification
    StatusDescription = "Success"
};

await _deviceClient.CompleteFileUploadAsync(successfulFileUploadCompletionNotification);

Jika Anda memeriksa file parameter.cs , Anda akan melihat bahwa:

  • Sampel mengharuskan Anda untuk melewati parameter, p, yang mengambil string koneksi perangkat.

  • Secara default, sampel perangkat menggunakan protokol MQTT untuk berkomunikasi dengan IoT Hub. Anda dapat menggunakan parameter t untuk mengubah protokol transportasi ini. Terlepas dari pilihan ini, klien blob Azure selalu menggunakan HTTPS sebagai protokol untuk mengunggah file penyimpanan Azure.

Mendapatkan string koneksi IoT hub

Dalam artikel ini, Anda membuat layanan backend untuk menerima pesan pemberitahuan unggahan file dari hub IoT yang Anda buat. Untuk menerima pesan pemberitahuan unggahan file, layanan Anda memerlukan izin sambungkan layanan. Secara default, setiap IoT Hub dibuat dengan kebijakan akses bersama bernama layanan yang memberikan izin ini.

Untuk mendapatkan string koneksi Azure IoT Hub untuk kebijakan layanan, ikuti langkah-langkah berikut:

  1. Di portal Azure, pilih Grup sumber daya. Pilih grup sumber daya tempat hub Anda berada, lalu pilih hub Anda dari daftar sumber daya.

  2. Di panel sisi kiri hub IoT Anda, pilih Kebijakan akses bersama.

  3. Dari daftar kebijakan, pilih kebijakan layanan.

  4. Salin String koneksi utama dan simpan nilainya.

Cuplikan layar menampilkan cara mengambil string koneksi dari IoT Hub Anda di portal Azure.

Untuk mengetahui informasi selengkapnya tentang kebijakan dan izin akses bersama IoT Hub, lihat Kontrol akses dan izin.

Menerima pemberitahuan unggahan file

Di bagian ini, Anda membuat aplikasi konsol Java yang menerima pesan pemberitahuan pengunggahan file dari IoT Hub.

  1. Buka jendela perintah dan buka folder tempat Anda ingin membuat proyek. Buat folder bernama ReadFileUploadNotifications dan ubah direktori ke folder tersebut.

    mkdir ReadFileUploadNotification
cd ReadFileUploadNotification

  2. Jalankan perintah berikut untuk membuat proyek konsol C#. Setelah menjalankan perintah, folder akan berisi file Program.cs dan file ReadFileUploadNotification.csproj.

    dotnet new console --language c#

  3. Jalankan perintah berikut untuk menambahkan paket Microsoft.Azure.Devices ke file proyek. Paket ini adalah layanan Azure IoT .NET SDK.

    dotnet add package Microsoft.Azure.Devices

  4. Buka file Program.cs dan tambahkan pernyataan berikut di bagian atas file:

    using Microsoft.Azure.Devices;

  5. Tambahkan bidang berikut ke kelas Program. Ganti nilai tempat penampung {iot hub connection string} dengan string koneksi IoT hub yang Anda salin sebelumnya di Mendapatkan string koneksi hub IoT:

    static ServiceClient serviceClient;
static string connectionString = "{iot hub connection string}";

  6. Tambahkan metode berikut ke kelas Program:

    private async static void ReceiveFileUploadNotificationAsync()
{
    var notificationReceiver = serviceClient.GetFileNotificationReceiver();
    Console.WriteLine("\nReceiving file upload notification from service");
    while (true)
    {
        var fileUploadNotification = await notificationReceiver.ReceiveAsync();
        if (fileUploadNotification == null) continue;
        Console.ForegroundColor = ConsoleColor.Yellow;
        Console.WriteLine("Received file upload notification: {0}", 
          string.Join(", ", fileUploadNotification.BlobName));
        Console.ResetColor();
        await notificationReceiver.CompleteAsync(fileUploadNotification);
    }
}

    Perhatikan pola terima ini sama dengan yang digunakan untuk menerima pesan cloud-to-device dari aplikasi perangkat.

  7. Akhirnya, ganti metode Utama dengan kode berikut:

    Console.WriteLine("Receive file upload notifications\n");
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);
ReceiveFileUploadNotificationAsync();
Console.WriteLine("Press Enter to exit\n");
Console.ReadLine();

Menjalankan aplikasi

Sekarang Anda siap untuk menjalankan aplikasi.

  1. Pertama, jalankan aplikasi layanan untuk menerima pemberitahuan pengunggahan file dari hub IoT. Di perintah Anda pada folder ReadFileUploadNotification, jalankan perintah berikut:

    dotnet restore
dotnet run

    Aplikasi ini dimulai dan menunggu pemberitahuan pengunggahan file dari hub IoT Anda:

    Receive file upload notifications


Receiving file upload notification from service
Press Enter to exit

  2. Selanjutnya, jalankan aplikasi perangkat untuk mengunggah file ke penyimpanan Azure. Buka perintah baru dan ubah folder ke azure-iot-sdk-csharp\iothub\device\samples\getting started\FileUploadSample di bawah folder tempat Anda memperluas Azure IoT C# SDK. Jalankan perintah berikut. {Your device connection string} Ganti nilai tempat penampung di perintah kedua dengan perangkat string koneksi Anda lihat saat mendaftarkan perangkat di hub IoT.

    dotnet restore
dotnet run --p "{Your device connection string}"

    Output berikut dari aplikasi perangkat setelah pengunggahan selesai:

      Uploading file TestPayload.txt
  Getting SAS URI from IoT Hub to use when uploading the file...
  Successfully got SAS URI (https://contosostorage.blob.core.windows.net/contosocontainer/MyDevice%2FTestPayload.txt?sv=2018-03-28&sr=b&sig=x0G1Baf%2BAjR%2BTg3nW34zDNKs07p6dLzkxvZ3ZSmjIhw%3D&se=2021-05-04T16%3A40%3A52Z&sp=rw) from IoT Hub
  Uploading file TestPayload.txt using the Azure Storage SDK and the retrieved SAS URI for authentication
  Successfully uploaded the file to Azure Storage
  Notified IoT Hub that the file upload succeeded and that the SAS URI can be freed.
  Time to upload file: 00:00:01.5077954.
  Done.

  3. Perhatikan bahwa aplikasi layanan menunjukkan bahwa telah menerima pemberitahuan pengunggahan file:

    Receive file upload notifications


Receiving file upload notification from service
Press Enter to exit

Received file upload notification: myDeviceId/TestPayload.txt

Memverifikasi unggahan file

Anda dapat menggunakan portal untuk menampilkan file yang diunggah di kontainer penyimpanan yang Anda konfigurasikan:

  1. Navigasikan ke akun penyimpanan Anda di portal Microsoft Azure.

  2. Di panel kiri akun penyimpanan Anda, pilih Kontainer.

  3. Pilih kontainer tempat Anda mengunggah file.

  4. Pilih folder yang dinamai sesuai dengan peranti Anda.

  5. Pilih blob tempat Anda mengunggah filenya. Dalam artikel ini, blob itu bernama TestPayload.txt.

    Cuplikan layar memilih file yang diunggah di portal Microsoft Azure.

  6. Lihat properti blob pada halaman yang terbuka. Anda dapat memilih Unduh untuk mengunduh file dan melihat kontennya secara lokal.

Langkah berikutnya

Dalam artikel ini, Anda mempelajari cara menggunakan fitur pengunggahan file IoT Hub untuk menyederhanakan pengunggahan file dari perangkat. Anda dapat terus menjelajahi fitur ini dengan artikel berikut: