使用 IoT 中樞上傳檔案

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

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

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

檔案上傳概觀

IoT 中樞會針對 Blob 容器和針對從中樞上傳檔案而設定的 Azure 儲存器帳戶，提供個別上傳的共用存取簽章 （SAS） URI，協助從連線裝置上傳檔案。 使用檔案上傳搭配 IoT 中樞 有三個部分：

• 在IoT中樞上設定 Azure 記憶體帳戶和 Blob 容器。
• 從裝置上傳檔案。
• 選擇性地通知後端服務已完成的檔案上傳。

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

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

1. 裝置會使用 IoT 中樞起始檔案上傳。 它會傳遞要求中的 Blob 名稱，並取得 SAS URI 和傳回中的相互關聯識別碼。 SAS URI 包含 Azure 儲存體的 SAS 權杖，可授與 Blob 容器中要求 Blob 的裝置讀取寫入權限。 如需詳細資訊，請參閱裝置：初始化檔案上傳。

2. 裝置會使用 SAS URI 安全呼叫 Azure Blob 儲存體 API，並將檔案上傳至 Blob 容器。 如需詳細資訊，請參閱裝置：使用 Azure 儲存體 API 上傳檔案。

3. 檔案上傳完成時，裝置會使用起始上傳時從 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 IoT 中樞會使用以金鑰為基礎的驗證，以連結和授權 Azure 儲存體。 您也可設定使用者指派或系統指派的受控識別，以驗證 Azure IoT 中樞的 Azure 儲存體。 受控識別在 Microsoft Entra ID 中以安全的方式為 Azure 服務提供自動受控的身分識別。

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

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

IoT 中樞 記憶體和驗證設定

下列設定會將儲存體帳戶和容器與您的 IoT 中樞產生關聯，並控制中樞向 Azure 儲存體進行驗證的方式。 這些設定不會影響裝置向 Azure 儲存體進行驗證的方式。 您仍然需要使用 SAS URI 將裝置連線到記憶體。 現在系統會使用連接字串來產生 SAS URI。

如需配置檔案上傳以使用身分識別型驗證的相關信息，請參閱 使用受控識別來配置檔案上傳。

檔案上傳設定

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

檔案上傳通知設定

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

使用 SDK 上傳檔案

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

裝置：初始化檔案上傳

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

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

{
    "blobName":"myfile.txt"
}

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"
}

收到回應時，裝置會：

• 儲存相互關聯識別碼，在檔案上傳完成時，將完整通知包含在 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"
}

從裝置收到檔案上傳完整通知時，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"
}

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

下一步

• 如何在 IoT 中樞上設定檔案上傳

• 如何在 IoT 中樞上設定受控識別