Ladda upp filer från en enhet till molnet med Azure IoT Hub
Den här artikeln visar hur du:
- Använd filuppladdningsfunktionerna i IoT Hub för att ladda upp en fil till Azure Blob Storage med hjälp av en Azure IoT-enhet och tjänst-SDK:er.
- Meddela IoT Hub att filen har laddats upp och skapa en serverdelstjänst för att ta emot meddelanden om filuppladdning från IoT Hub med hjälp av Azure IoT-tjänstens SDK:er.
I vissa scenarier kan du inte enkelt mappa de data som dina enheter skickar till de relativt små meddelanden från enhet till moln som IoT Hub accepterar. Med filuppladdningsfunktionerna i IoT Hub kan du flytta stora eller komplexa data till molnet. Till exempel:
- Videoklipp
- Stora filer som innehåller bilder
- Vibrationsdata samplas med hög frekvens
- Någon form av förbearbetade data
Dessa filer bearbetas vanligtvis i molnet med hjälp av verktyg som Azure Data Factory eller Hadoop-stacken. När du behöver ladda upp filer från en enhet kan du fortfarande använda IoT Hubs säkerhet och tillförlitlighet. Den här artikeln visar hur.
Den här artikeln är avsedd att komplettera runnable SDK-exempel som refereras inifrån den här artikeln.
Mer information finns i:
Viktigt!
Filuppladdningsfunktioner på enheter som använder X.509-certifikatutfärdarautentisering (CA) är i offentlig förhandsversion och förhandsgranskningsläget måste vara aktiverat. Det är allmänt tillgängligt på enheter som använder X.509 tumavtrycksautentisering eller X.509-certifikatattestering med Azure Device Provisioning Service. Mer information om X.509-autentisering med IoT Hub finns i X.509-certifikat som stöds.
Förutsättningar
En IoT-hubb. Vissa SDK-anrop kräver den primära IoT Hub-niska veze, så anteckna niska veze.
En registrerad enhet. Vissa SDK-anrop kräver enhetens primära niska veze, så anteckna niska veze.
IoT Hub Service Connect-behörighet – För att ta emot meddelanden om filuppladdning behöver serverdelstjänsten behörigheten Service Connect . Som standard skapas varje IoT Hub med en princip för delad åtkomst med namnet service som ger den här behörigheten. Mer information finns i Ansluta till en IoT-hubb.
Konfigurera filuppladdning i din IoT-hubb genom att länka ett Azure Storage-konto och en Azure Blob Storage-container. Du kan konfigurera dessa med hjälp av Azure-portalen, Azure CLI eller Azure PowerShell.
Översikt
Den här instruktioner innehåller två avsnitt:
- Ladda upp en fil från ett enhetsprogram
- Ta emot meddelande om filuppladdning i ett serverdelsprogram
Ladda upp en fil från ett enhetsprogram
I det här avsnittet beskrivs hur du laddar upp en fil från en enhet till en IoT-hubb med klassen DeviceClient i Azure IoT SDK för .NET.
Följ den här proceduren för att ladda upp en fil från en enhet till IoT Hub:
- Ansluta till IoT Hub
- Hämta en SAS-URI från IoT Hub
- Ladda upp filen till Azure Storage
- Meddela IoT Hub om filuppladdningsstatusen
Ansluta till enheten
Anropa CreateFromConnectionString för att ansluta till enheten. Skicka enhetens primära niska veze.
AMQP
är standardprotokollet för transport.
static string connectionString = "{device primary connection string}";
deviceClient = DeviceClient.CreateFromConnectionString(connectionString);
Hämta en SAS-URI från IoT Hub
Anropa GetFileUploadSasUriAsync för att hämta information om filuppladdning. SAS-URI:n används i nästa steg för att ladda upp en fil från en enhet till 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();
Ladda upp en fil till Azure Storage
Så här laddar du upp en fil till Azure Storage:
Skapa ett blockBlobClient-objekt som skickar en URI för filuppladdning.
Använd metoden UploadAsync för att ladda upp en fil till Blob Storage och skicka SAS-URI:n. Du kan också lägga till alternativ för blobuppladdning och tokenparametrar för annullering.
Azure Blob-klienten använder alltid HTTPS som protokoll för att ladda upp filen till Azure Storage.
I det här exemplet BlockBlobClient
skickas SAS-URI:n för att skapa en Azure Storage-blockblobklient och laddar upp filen:
var blockBlobClient = new BlockBlobClient(uploadUri);
await blockBlobClient.UploadAsync(fileStreamSource, null, null);
Meddela IoT Hub om filuppladdningsstatusen
Använd CompleteFileUploadAsync för att meddela IoT Hub att enhetsklienten har slutfört uppladdningen och skickar ett FileUploadCompletionNotification-objekt . Flaggan IsSuccess
anger om uppladdningen lyckades eller inte. När du har fått ett meddelande släpper IoT Hub resurser som är associerade med uppladdningen (SAS-URI:n).
Om meddelanden om filuppladdning är aktiverade skickar IoT Hub ett meddelande om filuppladdning till serverdelstjänster som har konfigurerats för meddelande om filuppladdning.
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);
Exempel på SDK-filuppladdning
SDK:et innehåller det här filuppladdningsexemplet.
Få ett meddelande om filuppladdning i ett serverdelsprogram
Du kan skapa en serverdelstjänst för att ta emot meddelanden om filuppladdning från IoT Hub.
Klassen ServiceClient innehåller metoder som tjänster kan använda för att ta emot meddelanden om filuppladdning.
Så här tar du emot meddelande om filuppladdning:
- Anropa CreateFromConnectionString för att ansluta till IoT Hub. Skicka den primära IoT Hub-niska veze.
- Skapa en CancellationToken.
- Anropa GetFileNotificationReceiver för att skapa en meddelandemottagare.
- Använd en loop med ReceiveAsync för att vänta på filuppladdningsmeddelandet.
Till exempel:
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);
}
Översikt
Den här instruktioner innehåller två avsnitt:
- Ladda upp en fil från ett enhetsprogram
- Ta emot meddelande om filuppladdning i ett serverdelsprogram
Ladda upp en fil från ett enhetsprogram
I det här avsnittet beskrivs hur du laddar upp en fil från en enhet till en IoT-hubb med klassen DeviceClient från Azure IoT SDK för Java.
Följ den här proceduren för att ladda upp en fil från en enhet till IoT Hub:
- Ansluta till enheten
- Hämta en SAS-URI från IoT Hub
- Ladda upp filen till Azure Storage
- Skicka statusmeddelande för filuppladdning till IoT Hub
Anslutningsprotokoll
Filuppladdningsåtgärder använder alltid HTTPS, men DeviceClient kan definiera IotHubClientProtocol för andra tjänster som telemetri, enhetsmetod och enhetstvilling.
IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
Ansluta till enheten
Instansiera DeviceClient
för att ansluta till enheten med hjälp av enhetens primära niska veze.
String connString = "{IoT hub connection string}";
DeviceClient client = new DeviceClient(connString, protocol);
Hämta en SAS-URI från IoT Hub
Anropa getFileUploadSasUri för att hämta ett FileUploadSasUriResponse-objekt .
FileUploadSasUriResponse
innehåller dessa metoder och returnerar värden. Returvärdena kan skickas till filuppladdningsmetoder.
Metod | Returvärde |
---|---|
getCorrelationId() |
Korrelations-ID |
getContainerName() |
Containerns namn |
getBlobName() |
Blobnamn |
getBlobUri() |
Blob-URI |
Till exempel:
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());
Ladda upp filen till Azure Storage
Skicka blob-URI-slutpunkten till BlobClientBuilder.buildclient för att skapa BlobClient-objektet .
BlobClient blobClient =
new BlobClientBuilder()
.endpoint(sasUriResponse.getBlobUri().toString())
.buildClient();
Anropa uploadFromFile för att ladda upp filen till Blob Storage.
String fullFileName = "Path of the file to upload";
blobClient.uploadFromFile(fullFileName);
Skicka statusmeddelande för filuppladdning till IoT Hub
Skicka ett meddelande om uppladdningsstatus till IoT Hub efter ett filuppladdningsförsök.
Skapa ett FileUploadCompletionNotification-objekt . Skicka statusen correlationId
för lyckad filuppladdning och isSuccess
filuppladdning. Skicka ett isSuccess
true
värde när filuppladdningen lyckades, false
när inte.
FileUploadCompletionNotification
måste anropas även när filuppladdningen misslyckas. IoT Hub har ett fast antal SAS-URI:er som tillåts vara aktiva vid en viss tidpunkt. När du är klar med filuppladdningen bör du frigöra DIN SAS-URI så att andra SAS-URI:er kan genereras. Om en SAS-URI inte frigörs via det här API:et frigörs den så småningom baserat på hur länge SAS-URI:er har konfigurerats för att leva på en IoT-hubb.
Det här exemplet skickar en lyckad status.
FileUploadCompletionNotification completionNotification = new FileUploadCompletionNotification(sasUriResponse.getCorrelationId(), true);
client.completeFileUpload(completionNotification);
Stäng klienten
client
Frigör resurserna.
client.closeNow();
Få ett meddelande om filuppladdning i ett serverdelsprogram
Du kan skapa ett serverdelsprogram för att ta emot meddelanden om filuppladdning.
Så här skapar du ett meddelandeprogram för filuppladdning:
- Ansluta till IoT Hub-tjänstklienten
- Sök efter ett meddelande om filuppladdning
Klassen ServiceClient innehåller metoder som tjänster kan använda för att ta emot meddelanden om filuppladdning.
Ansluta till IoT Hub-tjänstklienten
Skapa ett IotHubServiceClientProtocol
objekt. Anslutningen använder protokollet AMQPS
.
Anropa createFromConnectionString
för att ansluta till IoT Hub. Skicka den primära IoT Hub-niska veze.
private static final String connectionString = "{IoT hub primary connection string}";
private static final IotHubServiceClientProtocol protocol = IotHubServiceClientProtocol.AMQPS;
ServiceClient sc = ServiceClient.createFromConnectionString(connectionString, protocol);
Sök efter filuppladdningsstatus
Så här söker du efter filuppladdningsstatus:
- Skapa ett getFileUploadNotificationReceiver-objekt .
- Använd open för att ansluta till IoT Hub.
- Anropa mottagningen för att söka efter filuppladdningsstatusen. Den här metoden returnerar ett fileUploadNotification-objekt . Om ett uppladdningsmeddelande tas emot kan du visa fält för uppladdningsstatus med hjälp av fileUploadNotification-metoder .
Till exempel:
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();
Exempel på SDK-filuppladdning
Installera paket
Biblioteket azure-iot-device måste installeras innan någon relaterad kod anropas.
pip install azure-iot-device
Azure.storage.blob-paketet används för att utföra filuppladdningen.
pip install azure.storage.blob
Ladda upp fil från ett enhetsprogram
I det här avsnittet beskrivs hur du laddar upp en fil från en enhet till en IoT-hubb med klassen IoTHubDeviceClient från Azure IoT SDK för Python.
Följ den här proceduren för att ladda upp en fil från en enhet till IoT Hub:
- Ansluta till enheten
- Hämta bloblagringsinformation
- Ladda upp filen till Blob Storage
- Meddela IoT-hubben om uppladdningsstatus
Importera bibliotek
import os
from azure.iot.device import IoTHubDeviceClient
from azure.core.exceptions import AzureError
from azure.storage.blob import BlobClient
Ansluta till enheten
Så här ansluter du till enheten:
Anropa create_from_connection_string för att lägga till enhetens primära niska veze.
Anropa anslut för att ansluta enhetsklienten.
Till exempel:
# 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()
Hämta bloblagringsinformation
Anropa get_storage_info_for_blob för att få information från en IoT-hubb om ett länkat Azure Storage-konto. Den här informationen innehåller värdnamnet, containernamnet, blobnamnet och en SAS-token. Metoden get_storage_info_for_blob
returnerar också en correlation_id
, som används i notify_blob_upload_status
-metoden. correlation_id
är IoT Hub:s sätt att markera vilken blob du arbetar med.
# 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)
Ladda upp en fil till Blob Storage
Så här laddar du upp en fil till Blob Storage:
- Använd from_blob_url för att skapa ett BlobClient-objekt från en blob-URL.
- Anropa upload_blob för att ladda upp filen till Blob Storage.
I det här exemplet parsas blob_info
strukturen för att skapa en URL som används för att initiera en BlobClient. Sedan anropas upload_blob
för att ladda upp filen till 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)
Meddela IoT-hubben om uppladdningsstatus
Använd notify_blob_upload_status för att meddela IoT Hub om status för bloblagringsåtgärden. Skicka den erhållna correlation_id
get_storage_info_for_blob
metoden. correlation_id
Används av IoT Hub för att meddela alla tjänster som kanske lyssnar efter ett meddelande om status för filuppladdningsaktiviteten.
I det här exemplet meddelas IoT-hubben för en lyckad filuppladdning:
device_client.notify_blob_upload_status(storage_info["correlationId"], True, 200, "OK: {}".format(PATH_TO_FILE)
Stäng av enhetsklienten
Stäng av klienten. När den här metoden anropas leder alla försök till ytterligare klientanrop till att en ClientError aktiveras.
device_client.shutdown()
Exempel på SDK-filuppladdning
SDK:et innehåller två exempel på filuppladdning:
Översikt
Den här instruktioner innehåller två avsnitt:
- Ladda upp en fil från ett enhetsprogram
- Ta emot meddelande om filuppladdning i ett serverdelsprogram
Ladda upp en fil från ett enhetsprogram
I det här avsnittet beskrivs hur du laddar upp en fil från en enhet till en IoT-hubb med azure-iot-device-paketet i Azure IoT SDK för Node.js.
Installera SDK-paket
Kör det här kommandot för att installera azure-iot-device SDK, azure-iot-device-mqtt och paketen @azure/storage-blob på utvecklingsdatorn:
npm install azure-iot-device azure-iot-device-mqtt @azure/storage-blob --save
Paketet azure-iot-device innehåller objekt som samverkar med IoT-enheter.
Följ den här proceduren för att ladda upp en fil från en enhet till IoT Hub:
- Hämta signaturer för delad blobåtkomst
- Ladda upp filen till Azure Storage
- Skicka statusmeddelande för filuppladdning till IoT Hub
Skapa moduler
Skapa klient-, protokoll-, fel- och sökvägsmoduler med hjälp av de installerade paketen.
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');
Hämta en SAS-URI från IoT Hub
Använd getBlobSharedAccessSignature för att hämta sas-token för det länkade lagringskontot från IoT Hub. Enligt beskrivningen i förhandskraven är IoT-hubben länkad till Blob Storage.
Till exempel:
// 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');
}
Ladda upp filen till IoT Hub
Så här laddar du upp en fil från en enhet till IoT Hub:
- Skapa en dataströmspipeline
- Skapa blob-URL:en
- Skapa en BlockBlobClient för filuppladdning till Blob Storage
- Anropa uploadFile för att ladda upp filen till Blob Storage
- Anropa notifyBlobUploadStatus för att meddela IoT Hub att uppladdningen lyckades eller misslyckades
Till exempel:
// 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);
Ta emot meddelande om filuppladdning i ett serverdelsprogram
Du kan skapa ett serverdelsprogram för att kontrollera IoT Hub-tjänstklienten för meddelanden om enhetsfiluppladdning.
Så här skapar du ett meddelandeprogram för filuppladdning:
- Ansluta till IoT Hub-tjänstklienten
- Sök efter ett meddelande om filuppladdning
Ansluta till IoT Hub-tjänstklienten
Klassen ServiceClient innehåller metoder som tjänster kan använda för att ta emot meddelanden om filuppladdning.
Anslut till IoT Hub med hjälp av fromConnectionString. Skicka den primära IoT Hub-niska veze.
const Client = require('azure-iothub').Client;
const connectionString = "{IoT hub primary connection string}";
const serviceClient = Client.fromConnectionString(connectionString);
Öppna anslutningen till IoT Hub.
//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');
Sök efter ett meddelande om filuppladdning
Så här söker du efter meddelanden om filuppladdning:
- Anropa getFileNotificationReceiver. Ange namnet på en metod för återanrop av filuppladdning som anropas när meddelanden tas emot.
- Bearbeta meddelanden om filuppladdning i motringningsmetoden.
I det här exemplet konfigureras en receiveFileUploadNotification
mottagare för återanrop av meddelanden. Mottagaren tolkar statusinformationen för filuppladdningen och skriver ut ett statusmeddelande till konsolen.
//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');
}
});
});
}
Exempel på SDK-filuppladdning
SDK:et innehåller en uppladdning till det avancerade blobexemplet.