Fájlok feltöltése az IoT Hubbal

  • Cikk

Számos olyan eset van, amikor nem tudja könnyen leképíteni az eszköz adatait az IoT Hub által elfogadott, viszonylag kis méretű, eszközről felhőbe irányuló üzenetekre. Például nagy méretű médiafájlok, például videók küldése; vagy nagy telemetriai kötegek küldése, amelyeket időszakosan csatlakoztatott eszközök töltenek fel, vagy összesítettek és tömörítve a sávszélesség megtakarítása érdekében.

Ha nagy méretű fájlokat kell feltöltenie egy eszközről, továbbra is használhatja az IoT Hub biztonságát és megbízhatóságát. Az üzenetek önmagán keresztüli közvetítése helyett azonban az IoT Hub kézbesítőként működik egy társított Azure Storage-fiókhoz. Az IoT Hub értesítést is tud nyújtani a háttérszolgáltatásoknak, ha egy eszköz befejez egy fájlfeltöltést.

Ha segítségre van szüksége a jelentett tulajdonságok, az eszközről a felhőbe irányuló üzenetek vagy a fájlfeltöltések használatának eldöntéséhez, tekintse meg az eszközről a felhőbe irányuló kommunikációs útmutatót.

Fontos

Az X.509 hitelesítésszolgáltatói (CA) hitelesítést használó eszközökön a fájlfeltöltési funkció nyilvános előzetes verzióban érhető el, és engedélyezni kell az előnézeti módot. Általánosan elérhető x.509 ujjlenyomat-hitelesítést vagy X.509-tanúsítványigazolást használó eszközökön az Azure Device Provisioning Service-ben. Az IoT Hub x.509-hitelesítésével kapcsolatos további információkért lásd a támogatott X.509-tanúsítványokat.

A fájlfeltöltés áttekintése

Az IoT Hub lehetővé teszi a csatlakoztatott eszközökről történő fájlfeltöltést azáltal, hogy megosztott hozzáférésű jogosultságkód (SAS) URI-kat biztosít nekik feltöltésenként egy olyan blobtárolóhoz és Azure Storage-fiókhoz, amelyet előre konfiguráltak a központtal. A fájlfeltöltések az IoT Hub használatával három részből állnak: az Azure Storage-fiók és a blobtároló előzetes konfigurálása az IoT Hubon, fájlok feltöltése az eszközökről, és opcionálisan a befejezett fájlfeltöltések háttérszolgáltatásainak értesítése.

A fájlfeltöltési funkció használatához azure-tárfiókot és blobtárolót kell társítania az IoT Hubhoz. Konfigurálhat olyan beállításokat is, amelyek szabályozzák az IoT Hub Azure Storage-beli hitelesítését, az IoT Hub által az eszközöknek kiközvetített SAS-URI-k élettartamát (TTL), valamint fájlfeltöltési értesítéseket a háttérszolgáltatásokba. További információ: Azure Storage-fiók társítása az IoT Hubbal.

Az eszközök egy háromlépéses folyamatot követve feltöltenek egy fájlt a társított blobtárolóba:

  1. Az eszköz kezdeményezi a fájlfeltöltést az IoT Hubbal. Átadja egy blob nevét a kérelemben, és kap egy SAS URI-t és egy korrelációs azonosítót cserébe. Az SAS URI tartalmaz egy SAS-jogkivonatot az Azure Storage-hoz, amely olvasási-írási engedélyt ad az eszköznek a blobtároló kért blobján. További információ : Eszköz: Fájlfeltöltés inicializálása.

  2. Az eszköz az SAS URI használatával biztonságosan meghívja az Azure Blob Storage API-kat a fájl blobtárolóba való feltöltéséhez. További információ : Eszköz: Fájl feltöltése Azure Storage API-k használatával.

  3. Amikor a fájlfeltöltés befejeződött, az eszköz a feltöltés indításakor az IoT Hubtól kapott korrelációs azonosítóval értesíti a befejezési állapot IoT Hubját. További információ : Eszköz: Az IoT Hub értesítése befejezett fájlfeltöltésről.

A háttérszolgáltatások feliratkozhatnak a fájlfeltöltési értesítésekre az IoT Hub szolgáltatással kapcsolatos fájlfeltöltési értesítési végpontján. Ha engedélyezte ezeket az értesítéseket az IoT Hubon, az ezen a végponton küldi el őket, amikor egy eszköz értesíti a központot arról, hogy befejezte a fájlfeltöltést. A szolgáltatások ezen értesítések használatával aktiválhatják a blobadatok további feldolgozását. További információ: Szolgáltatás: Fájlfeltöltési értesítések.

A fájlfeltöltést az Azure IoT-eszköz- és szolgáltatási SDK-k teljes mértékben támogatják. További információ: Fájlfeltöltés SDK használatával.

Fájlfeltöltési kvóták és korlátok

Az IoT Hub szabályozási korlátozásokat vezet be az adott időszakban kezdeményezhető fájlfeltöltések számára. A küszöbérték az IoT Hub termékváltozatán és egységeinek számán alapul. Emellett minden eszköz egyszerre legfeljebb 10 egyidejű aktív fájlfeltöltésre korlátozódik. További információ: IoT Hub-kvóták és szabályozás.

Azure Storage-fiók társítása az IoT Hubbal

A fájlfeltöltési funkciók használatához azure-tárfiókot és blobtárolót kell társítania az IoT Hubhoz. Az IoT Hubon regisztrált eszközökről származó összes fájlfeltöltés ebbe a tárolóba kerül. A tárfiók és a blobtároló IoT Hubon való konfigurálásához lásd : IoT Hub-fájlok feltöltésének konfigurálása az Azure Portal használatával, IoT Hub-fájlfeltöltések konfigurálása az Azure CLI-vel, vagy IoT Hub-fájlfeltöltések konfigurálása a PowerShell használatával. Az IoT Hub felügyeleti API-kkal programozott módon konfigurálhatja a fájlfeltöltéseket.

Ha a portált használja, a konfiguráció során létrehozhat egy tárfiókot és egy tárolót. Egyéb esetben tárfiók létrehozásához lásd : Tárfiók létrehozása az Azure Storage dokumentációjában. Miután rendelkezik tárfiókjával, megtudhatja, hogyan hozhat létre blobtárolót az Azure Blob Storage rövid útmutatóiban. Az Azure IoT Hub alapértelmezés szerint kulcsalapú hitelesítést használ az Azure Storage-hoz való csatlakozáshoz és engedélyezéshez. A felhasználó által hozzárendelt vagy rendszer által hozzárendelt felügyelt identitásokat is konfigurálhatja az Azure IoT Hub azure Storage-beli hitelesítéséhez. A felügyelt identitások biztonságos módon biztosítják az Azure-szolgáltatásokat egy automatikusan felügyelt identitással a Microsoft Entra-azonosítóban. A felügyelt identitások konfigurálásáról a felügyelt identitások IoT Hub-támogatásának A fájlfeltöltés konfigurálása felügyelt identitásokkal című szakaszában olvashat.

A fájlfeltöltésre az Azure Storage tűzfalbeállításai vonatkoznak. A hitelesítési konfiguráció alapján gondoskodnia kell arról, hogy az eszközök kommunikálni tudjanak az Azure Storage-ral.

Számos más beállítás is szabályozza a fájlfeltöltések és a fájlfeltöltési értesítések viselkedését. Az alábbi szakaszok az összes elérhető beállítást felsorolják. Attól függően, hogy az Azure Portalt, az Azure CLI-t, a PowerShellt vagy a felügyeleti API-kat használja-e a fájlfeltöltések konfigurálásához, előfordulhat, hogy néhány beállítás nem érhető el. Győződjön meg arról, hogy az enableFileUploadNotifications beállítást adja meg, ha a fájlfeltöltés befejezésekor értesítéseket szeretne küldeni a háttérszolgáltatásoknak.

Az Iot Hub tárolási és hitelesítési beállításai

Az alábbi beállítások egy tárfiókot és tárolót társítanak az IoT Hubhoz, és szabályozják, hogy a központ hogyan hitelesít az Azure Storage-ral. Ezek a beállítások nem befolyásolják az eszközök Azure Storage-ral való hitelesítését. Az eszközök mindig az IoT Hubról lekért SAS URI-ban bemutatott SAS-jogkivonattal hitelesítik magukat.

Property Leírás Tartomány és alapértelmezett
storageEndpoints.$default.authenticationType Szabályozza, hogy az IoT Hub hogyan hitelesít az Azure Storage-ral. A lehetséges értékek keyBased és identityBased. Alapértelmezett: keyBased.
storageEndpoints.$default.connectionString A kapcsolati sztring az Azure Storage-fiókba a fájlfeltöltésekhez. Alapértelmezett: Üres sztring.
storageEndpoints.$default.containerName Annak a tárolónak a neve, amelybe fájlokat szeretne feltölteni. Alapértelmezett: Üres sztring.
storageEndpoints.$default.identity Az identitásalapú hitelesítéshez használandó felügyelt identitás. A lehetséges értékek [system] a rendszer által hozzárendelt felügyelt identitás vagy egy felhasználó által hozzárendelt felügyelt identitás erőforrás-azonosítója. Az érték nem kulcsalapú hitelesítéshez használatos. Alapértelmezett: null.

Fájlfeltöltési beállítások

Az alábbi beállítások szabályozzák a fájlfeltöltéseket az eszközről.

Property Leírás Tartomány és alapértelmezett
storageEndpoints.$default.ttlAsIso8601 Alapértelmezett TTL az IoT Hub által létrehozott SAS URI-khoz. ISO_8601 intervallum legfeljebb 48 óra (legalább egy perc). Alapértelmezett: egy óra.

Fájlfeltöltési értesítés beállításai

Az alábbi beállítások szabályozzák a fájlfeltöltési értesítéseket a háttérszolgáltatásokba.

Property Leírás Tartomány és alapértelmezett
enableFileUploadNotifications Azt szabályozza, hogy a fájlfeltöltési értesítések a fájlértesítések végpontjára legyenek-e írva. Bool. Alapértelmezett: Hamis.
fileNotifications.ttlAsIso8601 Alapértelmezett TTL fájlfeltöltési értesítésekhez. ISO_8601 intervallum legfeljebb 48 óra (legalább egy perc). Alapértelmezett: egy óra.
fileNotifications.lockDuration A fájlfeltöltési értesítések várólistájának zárolási időtartama. 5-300 másodperc. Alapértelmezett: 60 másodperc.
fileNotifications.maxDeliveryCount A fájlfeltöltési értesítési üzenetsor maximális kézbesítési száma. 1 és 100 között. Alapértelmezett: 10.

Fájlfeltöltés SDK használatával

Az alábbi útmutatók részletes útmutatást nyújtanak a fájlok Azure IoT-eszköz- és szolgáltatási SDK-k használatával történő feltöltéséhez. Az útmutatók bemutatják, hogyan társíthat tárfiókot egy IoT Hubhoz az Azure Portal használatával. Az útmutatók kódrészleteket is tartalmaznak, vagy olyan mintákra hivatkoznak, amelyek végigvezetik a feltöltésen.

Útmutató Példa eszköz SDK-ra Példa a Service SDK-ra
.NET Igen Igen
Java Igen Igen
Node.js Igen Igen
Python Igen Nem (nem támogatott)

Megjegyzés:

A C-eszköz SDK egyetlen hívást használ az eszközügyfélen a fájlfeltöltések végrehajtásához. További információ: IoTHubDeviceClient_UploadToBlobAsync() és IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync(). Ezek a függvények egyetlen hívásban hajtják végre a fájlfeltöltés minden aspektusát: a feltöltés kezdeményezését, a fájl Azure Storage-ba való feltöltését, valamint az IoT Hub értesítését, amikor befejeződik. Ez az interakció azt jelenti, hogy az eszköz által az IoT Hubbal való kommunikációhoz használt protokollon kívül az eszköznek HTTPS-en keresztül is kommunikálnia kell az Azure Storage-ral, mivel ezek a függvények hívásokat intéznek az Azure Storage API-khoz.

Eszköz: Fájlfeltöltés inicializálása

Az eszköz meghívja a Create File Upload SAS URI REST API-t vagy az azzal egyenértékű API-t az egyik eszköz SDK-jában a fájlfeltöltés kezdeményezéséhez.

Támogatott protokollok: HTTPS
Végpont: {iot hub}.azure-devices.net/devices/{deviceId}/files
Metódus: POST

{
    "blobName":"myfile.txt"
}
Property Leírás
blobName Annak a blobnak a neve, amely a SAS URI-t hozza létre.

Az IoT Hub egy korrelációs azonosítóval és egy SAS URI azon elemeivel válaszol, amelyeket az eszköz az Azure Storage-ral való hitelesítéshez használhat. Ez a válasz a cél IoT Hub szabályozási korlátaira és eszközenkénti feltöltési korlátaira vonatkozik.

{
    "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 Leírás
correlationId Annak az eszköznek az azonosítója, amelyet a fájlfeltöltés teljes értesítésének az IoT Hubba való küldésekor használ.
Hostname Az Azure Storage-fiók állomásneve az IoT Hubon konfigurált tárfiókhoz
containerName Az IoT Hubon konfigurált blobtároló neve.
blobName Az a hely, ahol a blob a tárolóban lesz tárolva. A név formátuma a következő: {device ID of the device making the request}/{blobName in the request}
sasToken Sas-jogkivonat, amely olvasási-írási hozzáférést biztosít a blobon az Azure Storage-nal. A jogkivonatot az IoT Hub hozza létre és írja alá.

Amikor megkapja a választ, az eszköz:

  • Menti a korrelációs azonosítót, hogy a fájl feltöltése teljes értesítésben szerepeljen az IoT Hubra a feltöltés befejezésekor.

  • A többi tulajdonsággal létrehoz egy SAS URI-t annak a blobnak, amelyet az Azure Storage-ral való hitelesítéshez használ. Az SAS URI tartalmazza a kért blob erőforrás-URI-jának és az SAS-jogkivonatnak az erőforrás-URI-t. A következő formában történik: https://{hostName}/{containerName}/{blobName}{sasToken} (A sasToken válasz tulajdonsága egy bevezető "?" karaktert tartalmaz.) A kapcsos zárójelek nem szerepelnek a kapcsos zárójelben.

    Az előző mintában visszaadott értékek esetében például az SAS URI a következő: 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

    Az SAS URI-val és SAS-jogkivonattal kapcsolatos további információkért lásd : Szolgáltatás SAS létrehozása az Azure Storage dokumentációjában.

Eszköz: Fájl feltöltése Azure Storage API-k használatával

Az eszköz az Azure Blob Storage REST API-jait vagy az azzal egyenértékű Azure Storage SDK API-kat használja a fájl Azure Storage-blobba való feltöltéséhez.

Támogatott protokollok: HTTPS

Az alábbi példa egy Kis blokkblob létrehozására vagy frissítésére vonatkozó Put Blob-kérést mutat be. Figyelje meg, hogy a kéréshez használt URI az IoT Hub által az előző szakaszban visszaadott SAS URI. A x-ms-blob-type fejléc azt jelzi, hogy ez a kérés egy blokkblobhoz tartozik. Ha a kérés sikeres, az Azure Storage egy 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

Az Azure Storage API-k használata meghaladja a jelen cikk hatókörét. Az ebben a szakaszban korábban hivatkozott Azure Blob Storage REST API-k mellett az első lépésekhez az alábbi dokumentációt is megismerheti:

Eszköz: Az IoT Hub értesítése a befejezett fájlfeltöltésről

Az eszköz meghívja az Update File Upload Status REST API-t vagy az azzal egyenértékű API-t az egyik eszköz SDK-jában a fájlfeltöltés befejezésekor. Az eszköznek frissítenie kell a fájlfeltöltés állapotát az IoT Hub használatával, függetlenül attól, hogy a feltöltés sikeres vagy sikertelen.

Támogatott protokollok: HTTPS
Végpont: {iot hub}.azure-devices.net/devices/{deviceId}/files/notifications
Metódus: POST

{
    "correlationId": "MjAyMTA3MzAwNjIxXzBiNjgwOGVkLWZjNzQtN...MzYzLWRlZmI4OWQxMzdmNF9teWZpbGUudHh0X3ZlcjIuMA==",
    "isSuccess": true,
    "statusCode": 200,
    "statusDescription": "File uploaded successfully"
}
Property Leírás
correlationId A kezdeti SAS URI-kérelemben kapott korrelációs azonosító.
isSuccess Logikai érték, amely jelzi, hogy a fájlfeltöltés sikeres volt-e.
statusCode Egy egész szám, amely a fájlfeltöltés állapotkódját jelöli. Általában három számjegy; például 200 vagy 201.
statusDescription A fájlfeltöltés állapotának leírása.

Amikor teljes körű fájlfeltöltési értesítést kap az eszközről, az IoT Hub:

  • Fájlfeltöltési értesítést aktivál a háttérszolgáltatásoknak, ha a fájlfeltöltési értesítések konfigurálva vannak.

  • Felszabadítja a fájlfeltöltéshez társított erőforrásokat. Ha az IoT Hub nem kap értesítést, az erőforrásokat mindaddig fenntartja, amíg a feltöltéshez társított SAS URI élettartam (TTL) el nem jár.

Szolgáltatás: Fájlfeltöltési értesítések

Ha a fájlfeltöltési értesítések engedélyezve vannak az IoT Hubon, a központ egy értesítési üzenetet hoz létre a háttérszolgáltatások számára, amikor értesítést kap egy eszközről a fájlfeltöltés befejezéséről. Az IoT Hub szolgáltatással elérhető végponton keresztül küldi el ezeket a fájlfeltöltési értesítéseket. A fájlfeltöltési értesítések fogadási szemantikája ugyanaz, mint a felhőből az eszközre irányuló üzenetek esetében, és ugyanazzal az üzenet életciklusával rendelkezik. A szolgáltatás SDK-k api-kat fednek fel a fájlfeltöltési értesítések kezeléséhez.

Támogatott protokollok AMQP, AMQP-WS
Végpont: {iot hub}.azure-devices.net/messages/servicebound/fileuploadnotifications
GET metódus

A fájlfeltöltési értesítési végpontról lekért összes üzenet egy JSON-rekord:

{
    "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 Leírás
enqueuedTimeUtc Az értesítés létrehozásának idejét jelző időbélyeg.
deviceId A fájlt feltöltő eszköz eszközazonosítója.
blobUri A feltöltött fájl URI-ja.
blobName A feltöltött fájl neve. A név formátuma a következő: {device ID of the device}/{name of the blob}
lastUpdatedTime A fájl utolsó frissítésének idejét jelző időbélyeg.
blobSizeInBytes Egy egész szám, amely a feltöltött fájl méretét jelöli bájtban.

A szolgáltatások értesítéseket használhatnak a feltöltések kezeléséhez. Elindíthatják például a blobadatok saját feldolgozását, a blobadatok más Azure-szolgáltatások használatával történő feldolgozását, vagy naplózhatják a fájlfeltöltési értesítést későbbi felülvizsgálat céljából.

Következő lépések