Share via

Nahrávání souborů s využitím služby IoT Hub

  • Článek

Existuje mnoho scénářů, kdy nemůžete snadno namapovat data zařízení na relativně malé zprávy typu zařízení-cloud, které IoT Hub přijímá. Například odesílání velkých mediálních souborů, jako je video; nebo odesílání velkých dávek telemetrie buď nahraných přerušovaně připojenými zařízeními, nebo agregovanými a komprimovanými za účelem úspory šířky pásma.

Pokud potřebujete nahrát velké soubory ze zařízení, můžete dál používat zabezpečení a spolehlivost ioT Hubu. Místo zprostředkování zpráv sama o sobě ale IoT Hub funguje jako dispečer přidruženého účtu úložiště Azure. IoT Hub může také poskytovat oznámení back-endovým službám, když zařízení dokončí nahrávání souborů.

Pokud potřebujete pomoc s rozhodováním, kdy použít ohlášené vlastnosti, zprávy typu zařízení-cloud nebo nahrání souborů, přečtěte si pokyny pro komunikaci typu zařízení-cloud.

Důležité

Funkce nahrávání souborů na zařízeních, která používají ověřování certifikační autority (CA) X.509, je ve verzi Public Preview a musí být povolený režim náhledu. Je obecně dostupná na zařízeních, která používají ověřování kryptografického otisku X.509 nebo ověření identity certifikátu X.509 se službou Azure Device Provisioning. Další informace o ověřování X.509 ve službě IoT Hub najdete v tématu Podporované certifikáty X.509.

Přehled nahrávání souborů

IoT Hub usnadňuje nahrávání souborů z připojených zařízení tím, že jim poskytne identifikátory URI sdíleného přístupového podpisu (SAS) pro kontejner objektů blob a účet úložiště Azure, který je předem nakonfigurovaný s centrem. Při nahrávání souborů ve službě IoT Hub existují tři části: předkonfigurování účtu úložiště Azure a kontejneru objektů blob ve službě IoT Hub, nahrávání souborů ze zařízení a volitelně upozorňování back-endových služeb na dokončené nahrávání souborů.

Než budete moct použít funkci nahrání souboru, musíte ke službě IoT Hub přidružit účet úložiště Azure a kontejner objektů blob. Můžete také nakonfigurovat nastavení, která řídí, jak se IoT Hub ověřuje pomocí úložiště Azure, hodnoty TTL (Time to Live) identifikátorů URI SAS, které centrum IoT hub předává zařízením, a odesílat oznámení do back-endových služeb. Další informace najdete v tématu Přidružení účtu úložiště Azure ke službě IoT Hub.

Zařízení nahrají soubor do přidruženého kontejneru objektů blob pomocí tří kroků:

  1. Zařízení inicializuje nahrání souboru pomocí IoT Hubu. Předá název objektu blob v požadavku a vrátí identifikátor URI SAS a ID korelace. Identifikátor URI SAS obsahuje token SAS pro úložiště Azure, který udělí zařízení oprávnění ke čtení a zápisu požadovaného objektu blob v kontejneru objektů blob. Další informace najdete v tématu Zařízení: Inicializace nahrání souboru.

  2. Zařízení používá identifikátor URI SAS k bezpečnému volání rozhraní API služby Azure Blob Storage k nahrání souboru do kontejneru objektů blob. Další informace najdete v tématu Zařízení: Nahrání souboru pomocí rozhraní API úložiště Azure.

  3. Po dokončení nahrávání souboru zařízení upozorní centrum IoT na stav dokončení pomocí ID korelace, které přijal ze služby IoT Hub při zahájení nahrávání. Další informace najdete v tématu Zařízení: Oznámení IoT Hubu o dokončení nahrávání souborů.

Back-endové služby se můžou přihlásit k odběru oznámení o nahrávání souborů na koncovém bodu oznámení o nahrávání souborů v centru IoT Hub. Pokud jste tato oznámení povolili ve službě IoT Hub, doručí je do tohoto koncového bodu pokaždé, když zařízení oznámí centru, že dokončilo nahrávání souboru. Služby můžou tato oznámení použít k aktivaci dalšího zpracování dat objektů blob. Další informace najdete v tématu Služba: Oznámení o nahrání souborů.

Nahrávání souborů je plně podporováno sadami SDK pro zařízení a služby Azure IoT. Další informace najdete v tématu Nahrání souboru pomocí sady SDK.

Kvóty a omezení nahrávání souborů

IoT Hub omezuje omezení počtu nahrávání souborů, které může v daném období zahájit. Prahová hodnota vychází ze skladové položky a počtu jednotek vašeho centra IoT. Kromě toho je každé zařízení omezené na 10 souběžných aktivních nahrávání souborů najednou. Další informace najdete v tématu Kvóty a omezování služby IoT Hub.

Přidružení účtu úložiště Azure ke službě IoT Hub

Abyste mohli používat funkce nahrávání souborů, musíte k centru IoT přidružit účet úložiště Azure a kontejner objektů blob. Všechny soubory nahrané ze zařízení zaregistrovaných ve službě IoT Hub se přesunou do tohoto kontejneru. Pokud chcete nakonfigurovat účet úložiště a kontejner objektů blob ve službě IoT Hub, přečtěte si téma Konfigurace nahrávání souborů ioT Hubu pomocí webu Azure Portal, konfigurace nahrávání souborů ioT Hubu pomocí Azure CLI nebo konfigurace nahrávání souborů IoT Hubu pomocí PowerShellu. Rozhraní API pro správu služby IoT Hub můžete také použít ke konfiguraci nahrávání souborů prostřednictvím kódu programu.

Pokud používáte portál, můžete během konfigurace vytvořit účet úložiště a kontejner. Pokud chcete vytvořit účet úložiště, přečtěte si téma Vytvoření účtu úložiště v dokumentaci k Úložišti Azure. Jakmile máte účet úložiště, můžete se podívat, jak vytvořit kontejner objektů blob v rychlých startech služby Azure Blob Storage. Azure IoT Hub ve výchozím nastavení používá ověřování založené na klíčích k připojení a autorizaci s Azure Storage. Můžete také nakonfigurovat spravované identity přiřazené uživatelem nebo systémem pro ověření služby Azure IoT Hub pomocí služby Azure Storage. Spravované identity zabezpečeným způsobem poskytují službám Azure automaticky spravovanou identitu v Microsoft Entra ID. Informace o konfiguraci spravovaných identit najdete v části Konfigurace nahrávání souborů s využitím podpory spravovaných identit ve službě IoT Hub pro spravované identity.

Na nahrávání souborů se vztahuje nastavení brány firewall služby Azure Storage. Na základě konfigurace ověřování budete muset zajistit, aby vaše zařízení komunikují s úložištěm Azure.

Existuje několik dalších nastavení, která řídí chování nahrávání souborů a oznámení o nahrávání souborů. V následujících částech jsou uvedená všechna dostupná nastavení. V závislosti na tom, jestli ke konfiguraci nahrávání souborů používáte Azure Portal, Azure CLI, PowerShell nebo rozhraní API pro správu, nemusí být některá z těchto nastavení dostupná. Nastavení enableFileUploadNotifications nezapomeňte nastavit, pokud chcete, aby se oznámení odesílaná back-endovým službám po dokončení nahrávání souboru.

Nastavení úložiště a ověřování služby Iot Hub

Následující nastavení přidruží účet úložiště a kontejner k vašemu centru IoT a řídí, jak se vaše centrum ověřuje s úložištěm Azure. Tato nastavení nemají vliv na ověřování zařízení pomocí úložiště Azure. Zařízení se vždy ověřují pomocí tokenu SAS uvedeného v identifikátoru URI SAS načteného ze služby IoT Hub.

Vlastnost Popis Rozsah a výchozí nastavení
storageEndpoints.$default.authenticationType Řídí, jak se IoT Hub ověřuje pomocí úložiště Azure. Možné hodnoty jsou keyBased a identityBased. Výchozí hodnota: keyBased.
storageEndpoints.$default.connectionString Připojovací řetězec k účtu úložiště Azure, který se má použít pro nahrávání souborů. Výchozí: Prázdný řetězec.
storageEndpoints.$default.containerName Název kontejneru pro nahrání souborů. Výchozí: Prázdný řetězec.
storageEndpoints.$default.identity Spravovaná identita, která se má použít pro ověřování na základě identity. Možné hodnoty jsou [system] pro spravovanou identitu přiřazenou systémem nebo ID prostředku pro spravovanou identitu přiřazenou uživatelem. Hodnota se nepoužívá pro ověřování na základě klíče. Výchozí hodnota: null.

Nastavení nahrávání souborů

Následující řídicí soubor nastavení se nahraje ze zařízení.

Vlastnost Popis Rozsah a výchozí nastavení
storageEndpoints.$default.ttlAsIso8601 Výchozí hodnota TTL pro identifikátory URI SAS vygenerované službou IoT Hub ISO_8601 interval až 48 hodin (minimálně jednu minutu). Výchozí hodnota: jedna hodina.

Nastavení oznámení pro nahrání souboru

Následující nastavení řídí odesílání oznámení o nahrávání souborů do back-endových služeb.

Vlastnost Popis Rozsah a výchozí nastavení
enableFileUploadNotifications Určuje, jestli se oznámení o nahrávání souborů zapisují do koncového bodu oznámení souborů. Bool. Výchozí hodnota: Nepravda.
fileNotifications.ttlAsIso8601 Výchozí hodnota TTL pro oznámení o nahrávání souborů ISO_8601 interval až 48 hodin (minimálně jednu minutu). Výchozí hodnota: jedna hodina.
fileNotifications.lockDuration Doba trvání uzamčení fronty oznámení nahrání souboru 5 až 300 sekund. Výchozí hodnota: 60 sekund.
fileNotifications.maxDeliveryCount Maximální počet doručení pro frontu oznámení pro nahrání souboru 1 až 100. Výchozí hodnota: 10.

Nahrání souborů pomocí sady SDK

Následující návody poskytují úplné podrobné pokyny k nahrání souborů pomocí sad SDK pro zařízení a služby Azure IoT. V průvodcích se dozvíte, jak pomocí webu Azure Portal přidružit účet úložiště k centru IoT. Příručky také obsahují fragmenty kódu nebo odkazují na ukázky, které vás provedou nahráním.

Praktičtí průvodci Příklad sady SDK pro zařízení Příklad sady SDK služby
.NET Ano Yes
Java Ano Yes
Node.js Ano Yes
Python Ano Ne (nepodporuje se)

Poznámka:

Sada SDK pro zařízení jazyka C používá k nahrání souborů jedno volání klienta zařízení. Další informace najdete v tématu IoTHubDeviceClient_UploadToBlobAsync() a IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync(). Tyto funkce provádějí všechny aspekty nahrávání souboru v jednom volání: iniciování nahrávání, nahrání souboru do úložiště Azure a oznámení IoT Hubu po dokončení. Tato interakce znamená, že kromě jakéhokoli protokolu, který zařízení používá ke komunikaci se službou IoT Hub, musí být zařízení také schopné komunikovat přes PROTOKOL HTTPS se službou Azure Storage, protože tyto funkce volávají rozhraní API úložiště Azure.

Zařízení: Inicializace nahrání souboru

Zařízení volá rozhraní REST API IDENTIFIKÁTORu URI CREATE File Upload SAS nebo ekvivalentní rozhraní API v některé ze sad SDK zařízení k zahájení nahrávání souborů.

Podporované protokoly: HTTPS
Koncový bod: {iot hub}.azure-devices.net/devices/{deviceId}/files
Metoda: POST

{
    "blobName":"myfile.txt"
}
Vlastnost Popis
blobName Název objektu blob pro vygenerování identifikátoru URI SAS pro.

IoT Hub reaguje s ID korelace a prvky identifikátoru URI SAS, které zařízení může použít k ověření v úložišti Azure. Tato odpověď podléhá omezením omezování a limitům nahrávání jednotlivých zařízení cílového centra IoT.

{
    "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"
}
Vlastnost Popis
correlationId Identifikátor zařízení, který se má použít při odesílání kompletního oznámení o nahrání souboru do IoT Hubu.
Hostname Název hostitele účtu úložiště Azure pro účet úložiště nakonfigurovaný ve službě IoT Hub
containerName Název kontejneru objektů blob nakonfigurovaného ve službě IoT Hub.
blobName Umístění, kam bude objekt blob uložen v kontejneru. Název je v následujícím formátu: {device ID of the device making the request}/{blobName in the request}
sasToken Token SAS, který uděluje přístup pro čtení a zápis do objektu blob pomocí úložiště Azure. Token se vygeneruje a podepíše službou IoT Hub.

Když obdrží odpověď, zařízení:

  • Uloží ID korelace, které se má zahrnout do nahrání souboru, úplné oznámení do Centra IoT po dokončení nahrávání.

  • Použije ostatní vlastnosti k vytvoření identifikátoru URI SAS pro objekt blob, který používá k ověření v úložišti Azure. Identifikátor URI SAS obsahuje identifikátor URI prostředku pro požadovaný objekt blob a token SAS. Má následující podobu: https://{hostName}/{containerName}/{blobName}{sasToken} (Vlastnost sasToken v odpovědi obsahuje úvodní znak "?".) Složené závorky nejsou zahrnuty.

    Například pro hodnoty vrácené v předchozí ukázce je identifikátor URI SAS: 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

    Další informace o identifikátoru URI SAS a tokenu SAS najdete v dokumentaci k vytvoření sdíleného přístupového podpisu služby v dokumentaci k úložišti Azure.

Zařízení: Nahrání souboru pomocí rozhraní API služby Azure Storage

Zařízení k nahrání souboru do objektu blob v úložišti Azure používá rozhraní REST API služby Azure Blob Storage nebo ekvivalentní rozhraní API sady Azure Storage SDK.

Podporované protokoly: HTTPS

Následující příklad ukazuje požadavek Put Blob na vytvoření nebo aktualizaci malého objektu blob bloku. Všimněte si, že identifikátor URI použitý pro tento požadavek je identifikátor URI SAS vrácený službou IoT Hub v předchozí části. Hlavička x-ms-blob-type označuje, že tento požadavek je určený pro objekt blob bloku. Pokud je požadavek úspěšný, azure storage vrátí 201 Createdhodnotu .

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

Práce s rozhraními API úložiště Azure je nad rámec tohoto článku. Kromě rozhraní REST API služby Azure Blob Storage propojených dříve v této části můžete prozkoumat následující dokumentaci, která vám pomůže začít:

  • Další informace o práci s objekty blob v úložišti Azure najdete v dokumentaci ke službě Azure Blob Storage.

  • Informace o použití klientských sad SDK služby Azure Storage k nahrání objektů blob najdete v referenčních informacích k rozhraní API služby Azure Blob Storage.

Zařízení: Oznámení IoT Hubu o dokončení nahrávání souboru

Zařízení po dokončení nahrávání souboru volá rozhraní REST API stavu aktualizace souboru nebo ekvivalentní rozhraní API v jedné ze sad SDK zařízení. Zařízení by mělo aktualizovat stav nahrávání souborů službou IoT Hub bez ohledu na to, jestli nahrávání proběhne úspěšně nebo selže.

Podporované protokoly: HTTPS
Koncový bod: {iot hub}.azure-devices.net/devices/{deviceId}/files/notifications
Metoda: POST

{
    "correlationId": "MjAyMTA3MzAwNjIxXzBiNjgwOGVkLWZjNzQtN...MzYzLWRlZmI4OWQxMzdmNF9teWZpbGUudHh0X3ZlcjIuMA==",
    "isSuccess": true,
    "statusCode": 200,
    "statusDescription": "File uploaded successfully"
}
Vlastnost Popis
correlationId ID korelace přijaté v počátečním požadavku URI SAS.
isSuccess Logická hodnota označující, jestli bylo nahrávání souboru úspěšné.
statusCode Celé číslo, které představuje stavový kód nahrání souboru. Obvykle tři číslice; například 200 nebo 201.
statusDescription Popis stavu nahrání souboru.

Když obdrží úplné oznámení o nahrání souboru ze zařízení, IoT Hub:

  • Aktivuje oznámení o nahrání souboru do back-endových služeb, pokud jsou nakonfigurovaná oznámení o nahrávání souborů.

  • Uvolní prostředky přidružené k nahrání souboru. Pokud IoT Hub neobdrží oznámení, bude udržovat prostředky, dokud nevyprší platnost identifikátoru URI SAS (TTL) přidruženého k odeslání.

Služba: Oznámení o nahrání souborů

Pokud jsou ve službě IoT Hub povolená oznámení o nahrávání souborů, vaše centrum vygeneruje zprávu oznámení pro back-endové služby, když obdrží oznámení ze zařízení, že je nahrávání souboru dokončené. IoT Hub doručuje tato oznámení o nahrávání souborů prostřednictvím koncového bodu směřujícího ke službě. Sémantika příjmu pro oznámení o nahrávání souborů je stejná jako u zpráv typu cloud-zařízení a mají stejný životní cyklus zpráv. Sady SDK služby zpřístupňují rozhraní API pro zpracování oznámení o nahrávání souborů.

Podporované protokoly AMQP, AMQP-WS
Koncový bod: {iot hub}.azure-devices.net/messages/servicebound/fileuploadnotifications
Metoda GET

Každá zpráva načtená z koncového bodu oznámení pro nahrání souboru je záznam JSON:

{
    "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"
}
Vlastnost Popis
enqueuedTimeUtc Časové razítko označující, kdy se oznámení vytvořilo.
deviceId ID zařízení, které soubor nahrálo.
blobUri Identifikátor URI nahraného souboru.
blobName Název nahraného souboru. Název je v následujícím formátu: {device ID of the device}/{name of the blob}
lastUpdatedTime Časové razítko označující, kdy byl soubor naposledy aktualizován.
blobSizeInBytes Celé číslo, které představuje velikost nahraného souboru v bajtech.

Služby můžou ke správě nahrávání používat oznámení. Mohou například aktivovat vlastní zpracování dat objektů blob, aktivovat zpracování dat objektu blob pomocí jiných služeb Azure nebo protokolovat oznámení o nahrání souboru pro pozdější kontrolu.

Další kroky