Ladda upp filer med IoT Hub

  • Artikel

Det finns många scenarier där du inte enkelt kan mappa dina enhetsdata till de relativt små meddelanden från enhet till moln som IoT Hub accepterar. Till exempel att skicka stora mediefiler som video; eller skicka stora telemetribatch, antingen uppladdade av tillfälligt anslutna enheter eller aggregerade och komprimerade för att spara bandbredd.

När du behöver ladda upp stora filer från en enhet kan du fortfarande använda IoT Hubs säkerhet och tillförlitlighet. I stället för att asynkrona meddelanden via sig själv fungerar IoT Hub som en avsändare till ett associerat Azure-lagringskonto. IoT Hub kan också skicka meddelanden till serverdelstjänster när en enhet slutför en filuppladdning.

Om du behöver hjälp med att bestämma när du ska använda rapporterade egenskaper, enhets-till-moln-meddelanden eller filuppladdningar läser du Vägledning för kommunikation från enhet till moln.

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.

Översikt över filuppladdning

En IoT-hubb underlättar filuppladdningar från anslutna enheter genom att ge dem SAS-URI:er (signatur för delad åtkomst) per uppladdning för en blobcontainer och ett Azure Storage-konto som har förkonfigurerats med hubben. Det finns tre delar i att använda filuppladdningar med IoT Hub: förkonfigurera ett Azure-lagringskonto och en blobcontainer på din IoT-hubb, ladda upp filer från enheter och eventuellt meddela serverdelstjänster om slutförda filuppladdningar.

Innan du kan använda filuppladdningsfunktionen måste du associera ett Azure Storage-konto och en blobcontainer med din IoT-hubb. Du kan också konfigurera inställningar som styr hur IoT Hub autentiserar med Azure Storage, time-to-live (TTL) för DE SAS-URI:er som IoT Hub delar ut till enheter och meddelanden om filuppladdning till dina serverdelstjänster. Mer information finns i Associera ett Azure Storage-konto med IoT Hub.

Enheter följer en trestegsprocess för att ladda upp en fil till den associerade blobcontainern:

  1. Enheten initierar filuppladdningen med IoT-hubben. Den skickar namnet på en blob i begäran och hämtar en SAS-URI och ett korrelations-ID i gengäld. SAS-URI:n innehåller en SAS-token för Azure Storage som ger enheten läs- och skrivbehörighet för den begärda bloben i blobcontainern. Mer information finns i Enhet: Initiera en filuppladdning.

  2. Enheten använder SAS-URI:n för att anropa Azure Blob Storage-API:er på ett säkert sätt för att ladda upp filen till blobcontainern. Mer information finns i Enhet: Ladda upp fil med Azure Storage-API:er.

  3. När filuppladdningen är klar meddelar enheten IoT-hubben om slutförandestatusen med hjälp av korrelations-ID:t som den fick från IoT Hub när uppladdningen initierades. Mer information finns i Enhet: Meddela IoT Hub om en slutförd filuppladdning.

Serverdelstjänster kan prenumerera på meddelanden om filuppladdning på IoT-hubbens tjänstriktade meddelandeslutpunkt för filuppladdning. Om du har aktiverat dessa meddelanden på din IoT-hubb levererar den dem på den här slutpunkten när en enhet meddelar hubben att den har slutfört en filuppladdning. Tjänsterna kan använda dessa meddelanden för att utlösa ytterligare bearbetning av blobdata. Mer information finns i Tjänst: Meddelanden om filuppladdning.

Filuppladdning stöds fullt ut av Azure IoT-enhets- och tjänst-SDK:er. Mer information finns i Filuppladdning med hjälp av ett SDK.

Kvoter och gränser för filuppladdning

IoT Hub begränsar antalet filuppladdningar som kan initieras under en viss period. Tröskelvärdet baseras på SKU:n och antalet enheter i din IoT-hubb. Dessutom är varje enhet begränsad till 10 samtidiga aktiva filuppladdningar åt gången. Mer information finns i IoT Hub-kvoter och begränsning.

Associera ett Azure Storage-konto med IoT Hub

Du måste associera ett Azure Storage-konto och en blobcontainer med din IoT-hubb för att kunna använda filuppladdningsfunktioner. Alla filuppladdningar från enheter som registrerats med din IoT-hubb går till den här containern. Information om hur du konfigurerar ett lagringskonto och en blobcontainer på din IoT-hubb finns i Konfigurera IoT Hub-filuppladdningar med Hjälp av Azure-portalen, Konfigurera IoT Hub-filuppladdningar med Hjälp av PowerShell. Du kan också använda API:er för IoT Hub-hantering för att konfigurera filuppladdningar programmatiskt.

Om du använder portalen kan du skapa ett lagringskonto och en container under konfigurationen. Om du vill skapa ett lagringskonto kan du läsa Skapa ett lagringskonto i Azure Storage-dokumentationen. När du har ett lagringskonto kan du se hur du skapar en blobcontainer i Azure Blob Storage-snabbstarterna. Som standard använder Azure IoT Hub nyckelbaserad autentisering för att ansluta och auktorisera med Azure Storage. Du kan också konfigurera användartilldelade eller systemtilldelade hanterade identiteter för att autentisera Azure IoT Hub med Azure Storage. Hanterade identiteter tillhandahåller Azure-tjänster med en automatiskt hanterad identitet i Microsoft Entra-ID på ett säkert sätt. Information om hur du konfigurerar hanterade identiteter finns i avsnittet Konfigurera filuppladdning med hanterade identiteter i IoT Hub-stöd för hanterade identiteter.

Filuppladdning omfattas av Azure Storages brandväggsinställningar. Baserat på din autentiseringskonfiguration måste du se till att dina enheter kan kommunicera med Azure Storage.

Det finns flera andra inställningar som styr beteendet för filuppladdningar och meddelanden om filuppladdning. I följande avsnitt visas alla tillgängliga inställningar. Beroende på om du använder Azure-portalen, Azure CLI, PowerShell eller hanterings-API:erna för att konfigurera filuppladdningar kanske vissa av dessa inställningar inte är tillgängliga. Ange inställningen enableFileUploadNotifications om du vill att meddelanden ska skickas till serverdelstjänsterna när en filuppladdning är klar.

Lagrings- och autentiseringsinställningar för Iot Hub

Följande inställningar associerar ett lagringskonto och en container med din IoT-hubb och styr hur din hubb autentiserar med Azure Storage. De här inställningarna påverkar inte hur enheter autentiseras med Azure Storage. Enheter autentiserar alltid med SAS-token som visas i SAS-URI:n som hämtats från IoT Hub.

Property Beskrivning Intervall och standard
storageEndpoints.$default.authenticationType Styr hur IoT Hub autentiserar med Azure Storage. Möjliga värden är keyBased och identityBased. Standard: keyBased.
storageEndpoints.$default.connectionString Anslutningssträng till Azure Storage-kontot som ska användas för filuppladdningar. Standard: Tom sträng.
storageEndpoints.$default.containerName Namnet på containern som du vill ladda upp filer till. Standard: Tom sträng.
storageEndpoints.$default.identity Den hanterade identitet som ska användas för identitetsbaserad autentisering. Möjliga värden är [system] för den systemtilldelade hanterade identiteten eller ett resurs-ID för en användartilldelad hanterad identitet. Värdet används inte för nyckelbaserad autentisering. Standard: null.

Inställningar för filuppladdning

Följande inställningar styr filuppladdningar från enheten.

Property Beskrivning Intervall och standard
storageEndpoints.$default.ttlAsIso8601 Standard-TTL för SAS-URI:er som genereras av IoT Hub. ISO_8601 intervall upp till 48 timmar (minst en minut). Standard: en timme.

Meddelandeinställningar för filuppladdning

Följande inställningar styr filuppladdningsmeddelanden till serverdelstjänster.

Property Beskrivning Intervall och standard
enableFileUploadNotifications Styr om filuppladdningsmeddelanden skrivs till slutpunkten för filmeddelanden. Bool. Standard: False.
fileNotifications.ttlAsIso8601 Standard-TTL för meddelanden om filuppladdning. ISO_8601 intervall upp till 48 timmar (minst en minut). Standard: en timme.
fileNotifications.lockDuration Lås varaktigheten för kön för filuppladdningsmeddelanden. 5 till 300 sekunder. Standard: 60 sekunder.
fileNotifications.maxDeliveryCount Maximalt leveransantal för meddelandekön för filuppladdning. 1 till 100. Standard: 10.

Filuppladdning med hjälp av ett SDK

Följande instruktionsguider innehåller fullständiga, stegvisa instruktioner för att ladda upp filer med hjälp av Azure IoT-enhets- och tjänst-SDK:er. Guiderna visar hur du använder Azure-portalen för att associera ett lagringskonto med en IoT-hubb. Guiderna innehåller också kodfragment eller refererar till exempel som vägleder dig genom en uppladdning.

Instruktionsguide Exempel på enhets-SDK Exempel på Tjänst-SDK
.NET Ja Ja
Java Ja Ja
Node.js Ja Ja
Python Ja Nej (stöds inte)

Kommentar

C-enhetens SDK använder ett enda anrop på enhetsklienten för att utföra filuppladdningar. Mer information finns i IoTHubDeviceClient_UploadToBlobAsync() och IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync(). Dessa funktioner utför alla aspekter av filuppladdningen i ett enda anrop: initiera uppladdningen, ladda upp filen till Azure Storage och meddela IoT Hub när den är klar. Den här interaktionen innebär att enheten, utöver det protokoll som enheten använder för att kommunicera med IoT Hub, också måste kunna kommunicera via HTTPS med Azure Storage eftersom dessa funktioner gör anrop till Azure Storage-API:erna.

Enhet: Initiera en filuppladdning

Enheten anropar REST API:et Create File Upload SAS URI eller motsvarande API i någon av enhetens SDK:er för att initiera en filuppladdning.

Protokoll som stöds: HTTPS
Slutpunkt: {iot hub}.azure-devices.net/devices/{deviceId}/files
Metod: POST

{
    "blobName":"myfile.txt"
}
Property Beskrivning
blobName Namnet på bloben som ska generera SAS-URI:n för.

IoT Hub svarar med ett korrelations-ID och elementen i en SAS-URI som enheten kan använda för att autentisera med Azure Storage. Det här svaret omfattas av begränsningarna och uppladdningsgränserna per enhet för mål-IoT-hubben.

{
    "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"
}
Property Beskrivning
correlationId Identifieraren för enheten som ska användas när du skickar hela meddelandet om filuppladdning till IoT Hub.
Värdnamn Värdnamnet för Azure-lagringskontot för lagringskontot som konfigurerats på IoT-hubben
containerName Namnet på blobcontainern som konfigurerats på IoT-hubben.
blobName Platsen där bloben ska lagras i containern. Namnet är i följande format: {device ID of the device making the request}/{blobName in the request}
sasToken En SAS-token som ger läs- och skrivåtkomst till bloben med Azure Storage. Token genereras och signeras av IoT Hub.

När den tar emot svaret:

  • Sparar korrelations-ID:t som ska inkluderas i det fullständiga meddelandet om filuppladdning till IoT Hub när uppladdningen är klar.

  • Använder de andra egenskaperna för att konstruera en SAS-URI för den blob som används för att autentisera med Azure Storage. SAS-URI:n innehåller resurs-URI:n för den begärda bloben och SAS-token. Den har följande formulär: https://{hostName}/{containerName}/{blobName}{sasToken} (Egenskapen sasToken i svaret innehåller ett inledande ?-tecken.) Klammerparenteserna ingår inte.

    För de värden som returnerades i föregående exempel är SAS-URI: 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

    Mer information om SAS-URI och SAS-token finns i Skapa en tjänst-SAS i Azure Storage-dokumentationen.

Enhet: Ladda upp fil med Azure Storage-API:er

Enheten använder REST-API:er för Azure Blob Storage eller motsvarande Azure Storage SDK-API:er för att ladda upp filen till bloben i Azure Storage.

Protokoll som stöds: HTTPS

I följande exempel visas en Put Blob-begäran om att skapa eller uppdatera en liten blockblob. Observera att den URI som används för den här begäran är DEN SAS-URI som returnerades av IoT Hub i föregående avsnitt. Rubriken x-ms-blob-type anger att den här begäran gäller för en blockblob. Om begäran lyckas returnerar Azure Storage en 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

Att arbeta med Azure Storage-API:er ligger utanför omfånget för den här artikeln. Förutom rest-API:er för Azure Blob Storage som länkats tidigare i det här avsnittet kan du utforska följande dokumentation som hjälper dig att komma igång:

  • Mer information om hur du arbetar med blobar i Azure Storage finns i dokumentationen om Azure Blob Storage.

  • Information om hur du använder Azure Storage-klient-SDK:er för att ladda upp blobar finns i Referens för Azure Blob Storage API.

Enhet: Meddela IoT Hub om en slutförd filuppladdning

Enheten anropar REST-API:et för uppdateringsfiluppladdningsstatus eller motsvarande API i någon av enhetens SDK:er när filuppladdningen är klar. Enheten bör uppdatera filuppladdningsstatusen med IoT Hub oavsett om uppladdningen lyckas eller misslyckas.

Protokoll som stöds: HTTPS
Slutpunkt: {iot hub}.azure-devices.net/devices/{deviceId}/files/notifications
Metod: POST

{
    "correlationId": "MjAyMTA3MzAwNjIxXzBiNjgwOGVkLWZjNzQtN...MzYzLWRlZmI4OWQxMzdmNF9teWZpbGUudHh0X3ZlcjIuMA==",
    "isSuccess": true,
    "statusCode": 200,
    "statusDescription": "File uploaded successfully"
}
Property Beskrivning
correlationId Korrelations-ID:t som togs emot i den första SAS-URI-begäran.
isSuccess Ett booleskt värde som anger om filuppladdningen lyckades.
statusCode Ett heltal som representerar statuskoden för filuppladdningen. Vanligtvis tre siffror; till exempel 200 eller 201.
statusDescription En beskrivning av filuppladdningsstatusen.

När den tar emot en fullständig filuppladdningsavisering från enheten, IoT Hub:

  • Utlöser ett meddelande om filuppladdning till serverdelstjänster om meddelanden om filuppladdning har konfigurerats.

  • Frigör resurser som är associerade med filuppladdningen. Om IoT Hub inte får något meddelande kommer det att underhålla resurserna tills SAS URI time-to-live (TTL) som är associerad med uppladdningen upphör att gälla.

Tjänst: Meddelanden om filuppladdning

Om meddelanden om filuppladdning är aktiverade på din IoT-hubb genererar hubben ett meddelande för serverdelstjänster när den tar emot meddelanden från en enhet om att en filuppladdning är klar. IoT Hub levererar dessa meddelanden om filuppladdning via en tjänstinriktad slutpunkt. Ta emot semantik för meddelanden om filuppladdning är samma som för meddelanden från moln till enhet och har samma livscykel för meddelanden. Tjänst-SDK:er exponerar API:er för att hantera meddelanden om filuppladdning.

Protokoll som stöds AMQP, AMQP-WS
Slutpunkt: {iot hub}.azure-devices.net/messages/servicebound/fileuploadnotifications
Get-metod

Varje meddelande som hämtas från meddelandeslutpunkten för filuppladdning är en JSON-post:

{
    "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"
}
Property Beskrivning
enqueuedTimeUtc Tidsstämpel som anger när meddelandet skapades.
deviceId Enhets-ID för enheten som laddade upp filen.
blobUri URI:n för den uppladdade filen.
blobName Namnet på den uppladdade filen. Namnet är i följande format: {device ID of the device}/{name of the blob}
lastUpdatedTime Tidsstämpel som anger när filen senast uppdaterades.
blobSizeInBytes Ett heltal som representerar storleken på den uppladdade filen i byte.

Tjänster kan använda meddelanden för att hantera uppladdningar. De kan till exempel utlösa sin egen bearbetning av blobdata, utlösa bearbetning av blobdata med hjälp av andra Azure-tjänster eller logga meddelandet om filuppladdning för senare granskning.

Nästa steg