Nahrávání souborů s využitím služby IoT Hub
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é jsou nakonfigurované pro nahrání souborů z centra. Při nahrávání souborů ve službě IoT Hub existují tři části:
- Konfigurace účtu úložiště Azure a kontejneru objektů blob ve službě IoT Hub
- Nahrávání souborů ze zařízení
- Volitelně můžete upozorňovat back-endové služby 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ů:
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.
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.
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ů.
Sady SDK pro zařízení a služby Azure IoT plně podporují nahrávání souborů. 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 přejdou 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.
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.
Na nahrávání souborů se vztahuje nastavení brány firewall služby Azure Storage. Potřebujete zajistit, aby vaše zařízení mohly komunikovat s úložištěm Azure podle vaší konfigurace ověřování.
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. Stále potřebujete připojit zařízení k úložišti pomocí identifikátoru URI SAS. Dnes se identifikátor URI SAS generuje pomocí připojovací řetězec.
Informace o konfiguraci nahrávání souborů pro použití ověřování na základě identity najdete v tématu Konfigurace nahrávání souborů pomocí spravovaných identit.
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}
(VlastnostsasToken
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 Created
hodnotu .
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í, udržuje 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.