Bagikan melalui


Mengunggah file dari perangkat ke cloud dengan Azure IoT Hub

Artikel ini menunjukkan cara untuk:

  • Gunakan kemampuan pengunggahan file IoT Hub untuk mengunggah file ke Azure Blob Storage, menggunakan perangkat Azure IoT dan SDK layanan.
  • Beri tahu IoT Hub bahwa file berhasil diunggah dan buat layanan backend untuk menerima pemberitahuan pengunggahan file dari IoT Hub, menggunakan SDK layanan Azure IoT.

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. Kemampuan unggahan file di IoT Hub memungkinkan Anda memindahkan data besar atau kompleks ke cloud. 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.

Artikel ini dimaksudkan untuk melengkapi sampel SDK yang dapat dijalankan yang dirujuk dari dalam artikel ini.

Untuk informasi selengkapnya, lihat:

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. Beberapa panggilan SDK memerlukan string koneksi utama IoT Hub, jadi catat string koneksi.

  • Perangkat terdaftar. Beberapa panggilan SDK memerlukan string koneksi utama perangkat, jadi catat string koneksi.

  • Izin IoT Hub Service Connect - Untuk menerima pesan pemberitahuan unggahan file, layanan backend Anda memerlukan izin Service Connect . Secara default, setiap IoT Hub dibuat dengan kebijakan akses bersama bernama layanan yang memberikan izin ini. Untuk informasi selengkapnya, lihat Menyambungkan ke hub IoT.

  • Konfigurasikan pengunggahan file di hub IoT Anda dengan menautkan akun Azure Storage dan kontainer Azure Blob Storage. Anda dapat mengonfigurasi ini menggunakan portal Azure, Azure CLI, atau Azure PowerShell.

Gambaran Umum

Panduan ini berisi dua bagian:

  • Mengunggah file dari aplikasi perangkat
  • Menerima pemberitahuan unggahan file dalam aplikasi backend

Mengunggah file dari aplikasi perangkat

Bagian ini menjelaskan cara mengunggah file dari perangkat ke hub IoT menggunakan kelas DeviceClient di Azure IoT SDK untuk .NET.

Ikuti prosedur ini untuk mengunggah file dari perangkat ke hub IoT:

  1. Menyambungkan ke hub IoT
  2. Mendapatkan URI SAS dari hub IoT
  3. Mengunggah file ke penyimpanan Azure
  4. Memberi tahu hub IoT tentang status pengunggahan file

Menyambungkan ke perangkat

Panggil CreateFromConnectionString untuk menyambungkan ke perangkat. Berikan string koneksi utama perangkat.

AMQP adalah protokol transportasi default.

static string connectionString = "{device primary connection string}";
deviceClient = DeviceClient.CreateFromConnectionString(connectionString);

Mendapatkan URI SAS dari hub IoT

Panggil GetFileUploadSasUriAsync untuk mendapatkan detail pengunggahan file. URI SAS digunakan pada langkah berikutnya untuk mengunggah file dari perangkat ke Blob Storage.

const string filePath = "TestPayload.txt";
using var fileStreamSource = new FileStream(filePath, FileMode.Open);
var fileName = Path.GetFileName(fileStreamSource.Name);
var fileUploadSasUriRequest = new FileUploadSasUriRequest
{
    BlobName = fileName
};

FileUploadSasUriResponse sasUri = await _deviceClient.GetFileUploadSasUriAsync(fileUploadSasUriRequest, System.Threading.CancellationToken cancellationToken = default);
Uri uploadUri = sasUri.GetBlobUri();

Mengunggah file ke penyimpanan Azure

Untuk mengunggah file ke penyimpanan Azure:

  1. Buat objek blockBlobClient , melewati URI unggahan file.

  2. Gunakan metode UploadAsync untuk mengunggah file ke Blob Storage, melewati SAS URI. Anda dapat secara opsional menambahkan opsi unggahan Blob dan parameter token pembatalan.

Klien Azure Blob selalu menggunakan HTTPS sebagai protokol untuk mengunggah file ke Azure Storage.

Dalam contoh ini, BlockBlobClient diteruskan URI SAS untuk membuat klien Blob blok Azure Storage dan mengunggah file:

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

Memberi tahu hub IoT tentang status pengunggahan file

Gunakan CompleteFileUploadAsync untuk memberi tahu hub IoT bahwa klien perangkat menyelesaikan unggahan, meneruskan objek FileUploadCompletionNotification . Bendera IsSuccess menunjukkan apakah unggahan berhasil atau tidak. Setelah diberi tahu, hub IoT akan merilis sumber daya yang terkait dengan unggahan (SAS URI).

Jika pemberitahuan unggahan file diaktifkan, hub IoT mengirimkan pesan pemberitahuan unggahan file ke layanan backend yang dikonfigurasi untuk pemberitahuan unggahan file.

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);

Sampel unggahan file SDK

SDK menyertakan sampel unggahan file ini.

Menerima pemberitahuan unggahan file di aplikasi backend

Anda dapat membuat layanan backend untuk menerima pesan pemberitahuan unggahan file dari hub IoT.

Kelas ServiceClient berisi metode yang dapat digunakan layanan untuk menerima pemberitahuan unggahan file.

Untuk menerima pemberitahuan unggahan file:

  1. Panggil CreateFromConnectionString untuk menyambungkan ke hub IoT. Lewati string koneksi utama hub IoT.
  2. Buat CancellationToken.
  3. Hubungi GetFileNotificationReceiver untuk membuat penerima pemberitahuan.
  4. Gunakan perulangan dengan ReceiveAsync untuk menunggu pemberitahuan unggahan file.

Contohnya:

using Microsoft.Azure.Devices;
static ServiceClient serviceClient;
static string connectionString = "{IoT hub connection string}";
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);

// Define the cancellation token
CancellationTokenSource source = new CancellationTokenSource();
CancellationToken token = source.Token;

// Create a notification receiver
var notificationReceiver = serviceClient.GetFileNotificationReceiver();
Console.WriteLine("\nReceiving file upload notification from service");

// Check for file upload notifications
while (true)
{
    var fileUploadNotification = await notificationReceiver.ReceiveAsync(token);
    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);
}

Gambaran Umum

Panduan ini berisi dua bagian:

  • Mengunggah file dari aplikasi perangkat
  • Menerima pemberitahuan unggahan file dalam aplikasi backend

Mengunggah file dari aplikasi perangkat

Bagian ini menjelaskan cara mengunggah file dari perangkat ke hub IoT menggunakan kelas DeviceClient dari Azure IoT SDK for Java.

Ikuti prosedur ini untuk mengunggah file dari perangkat ke hub IoT:

  1. Menyambungkan ke perangkat
  2. Mendapatkan URI SAS dari hub IoT
  3. Mengunggah file ke Azure Storage
  4. Mengirim pemberitahuan status unggahan file ke hub IoT

Protokol koneksi

Operasi unggahan file selalu menggunakan HTTPS, tetapi DeviceClient dapat menentukan IotHubClientProtocol untuk layanan lain seperti telemetri, metode perangkat, dan kembar perangkat.

IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;

Menyambungkan ke perangkat

Buat instans DeviceClient untuk menyambungkan ke perangkat menggunakan string koneksi utama perangkat.

String connString = "{IoT hub connection string}";
DeviceClient client = new DeviceClient(connString, protocol);

Mendapatkan URI SAS dari hub IoT

Panggil getFileUploadSasUri untuk mendapatkan objek FileUploadSasUriResponse .

FileUploadSasUriResponse mencakup metode ini dan mengembalikan nilai. Nilai yang dikembalikan dapat diteruskan ke metode unggahan file.

Metode Nilai hasil
getCorrelationId() ID Korelasi
getContainerName() Nama kontainer
getBlobName() Nama blob
getBlobUri() Blob URI

Contohnya:

FileUploadSasUriResponse sasUriResponse = client.getFileUploadSasUri(new FileUploadSasUriRequest(file.getName()));

System.out.println("Successfully got SAS URI from IoT hub");
System.out.println("Correlation Id: " + sasUriResponse.getCorrelationId());
System.out.println("Container name: " + sasUriResponse.getContainerName());
System.out.println("Blob name: " + sasUriResponse.getBlobName());
System.out.println("Blob Uri: " + sasUriResponse.getBlobUri());

Mengunggah file ke Azure Storage

Teruskan titik akhir URI blob ke BlobClientBuilder.buildclient untuk membuat objek BlobClient .

BlobClient blobClient =
    new BlobClientBuilder()
        .endpoint(sasUriResponse.getBlobUri().toString())
        .buildClient();

Panggil uploadFromFile untuk mengunggah file ke Blob Storage.

String fullFileName = "Path of the file to upload";
blobClient.uploadFromFile(fullFileName);

Mengirim pemberitahuan status unggahan file ke hub IoT

Kirim pemberitahuan status unggahan ke hub IoT setelah upaya unggahan file.

Buat objek FileUploadCompletionNotification . Berikan status keberhasilan correlationId unggahan file dan isSuccess . isSuccess true Berikan nilai saat unggahan file berhasil, false jika tidak.

FileUploadCompletionNotification harus dipanggil bahkan ketika pengunggahan file gagal. Hub IoT memiliki jumlah URI SAS tetap yang diizinkan untuk aktif pada waktu tertentu. Setelah selesai dengan pengunggahan file, Anda harus membebaskan URI SAS Anda sehingga URI SAS lainnya dapat dihasilkan. Jika URI SAS tidak dibebesarkan melalui API ini, maka akhirnya membebaskan dirinya berdasarkan berapa lama URI SAS dikonfigurasi untuk hidup di hub IoT.

Contoh ini melewati status berhasil.

FileUploadCompletionNotification completionNotification = new FileUploadCompletionNotification(sasUriResponse.getCorrelationId(), true);
client.completeFileUpload(completionNotification);

Tutup klien

Bebaskan client sumber daya.

client.closeNow();

Menerima pemberitahuan unggahan file di aplikasi backend

Anda dapat membuat aplikasi backend untuk menerima pemberitahuan unggahan file.

Untuk membuat aplikasi pemberitahuan unggahan file:

  1. Menyambungkan ke klien layanan hub IoT
  2. Memeriksa pemberitahuan unggahan file

Kelas ServiceClient berisi metode yang dapat digunakan layanan untuk menerima pemberitahuan unggahan file.

Menyambungkan ke klien layanan hub IoT

Buat objek IotHubServiceClientProtocol. Koneksi menggunakan AMQPS protokol.

Panggil createFromConnectionString untuk menyambungkan ke hub IoT. Lewati string koneksi utama hub IoT.

private static final String connectionString = "{IoT hub primary connection string}";
private static final IotHubServiceClientProtocol protocol = IotHubServiceClientProtocol.AMQPS;
ServiceClient sc = ServiceClient.createFromConnectionString(connectionString, protocol);

Periksa status unggahan file

Untuk memeriksa status unggahan file:

  1. Buat objek getFileUploadNotificationReceiver .
  2. Gunakan buka untuk menyambungkan ke hub IoT.
  3. Panggilan menerima untuk memeriksa status unggahan file. Metode ini mengembalikan objek fileUploadNotification . Jika pemberitahuan unggahan diterima, Anda dapat melihat bidang status unggahan menggunakan metode fileUploadNotification .

Contohnya:

FileUploadNotificationReceiver receiver = sc.getFileUploadNotificationReceiver();
receiver.open();
FileUploadNotification fileUploadNotification = receiver.receive(2000);

if (fileUploadNotification != null)
{
    System.out.println("File Upload notification received");
    System.out.println("Device Id : " + fileUploadNotification.getDeviceId());
    System.out.println("Blob Uri: " + fileUploadNotification.getBlobUri());
    System.out.println("Blob Name: " + fileUploadNotification.getBlobName());
    System.out.println("Last Updated : " + fileUploadNotification.getLastUpdatedTimeDate());
    System.out.println("Blob Size (Bytes): " + fileUploadNotification.getBlobSizeInBytes());
    System.out.println("Enqueued Time: " + fileUploadNotification.getEnqueuedTimeUtcDate());
}
else
{
    System.out.println("No file upload notification");
}

// Close the receiver object
receiver.close();

Sampel unggahan file SDK

Ada dua sampel unggahan file Java.

Memasang paket

Pustaka azure-iot-device harus diinstal sebelum memanggil kode terkait.

pip install azure-iot-device

Paket azure.storage.blob digunakan untuk melakukan unggahan file.

pip install azure.storage.blob

Mengunggah file dari aplikasi perangkat

Bagian ini menjelaskan cara mengunggah file dari perangkat ke hub IoT menggunakan kelas IoTHubDeviceClient dari Azure IoT SDK untuk Python.

Ikuti prosedur ini untuk mengunggah file dari perangkat ke hub IoT:

  1. Menyambungkan ke perangkat
  2. Mendapatkan informasi Blob Storage
  3. Mengunggah file ke Blob Storage
  4. Memberi tahu hub IoT tentang status unggahan

Mengimpor pustaka

import os
from azure.iot.device import IoTHubDeviceClient
from azure.core.exceptions import AzureError
from azure.storage.blob import BlobClient

Menyambungkan ke perangkat

Untuk menyambungkan ke perangkat:

  1. Panggil create_from_connection_string untuk menambahkan string koneksi utama perangkat.

  2. Panggil sambungkan untuk menyambungkan klien perangkat.

Contohnya:

# Add your IoT hub primary connection string
CONNECTION_STRING = "{Device primary connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(CONNECTION_STRING)

# Connect the client
device_client.connect()

Mendapatkan informasi Blob Storage

Panggil get_storage_info_for_blob untuk mendapatkan informasi dari hub IoT tentang akun Azure Storage yang ditautkan. Informasi ini mencakup nama host, nama kontainer, nama blob, dan token SAS. Metode ini get_storage_info_for_blob juga mengembalikan correlation_id, yang digunakan dalam notify_blob_upload_status metode . correlation_id adalah cara IoT Hub untuk menandai Blob mana yang sedang Anda kerjakan.

# Get the storage info for the blob
PATH_TO_FILE = "{Full path to local file}"
blob_name = os.path.basename(PATH_TO_FILE)
blob_info = device_client.get_storage_info_for_blob(blob_name)

Mengunggah file ke Blob Storage

Untuk mengunggah file ke Blob Storage:

  1. Gunakan from_blob_url untuk membuat objek BlobClient dari URL blob.
  2. Panggil upload_blob untuk mengunggah file ke Blob Storage.

Contoh ini menguraikan blob_info struktur untuk membuat URL yang digunakannya untuk menginisialisasi BlobClient. Kemudian panggilan upload_blob untuk mengunggah file ke Blob Storage.

try:
    sas_url = "https://{}/{}/{}{}".format(
        blob_info["hostName"],
        blob_info["containerName"],
        blob_info["blobName"],
        blob_info["sasToken"]
    )

    print("\nUploading file: {} to Azure Storage as blob: {} in container {}\n".format(file_name, blob_info["blobName"], blob_info["containerName"]))

    # Upload the specified file
    with BlobClient.from_blob_url(sas_url) as blob_client:
        with open(file_name, "rb") as f:
            result = blob_client.upload_blob(f, overwrite=True)
            return (True, result)

except FileNotFoundError as ex:
    # catch file not found and add an HTTP status code to return in notification to IoT hub
    ex.status_code = 404
    return (False, ex)

except AzureError as ex:
    # catch Azure errors that might result from the upload operation
    return (False, ex)

Memberi tahu hub IoT tentang status unggahan

Gunakan notify_blob_upload_status untuk memberi tahu hub IoT tentang status operasi Blob Storage. Berikan yang correlation_id diperoleh dengan get_storage_info_for_blob metode . correlation_id digunakan oleh hub IoT untuk memberi tahu layanan apa pun yang mungkin mendengarkan pemberitahuan mengenai status tugas pengunggahan file.

Contoh ini memberi tahu hub IoT tentang pengunggahan file yang berhasil:

device_client.notify_blob_upload_status(storage_info["correlationId"], True, 200, "OK: {}".format(PATH_TO_FILE)

Mematikan klien perangkat

Matikan klien. Setelah metode ini dipanggil, setiap upaya pada panggilan klien lebih lanjut mengakibatkan ClientError dinaikkan.

device_client.shutdown()

Sampel unggahan file SDK

SDK menyertakan dua sampel unggahan file:

Gambaran Umum

Panduan ini berisi dua bagian:

  • Mengunggah file dari aplikasi perangkat
  • Menerima pemberitahuan unggahan file dalam aplikasi backend

Mengunggah file dari aplikasi perangkat

Bagian ini menjelaskan cara mengunggah file dari perangkat ke hub IoT menggunakan paket azure-iot-device di Azure IoT SDK untuk Node.js.

Menginstal paket SDK

Jalankan perintah ini untuk menginstal SDK perangkat azure-iot-device , azure-iot-device-mqtt, dan paket @azure/storage-blob pada komputer pengembangan Anda:

npm install azure-iot-device azure-iot-device-mqtt @azure/storage-blob --save

Paket azure-iot-device berisi objek yang berinteraksi dengan perangkat IoT.

Ikuti prosedur ini untuk mengunggah file dari perangkat ke hub IoT:

  1. Mendapatkan tanda tangan akses bersama Blob
  2. Mengunggah file ke Azure Storage
  3. Mengirim pemberitahuan status unggahan file ke hub IoT

Membuat modul

Buat modul Klien, Protokol, kesalahan, dan jalur menggunakan paket yang diinstal.

const Client = require('azure-iot-device').Client;
const Protocol = require('azure-iot-device-mqtt').Mqtt;
const errors = require('azure-iot-common').errors;
const path = require('path');

Mendapatkan URI SAS dari hub IoT

Gunakan getBlobSharedAccessSignature untuk mendapatkan token SAS akun penyimpanan tertaut dari hub IoT. Seperti yang dijelaskan dalam prasyarat, hub IoT ditautkan ke Blob Storage.

Contohnya:

// make sure you set these environment variables prior to running the sample.
const localFilePath = process.env.PATH_TO_FILE;
const storageBlobName = path.basename(localFilePath);
const blobInfo = await client.getBlobSharedAccessSignature(storageBlobName);
if (!blobInfo) {
throw new errors.ArgumentError('Invalid upload parameters');
}

Mengunggah file ke hub IoT

Untuk mengunggah file dari perangkat ke hub IoT:

  1. Membuat alur aliran
  2. Membuat URL blob
  3. Membuat BlockBlobClient untuk unggahan file ke Blob Storage
  4. Panggil uploadFile untuk mengunggah file ke Blob Storage
  5. Hubungi notifyBlobUploadStatus untuk memberi tahu hub IoT bahwa unggahan berhasil atau gagal

Contohnya:

// Open the pipeline
const pipeline = newPipeline(new AnonymousCredential(), {
retryOptions: { maxTries: 4 },
telemetry: { value: 'HighLevelSample V1.0.0' }, // Customized telemetry string
keepAliveOptions: { enable: false }
});

// Construct the blob URL
const { hostName, containerName, blobName, sasToken } = blobInfo;
const blobUrl = `https://${hostName}/${containerName}/${blobName}${sasToken}`;

// Create the BlockBlobClient for file upload to Blob Storage
const blobClient = new BlockBlobClient(blobUrl, pipeline);

// Setup blank status notification arguments to be filled in on success/failure
let isSuccess;
let statusCode;
let statusDescription;

const uploadStatus = await blobClient.uploadFile(localFilePath);
console.log('uploadStreamToBlockBlob success');

  try {
    const uploadStatus = await blobClient.uploadFile(localFilePath);
    console.log('uploadStreamToBlockBlob success');

    // Save successful status notification arguments
    isSuccess = true;
    statusCode = uploadStatus._response.status;
    statusDescription = uploadStatus._response.bodyAsText;

    // Notify IoT hub of upload to blob status (success)
    console.log('notifyBlobUploadStatus success');
  }
  catch (err) {
    isSuccess = false;
    statusCode = err.code;
    statusDescription = err.message;

    console.log('notifyBlobUploadStatus failed');
    console.log(err);
  }

// Send file upload status notification to IoT hub
await client.notifyBlobUploadStatus(blobInfo.correlationId, isSuccess, statusCode, statusDescription);

Menerima pemberitahuan unggahan file dalam aplikasi backend

Anda dapat membuat aplikasi backend untuk memeriksa klien layanan hub IoT untuk pemberitahuan unggahan file perangkat.

Untuk membuat aplikasi pemberitahuan unggahan file:

  1. Menyambungkan ke klien layanan hub IoT
  2. Memeriksa pemberitahuan unggahan file

Menyambungkan ke klien layanan hub IoT

Kelas ServiceClient berisi metode yang dapat digunakan layanan untuk menerima pemberitahuan unggahan file.

Sambungkan ke hub IoT menggunakan fromConnectionString. Lewati string koneksi utama hub IoT.

const Client = require('azure-iothub').Client;
const connectionString = "{IoT hub primary connection string}";
const serviceClient = Client.fromConnectionString(connectionString);

Buka koneksi ke hub IoT.

//Open the connection to IoT hub
serviceClient.open(function (err) {
  if (err) {
    console.error('Could not connect: ' + err.message);
  } else {
    console.log('Service client connected');

Memeriksa pemberitahuan unggahan file

Untuk memeriksa pemberitahuan unggahan file:

  1. Panggil getFileNotificationReceiver. Berikan nama metode panggilan balik unggahan file yang dipanggil saat pesan pemberitahuan diterima.
  2. Memproses pemberitahuan pengunggahan file dalam metode panggilan balik.

Contoh ini menyiapkan receiveFileUploadNotification penerima panggilan balik pemberitahuan. Penerima menginterpretasikan informasi status unggahan file dan mencetak pesan status ke konsol.

//Set up the receiveFileUploadNotification notification message callback receiver
serviceClient.getFileNotificationReceiver(function receiveFileUploadNotification(err, receiver){
if (err) {
  console.error('error getting the file notification receiver: ' + err.toString());
} else {
  receiver.on('message', function (msg) {
    console.log('File upload from device:')
    console.log(msg.getData().toString('utf-8'));
    receiver.complete(msg, function (err) {
      if (err) {
        console.error('Could not finish the upload: ' + err.message);
      } else {
        console.log('Upload complete');
      }
    });
  });
}

Sampel unggahan file SDK

SDK menyertakan unggahan ke sampel tingkat lanjut blob.