使用 Azure IoT 中樞 將檔案從您的裝置上傳至雲端（.NET）

  • 發行項

本文示範如何使用 Azure IoT、.NET 裝置和服務 SDK，發送 IoT 中樞的上傳功能，上傳檔案至 Azure blob 儲存體。

將遙測從裝置傳送至 IoT 中樞快速入門和使用 IoT 中樞傳送雲端到裝置的訊息文章說明 IoT 中樞基本的裝置到雲端和雲端到裝置傳訊功能。 使用 IoT 中樞設定訊息路由教學課程示範在 Microsoft Azure Blob 儲存體中，可靠地儲存裝置到雲端訊息的方式。 不過，在某些情況下，您無法輕易地將裝置所傳送的資料對應至 IoT 中樞接受且相對較小的裝置到雲端的訊息。 例如：

  • 影片
  • 包含映像的大型檔案
  • 取樣高頻率的震動資料
  • 某種經前置處理過的資料

這些檔案通常會使用工具 (例如 Azure Data Factory 或 Hadoop 堆疊) 在雲端中進行批次處理。 當您需要從裝置上傳檔案時，您仍然可以使用安全可靠的 IoT 中樞。 本文會說明如何操作。

在本文結尾，您會執行兩個 .NET 主控台應用程式：

  • FileUploadSample。 這個裝置應用程式可以使用 IoT 中樞提供的 SAS URI，將檔案上傳到儲存體。 此範例來自您在必要條件中下載的 Azure IoT C# SDK 存放庫。

  • ReadFileUploadNotification： 這個服務應用程式會接收來自 IoT 中樞的檔案上傳通知。 您建立此應用程式。

注意

IoT 中樞透過 Azure IoT 裝置 SDK 來支援許多裝置平台和語言 (包括 C、Java、Python 及 JavaScript)。 若要了解如何將裝置連線至 Azure IoT 中樞，請參閱 Azure IoT 開發人員中心。

重要

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

必要條件

  • 一個 IoT 中樞。 使用 CLI 或 Azure 入口網站建立一個。

  • 已註冊的裝置。 在 Azure 入口網站中註冊一個。

  • 您在本文中執行的範例應用程式使用 C# 與.NET Core 撰寫。

    從 .NET 下載適用於多種平台的 .NET Core SDK。

    您可以使用下列命令，確認開發機器上 .NET Core SDK 目前的版本：

    dotnet --version

  • 從下載範例下載 Azure IoT C# SDK，然後將 ZIP 封存解壓縮。

  • 應該在您的防火牆中開放連接埠 8883。 本文中的範例會使用 MQTT 通訊協定，其會透過連接埠 8883 進行通訊。 某些公司和教育網路環境可能會封鎖此連接埠。 如需此問題的詳細資訊和解決方法，請參閱連線至 IoT 中樞 (MQTT)。

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

如果要從裝置上傳檔案，您必須擁有 Azure 儲存體帳戶及與 IoT 中樞相關聯的 Azure Blob 儲存體容器。 當您將儲存體帳戶和容器與您的 IoT 中樞建立關聯後，IoT 中樞可以在裝置要求時提供 SAS URI 的元素。 接著裝置可以使用這些元素來建構 SAS URI，其用來向 Azure 儲存體進行驗證，並將檔案上傳至 blob 容器。

若要將 Azure 儲存體帳戶與 IoT 中樞產生關聯：

  1. 請在 [中樞設定] 底下，選取 IoT 中樞左窗格中的 [檔案上傳]。

    顯示從入口網站選取檔案上傳設定的螢幕快照。

  2. 在 [檔案上傳] 窗格中，選取 [Azure 儲存體容器]。 在本文中，建議您將儲存體帳戶及 IoT 中樞設為相同區域。

    • 如果您已經有想要使用的儲存體帳戶，請從清單中選取。

    • 若要建立新的儲存體帳戶，請選取 [+ 儲存體帳戶]。 提供儲存體帳戶的名稱，確定 [位置] 設為與 IoT 中樞相同的區域，然後選取 [確定]。 新帳戶會建立在與 IoT 中樞相同的資源群組中。 部署完成時，請從清單中選取儲存體帳戶。

    選取儲存體帳戶後，[容器] 窗格隨即開啟。

  3. 在 [容器] 窗格中，選取 blob 容器。

    • 如果您已經有要使用的 blob 容器，請從清單中選取，然後按一下 [選取]。

    • 若要建立新的 blob 容器，請選取 [+ 容器]。 提供新容器的名稱。 針對本文的目的，您可以將所有其他欄位保留為預設值。 選取 建立。 部署完成時，從清單中選取容器，然後按一下 [選取]。

  4. 返回 [檔案上傳] 窗格，確定檔案通知已設為 [開啟]。 您可以保留所有其他設定的預設值。 選取 [儲存]，並等待設定完成，再繼續進行下一小節。

    顯示入口網站中確認檔案上傳設定的螢幕快照。

如需如何建立 Azure 儲存體帳戶的詳細指示，請參閱 [建立儲存體帳戶]。 如需如何將儲存體帳戶及 blob 容器與 IoT 中樞建立關聯的詳細指示，請參閱 [使用 Azure 入口網站設定檔案上傳]。

從裝置應用程式上傳檔案

在此文章中，您會使用之前從 Azure IoT C# SDK 存放庫下載的範例作為裝置應用程式。 您可以使用 Visual Studio、Visual Studio Code 或您選擇的文字編輯器來開啟下列檔案。

範例位於您將 Azure IoT C# SDK 解壓縮所在資料夾中的 azure-iot-sdk-csharp/iothub/device/samples/getting started/FileUploadSample 上。

檢查 FileUpLoadSample.cs 中的程式碼。 這個檔案包含主要範例邏輯。 建立 IoT 中樞裝置用戶端後，它會遵循從裝置上傳檔案的標準三部分程序：

  1. 程式碼會呼叫裝置用戶端上的 GetFileUploadSasUriAsync 方法，以從 IoT 中樞取得 SAS URI：

    var fileUploadSasUriRequest = new FileUploadSasUriRequest
{
    BlobName = fileName
};

// Lines removed for clarity

FileUploadSasUriResponse sasUri = await _deviceClient.GetFileUploadSasUriAsync(fileUploadSasUriRequest);
Uri uploadUri = sasUri.GetBlobUri();

  2. 這個程式碼會使用 SAS URI 將檔案上傳至 Azure 儲存體。 在這個範例中，它會使用 SAS URI 來建立 Azure 儲存體區塊 Blob 用戶端，並上傳檔案：

    var blockBlobClient = new BlockBlobClient(uploadUri);
await blockBlobClient.UploadAsync(fileStreamSource, new BlobUploadOptions());

  3. 該程式碼會通知 IoT 中樞上傳已完成。 這會告訴 IoT 中樞，其可以釋放與上傳相關聯的資源 (SAS URI)。 如果已啟用檔案上傳通知，IoT 中樞會將通知訊息傳送至後端服務。

    var successfulFileUploadCompletionNotification = new FileUploadCompletionNotification
{
    // Mandatory. Must be the same value as the correlation id returned in the sas uri response
    CorrelationId = sasUri.CorrelationId,

    // Mandatory. Will be present when service client receives this file upload notification
    IsSuccess = true,

    // Optional, user defined status code. Will be present when service client receives this file upload notification
    StatusCode = 200,

    // Optional, user-defined status description. Will be present when service client receives this file upload notification
    StatusDescription = "Success"
};

await _deviceClient.CompleteFileUploadAsync(successfulFileUploadCompletionNotification);

如果您檢查 parameter.cs 檔案，您會看到：

  • 這個範例會要求您傳遞採用裝置連接字串的參數 p。

  • 根據預設，該裝置範例會使用 MQTT 通訊協定與IoT 中樞進行通訊。 您可以使用參數 t 來變更這個傳輸通訊協定。 不論此選項為何，Azure Blob 用戶端一律會使用 HTTPS 作為通訊協定來上傳 Azure 記憶體檔案。

取得 IoT 中樞連接字串

在本文中，您將建立後端服務，接收來自 IoT 中樞的檔案上傳通知訊息。 若要接收檔案上傳通知訊息，則服務需要服務連線權限。 根據預設，每個 IoT 中樞都是透過授與此權限且名為服務的共用存取原則所建立。

若要取得服務原則的 IoT 中樞連接字串，請遵循下列步驟：

  1. 在 Azure 入口網站中，選取 [資源群組]。 選取中樞所在的資源群組，然後從資源清單選取中樞。

  2. 在 IoT 中樞的左側窗格中，選取 [共用存取原則]。

  3. 從原則清單中，選取服務原則。

  4. 複製 [主要連接字串] 並儲存該值。

顯示如何在 Azure 入口網站 中從 IoT 中樞 擷取 連接字串 的螢幕快照。

如需 IoT 中樞共用存取原則和權限的詳細資訊，請參閱存取控制及權限。

接收檔案上傳通知

在本節中，您將建立一個 C# 主控台應用程式，接收來自 IoT 中樞的檔案上傳通知訊息。

  1. 開啟命令視窗，並移至您要建立專案的所在資料夾。 建立名為 ReadFileUploadNotifications 的資料夾，並將目錄變更為該資料夾。

    mkdir ReadFileUploadNotification
cd ReadFileUploadNotification

  2. 執行下列命令來建立 C# 主控台專案。 執行命令後，資料夾將包含 Program.cs 檔案和 ReadFileUploadNotification.csproj 檔案。

    dotnet new console --language c#

  3. 執行下列命令，將 Microsoft.Azure.Devices 套件新增至專案檔。 這個套件是 Azure IoT .NET 服務 SDK。

    dotnet add package Microsoft.Azure.Devices

  4. 開啟 Program.cs 檔案，並在檔案的頂端新增下列陳述式：

    using Microsoft.Azure.Devices;

  5. 將下列欄位新增到 Program 類別。 將 {iot hub connection string} 預留位置值取代為先前在 取得 IoT 中樞連接字串內複製的 IoT 中樞連接字串：

    static ServiceClient serviceClient;
static string connectionString = "{iot hub connection string}";

  6. 將下列方法加入至 Program 類別：

    private async static void ReceiveFileUploadNotificationAsync()
{
    var notificationReceiver = serviceClient.GetFileNotificationReceiver();
    Console.WriteLine("\nReceiving file upload notification from service");
    while (true)
    {
        var fileUploadNotification = await notificationReceiver.ReceiveAsync();
        if (fileUploadNotification == null) continue;
        Console.ForegroundColor = ConsoleColor.Yellow;
        Console.WriteLine("Received file upload notification: {0}", 
          string.Join(", ", fileUploadNotification.BlobName));
        Console.ResetColor();
        await notificationReceiver.CompleteAsync(fileUploadNotification);
    }
}

    請注意，此接收模式與用來從裝置應用程式接收雲端到裝置訊息的模式相同。

  7. 最後，將 Main 方法中的行取代成下列內容：

    Console.WriteLine("Receive file upload notifications\n");
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);
ReceiveFileUploadNotificationAsync();
Console.WriteLine("Press Enter to exit\n");
Console.ReadLine();

執行應用程式

現在您已經準備好執行應用程式。

  1. 首先，執行服務應用程式以接收來自 IoT 中樞的檔案上傳通知。 在命令提示字元上，於 ReadFileUploadNotification 資料夾中執行下列命令：

    dotnet restore
dotnet run

    應用程式會啟動並等待 IoT 中樞的檔案上傳通知：

    Receive file upload notifications


Receiving file upload notification from service
Press Enter to exit

  2. 接下來，執行裝置應用程式，將檔案上傳至 Azure 儲存體。 開啟新的命令提示字元，並將資料夾變更為您展開 Azure IoT C# SDK 所在資料夾底下的 azure-iot-sdk-csharp\iothub\device\samples\getting started\FileUploadSample。 執行下列 命令。 將{Your device connection string}第二個命令中的佔位元值取代為您在IoT中樞註冊裝置時看到的裝置 連接字串。

    dotnet restore
dotnet run --p "{Your device connection string}"

    上傳完成後，下列輸出來自裝置應用程式：

      Uploading file TestPayload.txt
  Getting SAS URI from IoT Hub to use when uploading the file...
  Successfully got SAS URI (https://contosostorage.blob.core.windows.net/contosocontainer/MyDevice%2FTestPayload.txt?sv=2018-03-28&sr=b&sig=x0G1Baf%2BAjR%2BTg3nW34zDNKs07p6dLzkxvZ3ZSmjIhw%3D&se=2021-05-04T16%3A40%3A52Z&sp=rw) from IoT Hub
  Uploading file TestPayload.txt using the Azure Storage SDK and the retrieved SAS URI for authentication
  Successfully uploaded the file to Azure Storage
  Notified IoT Hub that the file upload succeeded and that the SAS URI can be freed.
  Time to upload file: 00:00:01.5077954.
  Done.

  3. 請注意，服務應用程式會顯示其已收到的檔案上傳通知：

    Receive file upload notifications


Receiving file upload notification from service
Press Enter to exit

Received file upload notification: myDeviceId/TestPayload.txt

確認檔案上傳

您可以使用入口網站檢視您所設定之儲存體容器中的上傳檔案：

  1. 在 Azure 入口網站中瀏覽至您的儲存體帳戶。

  2. 在儲存體帳戶的左窗格中，選取 [容器]。

  3. 選取您上傳檔案的容器。

  4. 選取以您裝置命名的資料夾。

  5. 選取您上傳檔案的 blob。 在本文中，它是名為 TestPayload.txt 的 blob。

    選取 Azure 入口網站 中上傳檔案的螢幕快照。

  6. 檢視開啟頁面上的 Blob 屬性。 您可以選取 [下載] 以下載檔案，並在本機檢視其內容。

下一步

在本文中，您已學到如何使用 IoT 中樞的檔案上傳功能來簡化從裝置上傳檔案。 您可以閱讀下列文章來繼續探索這個功能：