Bestanden uploaden met IoT Hub
Er zijn veel scenario's waarin u uw apparaatgegevens niet eenvoudig kunt toewijzen aan de relatief kleine apparaat-naar-cloud-berichten die ioT Hub accepteert. Bijvoorbeeld het verzenden van grote mediabestanden zoals video; of door grote telemetriebatches te verzenden, geüpload door onregelmatig verbonden apparaten of samengevoegd en gecomprimeerd om bandbreedte te besparen.
Wanneer u grote bestanden vanaf een apparaat moet uploaden, kunt u nog steeds de beveiliging en betrouwbaarheid van IoT Hub gebruiken. In plaats van berichten via zichzelf te brokeren, fungeert IoT Hub echter als dispatcher naar een gekoppeld Azure-opslagaccount. IoT Hub kan ook meldingen aan back-endservices bieden wanneer een apparaat een bestand uploadt.
Als u hulp nodig hebt bij het bepalen wanneer u gerapporteerde eigenschappen, apparaat-naar-cloud-berichten of bestandsuploads wilt gebruiken, raadpleegt u de richtlijnen voor apparaat-naar-cloud-communicatie.
Belangrijk
De functionaliteit voor het uploaden van bestanden op apparaten die X.509-verificatie (CA) gebruiken, is in openbare preview en de preview-modus moet zijn ingeschakeld. Het is algemeen beschikbaar op apparaten die gebruikmaken van X.509-vingerafdrukverificatie of X.509-certificaatattestation met Azure Device Provisioning Service. Zie Ondersteunde X.509-certificaten voor meer informatie over X.509-verificatie met IoT Hub.
Overzicht van het uploaden van bestanden
Een IoT Hub faciliteert het uploaden van bestanden vanaf verbonden apparaten door ze te voorzien van SAS-URI's (Shared Access Signature) per upload voor een blobcontainer en Een Azure-opslagaccount dat vooraf is geconfigureerd met de hub. Er zijn drie onderdelen voor het gebruik van bestandsuploads met IoT Hub: het vooraf configureren van een Azure-opslagaccount en blobcontainer op uw IoT-hub, het uploaden van bestanden vanaf apparaten en optioneel het melden van back-endservices van voltooide bestandsuploads.
Voordat u de functie voor het uploaden van bestanden kunt gebruiken, moet u een Azure-opslagaccount en blobcontainer koppelen aan uw IoT-hub. U kunt ook instellingen configureren die bepalen hoe IoT Hub wordt geverifieerd met Azure Storage, de time-to-live (TTL) van de SAS-URI's die de IoT-hub uitdeelt aan apparaten en meldingen voor het uploaden van bestanden naar uw back-endservices. Zie Een Azure-opslagaccount koppelen aan IoT Hub voor meer informatie.
Apparaten volgen een proces in drie stappen om een bestand te uploaden naar de bijbehorende blobcontainer:
Het apparaat initieert het uploaden van het bestand met de IoT-hub. Hiermee wordt de naam van een blob in de aanvraag doorgegeven en wordt een SAS-URI en een correlatie-id geretourneerd. De SAS-URI bevat een SAS-token voor Azure Storage waarmee het apparaat lees-schrijfmachtigingen voor de aangevraagde blob in de blobcontainer worden verleend. Zie Apparaat: Uploaden van een bestand initialiseren voor meer informatie.
Het apparaat gebruikt de SAS-URI om Azure Blob Storage-API's veilig aan te roepen om het bestand te uploaden naar de blobcontainer. Zie Apparaat: Bestand uploaden met behulp van Azure Storage-API's voor meer informatie.
Wanneer het uploaden van het bestand is voltooid, meldt het apparaat de IoT-hub van de voltooiingsstatus met behulp van de correlatie-id die het heeft ontvangen van IoT Hub toen het uploaden werd gestart. Zie Apparaat: IoT Hub waarschuwen voor een voltooide bestandsupload voor meer informatie.
Back-endservices kunnen zich abonneren op meldingen voor het uploaden van bestanden op het servicegerichte eindpunt voor het uploaden van bestanden van de IoT-hub. Als u deze meldingen hebt ingeschakeld op uw IoT-hub, worden deze op dit eindpunt bezorgd wanneer een apparaat de hub meldt dat het een bestand heeft geüpload. Services kunnen deze meldingen gebruiken om verdere verwerking van de blobgegevens te activeren. Zie Service: Uploadmeldingen voor bestanden voor meer informatie.
Het uploaden van bestanden wordt volledig ondersteund door de Azure IoT-apparaat- en service-SDK's. Zie Bestand uploaden met behulp van een SDK voor meer informatie.
Quota en limieten voor het uploaden van bestanden
IoT Hub legt beperkingen op voor het aantal bestandsuploads dat in een bepaalde periode kan worden gestart. De drempelwaarde is gebaseerd op de SKU en het aantal eenheden van uw IoT-hub. Daarnaast is elk apparaat beperkt tot 10 gelijktijdige actieve bestandsuploads tegelijk. Zie IoT Hub-quota en bandbreedtebeperking voor meer informatie.
Een Azure-opslagaccount koppelen aan IoT Hub
U moet een Azure Storage-account en blobcontainer koppelen aan uw IoT-hub om functies voor het uploaden van bestanden te kunnen gebruiken. Alle bestanden worden geüpload vanaf apparaten die zijn geregistreerd bij uw IoT-hub, worden naar deze container verzonden. Als u een opslagaccount en blobcontainer in uw IoT Hub wilt configureren, raadpleegt u Uploads van IoT Hub-bestanden configureren met behulp van Azure Portal, IoT Hub-bestandsuploads configureren met behulp van Azure CLI of IoT Hub-bestandsuploads configureren met behulp van PowerShell. U kunt ook de IoT Hub-beheer-API's gebruiken om programmatisch bestandsuploads te configureren.
Als u de portal gebruikt, kunt u tijdens de configuratie een opslagaccount en container maken. Als u een opslagaccount wilt maken, raadpleegt u Een opslagaccount maken in de Documentatie voor Azure Storage. Zodra u een opslagaccount hebt, kunt u zien hoe u een blobcontainer maakt in de quickstarts voor Azure Blob Storage. Azure IoT Hub maakt standaard gebruik van verificatie op basis van sleutels om verbinding te maken en te autoriseren met Azure Storage. U kunt ook door de gebruiker toegewezen of door het systeem toegewezen beheerde identiteiten configureren om Azure IoT Hub te verifiëren met Azure Storage. Beheerde identiteiten bieden Azure-services met een automatisch beheerde identiteit in Microsoft Entra ID op een veilige manier. Zie de sectie Bestand uploaden configureren met beheerde identiteiten van IoT Hub-ondersteuning voor beheerde identiteiten voor beheerde identiteiten voor meer informatie over het configureren van beheerde identiteiten.
Het uploaden van bestanden is onderhevig aan de firewallinstellingen van Azure Storage. Op basis van uw verificatieconfiguratie moet u ervoor zorgen dat uw apparaten kunnen communiceren met Azure Storage.
Er zijn verschillende andere instellingen waarmee het gedrag van bestandsuploads en meldingen voor het uploaden van bestanden wordt bepaald. In de volgende secties worden alle beschikbare instellingen weergegeven. Afhankelijk van of u Azure Portal, Azure CLI, PowerShell of de beheer-API's gebruikt om bestandsuploads te configureren, zijn sommige van deze instellingen mogelijk niet beschikbaar. Zorg ervoor dat u de instelling enableFileUploadNotifications instelt als u meldingen naar uw back-endservices wilt verzenden wanneer het uploaden van bestanden is voltooid.
IoT Hub-opslag- en verificatie-instellingen
De volgende instellingen koppelen een opslagaccount en container aan uw IoT-hub en bepalen hoe uw hub wordt geverifieerd met Azure Storage. Deze instellingen zijn niet van invloed op de verificatie van apparaten met Azure Storage. Apparaten verifiëren altijd met het SAS-token dat wordt weergegeven in de SAS-URI die is opgehaald uit IoT Hub.
| Eigenschappen | Beschrijving | Bereik en standaard |
|---|---|---|
| storageEndpoints.$default.authenticationType | Hiermee bepaalt u hoe de IoT Hub wordt geverifieerd met Azure Storage. | Mogelijke waarden zijn keyBased en identityBased. Standaard: keyBased. |
| storageEndpoints.$default.connectionString | De verbindingsreeks naar het Azure-opslagaccount dat moet worden gebruikt voor het uploaden van bestanden. | Standaard: lege tekenreeks. |
| storageEndpoints.$default.containerName | De naam van de container waar u bestanden naar wilt uploaden. | Standaard: lege tekenreeks. |
| storageEndpoints.$default.identity | De beheerde identiteit die moet worden gebruikt voor verificatie op basis van identiteiten. | Mogelijke waarden zijn [system] voor de door het systeem toegewezen beheerde identiteit of een resource-id voor een door de gebruiker toegewezen beheerde identiteit. De waarde wordt niet gebruikt voor verificatie op basis van sleutels. Standaard: null. |
Instellingen voor het uploaden van bestanden
Met de volgende instellingen bepaalt u het uploaden van bestanden vanaf het apparaat.
| Eigenschappen | Beschrijving | Bereik en standaard |
|---|---|---|
| storageEndpoints.$default.ttlAsIso8601 | Standaard-TTL voor SAS-URI's die worden gegenereerd door IoT Hub. | ISO_8601 interval tot 48 uur (minimaal één minuut). Standaard: één uur. |
Meldingsinstellingen voor het uploaden van bestanden
Met de volgende instellingen kunt u meldingen voor het uploaden van bestanden naar back-endservices beheren.
| Eigenschappen | Beschrijving | Bereik en standaard |
|---|---|---|
| enableFileUploadNotifications | Hiermee bepaalt u of meldingen voor het uploaden van bestanden naar het eindpunt voor bestandsmeldingen worden geschreven. | Bool. Standaard: Onwaar. |
| fileNotifications.ttlAsIso8601 | Standaard-TTL voor meldingen voor het uploaden van bestanden. | ISO_8601 interval tot 48 uur (minimaal één minuut). Standaard: één uur. |
| fileNotifications.lockDuration | Vergrendelingsduur voor de wachtrij voor bestandsuploadmeldingen. | 5 tot 300 seconden. Standaard: 60 seconden. |
| fileNotifications.maxDeliveryCount | Maximum aantal bezorgingen voor de meldingswachtrij voor het uploaden van bestanden. | 1 tot 100. Standaard: 10. |
Bestand uploaden met behulp van een SDK
De volgende handleidingen bevatten volledige, stapsgewijze instructies voor het uploaden van bestanden met behulp van de Azure IoT-apparaat- en service-SDK's. De handleidingen laten zien hoe u Azure Portal gebruikt om een opslagaccount te koppelen aan een IoT-hub. De handleidingen bevatten ook codefragmenten of verwijzen naar voorbeelden die u begeleiden bij het uploaden.
| Instructiegids | Voorbeeld van Device SDK | Voorbeeld van service-SDK |
|---|---|---|
| .NET | Ja | Ja |
| Java | Ja | Ja |
| Node.js | Ja | Ja |
| Python | Ja | Nee (niet ondersteund) |
Notitie
De SDK voor C-apparaten maakt gebruik van één aanroep op de apparaatclient om bestandsuploads uit te voeren. Zie IoTHubDeviceClient_UploadToBlobAsync() en IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync() voor meer informatie. Met deze functies worden alle aspecten van het uploaden van bestanden in één aanroep uitgevoerd: het uploaden starten, het bestand uploaden naar Azure Storage en IoT Hub waarschuwen wanneer het is voltooid. Deze interactie betekent dat, naast het protocol dat het apparaat gebruikt om te communiceren met IoT Hub, het apparaat ook via HTTPS moet kunnen communiceren met Azure Storage, omdat deze functies aanroepen doen naar de Azure Storage-API's.
Apparaat: Uploaden van een bestand initialiseren
Het apparaat roept de REST API voor het uploaden van SAS-URI's voor bestandsupload of de equivalente API in een van de apparaat-SDK's aan om een bestandsupload te starten.
Ondersteunde protocollen: HTTPS
Eindpunt: {iot hub}.azure-devices.net/devices/{deviceId}/files
Methode: POST
{
"blobName":"myfile.txt"
}
| Eigenschappen | Beschrijving |
|---|---|
| blobName | De naam van de blob waarvoor de SAS-URI moet worden gegenereerd. |
IoT Hub reageert met een correlatie-id en de elementen van een SAS-URI die het apparaat kan gebruiken om te verifiëren met Azure Storage. Dit antwoord is onderhevig aan de beperkingslimieten en uploadlimieten per apparaat van de IoT-doelhub.
{
"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"
}
| Eigenschappen | Beschrijving |
|---|---|
| correlationId | De id voor het apparaat dat moet worden gebruikt bij het verzenden van de volledige melding voor het uploaden van het bestand naar IoT Hub. |
| Hostname | De hostnaam van het Azure-opslagaccount voor het opslagaccount dat is geconfigureerd op de IoT-hub |
| containerName | De naam van de blobcontainer die is geconfigureerd op de IoT-hub. |
| blobName | De locatie waar de blob wordt opgeslagen in de container. De naam heeft de volgende indeling: {device ID of the device making the request}/{blobName in the request} |
| sasToken | Een SAS-token dat lees-/schrijftoegang verleent op de blob met Azure Storage. Het token wordt gegenereerd en ondertekend door IoT Hub. |
Wanneer het antwoord wordt ontvangen, wordt het apparaat:
Slaat de correlatie-id op die moet worden opgenomen in de volledige melding voor het uploaden van bestanden naar IoT Hub wanneer het uploaden is voltooid.
Gebruikt de andere eigenschappen om een SAS-URI te maken voor de blob die wordt gebruikt voor verificatie met Azure Storage. De SAS-URI bevat de resource-URI voor de aangevraagde blob en het SAS-token. Deze heeft de volgende vorm:
https://{hostName}/{containerName}/{blobName}{sasToken}(DesasTokeneigenschap in het antwoord bevat een voorloopteken '?'.) De accolades zijn niet inbegrepen.Voor de waarden die in het vorige voorbeeld worden geretourneerd, is de SAS-URI bijvoorbeeld,
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=rwZie Een service-SAS maken in de Documentatie voor Azure Storage voor meer informatie over de SAS-URI en het SAS-token.
Apparaat: Bestand uploaden met behulp van Azure Storage-API's
Het apparaat maakt gebruik van de REST API's van Azure Blob Storage of equivalente AZURE Storage SDK-API's om het bestand te uploaden naar de blob in Azure Storage.
Ondersteunde protocollen: HTTPS
In het volgende voorbeeld ziet u een Put Blob-aanvraag om een kleine blok-blob te maken of bij te werken. U ziet dat de URI die voor deze aanvraag wordt gebruikt, de SAS-URI is die in de vorige sectie door IoT Hub wordt geretourneerd. De x-ms-blob-type header geeft aan dat deze aanvraag voor een blok-blob is. Als de aanvraag is geslaagd, retourneert Azure Storage een 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
Werken met Azure Storage-API's valt buiten het bereik van dit artikel. Naast de REST API's van Azure Blob Storage die eerder in deze sectie zijn gekoppeld, kunt u de volgende documentatie verkennen om aan de slag te gaan:
Zie de documentatie voor Azure Blob Storage voor meer informatie over het werken met blobs in Azure Storage.
Zie de naslaginformatie over de Azure Blob Storage-API voor informatie over het gebruik van SDK's van de Azure Storage-client om blobs te uploaden.
Apparaat: IoT Hub informeren over het uploaden van een voltooid bestand
Het apparaat roept de REST API voor het uploaden van bestanden of de equivalente API aan in een van de apparaat-SDK's wanneer het uploaden van het bestand is voltooid. Het apparaat moet de uploadstatus van het bestand bijwerken met IoT Hub, ongeacht of het uploaden slaagt of mislukt.
Ondersteunde protocollen: HTTPS
Eindpunt: {iot hub}.azure-devices.net/devices/{deviceId}/files/notifications
Methode: POST
{
"correlationId": "MjAyMTA3MzAwNjIxXzBiNjgwOGVkLWZjNzQtN...MzYzLWRlZmI4OWQxMzdmNF9teWZpbGUudHh0X3ZlcjIuMA==",
"isSuccess": true,
"statusCode": 200,
"statusDescription": "File uploaded successfully"
}
| Eigenschappen | Beschrijving |
|---|---|
| correlationId | De correlatie-id die is ontvangen in de eerste SAS-URI-aanvraag. |
| isSuccess | Een Booleaanse waarde die aangeeft of het uploaden van het bestand is geslaagd. |
| statuscode | Een geheel getal dat de statuscode van het uploaden van het bestand vertegenwoordigt. Meestal drie cijfers; bijvoorbeeld 200 of 201. |
| statusDescription | Een beschrijving van de uploadstatus van het bestand. |
Wanneer er een volledige melding voor het uploaden van bestanden van het apparaat wordt ontvangen, ioT Hub:
Hiermee wordt een melding voor het uploaden van bestanden naar back-endservices geactiveerd als meldingen voor het uploaden van bestanden zijn geconfigureerd.
Releases resources die zijn gekoppeld aan het uploaden van bestanden. Als IoT Hub geen melding ontvangt, blijven de resources behouden totdat de SAS-URI time-to-live (TTL) die is gekoppeld aan de upload verloopt.
Service: Meldingen voor het uploaden van bestanden
Als meldingen voor het uploaden van bestanden zijn ingeschakeld op uw IoT-hub, genereert uw hub een melding voor back-endservices wanneer er een melding wordt ontvangen van een apparaat dat het uploaden van bestanden is voltooid. IoT Hub levert deze meldingen voor het uploaden van bestanden via een servicegericht eindpunt. De ontvangstsemantiek voor meldingen voor het uploaden van bestanden zijn hetzelfde als voor cloud-naar-apparaat-berichten en hebben dezelfde levenscyclus van berichten. De service-SDK's maken API's beschikbaar voor het verwerken van meldingen voor het uploaden van bestanden.
Ondersteunde protocollen AMQP, AMQP-WS
Eindpunt: {iot hub}.azure-devices.net/messages/servicebound/fileuploadnotifications
Methode GET
Elk bericht dat wordt opgehaald uit het eindpunt voor het uploaden van bestanden, is een JSON-record:
{
"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"
}
| Eigenschappen | Beschrijving |
|---|---|
| enqueuedTimeUtc | Tijdstempel die aangeeft wanneer de melding is gemaakt. |
| deviceId | De apparaat-id van het apparaat dat het bestand heeft geüpload. |
| blobUri | De URI van het geüploade bestand. |
| blobName | De naam van het geüploade bestand. De naam heeft de volgende indeling: {device ID of the device}/{name of the blob} |
| lastUpdatedTime | Tijdstempel die aangeeft wanneer het bestand voor het laatst is bijgewerkt. |
| blobSizeInBytes | Een geheel getal dat de grootte van het geüploade bestand in bytes vertegenwoordigt. |
Services kunnen meldingen gebruiken om uploads te beheren. Ze kunnen bijvoorbeeld hun eigen verwerking van de blobgegevens activeren, de verwerking van de blobgegevens activeren met behulp van andere Azure-services of de melding voor het uploaden van bestanden vastleggen voor later onderzoek.
Volgende stappen
Azure IoT-apparaat- en service-SDK's bevat de verschillende taal-SDK's die u kunt gebruiken wanneer u zowel apparaat- als service-apps ontwikkelt die communiceren met IoT Hub.