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

發行項
04/07/2024

本文示範如何使用 Python 執行 IoT 中樞的檔案上傳，將檔案上傳至 Azure blob 儲存體。

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

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

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

在本文結束時，您會執行 Python 主控台應用程式 FileUpload.py，其會使用 Python 裝置 SDK 將檔案上傳至儲存體。

注意

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 憑證。

必要條件

使用中的 Azure 帳戶。 (如果您沒有帳戶，只需要幾分鐘的時間就可以建立免費帳戶。)
一個 IoT 中樞。使用 CLI 或 Azure 入口網站建立一個。
已註冊的裝置。在 Azure 入口網站中註冊一個。
建議使用 Python 3.7 版或更新版本。請務必使用安裝程式所需的 32 位元或 64 位元安裝。在安裝期間出現系統提示時，務必將 Python 新增至平台特有的環境變數。
應該在您的防火牆中開放連接埠 8883。本文中的裝置範例會使用 MQTT 通訊協定，其會透過連接埠 8883 進行通訊。某些公司和教育網路環境可能會封鎖此連接埠。如需此問題的詳細資訊和解決方法，請參閱連線至 IoT 中樞 (MQTT)。

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

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

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

請在 [中樞設定] 底下，選取 IoT 中樞左窗格中的 [檔案上傳]。
在 [檔案上傳] 窗格中，選取 [Azure 儲存體容器]。在本文中，建議您將儲存體帳戶及 IoT 中樞設為相同區域。
- 如果您已經有想要使用的儲存體帳戶，請從清單中選取。
- 若要建立新的儲存體帳戶，請選取 [+ 儲存體帳戶]。提供儲存體帳戶的名稱，確定 [位置] 設為與 IoT 中樞相同的區域，然後選取 [確定]。新帳戶會建立在與 IoT 中樞相同的資源群組中。部署完成時，請從清單中選取儲存體帳戶。
選取儲存體帳戶後，[容器] 窗格隨即開啟。
在 [容器] 窗格中，選取 blob 容器。
- 如果您已經有要使用的 blob 容器，請從清單中選取，然後按一下 [選取]。
- 若要建立新的 blob 容器，請選取 [+ 容器]。提供新容器的名稱。針對本文的目的，您可以將所有其他欄位保留為預設值。選取建立。部署完成時，從清單中選取容器，然後按一下 [選取]。
返回 [檔案上傳] 窗格，確定檔案通知已設為 [開啟]。您可以保留所有其他設定的預設值。選取 [儲存]，並等待設定完成，再繼續進行下一小節。

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

從裝置應用程式上傳檔案

在本節中，您可以建立裝置應用程式來將檔案上傳到 IoT 中樞。

在命令提示字元中，執行下列命令以安裝 azure-iot-device 套件。您可以使用此套件來協調 IoT 中樞的檔案上傳。
```
pip install azure-iot-device
```
在命令提示字元中，執行下列命令以安裝 azure.storage.blob 套件。您可以使用此套件來執行檔案上傳。
```
pip install azure.storage.blob
```
建立您將上傳至 blob 儲存體的測試檔案。
使用文字編輯器，在工作資料夾中建立 FileUpload.py 檔案。

在 FileUpload.py 檔案開頭處新增下列 import 陳述式和變數。

import os
from azure.iot.device import IoTHubDeviceClient
from azure.core.exceptions import AzureError
from azure.storage.blob import BlobClient

CONNECTION_STRING = "[Device Connection String]"
PATH_TO_FILE = r"[Full path to local file]"

在您的檔案中，將 [Device Connection String] 更換為您 IoT 中樞裝置的連接字串。將 [Full path to local file] 更換為用來測試所建立檔案的路徑，或更換為您想要上傳的任何裝置檔案。

建立函式以將檔案上傳至 blob 儲存體：

def store_blob(blob_info, file_name):
    try:
        sas_url = "https://{}/{}/{}{}".format(
            blob_info["hostName"],
            blob_info["containerName"],
            blob_info["blobName"],
            blob_info["sasToken"]
        )

        print("\nUploading file: {} to Azure Storage as blob: {} in container {}\n".format(file_name, blob_info["blobName"], blob_info["containerName"]))

        # Upload the specified file
        with BlobClient.from_blob_url(sas_url) as blob_client:
            with open(file_name, "rb") as f:
                result = blob_client.upload_blob(f, overwrite=True)
                return (True, result)

    except FileNotFoundError as ex:
        # catch file not found and add an HTTP status code to return in notification to IoT Hub
        ex.status_code = 404
        return (False, ex)

    except AzureError as ex:
        # catch Azure errors that might result from the upload operation
        return (False, ex)

此函式會剖析傳入的 blob_info 結構，以建立用來初始化 azure.storage.blob.BlobClient 的 URL。然後使用此用戶端將您的檔案上傳至 Azure blob 儲存體。

新增下列程式碼以連線用戶端並上傳檔案：

def run_sample(device_client):
    # Connect the client
    device_client.connect()

    # Get the storage info for the blob
    blob_name = os.path.basename(PATH_TO_FILE)
    storage_info = device_client.get_storage_info_for_blob(blob_name)

    # Upload to blob
    success, result = store_blob(storage_info, PATH_TO_FILE)

    if success == True:
        print("Upload succeeded. Result is: \n") 
        print(result)
        print()

        device_client.notify_blob_upload_status(
            storage_info["correlationId"], True, 200, "OK: {}".format(PATH_TO_FILE)
        )

    else :
        # If the upload was not successful, the result is the exception object
        print("Upload failed. Exception is: \n") 
        print(result)
        print()

        device_client.notify_blob_upload_status(
            storage_info["correlationId"], False, result.status_code, str(result)
        )

def main():
    device_client = IoTHubDeviceClient.create_from_connection_string(CONNECTION_STRING)

    try:
        print ("IoT Hub file upload sample, press Ctrl-C to exit")
        run_sample(device_client)
    except KeyboardInterrupt:
        print ("IoTHubDeviceClient sample stopped")
    finally:
        # Graceful exit
        device_client.shutdown()


if __name__ == "__main__":
    main()

此程式碼會建立 IoTHubDeviceClient，並使用下列 API 來管理 IoT 中樞的檔案上傳：

get_storage_info_for_blob 會從 IoT 中樞取得您先前建立的連結儲存體帳戶相關資訊。此資訊包括主機名稱、容器名稱、blob 名稱和 SAS 權杖。儲存體資訊會傳遞至上一個步驟中建立的 store_blob 函式，因此該函式中的 BlobClient 可以使用 Azure 儲存體進行驗證。 get_storage_info_for_blob 方法也會傳回 correlation_id，以用於 notify_blob_upload_status 方法。 correlation_id 是 IoT 中樞標記待用 blob 的方式。
notify_blob_upload_status 會向 IoT 中樞通知 blob 儲存體作業的狀態。您可以對其傳遞透過 get_storage_info_for_blob 方法取得的 correlation_id。 IoT 中樞可用其來通知任何可能接聽檔案上傳工作狀態通知的服務。

儲存並關閉 FileUpload.py 檔案。

執行應用程式

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

在工作資料夾的命令提示字元中，執行下列命令：
```
python FileUpload.py
```
下列螢幕擷取畫面顯示 FileUpload 應用程式的輸出：
您可以使用入口網站檢視您所設定之儲存體容器中的上傳檔案：

下一步

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

使用下列連結深入了解 Azure Blob 儲存體：

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

必要條件

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

從裝置應用程式上傳檔案

執行應用程式

下一步

其他資源

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