使用 IoT 中樞上傳檔案

發行項
05/11/2024

在許多情況下，您無法輕易將裝置資料對應至 IoT 中樞接受的較小型裝置到雲端訊息。例如，傳送如影片等大型媒體檔案；或傳送間歇性連線裝置上傳的大型遙測批次，或已彙總和壓縮以節省頻寬。

當您需要從裝置上傳大型檔案時，您仍然可以使用安全可靠的 IoT 中樞。但 IoT 中樞不是透過自身的代理訊息，而是做為相關聯 Azure 儲存體帳戶的發送器。當裝置完成檔案上傳時，IoT 中樞也可以提供通知給後端服務。

如果您需要協助以決定何時要使用報告屬性、裝置到雲端訊息或檔案上傳，請參閱裝置到雲端通訊指導。

重要

在使用 X.509 憑證授權 (CA) 驗證裝置上的檔案上傳功能目前為公開預覽狀態，請務必啟用預覽模式。該功能已在以下裝置上正式發行：搭配 Azure 裝置佈建服務之使用 X.509 指紋驗證或 X.509 憑證證明的裝置。若要深入了解使用 IoT 中樞的 X.509 驗證，請參閱支援的 X.509 憑證。

檔案上傳概觀

IoT 中樞會針對已預先設定的 Blob 容器和已預先設定的 Azure 儲存體帳戶，提供連線裝置的共用存取簽章 (SAS) URI，以協助從連線裝置上傳檔案。使用檔案上傳與 IoT 中樞有三個部分：在 IoT 中樞上預先設定 Azure 儲存體帳戶和 Blob 容器、從裝置上傳檔案，以及通知後端服務完成檔案上傳 (選用)。

使用檔案上傳功能之前，您必須將 Azure 儲存體帳戶和 blob 容器與您的 IoT 中樞建立關聯。您也可以針對設定控制項如何向 Azure 儲存體驗證 IoT 中樞、IoT 中樞向裝置送出之 SAS URI 存留時間 (TTL)，以及將通知檔案上傳通知傳送至後端服務的設定。如需深入了解，請參閱讓 Azure 儲存體帳戶與 IoT 中樞產生關聯。

裝置會遵循三個步驟的程式，將檔案上傳至相關聯的 Blob 容器：

裝置會使用 IoT 中樞起始檔案上傳。它會傳遞要求中的 Blob 名稱，並取得 SAS URI 和傳回中的相互關聯識別碼。 SAS URI 包含 Azure 儲存體的 SAS 權杖，可授與 Blob 容器中要求 Blob 的裝置讀取寫入權限。如需詳細資訊，請參閱裝置：初始化檔案上傳。
裝置會使用 SAS URI 安全呼叫 Azure Blob 儲存體 API，並將檔案上傳至 Blob 容器。如需詳細資訊，請參閱裝置：使用 Azure 儲存體 API 上傳檔案。
檔案上傳完成時，裝置會使用起始上傳時從 IoT 中樞收到的相互關聯識別碼，通知 IoT 中樞完成狀態。如需詳細資訊，請參閱裝置：通知 IoT 中樞已完成的檔案上傳。

後端服務可以訂閱 IoT 中樞服務面向檔案上傳通知端點上的檔案上傳通知。如果您已在 IoT 中樞上啟用這些通知，每當裝置通知中樞已完成檔案上傳時，就會在此端點上傳遞這些通知。服務可以使用這些通知來觸發 Blob 資料的進一步處理。如需詳細資訊，請參閱服務：檔案上傳通知。

Azure IoT 裝置和服務 SDK 完全支援檔案上傳。如需詳細資訊，請參閱使用 SDK 上傳檔案。

檔案上傳配額和限制

IoT 中樞會對可在指定期間起始的檔案上傳數目施加節流限制。閾值是以 IoT 中樞的 SKU 和單位數目為基礎。此外，每個裝置一次只能同時上傳 10 個使用中的檔案。如需詳細資訊，請參閱 IoT 中樞配額和節流。

讓 Azure 儲存體帳戶與 IoT 中樞產生關聯

您必須將 Azure 儲存體帳戶和 blob 容器與您的 IoT 中樞建立關聯，以使用檔案上傳功能。向 IoT 中樞註冊裝置上傳的所有檔案都會移至此容器。若要在 IoT 中樞上設定儲存體帳戶和 Blob 容器，請參閱使用 Azure 入口網站設定 IoT 中樞檔案上傳、使用 Azure CLI 設定 IoT 中樞檔案上傳，或使用 PowerShell 設定 IoT 中樞檔案上傳。您也可以使用 IoT 中樞管理 API，以程式設計的方式設定檔案上傳。

如果您使用入口網站，您可以在設定期間建立儲存體帳戶和容器。否則，若要建立儲存體帳戶，請參閱 Azure 儲存體文件中的建立儲存體帳戶。您擁有儲存體帳戶後，就可以在 Azure Blob 儲存體快速入門中了解如何建立 Blob 容器。依預設，Azure IoT 中樞會使用以金鑰為基礎的驗證，以連結和授權 Azure 儲存體。您也可設定使用者指派或系統指派的受控識別，以驗證 Azure IoT 中樞的 Azure 儲存體。受控識別在 Microsoft Entra ID 中以安全的方式為 Azure 服務提供自動受控的身分識別。若要了解如何設定受控識別，請參閱受控識別的 IoT 中樞支援中的使用受控識別設定檔案上傳一節。

檔案上傳受限於 Azure 儲存體的防火牆設定。根據驗證設定，您必須確定裝置可與 Azure 儲存體進行通訊。

有數個其他設定可控制檔案上傳和檔案上傳通知的行為。下列各節列出所有可用的設定。根據您是否使用 Azure 入口網站、Azure CLI、PowerShell，或管理 API 設定檔案上傳，其中部分設定可能無法使用。如果您想要在檔案上傳完成時，傳送通知至後端服務，請務必設定 enableFileUploadNotifications 設定。

IoT 中樞儲存體和驗證設定

下列設定會將儲存體帳戶和容器與您的 IoT 中樞產生關聯，並控制中樞向 Azure 儲存體進行驗證的方式。這些設定不會影響裝置向 Azure 儲存體進行驗證的方式。裝置始終使用從 IoT 中樞擷取的 SAS URI 中顯示的 SAS 權杖進行驗證。

屬性	說明	範圍和預設值
storageEndpoints.$default.authenticationType	控制 IoT 中樞如何向 Azure 儲存體進行驗證。	可能的值為 keyBased 和 identityBased。預設值：keyBased。
storageEndpoints.$default.connectionString	要用於檔案上傳的 Azure 儲存體帳戶連接字串。	預設值：空字串。
storageEndpoints.$default.containerName	要上傳檔案的容器名稱。	預設值：空字串。
storageEndpoints.$default.identity	用於身分識別型驗證的受控識別。	可能的值為 `[system]` 系統指派的受控識別，或使用者指派受控識別的資源識別碼。此值不會用於金鑰型驗證。預設值：null。

檔案上傳設定

下列設定控制檔案會從裝置上傳。

屬性	說明	範圍和預設值
storageEndpoints.$default.ttlAsIso8601	IoT 中樞所產生的 SAS URI 預設 TTL。	ISO_8601 間隔高達 48 個小時 (最小為一分鐘)。預設值：一小時。

檔案上傳通知設定

下列設定可控制檔案上傳通知至後端服務。

屬性	說明	範圍和預設值
enableFileUploadNotifications	控制是否將檔案上傳通知寫入檔案通知端點。	布林預設值：False。
fileNotifications.ttlAsIso8601	檔案上傳通知的預設 TTL。	ISO_8601 間隔高達 48 個小時 (最小為一分鐘)。預設值：一小時。
fileNotifications.lockDuration	檔案上傳通知佇列的鎖定持續時間。	5 到 300 秒。預設值：60 秒。
fileNotifications.maxDeliveryCount	檔案上傳通知佇列的傳遞計數上限。	1 到 100。預設值：10

使用 SDK 上傳檔案

下列操作指南提供使用 Azure IoT 裝置，和服務 SDK 上傳檔案的完整逐步指示。本指南會示範如何使用 Azure 入口網站建立儲存體帳戶與 IoT 中樞的關聯。本指南也包含程式碼片段，或參考引導您完成上傳的範例。

操作指南	裝置 SDK 範例	服務 SDK 範例
.NET	Yes	Yes
Java	Yes	Yes
Node.js	Yes	Yes
Python	Yes	否 (不支援)

注意

C 裝置 SDK 會在裝置用戶端上使用單一呼叫來執行檔案上傳。如需詳細資訊，請參閱 IoTHubDeviceClient_UploadToBlobAsync() and IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync()。這些函式會在單一呼叫中執行檔案上傳的所有層面：起始上傳、將檔案上傳至 Azure 儲存體，並在完成時通知 IoT 中樞。此互動表示除了裝置用來與 IoT 中樞通訊的任何通訊協定之外，裝置還必須能透過 HTTPS 與 Azure 儲存體進行通訊，因為這些函式會呼叫 Azure 儲存體 API。

裝置：初始化檔案上傳

裝置會呼叫建立檔案上傳 SAS URI REST API，或其中一個裝置 SDK 中的對等 API，以起始檔案上傳。

支援的通訊協定：HTTPS
端點：{iot hub}.azure-devices.net/devices/{deviceId}/files
方法：POST

{
    "blobName":"myfile.txt"
}

屬性	說明
BlobName	要為其產生 SAS URI 的 Blob 名稱。

IoT 中樞回應相互關聯識別碼，以及裝置可用來向 Azure 儲存體進行驗證的 SAS URI 元素。此回應受限於目標 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"
}

屬性	說明
correlationId	傳送檔案上傳完成通知給　IoT 中樞時，裝置要使用的識別碼。
hostName	IoT 中樞上設定之儲存體帳戶的 Azure 儲存體帳戶主機名稱
containerName	IoT 中樞上設定的 Blob 容器名稱。
BlobName	Blob 將儲存在容器中的位置。此名稱採用下列格式：`{device ID of the device making the request}/{blobName in the request}`
sasToken	SAS 權杖，可透過 Azure 儲存體授與 Blob 上的讀取寫入存取權。權杖由 IoT 中樞產生並簽署。

收到回應時，裝置會：

儲存相互關聯識別碼，在檔案上傳完成時，將完整通知包含在 IoT 中樞完成上傳。
使用其他屬性以建構其用來向 Azure 儲存體進行驗證之 Blob 的 SAS URI。 SAS URI 包含所要求 Blob 和 SAS 權杖的資源 URI。其格式如下：https://{hostName}/{containerName}/{blobName}{sasToken} (回應中的 sasToken 屬性包含前置「？」字元。)不包含大括號。

例如，針對上述範例中傳回的值，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

如需 SAS URI 和 SAS 權杖的詳細資訊，請參閱 Azure 儲存體文件中的建立服務 SAS。

裝置：使用 Azure 儲存體 API 上傳檔案

裝置會使用 Azure Blob 儲存體 REST API 或對等的 Azure 儲存體 SDK API，將檔案上傳至 Azure 儲存體中的 Blob。

支援的通訊協定：HTTPS

下列範例顯示放置 Blob 要求，以建立或更新小型區塊 Blob。請注意，用於此要求的 URI 是上一節中 IoT 中樞傳回的 SAS URI。 x-ms-blob-type標頭表示此要求適用於區塊 Blob。如果要求成功，Azure 儲存體會傳回 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

使用 Azure 儲存體 API 超出本文的範圍。除了本節先前連結的 Azure Blob 儲存體 REST API 之外，您也可以探索下列文件以協助您開始使用：

若要深入了解如何在 Azure 儲存體中使用 Blob，請參閱 Azure Blob 儲存體文件。
如需使用 Azure 儲存體用戶端 SDK 上傳 Blob 的相關資訊，請參閱 Azure Blob 儲存體 API 參考。

裝置：通知 IoT 中樞已完成檔案上傳

當裝置完成檔案上傳時，裝置會在其中一個裝置 SDK 中呼叫更新檔案上傳狀態 REST API 或對等的 API。無論上傳成功或失敗，裝置都應該使用　IoT 中樞更新檔案上傳狀態。

支援的通訊協定：HTTPS
端點：{iot hub}.azure-devices.net/devices/{deviceId}/files/notifications
方法：POST

{
    "correlationId": "MjAyMTA3MzAwNjIxXzBiNjgwOGVkLWZjNzQtN...MzYzLWRlZmI4OWQxMzdmNF9teWZpbGUudHh0X3ZlcjIuMA==",
    "isSuccess": true,
    "statusCode": 200,
    "statusDescription": "File uploaded successfully"
}

屬性	說明
correlationId	初始 SAS URI 要求中收到的相互關聯識別碼。
isSuccess	布林值，指出檔案上傳是否成功。
statusCode	整數，表示檔案上傳的狀態程式碼。通常是三位數;例如，200 或 201。
statusDescription	檔案上傳狀態的描述。

從裝置收到檔案上傳完整通知時，IoT 中樞：

如果已設定檔案上傳通知，則會觸發檔案上傳通知至後端服務。
釋放與檔案上傳關聯的資源。若 IoT 中樞未收到通知，其會維護資源，直到 SAS URI 存留時間 (TTL) 與上傳相關聯的時間到期為止。

服務：檔案上傳通知

如果在 IoT 中樞上啟用檔案上傳通知，則您的中樞會在從檔案上傳完成的裝置收到通知時，產生後端服務的通知訊息。 IoT 中樞會透過服務面向端點傳遞這些檔案上傳通知。檔案上傳通知的接收語意與雲端到裝置訊息的接收語意相同，並且具有相同的訊息生命週期。服務 SDK 會公開 API 來處理檔案上傳通知。

支援的通訊協定 AMQP、AMQP-WS
端點：{iot hub}.azure-devices.net/messages/servicebound/fileuploadnotifications
方法 GET

從檔案上傳通知端點擷取的每則訊息是 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"
}

屬性	說明
enqueuedTimeUtc	指出通知建立時間的時間戳記。
deviceId	上傳檔案之裝置的裝置識別碼。
blobUri	上傳檔案的 URI。
BlobName	上傳的檔案名稱。此名稱採用下列格式：`{device ID of the device}/{name of the blob}`
lastUpdatedTime	指出上次更新檔案的時間戳記。
blobSizeInBytes	整數，表示上傳檔案的大小，以位元組為單位。

服務可以使用通知來管理上傳。例如，他們可以觸發自己的 Blob 資料處理、使用其他 Azure 服務觸發 Blob 資料的處理，或記錄檔案上傳通知以供稍後檢閱。

下一步

檔案上傳操作指南
如何在 IoT 中樞上設定檔案上傳
如何在 IoT 中樞上設定受控識別
Azure Blob 儲存體文件
Azure IoT 裝置和服務 SDK 列出各種語言 SDK，可供您在開發與「IoT 中樞」互動的裝置和服務應用程式時使用。

共用方式為