使用直接方法的裝置管理 - Azure IoT Hub

需要 Visual Studio

概觀

本文說明如何使用適用於 .NET 的 Azure IoT SDK 來建立裝置和後端服務應用程式程式代碼以進行裝置直接訊息。

建立裝置應用程式

本節說明如何使用裝置應用程式程式代碼來建立直接方法回呼接聽程式。

重要

本文包含使用共用存取簽章 (也稱為對稱金鑰驗證) 連線裝置的步驟。此驗證方法方便進行測試和評估，但使用 X.509 憑證來驗證裝置是更安全的方法。若要深入了解，請參閱安全性最佳做法>連線安全性。

必要的裝置 NuGet 套件

以 C# 撰寫的裝置用戶端應用程式需要 Microsoft.Azure.Devices.Client NuGet 套件。

新增這些 using 語句以使用裝置連結庫。

using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;

連線到裝置

DeviceClient 類別會公開與裝置訊息互動所需的所有方法。

使用 CreateFromConnectionString 方法以及裝置連接字串和連線傳輸通訊協定來連線到裝置。

CreateFromConnectionString TransportType 傳輸通訊協定參數支援下列傳輸通訊協定：

Mqtt
Mqtt_WebSocket_Only
Mqtt_Tcp_Only
Amqp
Amqp_WebSocket_Only
Amqp_Tcp_Only
Http1

此範例會使用 Mqtt 傳輸通訊協定連線到裝置。

static string DeviceConnectionString = "{IoT hub device connection string}";
static deviceClient = null;
deviceClient = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
   TransportType.Mqtt);

建立直接方法回呼接聽程式

使用 SetMethodHandlerAsync 初始化直接方法回呼接聽程式。接聽程式與方法名稱關鍵詞相關聯，例如「重新啟動」。方法名稱可用於 IoT 中樞或後端應用程式中，以觸發裝置上的回呼方法。

此範例會設定名為 onReboot 的回呼接聽程式，以在呼叫「重新啟動」直接方法名稱時觸發。

try
{
      // setup callback for "reboot" method
      deviceClient.SetMethodHandlerAsync("reboot", onReboot, null).Wait();
      Console.WriteLine("Waiting for reboot method\n Press enter to exit.");
      Console.ReadLine();

      Console.WriteLine("Exiting...");

      // as a good practice, remove the "reboot" handler
      deviceClient.SetMethodHandlerAsync("reboot", null, null).Wait();
      deviceClient.CloseAsync().Wait();
}
catch (Exception ex)
{
      Console.WriteLine();
      Console.WriteLine("Error in sample: {0}", ex.Message);
}

繼續此範例，回 onReboot 呼方法會在裝置上實作直接方法。

處理程式函式會呼叫 MethodResponse ，將回應通知傳送給呼叫的應用程式。

static Task<MethodResponse> onReboot(MethodRequest methodRequest, object userContext)
{
      // In a production device, you would trigger a reboot 
      // scheduled to start after this method returns.
      // For this sample, we simulate the reboot by writing to the console
      // and updating the reported properties.
      try
      {
         Console.WriteLine("Rebooting!");
      }
      catch (Exception ex)
      {
         Console.WriteLine();
         Console.WriteLine("Error in sample: {0}", ex.Message);
      }

      string result = @"{""result"":""Reboot started.""}";
      return Task.FromResult(new MethodResponse(Encoding.UTF8.GetBytes(result), 200));
}

注意

為了簡單起見，本文章不會實作任何重試原則。在生產程式碼中，您應該如暫時性錯誤處理中所建議來實作重試原則 (例如指數輪詢)。

SDK 裝置範例

適用於 .NET 的 Azure IoT SDK 提供處理直接方法工作的裝置應用程式範例。如需詳細資訊，請參閱

建立後端應用程式

本節說明如何在裝置上觸發直接方法。

ServiceClient 類別會公開建立後端應用程式所需的所有方法，以將直接方法呼叫傳送至裝置。

必要的服務 NuGet 套件

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

新增這些 using 語句以使用服務連結庫。

using Microsoft.Azure.Devices;
using Microsoft.Azure.Devices.Shared;

連線至 IoT 中樞

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

共用存取原則
Microsoft Entra

重要

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

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

使用 CreateFromConnectionString 連接後端應用程式。

若要透過 IoT 中樞在裝置上叫用直接方法，則服務需要有服務連線權限。根據預設，每個 IoT 中樞都是透過授與此權限且名為服務的共用存取原則所建立。

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

ServiceClient serviceClient;
string connectionString = "{IoT hub service shared access policy connection string}";
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);

使用 Microsoft Entra 進行連線

使用 Microsoft Entra 的後端應用程式必須先成功驗證並取得安全性令牌認證，才能連線到 IoT 中樞。此令牌會傳遞至 IoT 中樞連接方法。如需設定和使用 Microsoft Entra 進行 IoT 中樞的一般資訊，請參閱使用 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 服務驗證的運作範例，請參閱角色型驗證範例。

在裝置上叫用方法

若要在裝置上叫用方法：

建立 CloudToDeviceMethod 物件。傳遞裝置直接方法名稱做為參數。
呼叫 InvokeDeviceMethodAsync 以在裝置上叫用方法。

此範例會呼叫「reboot」方法來起始裝置上的重新啟動。「重新啟動」方法會對應至裝置上的接聽程式，如本文的建立直接方法回呼接聽程式一節所述。

string targetDevice = "myDeviceId";
CloudToDeviceMethod method = new CloudToDeviceMethod("reboot");
method.ResponseTimeout = TimeSpan.FromSeconds(30);

CloudToDeviceMethodResult response = await serviceClient.InvokeDeviceMethodAsync(targetDevice, method);

Console.WriteLine("Invoked firmware update on device.");

SDK 服務範例

適用於 .NET 的 Azure IoT SDK 提供處理訊息工作之服務應用程式的工作範例。如需詳細資訊，請參閱

需要 Java SE 開發工具套件 8。請務必選取 [長期支援] 下的 [Java 8]，以瀏覽至 JDK 8 的下載。

概觀

本文說明如何使用適用於 Java 的 Azure IoT SDK，為裝置直接方法建立裝置和後端服務應用程式程式碼。

建立裝置應用程式

本節說明如何使用裝置應用程式程式代碼來建立直接方法回呼接聽程式。

重要

本文包含使用共用存取簽章 (也稱為對稱金鑰驗證) 連線裝置的步驟。此驗證方法方便進行測試和評估，但使用 X.509 憑證來驗證裝置是更安全的方法。若要深入了解，請參閱安全性最佳做法>連線安全性。

裝置匯入語句

使用下列裝置 import 陳述式來存取 Azure IoT SDK for Java。

import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.exceptions.IotHubClientException;
import com.microsoft.azure.sdk.iot.device.twin.DirectMethodPayload;
import com.microsoft.azure.sdk.iot.device.twin.DirectMethodResponse;
import com.microsoft.azure.sdk.iot.device.twin.MethodCallback;
import com.microsoft.azure.sdk.iot.device.transport.IotHubConnectionStatus;
import com.microsoft.azure.sdk.iot.device.twin.SubscriptionAcknowledgedCallback;

連線到裝置

DeviceClient 類別會公開與裝置上直接方法互動所需的所有方法。

若要連線到裝置，請執行下列動作：

使用 IotHubClientProtocol 來選擇傳輸通訊協定。例如：
```
IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
```

使用 DeviceClient 建構函式來新增裝置主要連接字串和通訊協定。

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

使用 open 將裝置連線到 IoT 中樞。如果用戶端已經開啟，方法就不會執行任何動作。
```
client.open(true);
```

建立直接方法回呼接聽程式

使用 subscribeToMethods 初始化直接方法回呼接聽程式。 subscribeToMethods 會接聽連入直接方法，直到連接終止為止。系統會針對每個直接方法呼叫接收方法名稱和承載。

接聽程式應該呼叫 DirectMethodResponse ，將方法回應通知傳送給呼叫的應用程式。

例如：

client.subscribeToMethods(
    (methodName, methodData, context) ->
    {
        System.out.println("Received a direct method invocation with name " + methodName + " and payload " + methodData.getPayloadAsJsonString());
        return new DirectMethodResponse(200, methodData);
    },
    null);
System.out.println("Successfully subscribed to direct methods");

注意

為了簡單起見，本文章不會實作任何重試原則。在生產程式碼中，您應該如暫時性錯誤處理中所建議來實作重試原則 (例如指數輪詢)。

SDK 裝置範例

Azure IoT SDK for Java 包含可測試本文所述裝置應用程式概念的工作範例。如需詳細資訊，請參閱直接方法範例。

建立後端應用程式

本節說明如何使用直接方法，在裝置上起始遠端重新啟動。

ServiceClient DeviceMethod 類別包含服務可用來存取裝置對應項的方法。

服務 import 陳述式

使用下列服務 import 陳述式來存取 Azure IoT SDK for Java。

import com.microsoft.azure.sdk.iot.service.methods.DirectMethodRequestOptions;
import com.microsoft.azure.sdk.iot.service.methods.DirectMethodsClient;
import com.microsoft.azure.sdk.iot.service.methods.DirectMethodResponse;

連線至 IoT 中樞

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

共用存取原則
Microsoft Entra

重要

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

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

使用 DeviceMethod 建構函式來新增服務主要連接字串，並連線到 IoT 中樞。

若要透過 IoT 中樞在裝置上叫用直接方法，則服務需要有服務連線權限。根據預設，每個 IoT 中樞都是透過授與此權限且名為服務的共用存取原則所建立。

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

例如：

String iotHubConnectionString = "HostName=xxxxx.azure-devices.net;SharedAccessKeyName=service;SharedAccessKey=xxxxxxxxxxxxxxxxxxxxxxxx";
DeviceMethod methodClient = new DeviceMethod(iotHubConnectionString);

使用 Microsoft Entra 進行連線

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

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

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

設定 Microsoft Entra 應用程式

您必須設定已針對您慣用的驗證認證設定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 服務驗證的工作範例，請參閱角色型驗證範例。

在裝置上叫用方法

呼叫 DeviceMethod.invoke 以在裝置上叫用方法，並傳回結果狀態。

invoke承載參數是選擇性的。如果沒有提供承載，請使用 null 。承載參數可以採用不同的數據形式，包括字串、位元組陣列和HashMap。如需範例，請參閱直接方法測試。

此範例會呼叫「reboot」方法來起始裝置上的重新啟動。「重新啟動」方法會對應至裝置上的接聽程式，如本文的建立直接方法回呼接聽程式一節所述。

例如：

String deviceId = "myFirstDevice";
String methodName = "reboot";
String payload = "Test payload";
Long responseTimeout = TimeUnit.SECONDS.toSeconds(30);
Long connectTimeout = TimeUnit.SECONDS.toSeconds(5);

MethodResult result = methodClient.invoke(deviceId, methodName, responseTimeout, connectTimeout, payload);
if (result == null)
{
    throw new IOException("Method invoke returns null");
}
System.out.println("Status=" + result.getStatus());

SDK 服務範例

適用於 Java 的 Azure IoT SDK 提供可處理直接方法工作的服務應用程式範例。如需詳細資訊，請參閱

Python SDK - 建議使用 Python 3.7 版或更新版本。請務必使用安裝程式所需的 32 位元或 64 位元安裝。在安裝期間出現系統提示時，務必將 Python 新增至平台特有的環境變數。

概觀

本文說明如何使用適用於 Python 的 Azure IoT SDK，為裝置直接方法建立裝置和後端服務應用程式程式代碼。

安裝套件

必須安裝 azure-iot-device 連結庫，才能建立裝置應用程式。

pip install azure-iot-device

必須安裝 azure-iot-hub 連結庫，才能建立後端服務應用程式。

pip install azure-iot-hub

建立裝置應用程式

本節說明如何使用裝置應用程式程式代碼來建立直接方法回呼接聽程式。

重要

本文包含使用共用存取簽章 (也稱為對稱金鑰驗證) 連線裝置的步驟。此驗證方法方便進行測試和評估，但使用 X.509 憑證來驗證裝置是更安全的方法。若要深入了解，請參閱安全性最佳做法>連線安全性。

裝置 import 陳述式

新增此 import 語句以存取 IoTHubDeviceClient 和 MethodResponse。

# import the device client library
from azure.iot.device import IoTHubDeviceClient, MethodResponse

連線到裝置

IoTHubDeviceClient 類別包含可用來使用直接方法的方法。

使用create_from_connection_string使用裝置連接字串將應用程式連線到裝置。

# substitute the device connection string in conn_str
# and add it to the IoTHubDeviceClient object
conn_str = "{IoT hub device connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(conn_str)

建立直接方法回呼

使用 on_method_request_received 建立接收直接方法時所呼叫的處理程式函式或協同程式。接聽程式與方法名稱關鍵詞相關聯，例如「重新啟動」。方法名稱可用於 IoT 中樞或後端應用程式中，以觸發裝置上的回呼方法。

處理程式函式應該建立 MethodResponse ，並將它傳遞給send_method_response ，以將直接方法回應通知傳送給呼叫的應用程式。

此範例會設定名為的 method_request_handler直接方法處理程式。

try:
    # Attach the handler to the client
    client.on_method_request_received = method_request_handler
except:
    # In the event of failure, clean up
    client.shutdown()

在此範例中 method_request_handler ，回呼方法會在裝置上實作直接方法。從服務應用程式呼叫「rebootDevice」直接方法時，會執行程序代碼。方法會呼叫 send_method_response ，以將直接方法回應通知傳送給呼叫端應用程式。

# Define the handler for method requests
def method_request_handler(method_request):
    if method_request.name == "rebootDevice":
        # Act on the method by rebooting the device
        print("Rebooting device")
        time.sleep(20)
        print("Device rebooted")
        # Create a method response indicating the method request was resolved
        resp_status = 200
        resp_payload = {"Response": "This is the response from the device"}
        method_response = MethodResponse(method_request.request_id, resp_status, resp_payload)
    else:
        # Create a method response indicating the method request was for an unknown method
        resp_status = 404
        resp_payload = {"Response": "Unknown method"}
        method_response = MethodResponse(method_request.request_id, resp_status, resp_payload)

    # Send the method response
    client.send_method_response(method_response)

SDK 裝置範例

適用於 Python 的 Azure IoT SDK 提供可處理直接方法工作的裝置應用程式範例。如需詳細資訊，請參閱接收直接方法。

建立後端應用程式

本節說明如何使用後端服務應用程式在裝置上呼叫直接方法。

IoTHubRegistryManager 類別會公開建立後端應用程式以將訊息傳送至裝置所需的所有方法。

服務 import 陳述式

新增這些匯入語句以連線到IoT中樞、傳送雲端到裝置直接方法，以及接收裝置直接方法回應。

from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import CloudToDeviceMethod, CloudToDeviceMethodResult

連線至 IoT 中樞

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

共用存取原則
Microsoft Entra

重要

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

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

使用 from_connection_string 連線到 IoT 中樞。

若要透過 IoT 中樞在裝置上叫用直接方法，則服務需要有服務連線權限。根據預設，每個 IoT 中樞都是透過授與此權限且名為服務的共用存取原則所建立。

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

例如：

# Connect to IoT hub
IOTHUB_CONNECTION_STRING = "{IoT hub service connection string}"
iothub_registry_manager = IoTHubRegistryManager.from_connection_string(IOTHUB_CONNECTION_STRING)

使用 Microsoft Entra 進行連線

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

如需 Python SDK 驗證的概觀，請參閱使用適用於 Python 的 Azure SDK 向 Azure 服務驗證 Python 應用程式

設定 Microsoft Entra 應用程式

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

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

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

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

使用 DefaultAzureCredential 進行驗證

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

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

Microsoft Entra 需要此匯入套件和對應的 import 語句：

pip install azure-identity

from azure.identity import DefaultAzureCredential

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

from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()

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

IoTHubRegistryManager，以使用 Entra 令牌認證建立與 IoT 中樞的服務連線。
IoTHubJobManager
DigitalTwinClient
IoTHubHttpRuntimeManager
IoTHubConfigurationManager

from_token_credential 需要兩個參數：

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

在此範例中，會使用 DefaultAzureCredential取得 Azure 認證。接著會提供 Azure 服務 URL 和認證，IoTHubRegistryManager.from_token_credential以建立 IoT 中樞的連線。

import sys
import os

from azure.identity import DefaultAzureCredential
from azure.iot.hub import IoTHubRegistryManager

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

# Set environment variables
os.environ['AZURE_CLIENT_SECRET'] = clientSecretValue
os.environ['AZURE_CLIENT_ID'] = clientID
os.environ['AZURE_TENANT_ID'] = tenantID

# Acquire a credential object
credential = DefaultAzureCredential()

# Use Entra to authorize IoT Hub service
print("Connecting to IoTHubRegistryManager...")
iothub_registry_manager = IoTHubRegistryManager.from_token_credential(
url="MyAzureDomain.azure-devices.net",
token_credential=credential)

程式碼範例

如需Microsoft Entra 服務驗證的工作範例，請參閱適用於 Python 的Microsoft驗證連結庫（MSAL）。

在裝置上叫用方法

您可以在裝置上依名稱叫用直接方法。方法名稱會識別方法。在建立直接方法回呼中顯示的下列和先前裝置範例中，直接方法名稱為 “rebootDevice”。

若要在裝置上叫用直接方法：

建立 CloudToDeviceMethod 物件。提供方法名稱和承載做為參數。
呼叫 invoke_device_method 以在裝置上叫用直接方法。提供裝置標識碼和 CloudToDeviceMethod 承載物件做為參數。

此範例會呼叫 CloudToDeviceMethod 以在裝置上叫用名為「rebootDevice」的直接方法。成功叫用直接方法之後，會顯示直接方法響應承載。

CONNECTION_STRING = "{IoTHubConnectionString}"
DEVICE_ID = "{deviceId}"

METHOD_NAME = "rebootDevice"
METHOD_PAYLOAD = "{\"method_number\":\"42\"}"
TIMEOUT = 60
WAIT_COUNT = 10

try:
    print ( "" )
    print ( "Invoking device to reboot..." )

    # Call the direct method.
    deviceMethod = CloudToDeviceMethod(method_name=METHOD_NAME, payload=METHOD_PAYLOAD)
    response = registry_manager.invoke_device_method(DEVICE_ID, deviceMethod)

    print ( "Successfully invoked the device to reboot." )

    print ( "The device has returned this payload:" )
    print ( response.payload )

except Exception as ex:
    print ( "" )
    print ( "Unexpected error {0}".format(ex) )
    return

SDK 服務範例

適用於 Python 的 Azure IoT SDK 提供可處理直接方法工作之服務應用程式的工作範例。如需詳細資訊，請參閱

需要Node.js 10.0.x 版或更新版本

概觀

本文說明如何使用適用於 Node.js 的 Azure IoT SDK，為裝置直接方法建立裝置和後端服務應用程式程式代碼。

建立裝置應用程式

本節說明如何使用裝置應用程式程式代碼來建立直接方法回呼。

安裝 SDK 套件

azure-iot-device 套件包含與 IoT 裝置互動的物件。執行此命令，在開發電腦上安裝 azure-iot-device 裝置 SDK：

npm install azure-iot-device --save

選擇傳輸通訊協定

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);
  }
})

建立直接方法回呼

呼叫 onDeviceMethod 來建立回呼處理程式函式或協同程式，該函式會在收到直接方法時呼叫。接聽程式與方法名稱關鍵詞相關聯，例如「重新啟動」。方法名稱可用於 IoT 中樞或後端應用程式中，以觸發裝置上的回呼方法。

回呼處理程式函式應該呼叫 response.send ，將回應通知訊息傳送至呼叫端應用程式。

本範例會設定名為的直接方法處理程式，該 onReboot 處理程式會在使用「重新啟動」直接方法名稱時呼叫。

client.onDeviceMethod('reboot', onReboot);

在此範例中 onReboot ，回呼方法會在裝置上實作直接方法。從服務應用程式呼叫「重新啟動」直接方法時，會執行程序代碼。函式會呼叫 response.send ，以將回應通知訊息傳送至呼叫端應用程式。

var onReboot = function(request, response) {

    // Respond the cloud app for the direct method
    response.send(200, 'Reboot started', function(err) {
        if (err) {
            console.error('An error occurred when sending a method response:\n' + err.toString());
        } else {
            console.log('Response to method \'' + request.methodName + '\' sent successfully.');
        }
    });

    // Add your device's reboot API for physical restart.
    console.log('Rebooting!');
};

SDK 裝置範例

適用於 Node.js的 Azure IoT SDK 提供處理裝置管理工作的裝置應用程式工作範例。如需詳細資訊，請參閱

建立後端應用程式

本節說明如何在裝置上叫用直接方法。

安裝服務 SDK 套件

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

npm install azure-iothub --save

連線至 IoT 中樞

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

共用存取原則
Microsoft Entra

重要

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

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

使用 fromConnectionString 連線到 IoT 中樞。

若要透過 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 ID 控制對 IoT 中樞的存取。

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

設定 Microsoft Entra 應用程式

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

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

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

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

使用 DefaultAzureCredential 進行驗證

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

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 身分識別範例。

在裝置上叫用方法

使用 invokeDeviceMethod 依名稱在裝置上叫用直接方法。方法名稱參數會識別直接方法。

此範例會呼叫「reboot」方法來起始裝置上的重新啟動。「重新啟動」方法會對應至裝置上的回呼處理程式函式，如本文的建立直接方法回呼一節所述。

var startRebootDevice = function(deviceToReboot) {

    var methodName = "reboot";

    var methodParams = {
        methodName: methodName,
        payload: null,
        timeoutInSeconds: 30
    };

    client.invokeDeviceMethod(deviceToReboot, methodParams, function(err, result) {
        if (err) {
            console.error("Direct method error: "+err.message);
        } else {
            console.log("Successfully invoked the device to reboot.");  
        }
    });
};

SDK 服務範例

適用於 Node.js的 Azure IoT SDK 提供處理裝置管理工作之服務應用程式的工作範例。如需詳細資訊，請參閱

共用方式為

裝置管理入門

必要條件

概觀

建立裝置應用程式

必要的裝置 NuGet 套件

連線到裝置

建立直接方法回呼接聽程式

SDK 裝置範例

建立後端應用程式

必要的服務 NuGet 套件

連線至 IoT 中樞

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

使用 Microsoft Entra 進行連線

設定 Microsoft Entra 應用程式

使用 DefaultAzureCredential 進行驗證

程式碼範例

在裝置上叫用方法

SDK 服務範例

概觀

建立裝置應用程式

裝置匯入語句

連線到裝置

建立直接方法回呼接聽程式

SDK 裝置範例

建立後端應用程式

服務 import 陳述式

連線至 IoT 中樞

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

使用 Microsoft Entra 進行連線

設定 Microsoft Entra 應用程式

使用 DefaultAzureCredential 進行驗證

使用 ClientSecretCredentialBuilder 進行驗證

其他驗證類別

程式碼範例

在裝置上叫用方法

SDK 服務範例

概觀

安裝套件

建立裝置應用程式

裝置 import 陳述式

連線到裝置

建立直接方法回呼

SDK 裝置範例

建立後端應用程式

服務 import 陳述式

連線至 IoT 中樞

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

使用 Microsoft Entra 進行連線

設定 Microsoft Entra 應用程式

使用 DefaultAzureCredential 進行驗證

程式碼範例

在裝置上叫用方法

SDK 服務範例

概觀

建立裝置應用程式

安裝 SDK 套件

選擇傳輸通訊協定

建立用戶端物件

建立通訊協議物件

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

開啟連線到 IoT 中樞

建立直接方法回呼

SDK 裝置範例

建立後端應用程式

安裝服務 SDK 套件

連線至 IoT 中樞

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

使用 Microsoft Entra 進行連線

設定 Microsoft Entra 應用程式

使用 DefaultAzureCredential 進行驗證

程式碼範例

在裝置上叫用方法

SDK 服務範例

意見反應

其他資源