使用 Azure IoT 中樞將檔案從裝置上傳至雲端

發行項
12/19/2024

本文會示範如何：

使用 IoT 中樞的檔案上傳功能，使用 Azure IoT 裝置和服務 SDK 將檔案上傳至 Azure Blob 儲存體。
通知 IoT 中樞檔案已成功上傳，並建立後端服務，以使用 Azure IoT 服務 SDK 從 IoT 中樞接收檔案上傳通知。

在某些情況下，您無法輕鬆地將裝置所傳送的數據對應到 IoT 中樞接受的相對小型裝置到雲端訊息。 IoT 中樞中的檔案上傳功能可讓您將大型或複雜的數據移至雲端。例如：

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

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

本文旨在補充本文中參考的可執行 SDK 範例。

如需詳細資訊，請參閱

重要

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

必要條件

IoT 中樞。某些 SDK 呼叫需要使用 IoT 中樞主要連接字串，因此請記下該連接字串。
已註冊的裝置。某些 SDK 呼叫需要使用裝置主要連接字串，因此請記下該連接字串。
IoT 中樞 Service Connect 許可權 - 若要接收檔案上傳通知訊息，後端服務需要 Service Connect 許可權。根據預設，每個 IoT 中樞都是透過授與此權限且名為服務的共用存取原則所建立。如需詳細資訊，請參閱連線到IoT中樞。
藉由連結 Azure 儲存體帳戶和 Azure Blob 儲存體容器，在IoT中樞中配置檔案上傳。您可以使用 Azure 入口網站、Azure CLI 或 Azure PowerShell 來設定這些設定。

概觀

本操作說明包含兩個區段：

從裝置應用程式上傳檔案
在後端應用程式中接收檔案上傳通知

從裝置應用程式上傳檔案

本節說明如何使用適用於 .NET 的 Azure IoT SDK 中的 DeviceClient 類別，將檔案從裝置上傳至 IoT 中樞。

請遵循此程式，將檔案從裝置上傳至IoT中樞：

連線至 IoT 中樞
從IoT中樞取得SAS URI
將檔案上傳至 Azure 記憶體
通知IoT中樞檔案上傳狀態

將裝置連線到 IoT 中樞

裝置應用程式可以使用下列方法向 IoT 中樞進行驗證：

X.509 憑證
共用存取金鑰

使用 X.509 憑證進行驗證

若要使用 X.509 憑證將裝置連線到 IoT 中樞：

使用 DeviceAuthenticationWithX509Certificate 建立包含裝置和憑證信息的物件。 DeviceAuthenticationWithX509Certificate 會當做第二個參數傳遞至 DeviceClient.Create （步驟 2）。
使用 DeviceClient.Create 將裝置連線到使用 X.509 憑證 IoT 中樞。

在這裡範例中，會將裝置和憑證資訊填入傳遞至 DeviceClient.Create的物件中。auth DeviceAuthenticationWithX509Certificate

此範例會顯示憑證輸入參數值做為局部變數，以便清楚起見。在生產系統中，將敏感性輸入參數儲存在環境變數或其他更安全的儲存位置。例如，使用 Environment.GetEnvironmentVariable("HOSTNAME") 來讀取主機名環境變數。

RootCertPath = "~/certificates/certs/sensor-thl-001-device.cert.pem";
Intermediate1CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate1.cert.pem";
Intermediate2CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate2.cert.pem";
DevicePfxPath = "~/certificates/certs/sensor-thl-001-device.cert.pfx";
DevicePfxPassword = "1234";
DeviceName = "MyDevice";
HostName = "xxxxx.azure-devices.net";

var chainCerts = new X509Certificate2Collection();
chainCerts.Add(new X509Certificate2(RootCertPath));
chainCerts.Add(new X509Certificate2(Intermediate1CertPath));
chainCerts.Add(new X509Certificate2(Intermediate2CertPath));
using var deviceCert = new X509Certificate2(DevicePfxPath, DevicePfxPassword);
using var auth = new DeviceAuthenticationWithX509Certificate(DeviceName, deviceCert, chainCerts);

using var deviceClient = DeviceClient.Create(
    HostName,
    auth,
    TransportType.Amqp);

如需憑證驗證的詳細資訊，請參閱：

程式碼範例

如需裝置 X.509 憑證驗證的工作範例，請參閱：

使用共用存取金鑰進行驗證

呼叫 CreateFromConnectionString 以連線到裝置。傳遞裝置主要連接字串。

AMQP 是預設傳輸通訊協定。

static string connectionString = "{device primary connection string}";
deviceClient = DeviceClient.CreateFromConnectionString(connectionString);

從IoT中樞取得SAS URI

呼叫 GetFileUploadSasUriAsync 以取得檔案上傳詳細數據。 SAS URI 會在下一個步驟中使用，將檔案從裝置上傳至 Blob 記憶體。

const string filePath = "TestPayload.txt";
using var fileStreamSource = new FileStream(filePath, FileMode.Open);
var fileName = Path.GetFileName(fileStreamSource.Name);
var fileUploadSasUriRequest = new FileUploadSasUriRequest
{
    BlobName = fileName
};

FileUploadSasUriResponse sasUri = await _deviceClient.GetFileUploadSasUriAsync(fileUploadSasUriRequest, System.Threading.CancellationToken cancellationToken = default);
Uri uploadUri = sasUri.GetBlobUri();

將檔案上傳至 Azure 記憶體

若要將檔案上傳至 Azure 記憶體：

建立 blockBlobClient 物件，並傳遞檔案上傳 URI。
使用 UploadAsync 方法將檔案上傳至 Blob 記憶體，並傳遞 SAS URI。您可以選擇性地新增 Blob 上傳選項和取消令牌參數。

Azure Blob 用戶端一律會使用 HTTPS 作為通訊協定，將檔案上傳至 Azure 儲存體。

在此範例中，BlockBlobClient會傳遞 SAS URI 來建立 Azure 儲存體區塊 Blob 用戶端，並上傳檔案：

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

通知IoT中樞檔案上傳狀態

使用 CompleteFileUploadAsync 通知 IoT 中樞裝置用戶端已完成上傳，並傳遞 FileUploadCompletionNotification 物件。旗 IsSuccess 標會指出上傳是否成功。收到通知后，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);

SDK 檔案上傳範例

SDK 包含此檔案上傳範例。

在後端應用程式中接收檔案上傳通知

您可以建立後端服務，以接收來自IoT中樞的檔案上傳通知訊息。

ServiceClient 類別包含服務可用來接收檔案上傳通知的方法。

新增服務 NuGet 套件

後端服務應用程式需要 Microsoft.Azure.Devices NuGet 套件。

連線至 IoT 中樞

您可以使用下列方法將後端服務連線到 IoT 中樞：

共用存取原則
Microsoft Entra

重要

本文包含使用共用存取簽章連線至服務的步驟。此驗證方法方便進行測試和評估，但使用 Microsoft Entra ID 或受控識別向服務進行驗證是更安全的方法。若要深入了解，請參閱安全性最佳做法 > 雲端安全性。

使用共用存取原則進行連線

使用 CreateFromConnectionString 將後端應用程式連線到裝置。您的應用程式需要 服務連線 許可權。提供此共用存取原則連接字串做為的參數。fromConnectionString 如需共用存取原則的詳細資訊，請參閱使用共用存取簽章控制對 IoT 中樞的存取。

例如：

using Microsoft.Azure.Devices;
static ServiceClient serviceClient;
static string connectionString = "{Shared access policy connection string}";
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);

使用 Microsoft Entra 進行連線

使用 Microsoft Entra 的後端應用程式必須先成功驗證並取得安全性令牌認證，才能連線到 IoT 中樞。此令牌會傳遞至 IoT 中樞連接方法。如需設定和使用 IoT 中樞 Microsoft Entra 的一般資訊，請參閱使用 Microsoft Entra 識別符控制對 IoT 中樞的存取。

設定 Microsoft Entra 應用程式

您必須設定已針對您慣用的驗證認證設定Microsoft Entra 應用程式。應用程式包含參數，例如後端應用程式用來驗證的客戶端密碼。可用的應用程式驗證群組態如下：

用戶端密碼
[MSSQLSERVER 的通訊協定內容]
同盟身分識別認證

Microsoft Entra 應用程式可能需要特定角色許可權，視執行的作業而定。例如，需要 IoT 中樞對應項參與者，才能對 IoT 中樞裝置和模組對應項啟用讀取和寫入存取權。如需詳細資訊，請參閱使用 Azure RBAC 角色指派來管理對 IoT 中樞的存取權。

如需設定 Microsoft Entra 應用程式的詳細資訊，請參閱快速入門：使用 Microsoft 身分識別平台註冊應用程式。

使用 DefaultAzureCredential 進行驗證

使用 Microsoft Entra 來驗證後端應用程式最簡單的方式是使用 DefaultAzureCredential，但建議在生產環境中使用不同的方法，包括特定TokenCredential或剖析。ChainedTokenCredential 為了簡單起見，本節說明使用 DefaultAzureCredential 和用戶端密碼的驗證。如需使用 DefaultAzureCredential之優缺點的詳細資訊，請參閱 DefaultAzureCredential 的使用指引。

DefaultAzureCredential 支援不同的驗證機制，並根據執行中的環境來判斷適當的認證類型。它會嘗試依序使用多個認證類型，直到找到有效的認證為止。

Microsoft Entra 需要下列 NuGet 套件和對應的 using 語句：

Azure.Core
Azure.Identity

using Azure.Core;
using Azure.Identity;

在此範例中，Microsoft Entra 應用程式註冊客戶端密碼、用戶端標識碼和租使用者標識元會新增至環境變數。這些環境變數是用來 DefaultAzureCredential 驗證應用程式。成功Microsoft Entra 驗證的結果是傳遞至 IoT 中樞連線方法的安全性令牌認證。

string clientSecretValue = "xxxxxxxxxxxxxxx";
string clientID = "xxxxxxxxxxxxxx";
string tenantID = "xxxxxxxxxxxxx";

Environment.SetEnvironmentVariable("AZURE_CLIENT_SECRET", clientSecretValue);
Environment.SetEnvironmentVariable("AZURE_CLIENT_ID", clientID);
Environment.SetEnvironmentVariable("AZURE_TENANT_ID", tenantID);

TokenCredential tokenCredential = new DefaultAzureCredential();

接著，產生的 TokenCredential 可以傳遞給任何接受 Microsoft Entra 認證的 SDK 用戶端的連線至 IoT 中樞方法：

在此範例中， TokenCredential 會傳遞至 ServiceClient.Create 以建立 ServiceClient 連接物件。

string hostname = "xxxxxxxxxx.azure-devices.net";
using var serviceClient = ServiceClient.Create(hostname, tokenCredential, TransportType.Amqp);

在此範例中， TokenCredential 會傳遞至 RegistryManager.Create 以建立 RegistryManager 物件。

string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);

程式碼範例

如需Microsoft Entra 服務驗證的運作範例，請參閱角色型驗證範例。

接收檔案上傳通知

若要接收檔案上傳通知：

建立 CancellationToken。
呼叫 GetFileNotificationReceiver 以建立通知接收者。
搭配 ReceiveAsync 使用循環來等候檔案上傳通知。

例如：

// Define the cancellation token
CancellationTokenSource source = new CancellationTokenSource();
CancellationToken token = source.Token;

// Create a notification receiver
var notificationReceiver = serviceClient.GetFileNotificationReceiver();
Console.WriteLine("\nReceiving file upload notification from service");

// Check for file upload notifications
while (true)
{
    var fileUploadNotification = await notificationReceiver.ReceiveAsync(token);
    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);
}

SDK 檔案上傳接收者範例

SDK 包含此檔案上傳接收者範例。

概觀

本操作說明包含兩個區段：

從裝置應用程式上傳檔案
在後端應用程式中接收檔案上傳通知

從裝置應用程式上傳檔案

本節說明如何使用適用於 Java 的 Azure IoT SDK 的 DeviceClient 類別，將檔案從裝置上傳至 IoT 中樞。

請遵循此程式，將檔案從裝置上傳至IoT中樞：

將裝置連線至 IoT 中樞
從IoT中樞取得SAS URI
將檔案上傳至 Azure 儲存體
將檔案上傳狀態通知傳送至IoT中樞

將裝置連線到 IoT 中樞

裝置應用程式可以使用下列方法來向 IoT 中樞進行驗證：

X.509 憑證
共用存取金鑰

使用 X.509 憑證進行驗證

若要使用 X.509 憑證將裝置連線到 IoT 中樞：

使用 buildSSLContext 建置 SSLContext 物件。
將 SSLContext 資訊新增至 ClientOptions 物件。
使用ClientOptions資訊呼叫 DeviceClient 以建立裝置對 IoT 中樞連線。

此範例會顯示憑證輸入參數值做為局部變數，以便清楚起見。在生產系統中，將敏感性輸入參數儲存在環境變數或其他更安全的儲存位置。例如，使用 Environment.GetEnvironmentVariable("PUBLICKEY") 來讀取公鑰憑證字串環境變數。

private static final String publicKeyCertificateString =
        "-----BEGIN CERTIFICATE-----\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "-----END CERTIFICATE-----\n";

//PEM encoded representation of the private key
private static final String privateKeyString =
        "-----BEGIN EC PRIVATE KEY-----\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "-----END EC PRIVATE KEY-----\n";

SSLContext sslContext = SSLContextBuilder.buildSSLContext(publicKeyCertificateString, privateKeyString);
ClientOptions clientOptions = ClientOptions.builder().sslContext(sslContext).build();
DeviceClient client = new DeviceClient(connString, protocol, clientOptions);

如需憑證驗證的詳細資訊，請參閱：

程式碼範例

如需裝置 X.509 憑證驗證的工作範例，請參閱：

使用共用存取金鑰進行驗證

檔案上傳作業一律使用 HTTPS，但 DeviceClient 可以定義遙測、裝置方法和裝置對應項等其他服務的 IotHubClientProtocol。

IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;

使用裝置主要連接字串具現化 DeviceClient 以連線到裝置。

String connString = "{IoT hub connection string}";
DeviceClient client = new DeviceClient(connString, protocol);

從IoT中樞取得SAS URI

呼叫 getFileUploadSasUri 以取得 FileUploadSasUriResponse 物件。

FileUploadSasUriResponse 包含這些方法和傳回值。傳回值可以傳遞至檔案上傳方法。

方法	傳回值
`getCorrelationId()`	相互關聯識別碼
`getContainerName()`	容器名稱
`getBlobName()`	Blob 名稱
`getBlobUri()`	Blob URI

例如：

FileUploadSasUriResponse sasUriResponse = client.getFileUploadSasUri(new FileUploadSasUriRequest(file.getName()));

System.out.println("Successfully got SAS URI from IoT hub");
System.out.println("Correlation Id: " + sasUriResponse.getCorrelationId());
System.out.println("Container name: " + sasUriResponse.getContainerName());
System.out.println("Blob name: " + sasUriResponse.getBlobName());
System.out.println("Blob Uri: " + sasUriResponse.getBlobUri());

將檔案上傳至 Azure 儲存體

將 Blob URI 端點傳遞至 BlobClientBuilder.buildclient 以建立 BlobClient 物件。

BlobClient blobClient =
    new BlobClientBuilder()
        .endpoint(sasUriResponse.getBlobUri().toString())
        .buildClient();

呼叫 uploadFromFile 將檔案上傳至 Blob 記憶體。

String fullFileName = "Path of the file to upload";
blobClient.uploadFromFile(fullFileName);

將檔案上傳狀態通知傳送至IoT中樞

在檔案上傳嘗試之後，將上傳狀態通知傳送至IoT中樞。

建立 FileUploadCompletionNotification 物件。 correlationId傳遞和 isSuccess 檔案上傳成功狀態。 isSuccess true當檔案上傳成功時傳遞值，false但未成功。

FileUploadCompletionNotification 即使檔案上傳失敗，也必須呼叫。 IoT 中樞具有固定數目的 SAS URI，可在任何指定時間處於作用中狀態。完成檔案上傳之後，您應該釋放 SAS URI，以便產生其他 SAS URI。如果 SAS URI 未透過此 API 釋出，則最終會根據 SAS URI 設定為在 IoT 中樞上生存的時間長度釋放自己。

此範例會傳遞成功狀態。

FileUploadCompletionNotification completionNotification = new FileUploadCompletionNotification(sasUriResponse.getCorrelationId(), true);
client.completeFileUpload(completionNotification);

關閉用戶端

client釋放資源。

client.closeNow();

建立後端應用程式

本節說明如何在後端應用程式中接收檔案上傳通知。

ServiceClient 類別包含服務可用來接收檔案上傳通知的方法。

新增 import 陳述式

新增這些 import 陳述式，以使用 Azure IoT Java SDK 和例外狀況處理常式。

import com.microsoft.azure.sdk.iot.service.*;
import java.io.IOException;
import java.net.URISyntaxException;

連線至 IoT 中樞

您可以使用下列方法將後端服務連線至 IoT 中樞：

共用存取原則
Microsoft Entra

重要

使用共用存取原則進行連線

定義連線通訊協定

使用 IotHubServiceClientProtocol 來定義服務用戶端用來與 IoT 中樞通訊的應用程式層通訊協定。

IotHubServiceClientProtocol 只接受 AMQPS 或 AMQPS_WS 列舉。

private static final IotHubServiceClientProtocol protocol =    
    IotHubServiceClientProtocol.AMQPS;

建立 ServiceClient 物件

建立 ServiceClient 物件，並提供 Iot 中樞連接字串和通訊協定。

若要將裝置上的檔案上傳至 IoT 中樞，您的服務需要服務連線許可權。根據預設，每個 IoT 中樞都是透過授與此權限且名為服務的共用存取原則所建立。

作為建 ServiceClient 構函式的參數，請提供服務共用存取原則。如需共用存取原則的詳細資訊，請參閱使用共用存取簽章控制對 IoT 中樞的存取。

String iotHubConnectionString = "HostName=xxxxx.azure-devices.net;SharedAccessKeyName=service;SharedAccessKey=xxxxxxxxxxxxxxxxxxxxxxxx";
private static final ServiceClient serviceClient (iotHubConnectionString, protocol);

開啟應用程式與 IoT 中樞之間的連線

開啟 AMQP傳送者連線。此方法會建立應用程式與 IoT 中樞之間的連線。

serviceClient.open();

使用 Microsoft Entra 進行連線

使用 Microsoft Entra 的後端應用程式必須先成功驗證並取得安全性令牌認證，才能連線到 IoT 中樞。此令牌會傳遞至 IoT 中樞連線方法。如需設定和使用 Microsoft Entra 進行 IoT 中樞的一般資訊，請參閱使用 Microsoft Entra 識別符控制對 IoT 中樞的存取。

如需 Java SDK 驗證的概觀，請參閱使用 Java 和 Azure 身分識別進行 Azure 驗證。

為了簡單起見，本節著重於使用用戶端密碼描述驗證。

設定 Microsoft Entra 應用程式

用戶端密碼
[MSSQLSERVER 的通訊協定內容]
同盟身分識別認證

Microsoft Entra 應用程式可能需要特定角色許可權，視執行的作業而定。例如，需要 IoT 中樞對應項參與者，才能對 IoT 中樞裝置和模組對應項啟用讀取和寫入存取權。如需詳細資訊，請參閱使用 Azure RBAC 角色指派來管理 IoT 中樞的存取權。

如需設定Microsoft Entra 應用程式的詳細資訊，請參閱快速入門：向 Microsoft 身分識別平台註冊應用程式。

使用 DefaultAzureCredential 進行驗證

使用 Microsoft Entra 來驗證後端應用程式最簡單的方式是使用 DefaultAzureCredential，但建議在生產環境中使用不同的方法，包括特定TokenCredential或剖析。ChainedTokenCredential 如需使用 DefaultAzureCredential之優缺點的詳細資訊，請參閱適用於 Java 的 Azure 身分識別用戶端連結庫中的認證鏈結。

DefaultAzureCredential 支援不同的驗證機制，並根據執行中的環境來判斷適當的認證類型。它會嘗試依序使用多個認證類型，直到找到有效的認證為止。

您可以使用 DefaultAzureCredentialBuilder 來驗證Microsoft Entra 應用程式認證。將用戶端秘密 tenantID、clientID 和用戶端秘密值等聯機參數儲存為環境變數。 TokenCredential建立之後，將它傳遞至 ServiceClient 或其他產生器做為 'credential' 參數。

在此範例中，DefaultAzureCredentialBuilder嘗試從 DefaultAzureCredential 中所述的清單驗證連線。成功Microsoft Entra 驗證的結果是傳遞至 ServiceClient 等建構函式的安全性令牌認證。

TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build();

使用 ClientSecretCredentialBuilder 進行驗證

您可以使用 ClientSecretCredentialBuilder ，使用用戶端秘密資訊建立認證。如果成功，這個方法會傳回可傳遞至 ServiceClient 或其他產生器做為 'credential' 參數的 TokenCredential。

在此範例中，Microsoft Entra 應用程式註冊客戶端密碼、用戶端標識碼和租使用者標識碼值已新增至環境變數。這些環境變數是用來 ClientSecretCredentialBuilder 建置認證。

string clientSecretValue = System.getenv("AZURE_CLIENT_SECRET");
string clientID = System.getenv("AZURE_CLIENT_ID");
string tenantID = System.getenv("AZURE_TENANT_ID");

TokenCredential credential =
     new ClientSecretCredentialBuilder()
          .tenantId(tenantID)
          .clientId(clientID)
          .clientSecret(clientSecretValue)
          .build();

其他驗證類別

Java SDK 也包含這些類別，這些類別會使用 Microsoft Entra 來驗證後端應用程式：

程式碼範例

如需Microsoft Entra 服務驗證的工作範例，請參閱角色型驗證範例。

檢查檔案上傳狀態

若要檢查檔案上傳狀態：

建立 getFileUploadNotificationReceiver 物件。
使用 open 連線到 IoT 中樞。
呼叫接收以檢查檔案上傳狀態。這個方法會傳回 fileUploadNotification 物件。如果收到上傳通知，您可以使用 fileUploadNotification 方法來檢視上傳狀態字段。

例如：

FileUploadNotificationReceiver receiver = serviceClient.getFileUploadNotificationReceiver();
receiver.open();
FileUploadNotification fileUploadNotification = receiver.receive(2000);

if (fileUploadNotification != null)
{
    System.out.println("File Upload notification received");
    System.out.println("Device Id : " + fileUploadNotification.getDeviceId());
    System.out.println("Blob Uri: " + fileUploadNotification.getBlobUri());
    System.out.println("Blob Name: " + fileUploadNotification.getBlobName());
    System.out.println("Last Updated : " + fileUploadNotification.getLastUpdatedTimeDate());
    System.out.println("Blob Size (Bytes): " + fileUploadNotification.getBlobSizeInBytes());
    System.out.println("Enqueued Time: " + fileUploadNotification.getEnqueuedTimeUtcDate());
}
else
{
    System.out.println("No file upload notification");
}

// Close the receiver object
receiver.close();

SDK 檔案上傳範例

有兩個 Java 檔案上傳範例。

安裝套件

必須先安裝 azure-iot-device 連結庫，才能呼叫任何相關的程序代碼。

pip install azure-iot-device

azure.storage.blob 套件可用來執行檔案上傳。

pip install azure.storage.blob

從裝置應用程式上傳檔案

本節說明如何使用適用於 Python 的 Azure IoT SDK IoT SDK 的 IoTHubDeviceClient 類別，將檔案從裝置上傳至 IoT 中樞。

匯入程式庫

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

將裝置連線到 IoT 中樞

裝置應用程式可以使用下列方法來向 IoT 中樞進行驗證：

X.509 憑證
共用存取金鑰

使用 X.509 憑證進行驗證

若要使用 X.509 憑證將裝置連線到 IoT 中樞：

使用 create_from_x509_certificate 新增 X.509 憑證參數
呼叫 connect 以連線裝置用戶端

此範例會顯示憑證輸入參數值做為局部變數，以便清楚起見。在生產系統中，將敏感性輸入參數儲存在環境變數或其他更安全的儲存位置。例如，使用 os.getenv("HOSTNAME") 來讀取主機名環境變數。

# The Azure IoT hub name
hostname = "xxxxx.azure-devices.net"

# The device that has been created on the portal using X509 CA signing or self-signing capabilities
device_id = "MyDevice"

# The X.509 certificate file name
cert_file = "~/certificates/certs/sensor-thl-001-device.cert.pfx"
key_file = "~/certificates/certs/sensor-thl-001-device.cert.key"
# The optional certificate pass phrase
pass_phrase = "1234"

x509 = X509(
    cert_file,
    key_file,
    pass_phrase,
)

# The client object is used to interact with your Azure IoT hub.
device_client = IoTHubDeviceClient.create_from_x509_certificate(
    hostname=hostname, device_id=device_id, x509=x509
)

# Connect to IoT Hub
await device_client.connect()

如需憑證驗證的詳細資訊，請參閱：

程式碼範例

如需裝置 X.509 憑證驗證的工作範例，請參閱 Async 中樞案例中檔名以 x509 結尾的範例。

使用共用存取金鑰進行驗證

若要將裝置連線至 IoT 中樞：

呼叫 create_from_connection_string 以新增裝置主要連接字串。
呼叫 connect 以連線裝置用戶端。

例如：

# Add your IoT hub primary connection string
CONNECTION_STRING = "{Device primary connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(CONNECTION_STRING)

# Connect the client
device_client.connect()

取得 Blob 記憶體資訊

呼叫 get_storage_info_for_blob，從IoT中樞取得連結 Azure 儲存體帳戶的相關信息。此資訊包括主機名稱、容器名稱、blob 名稱和 SAS 權杖。方法 get_storage_info_for_blob 也會傳 correlation_id回方法中使用的 notify_blob_upload_status 。 correlation_id是 IoT 中樞標記您要處理的 Blob 的方式。

# Get the storage info for the blob
PATH_TO_FILE = "{Full path to local file}"
blob_name = os.path.basename(PATH_TO_FILE)
blob_info = device_client.get_storage_info_for_blob(blob_name)

將檔案上傳至 Blob 記憶體

若要將檔案上傳至 Blob 記憶體：

使用 from_blob_url 從 Blob URL 建立 BlobClient 物件。
呼叫 upload_blob ，將檔案上傳至 Blob 記憶體。

此範例會blob_info剖析結構，以建立用來初始化 BlobClient 的 URL。然後它會呼叫 upload_blob 以將檔案上傳至 Blob 記憶體。

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)

通知IoT中樞上傳狀態

使用 notify_blob_upload_status 通知IoT中樞 Blob 記憶體作業的狀態。 correlation_id傳遞方法取得的 get_storage_info_for_blob 。 correlation_id IoT 中樞會使用來通知任何可能正在接聽檔案上傳工作狀態的通知的服務。

此範例會通知 IoT 中樞成功上傳檔案：

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

關閉裝置用戶端

關閉用戶端。呼叫此方法之後，任何嘗試進一步的用戶端呼叫都會導致引發 ClientError 。

device_client.shutdown()

SDK 檔案上傳範例

SDK 包含兩個檔案上傳範例：

概觀

本文說明如何使用適用於 Node.js 的 Azure IoT SDK 來建立裝置應用程式，以上傳檔案和後端服務應用程式接收檔案上傳通知。

建立裝置應用程式

本節說明如何使用適用於 Node.js 的 Azure IoT SDK 中的 azure-iot-device 套件，將檔案從裝置上傳至 IoT 中樞。

安裝 SDK 套件

執行此命令以在 開發計算機上安裝 azure-iot-device SDK、 azure-iot-device-mqtt 和 @azure/storage-blob 套件：

npm install azure-iot-device azure-iot-device-mqtt @azure/storage-blob --save

azure-iot-device 套件包含與 IoT 裝置互動的物件。

請遵循此程式，將檔案從裝置上傳至IoT中樞：

將裝置連線至 IoT 中樞
從 IoT 中樞取得 Blob 共用存取簽章（SAS）令牌
將檔案上傳至 Azure 儲存體
將檔案上傳狀態通知傳送至IoT中樞

建立模組

使用已安裝的套件建立客戶端、通訊協定、錯誤和路徑模組。

const Protocol = require('azure-iot-device-mqtt').Mqtt;
const errors = require('azure-iot-common').errors;
const path = require('path');

將裝置連線到 IoT 中樞

裝置應用程式可以使用下列方法向 IoT 中樞進行驗證：

X.509 憑證
共用存取金鑰

使用 X.509 憑證進行驗證

X.509 憑證會連結至裝置對 IoT 中樞連線傳輸。

若要使用 X.509 憑證設定裝置對 IoT 中樞連線：

從ConnectionString呼叫以新增裝置連接字串和傳輸類型。 x509=true新增至裝置連接字串，表示憑證已新增至 DeviceClientOptions。例如： HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true 。
使用憑證詳細數據設定 JSON 變數，並將其傳遞至 DeviceClientOptions。
呼叫 setOptions 以將 X.509 憑證和密鑰（以及選擇性的複雜密碼）新增至用戶端傳輸。
呼叫open以從裝置開啟連線至 IoT 中樞。

此範例顯示 JSON 變數內的憑證組態資訊。認證組態 options 會傳遞至 setOptions ，並使用開啟 open連線。

var options = {
   cert: myX509Certificate,
   key: myX509Key,
   passphrase: passphrase,
   http: {
     receivePolicy: {
       interval: 10
     }
   }
 }
 client.setOptions(options, callback);
 client.open(connectCallback);

如需憑證驗證的詳細資訊，請參閱：

程式碼範例

如需裝置 X.509 憑證驗證的運作範例，請參閱簡單的範例裝置 X.509。

使用共用存取金鑰進行驗證

選擇傳輸通訊協定

Client 物件支援這些通訊協定：

Amqp
Http - 使用 Http 時，Client 執行個體會不常檢查來自 IoT 中樞的訊息 (至少每25分鐘)。
Mqtt
MqttWs
AmqpWs

在開發電腦上安裝所需的傳輸通訊協定。

例如，此命令會安裝 Amqp 通訊協定：

npm install azure-iot-device-amqp --save

如需 MQTT、AMQP 和 HTTPS 支援之間差異的詳細資訊，請參閱雲端到裝置的通訊指引和選擇通訊協定。

建立用戶端物件

使用已安裝的套件建立 Client 物件。

例如：

const Client = require('azure-iot-device').Client;

建立通訊協議物件

使用已安裝的傳輸套件建立 Protocol 物件。

此範例會指派AMQP通訊協定：

const Protocol = require('azure-iot-device-amqp').Amqp;

新增裝置連接字串和傳輸通訊協定

呼叫 fromConnectionString 以提供裝置連線參數：

connStr - 裝置連接字串。
transportCtor - 傳輸通訊協定。

此範例會使用 Amqp 傳輸通訊協定：

const deviceConnectionString = "{IoT hub device connection string}"
const Protocol = require('azure-iot-device-mqtt').Amqp;
let client = Client.fromConnectionString(deviceConnectionString, Protocol);

開啟連線到 IoT 中樞

使用 open 方法來開啟 IoT 裝置與 IoT 中樞之間的連線。

例如：

client.open(function(err) {
  if (err) {
    console.error('error connecting to hub: ' + err);
    process.exit(1);
  }
})

從 IoT 中樞取得 SAS 令牌

使用 getBlobSharedAccessSignature 從 IoT 中樞取得連結的記憶體帳戶 SAS 令牌。

例如：

// make sure you set these environment variables prior to running the sample.
const localFilePath = process.env.PATH_TO_FILE;
const storageBlobName = path.basename(localFilePath);
const blobInfo = await client.getBlobSharedAccessSignature(storageBlobName);
if (!blobInfo) {
throw new errors.ArgumentError('Invalid upload parameters');
}

將檔案上傳至IoT中樞

若要將檔案從裝置上傳至IoT中樞：

建立數據流管線
建構 Blob URL
建立 BlockBlobClient 以將檔案上傳至 Blob 記憶體
呼叫 uploadFile 將檔案上傳至 Blob 記憶體
呼叫 notifyBlobUploadStatus 以通知 IoT 中樞上傳成功或失敗

例如：

// Open the pipeline
const pipeline = newPipeline(new AnonymousCredential(), {
retryOptions: { maxTries: 4 },
telemetry: { value: 'HighLevelSample V1.0.0' }, // Customized telemetry string
keepAliveOptions: { enable: false }
});

// Construct the blob URL
const { hostName, containerName, blobName, sasToken } = blobInfo;
const blobUrl = `https://${hostName}/${containerName}/${blobName}${sasToken}`;

// Create the BlockBlobClient for file upload to Blob Storage
const blobClient = new BlockBlobClient(blobUrl, pipeline);

// Setup blank status notification arguments to be filled in on success/failure
let isSuccess;
let statusCode;
let statusDescription;

const uploadStatus = await blobClient.uploadFile(localFilePath);
console.log('uploadStreamToBlockBlob success');

  try {
    const uploadStatus = await blobClient.uploadFile(localFilePath);
    console.log('uploadStreamToBlockBlob success');

    // Save successful status notification arguments
    isSuccess = true;
    statusCode = uploadStatus._response.status;
    statusDescription = uploadStatus._response.bodyAsText;

    // Notify IoT hub of upload to blob status (success)
    console.log('notifyBlobUploadStatus success');
  }
  catch (err) {
    isSuccess = false;
    statusCode = err.code;
    statusDescription = err.message;

    console.log('notifyBlobUploadStatus failed');
    console.log(err);
  }

// Send file upload status notification to IoT hub
await client.notifyBlobUploadStatus(blobInfo.correlationId, isSuccess, statusCode, statusDescription);

將本機檔案上傳至 Blob 記憶體

您可以從電腦將本機檔案上傳至 Blob 記憶體

const deviceClient = Client.fromConnectionString(deviceConnectionString, Protocol);
uploadToBlob(localFilePath, deviceClient)
  .catch((err) => {
    console.log(err);
  })
  .finally(() => {
    process.exit();
  });

SDK 檔案上傳範例

SDK 包含上傳至 Blob 進階範例。

建立後端應用程式

本節說明如何在後端應用程式中接收檔案上傳通知。

ServiceClient 類別包含服務可用來接收檔案上傳通知的方法。

安裝服務 SDK 套件

執行此命令，在開發電腦上安裝 azure-iothub：

npm install azure-iothub --save

連線至 IoT 中樞

您可以使用下列方法，將後端服務連線到 IoT 中樞：

共用存取原則
Microsoft Entra

重要

使用共用存取原則進行連線

使用 fromConnectionString 連線到 IoT 中樞。

若要從裝置上傳檔案，您的服務需要 服務連線 許可權。根據預設，每個 IoT 中樞都是透過授與此權限且名為服務的共用存取原則所建立。

作為的參數，CreateFromConnectionString請提供服務共用存取原則連接字串。如需共用存取原則的詳細資訊，請參閱使用共用存取簽章控制對 IoT 中樞的存取。

var Client = require('azure-iothub').Client;
var connectionString = '{IoT hub shared access policy connection string}';
var client = Client.fromConnectionString(connectionString);

使用 Microsoft Entra 進行連線

使用 Microsoft Entra 的後端應用程式必須先成功驗證並取得安全性令牌認證，才能連線到 IoT 中樞。此令牌會傳遞至 IoT 中樞連接方法。如需設定和使用 Microsoft Entra 進行 IoT 中樞的一般資訊，請參閱使用 Microsoft Entra 識別符控制對 IoT 中樞的存取。

如需Node.js SDK 驗證的概觀，請參閱：

設定 Microsoft Entra 應用程式

用戶端密碼
[MSSQLSERVER 的通訊協定內容]
同盟身分識別認證

Microsoft Entra 應用程式可能需要特定角色許可權，視執行的作業而定。例如，需要 IoT 中樞對應項參與者，才能啟用 IoT 中樞裝置和模塊對應項的讀取和寫入存取權。如需詳細資訊，請參閱使用 Azure RBAC 角色指派來管理對 IoT 中樞的存取權。

如需設定 Microsoft Entra 應用程式的詳細資訊，請參閱快速入門：向 Microsoft 身分識別平台註冊應用程式。

使用 DefaultAzureCredential 進行驗證

DefaultAzureCredential 支援不同的驗證機制，並根據執行中的環境來判斷適當的認證類型。它會嘗試依序使用多個認證類型，直到找到有效的認證為止。

Microsoft Entra 需要此套件：

npm install --save @azure/identity

在此範例中，Microsoft Entra 應用程式註冊客戶端密碼、用戶端標識碼和租使用者標識碼已新增至環境變數。這些環境變數是用來 DefaultAzureCredential 驗證應用程式。成功Microsoft Entra 驗證的結果是傳遞至 IoT 中樞連線方法的安全性令牌認證。

import { DefaultAzureCredential } from "@azure/identity";

// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();

然後，產生的認證令牌可以傳遞至 fromTokenCredential，以連線到任何接受 Microsoft Entra 認證的 SDK 用戶端 IoT 中樞：

fromTokenCredential 需要兩個參數：

Azure 服務 URL - Azure 服務 URL 的格式 {Your Entra domain URL}.azure-devices.net 應該不含 https:// 前置詞。例如： MyAzureDomain.azure-devices.net 。
Azure 認證令牌

在此範例中，會使用 DefaultAzureCredential取得 Azure 認證。接著會提供 Azure 網域 URL 和認證，Registry.fromTokenCredential以建立與 IoT 中樞的連線。

const { DefaultAzureCredential } = require("@azure/identity");

let Registry = require('azure-iothub').Registry;

// Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

// Set environment variables
process.env['AZURE_CLIENT_SECRET'] = clientSecretValue;
process.env['AZURE_CLIENT_ID'] = clientID;
process.env['AZURE_TENANT_ID'] = tenantID;

// Acquire a credential object
const credential = new DefaultAzureCredential()

// Create an instance of the IoTHub registry
hostName = 'MyAzureDomain.azure-devices.net';
let registry = Registry.fromTokenCredential(hostName,credential);

程式碼範例

如需Microsoft Entra 服務驗證的工作範例，請參閱 Azure 身分識別範例。

建立檔案上傳通知回呼接收者

若要建立檔案上傳通知回呼接收者：

呼叫 getFileNotificationReceiver。提供收到通知訊息時所呼叫的檔案上傳回呼方法名稱。
在回呼方法中處理檔案上傳通知。

本範例會設定 receiveFileUploadNotification 通知回呼接收者。接收者會解譯檔案上傳狀態資訊，並將狀態消息列印至主控台。

//Set up the receiveFileUploadNotification notification message callback receiver
serviceClient.getFileNotificationReceiver(function receiveFileUploadNotification(err, receiver){
if (err) {
  console.error('error getting the file notification receiver: ' + err.toString());
} else {
  receiver.on('message', function (msg) {
    console.log('File upload from device:')
    console.log(msg.getData().toString('utf-8'));
    receiver.complete(msg, function (err) {
      if (err) {
        console.error('Could not finish the upload: ' + err.message);
      } else {
        console.log('Upload complete');
      }
    });
  });
}

SDK 檔案上傳通知範例

SDK 包含檔案上傳範例。

共用方式為

使用 Azure IoT 中樞 將檔案從裝置上傳至雲端

必要條件

概觀

從裝置應用程式上傳檔案

將裝置連線到 IoT 中樞

使用 X.509 憑證進行驗證

程式碼範例

使用共用存取金鑰進行驗證

從IoT中樞取得SAS URI

將檔案上傳至 Azure 記憶體

通知IoT中樞檔案上傳狀態

SDK 檔案上傳範例

在後端應用程式中接收檔案上傳通知

新增服務 NuGet 套件

連線至 IoT 中樞

使用共用存取原則進行連線

使用 Microsoft Entra 進行連線

設定 Microsoft Entra 應用程式

使用 DefaultAzureCredential 進行驗證

程式碼範例

接收檔案上傳通知

SDK 檔案上傳接收者範例

概觀

從裝置應用程式上傳檔案

將裝置連線到 IoT 中樞

使用 X.509 憑證進行驗證

程式碼範例

使用共用存取金鑰進行驗證

從IoT中樞取得SAS URI

將檔案上傳至 Azure 儲存體

將檔案上傳狀態通知傳送至IoT中樞

關閉用戶端

建立後端應用程式

新增 import 陳述式

連線至 IoT 中樞

使用共用存取原則進行連線

定義連線通訊協定

建立 ServiceClient 物件

開啟應用程式與 IoT 中樞之間的連線

使用 Microsoft Entra 進行連線

設定 Microsoft Entra 應用程式

使用 DefaultAzureCredential 進行驗證

使用 ClientSecretCredentialBuilder 進行驗證

其他驗證類別

程式碼範例

檢查檔案上傳狀態

SDK 檔案上傳範例

安裝套件

從裝置應用程式上傳檔案

匯入程式庫

將裝置連線到 IoT 中樞

使用 X.509 憑證進行驗證

程式碼範例

使用共用存取金鑰進行驗證

取得 Blob 記憶體資訊

將檔案上傳至 Blob 記憶體

通知IoT中樞上傳狀態

關閉裝置用戶端

SDK 檔案上傳範例

概觀

建立裝置應用程式

安裝 SDK 套件

建立模組

將裝置連線到 IoT 中樞

使用 X.509 憑證進行驗證

程式碼範例

使用共用存取金鑰進行驗證

選擇傳輸通訊協定

建立用戶端物件

建立通訊協議物件

新增裝置連接字串和傳輸通訊協定

開啟連線到 IoT 中樞

從 IoT 中樞取得 SAS 令牌

將檔案上傳至IoT中樞

將本機檔案上傳至 Blob 記憶體

SDK 檔案上傳範例

建立後端應用程式

安裝服務 SDK 套件

連線至 IoT 中樞

使用 Azure IoT 中樞將檔案從裝置上傳至雲端