次の方法で共有

デバイス管理の開始

  • [アーティクル]

バックエンド アプリでは、Azure IoT Hub プリミティブ (デバイス ツインやダイレクト メソッドなど) を使用して、デバイス上のデバイス管理アクションをリモートで開始および監視できます。

バックエンド アプリケーションからダイレクト メソッドを使用して、デバイス管理操作 (再起動、出荷時の設定に戻す、ファームウェアの更新など) を開始します。

デバイスは次の操作を担当します。

  • IoT Hub から送信されたダイレクト メソッド要求の処理
  • デバイスでの対応するデバイス固有の操作の開始
  • 報告されるプロパティを介した IoT Hub への状態更新の提供

このアーティクルでは、バックエンド アプリとデバイス アプリをどのように連携させると、ダイレクト メソッドを使用してデバイスのアクションをリモートで開始してモニターできるかについて示します。

  • サービス アプリは、IoT ハブを介してデバイス アプリで再起動するためにダイレクト メソッドを呼び出します。
  • デバイス アプリは、デバイスを再起動するためにダイレクト メソッドを処理します。

Note

この記事で説明されている機能は、Standard レベルの IoT Hub でのみ使用できます。 Basic および Standard または Free レベルの IoT Hub の詳細については、ソリューションに適した IoT Hub のレベルの選択に関するページを参照してください。

Note

この記事は、この記事内から参照される Azure IoT SDK サンプルを補完するためのものです。 SDK ツールを使用して、デバイス アプリケーションとバックエンド アプリケーションの両方を構築できます。

前提条件

  • IoT ハブ

  • 登録済みのデバイス

  • アプリケーションが MQTT プロトコルを使用している場合は、必ずファイアウォールのポート 8883 を開きます。 MQTT プロトコルはポート 8883 経由で通信します。 このポートは、企業や教育用のネットワーク環境によってはブロックされている場合があります。 この問題の詳細と対処方法については、「IoT Hub への接続 (MQTT)」を参照してください。

  • Visual Studio が必要です

概要

この記事では、Azure IoT SDK for .NET を使用して、デバイス ダイレクト メッセージ用のデバイスおよびバックエンド サービス アプリケーション コードを作成する方法について説明します。

デバイス アプリケーションを作成する

このセクションでは、デバイス アプリケーション コードを使用してダイレクト メソッド コールバック リスナーを作成する方法について説明します。

重要

この記事では、Shared Access Signature (対称キー認証とも呼ばれます) を使用してデバイスを接続する手順について説明します。 この認証方法はテストと評価には便利ですが、X.509 証明書を使用してデバイスを認証する方が安全なアプローチです。 詳細については、「セキュリティのベスト プラクティス」>「接続のセキュリティ」をご覧ください。

必要なデバイス NuGet パッケージ

C# で記述されたデバイス クライアント アプリケーションには、Microsoft.Azure.Devices.Client NuGet パッケージが必要です。

次の using ステートメントを追加して、デバイス ライブラリを使用します。

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

デバイスへの接続

DeviceClient クラスは、デバイスからデバイス メッセージとやりとりするために必要なすべてのメソッドを公開しています。

CreateFromConnectionString メソッドと共にデバイス接続文字列と接続トランスポート プロトコルを使用してデバイスに接続します。

CreateFromConnectionStringTransportType トランスポート プロトコル パラメーターは、次のトランスポート プロトコルをサポートしています。

  • 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 を使用して、ダイレクト メソッド コールバック リスナーを初期化します。 リスナーは、"reboot" などのメソッド名キーワードに関連付けられています。 メソッド名を IoT Hub またはバックエンド アプリケーションで使用して、デバイスのコールバック メソッドをトリガーできます。

この例では、"reboot" ダイレクト メソッド名が呼び出されたときにトリガーされる、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));
}

Note

わかりやすくするために、この記事では再試行ポリシーは実装しません。 運用コードでは、「一時的な障害の処理」で推奨されているように、再試行ポリシー (エクスポネンシャル バックオフなど) を実装してください。

SDK デバイス サンプル

Azure IoT SDK for .NET には、ダイレクト メソッド タスクを処理するデバイス アプリの作業サンプルが用意されています。 詳細については、以下を参照してください:

バックエンド アプリケーションを作成する

このセクションでは、デバイスでダイレクト メソッドをトリガーする方法について説明します。

ServiceClient クラスは、バックエンド アプリケーションを作成するために必要なすべてのメソッドを公開して、デバイスにダイレクト メソッド呼び出しを送信します。

必要なサービス NuGet パッケージ

バックエンド サービス アプリケーションには、Microsoft.Azure.Devices NuGet パッケージが必要です。

次の using ステートメントを追加して、サービス ライブラリを使用します。

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

IoT Hub に接続する

次の方法を使用して、バックエンド サービスを IoT Hub に接続できます。

  • 共有アクセス ポリシー
  • Microsoft Entra

重要

この記事では、Shared Access Signature を使用してサービスに接続する手順について説明しています。 この認証方法はテストと評価には便利ですが、サービスに対する認証方法としては、Microsoft Entra ID またはマネージド ID を使用する方が安全です。 詳細については、「セキュリティのベスト プラクティス」の「クラウドのセキュリティ」 を参照してください。>

共有アクセス ポリシーを使用して接続する

CreateFromConnectionString を使用して、バックエンド アプリケーションを接続します。

IoT Hub を介してデバイス上で直接メソッドを呼び出すには、サービスにサービス接続アクセス許可が必要です。 既定では、どの IoT Hub も、このアクセス許可を付与する service という名前の共有アクセス ポリシーがある状態で作成されます。

CreateFromConnectionString するパラメーターとして、サービス 共有アクセス ポリシーを指定します。 共有アクセス ポリシーの詳細については、「Shared Access Signature を使用して IoT Hub へのアクセスを制御する」を参照してください。

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

Microsoft Entra を使用して接続する

Microsoft Entra を使用するバックエンド アプリは、IoT Hub に接続する前に、認証に成功してセキュリティ トークンの資格情報を取得する必要があります。 このトークンは、IoT Hub 接続メソッドに渡されます。 IoT Hub 用の Microsoft Entra の設定と使用に関する一般的な情報については、「Microsoft Entra ID を使用した IoT Hub へのアクセス制御」を参照してください。

Microsoft Entra アプリを構成する

優先する認証資格情報用に構成された Microsoft Entra アプリを設定する必要があります。 このアプリには、バックエンド アプリケーションで認証に使用されるクライアント シークレットなどのパラメーターが含まれています。 使用可能なアプリ認証構成は次のとおりです。

  • クライアント シークレット
  • [証明書]
  • フェデレーション ID 資格情報

Microsoft Entra アプリでは、実行される操作に応じて、特定のロールのアクセス許可が必要になる場合があります。 たとえば、IoT Hub デバイスとモジュール ツインへの読み取りと書き込みアクセスを有効にするには、IoT Hub ツイン共同作成者が必要です。 詳細については、「Azure RBAC ロールの割り当てを使用して IoT Hub へのアクセスを管理する」を参照してください。

Microsoft Entra アプリの設定の詳細については、「クイック スタート: Microsoft ID プラットフォームにアプリケーションを登録する」を参照してください。

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 アプリ登録のクライアント シークレット、クライアント ID、テナント ID が環境変数に追加されます。 これらの環境変数は、アプリケーションを認証するために DefaultAzureCredential で使用されます。 Microsoft Entra 認証が成功した結果、セキュリティ トークン資格情報が IoT Hub 接続メソッドに渡されます。

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 Hub メソッドに接続するために渡すことができます。

次の例では、ServiceClient 接続オブジェクトを作成するために、TokenCredential が ServiceClient.Create に渡されます。

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

次の例では、RegistryManager オブジェクトを作成するために、TokenCredential が RegistryManager.Create に渡されます。

string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);
コード サンプル

Microsoft Entra サービス認証の作業サンプルについては、ロール ベースの認証のサンプルのページを参照してください。

デバイスのメソッドの呼び出し

デバイスでメソッドを呼び出すには:

  1. CloudToDeviceMethod オブジェクトを作成します。 デバイス ダイレクト メソッド名をパラメーターとして渡します。
  2. InvokeDeviceMethodAsync を呼び出して、デバイスでメソッドを呼び出します。

この例では、"reboot" メソッドを呼び出して、デバイスで再起動を開始します。 "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 サービスのサンプル

Azure IoT SDK for .NET には、メッセージ タスクを処理するサービス アプリの作業サンプルが用意されています。 詳細については、以下を参照してください:

  • Java SE Development Kit 8 が必要です。 必ず「長期サポート」の「Java 8」を選択して JDK 8 のダウンロードに移動します。

概要

この記事では、Azure IoT SDK for Java を使用して、デバイス ダイレクト メソッド用のデバイスおよびバックエンド サービス アプリケーション コードを作成する方法について説明します。

デバイス アプリケーションを作成する

このセクションでは、デバイス アプリケーション コードを使用してダイレクト メソッド コールバック リスナーを作成する方法について説明します。

重要

この記事では、Shared Access Signature (対称キー認証とも呼ばれます) を使用してデバイスを接続する手順について説明します。 この認証方法はテストと評価には便利ですが、X.509 証明書を使用してデバイスを認証する方が安全なアプローチです。 詳細については、「セキュリティのベスト プラクティス」>「接続のセキュリティ」をご覧ください。

デバイス インポート ステートメント

次のデバイス インポート ステートメントを使用して、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 クラスは、デバイスのダイレクト メソッドとやりとりするのに必要なすべてのメソッドを公開しています。

デバイスに接続するには:

  1. IotHubClientProtocol を使用して、トランスポート プロトコルを選択します。 次に例を示します。

    IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;

  2. DeviceClient コンストラクターを使用して、デバイスのプライマリ接続文字列とプロトコルを追加します。

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

  3. open を使用して、デバイスを IoT Hub に接続します。 クライアントが既に開いている場合、メソッドは何も行いません。

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

Note

わかりやすくするために、この記事では再試行ポリシーは実装しません。 運用コードでは、「一時的な障害の処理」で推奨されているように、再試行ポリシー (エクスポネンシャル バックオフなど) を実装してください。

SDK デバイス サンプル

Azure IoT SDK for Java には、この記事で説明されているデバイス アプリの概念をテストするための動作するサンプルが含まれています。 詳細については、ダイレクト メソッドのサンプルを参照してください。

バックエンド アプリケーションを作成する

このセクションでは、ダイレクト メソッドを使用してデバイスでリモート再起動を開始する方法について説明します。

ServiceClient DeviceMethod クラスには、サービスがデバイス ツインにアクセスするために使用できるメソッドが含まれています。

サービス インポート ステートメント

次のサービス インポート ステートメントを使用して、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 Hub に接続する

次の方法を使用して、バックエンド サービスを IoT Hub に接続できます。

  • 共有アクセス ポリシー
  • Microsoft Entra

重要

この記事では、Shared Access Signature を使用してサービスに接続する手順について説明しています。 この認証方法はテストと評価には便利ですが、サービスに対する認証方法としては、Microsoft Entra ID またはマネージド ID を使用する方が安全です。 詳細については、「セキュリティのベスト プラクティス」の「クラウドのセキュリティ」 を参照してください。>

共有アクセス ポリシーを使用して接続する

DeviceMethod コンストラクターを使用して、サービスのプライマリ接続文字列を追加し、IoT ハブに接続します。

IoT Hub を介してデバイス上で直接メソッドを呼び出すには、サービスにサービス接続アクセス許可が必要です。 既定では、どの IoT Hub も、このアクセス許可を付与する service という名前の共有アクセス ポリシーがある状態で作成されます。

DeviceMethod パラメーターに対するパラメーターとして、サービス 共有アクセス ポリシーを指定します。 共有アクセス ポリシーの詳細については、「Shared Access Signature を使用して IoT Hub へのアクセスを制御する」を参照してください。

次に例を示します。

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

Microsoft Entra を使用して接続する

Microsoft Entra を使用するバックエンド アプリは、IoT Hub に接続する前に、認証に成功してセキュリティ トークンの資格情報を取得する必要があります。 このトークンは、IoT Hub 接続メソッドに渡されます。 IoT Hub 用の Microsoft Entra の設定と使用に関する一般的な情報については、「Microsoft Entra ID を使用した IoT Hub へのアクセス制御」を参照してください。

Java SDK 認証の概要については、「Java と Azure ID を使用した Azure 認証」を参照してください。

わかりやすくするために、このセクションでは、クライアント シークレットを使用した認証について説明します。

Microsoft Entra アプリを構成する

優先する認証資格情報用に構成された Microsoft Entra アプリを設定する必要があります。 このアプリには、バックエンド アプリケーションで認証に使用されるクライアント シークレットなどのパラメーターが含まれています。 使用可能なアプリ認証構成は次のとおりです。

  • クライアント シークレット
  • [証明書]
  • フェデレーション ID 資格情報

Microsoft Entra アプリでは、実行される操作に応じて、特定のロールのアクセス許可が必要になる場合があります。 たとえば、IoT Hub デバイスとモジュール ツインへの読み取りと書き込みアクセスを有効にするには、IoT Hub ツイン共同作成者が必要です。 詳細については、「Azure RBAC ロールの割り当てを使用して IoT Hub へのアクセスを管理する」を参照してください。

Microsoft Entra アプリの設定の詳細については、「クイック スタート: Microsoft ID プラットフォームにアプリケーションを登録する」を参照してください。

DefaultAzureCredential を使用して認証する

Microsoft Entra を使用してバックエンド アプリケーションを認証する最も簡単な方法は、DefaultAzureCredential を使用することですが、特定の TokenCredential や削減された ChainedTokenCredential など、運用環境では別の方法を使用することをお勧めします。 DefaultAzureCredential を使用する長所と短所の詳細については、「Java 用 Azure ID クライアント ライブラリの資格情報チェーン」を参照してください。

DefaultAzureCredential では、さまざまな認証メカニズムがサポートされ、実行されている環境に基づいて適切な資格情報の種類が決まります。 有効な資格情報が見つかるまで、複数の種類の資格情報の使用を順番に試みます。

Microsoft Entra アプリの資格情報は、DefaultAzureCredentialBuilder を使用して認証できます。 クライアント シークレット tenantID、clientID、クライアント シークレットの値などの接続パラメーターを環境変数として保存します。 TokenCredential が作成されたら、それを 'credential' パラメーターとして ServiceClient またはその他のビルダーに渡します。

この例では、DefaultAzureCredentialBuilder は、DefaultAzureCredential で説明されている一覧から接続の認証を試みます。 Microsoft Entra 認証が成功した結果として、セキュリティ トークン資格情報が ServiceClient などのコンストラクターに渡されます。

TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build();
ClientSecretCredentialBuilder を使用して認証する

クライアント シークレット情報を使用して資格情報を作成するには、ClientSecretCredentialBuilder を使用できます。 成功した場合、このメソッドは ServiceClient またはその他のビルダーに 'credential' パラメーターとして渡すことができる TokenCredential を返します。

この例では、Microsoft Entra アプリ登録のクライアント シークレット、クライアント ID、テナント ID の値が環境変数に追加されました。 これらの環境変数は、資格情報を構築するために 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" メソッドを呼び出して、デバイスで再起動を開始します。 "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 サービスのサンプル

Azure IoT SDK for Java には、ダイレクト メソッド タスクを処理するサービス アプリの動作するサンプルが用意されています。 詳細については、以下を参照してください:

  • Python SDK - Python バージョン 3.7 以降をお勧めします。 必ず、セットアップに必要な 32 ビットまたは 64 ビットのインストールを使用してください。 インストール中に求められた場合は、プラットフォーム固有の環境変数に Python を追加します。

概要

この記事では、Azure IoT SDK for Python を使用して、デバイス ダイレクト メソッド用のデバイスおよびバックエンド サービス アプリケーション コードを作成する方法について説明します。

パッケージをインストールする

デバイス アプリケーションを作成するには、azure-iot-device ライブラリがインストールされていなければなりません。

pip install azure-iot-device

バックエンド サービス アプリケーションを作成するには、azure-iot-hub ライブラリがインストールされていなければなりません。

pip install azure-iot-hub

デバイス アプリケーションを作成する

このセクションでは、デバイス アプリケーション コードを使用してダイレクト メソッド コールバック リスナーを作成する方法について説明します。

重要

この記事では、Shared Access Signature (対称キー認証とも呼ばれます) を使用してデバイスを接続する手順について説明します。 この認証方法はテストと評価には便利ですが、X.509 証明書を使用してデバイスを認証する方が安全なアプローチです。 詳細については、「セキュリティのベスト プラクティス」>「接続のセキュリティ」をご覧ください。

デバイス インポート ステートメント

このインポート ステートメントを追加して、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 を使用して、ダイレクト メソッドの受信時に呼び出されるハンドラー関数またはコルーチンを作成します。 リスナーは、"reboot" などのメソッド名キーワードに関連付けられています。 メソッド名を IoT Hub またはバックエンド アプリケーションで使用して、デバイスのコールバック メソッドをトリガーできます。

ハンドラー関数は、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 デバイス サンプル

Azure IoT SDK for Python には、ダイレクト メソッド タスクを処理するデバイス アプリの動作するサンプルが用意されています。 詳細については、ダイレクト メソッドを受信するを参照してください。

バックエンド アプリケーションを作成する

このセクションでは、バックエンド サービス アプリケーションを使用してデバイスでダイレクト メソッドを呼び出す方法について説明します。

IoTHubRegistryManager クラスは、メッセージをデバイスに送信するバックエンド アプリケーションを作成するために必要なすべてのメソッドを公開しています。

サービス インポート ステートメント

これらのインポート ステートメントを追加して、IoT Hub に接続し、cloud-to-device ダイレクト メソッドを送信し、デバイス ダイレクト メソッドの応答を受信します。

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

IoT Hub に接続する

次の方法を使用して、バックエンド サービスを IoT Hub に接続できます。

  • 共有アクセス ポリシー
  • Microsoft Entra

重要

この記事では、Shared Access Signature を使用してサービスに接続する手順について説明しています。 この認証方法はテストと評価には便利ですが、サービスに対する認証方法としては、Microsoft Entra ID またはマネージド ID を使用する方が安全です。 詳細については、「セキュリティのベスト プラクティス」の「クラウドのセキュリティ」 を参照してください。>

共有アクセス ポリシーを使用して接続する

from_connection_string を使用して、IoT Hub に接続します。

IoT Hub を介してデバイス上で直接メソッドを呼び出すには、サービスにサービス接続アクセス許可が必要です。 既定では、どの IoT Hub も、このアクセス許可を付与する service という名前の共有アクセス ポリシーがある状態で作成されます。

from_connection_string に対するパラメーターとして、サービス 共有アクセス ポリシーを指定します。 共有アクセス ポリシーの詳細については、「Shared Access Signature を使用して IoT Hub へのアクセスを制御する」を参照してください。

次に例を示します。

# 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 Hub に接続する前に、認証に成功してセキュリティ トークンの資格情報を取得する必要があります。 このトークンは、IoT Hub 接続メソッドに渡されます。 IoT Hub 用の Microsoft Entra の設定と使用に関する一般的な情報については、「Microsoft Entra ID を使用した IoT Hub へのアクセス制御」を参照してください。

Python SDK 認証の概要については、「Azure SDK for Python を使用して Azure サービスに対して Python アプリを認証する方法」を参照してください

Microsoft Entra アプリを構成する

優先する認証資格情報用に構成された Microsoft Entra アプリを設定する必要があります。 このアプリには、バックエンド アプリケーションで認証に使用されるクライアント シークレットなどのパラメーターが含まれています。 使用可能なアプリ認証構成は次のとおりです。

  • クライアント シークレット
  • [証明書]
  • フェデレーション ID 資格情報

Microsoft Entra アプリでは、実行される操作に応じて、特定のロールのアクセス許可が必要になる場合があります。 たとえば、IoT Hub デバイスとモジュール ツインへの読み取りと書き込みアクセスを有効にするには、IoT Hub ツイン共同作成者が必要です。 詳細については、「Azure RBAC ロールの割り当てを使用して IoT Hub へのアクセスを管理する」を参照してください。

Microsoft Entra アプリの設定の詳細については、「クイック スタート: Microsoft ID プラットフォームにアプリケーションを登録する」を参照してください。

DefaultAzureCredential を使用して認証する

Microsoft Entra を使用してバックエンド アプリケーションを認証する最も簡単な方法は、DefaultAzureCredential を使用することですが、特定の TokenCredential や削減された ChainedTokenCredential など、運用環境では別の方法を使用することをお勧めします。 わかりやすくするために、このセクションでは、 DefaultAzureCredential とクライアント シークレットを使用した認証について説明します。 DefaultAzureCredential を使用する長所と短所の詳細については、「Python 用 Azure ID クライアント ライブラリの資格情報チェーン」を参照してください。

DefaultAzureCredential では、さまざまな認証メカニズムがサポートされ、実行されている環境に基づいて適切な資格情報の種類が決まります。 有効な資格情報が見つかるまで、複数の種類の資格情報の使用を順番に試みます。

Microsoft Entra には、次の Import パッケージと、対応する import ステートメントが必要です。

pip install azure-identity

from azure.identity import DefaultAzureCredential

この例では、Microsoft Entra アプリ登録のクライアント シークレット、クライアント ID、テナント ID が環境変数に追加されました。 これらの環境変数は、アプリケーションを認証するために DefaultAzureCredential で使用されます。 Microsoft Entra 認証が成功した結果、セキュリティ トークン資格情報が IoT Hub 接続メソッドに渡されます。

from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()

結果として得られる AccessToken は、Microsoft Entra 資格情報を受け入れる SDK クライアントの IoT Hub に接続するために from_token_credential に渡すことができます。

from_token_credential には、次の 2 つのパラメーターが必要です。

  • Azure サービス URL - Azure サービスの URL は、https:// プレフィックスのない {Your Entra domain URL}.azure-devices.net 形式にする必要があります。 たとえば、MyAzureDomain.azure-devices.net のようにします。
  • Azure 資格情報トークン

次の例では、Azure 資格情報は DefaultAzureCredential を使用して取得されます。 その後、Azure サービスの URL と資格情報が IoTHubRegistryManager.from_token_credential に指定され、IoT Hub への接続が作成されます。

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" です。

デバイスに対してダイレクト メソッドを呼び出すには、次のようにします。

  1. CloudToDeviceMethod オブジェクトを作成します。 メソッド名とペイロードをパラメーターとして指定します。
  2. invoke_device_method を呼び出して、デバイスでダイレクト メソッドを呼び出します。 デバイス ID と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 サービスのサンプル

Azure IoT SDK for Python には、ダイレクト メソッド タスクを処理するサービス アプリの作業サンプルが用意されています。 詳細については、以下を参照してください:

  • Node.js バージョン 10.0.x 以降が必要です。

概要

この記事では、Azure IoT SDK for Node.js を使用して、デバイス ダイレクト メソッド用のデバイスおよびバックエンド サービス アプリケーション コードを作成する方法について説明します。

デバイス アプリケーションを作成する

このセクションでは、デバイス アプリケーション コードを使用してダイレクト メソッド コールバックを作成する方法について説明します。

SDK パッケージをインストールする

azure-iot-device パッケージには、IoT デバイスとやり取りするオブジェクトが含まれています。 次のコマンドを実行して、開発マシンに azure-iot-device デバイス SDK をインストールします。

npm install azure-iot-device --save

トランスポート プロトコルを選択する

Client オブジェクトでは、次のプロトコルがサポートされます。

  • Amqp
  • Http - Http を使用する場合、Client インスタンスは IoT Hub からのメッセージを頻繁にはチェックしません (少なくとも 25 分ごと)。
  • Mqtt
  • MqttWs
  • AmqpWs

必要なトランスポート プロトコルを開発マシンにインストールします。

たとえば、次のコマンドを使用すると、Amqp プロトコルをインストールできます。

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

MQTT、AMQP、および HTTPS のサポートの相違点の詳細については、「cloud-to-device 通信に関するガイダンス」と「通信プロトコルの選択」を参照してください。

クライアント オブジェクトの作成

インストールされたパッケージを使用して 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 Hub への接続を開く

open メソッドを使用して、IoT デバイスと IoT Hub の間の接続を開きます。

次に例を示します。

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

ダイレクト メソッド コールバックを作成する

onDeviceMethod を呼び出して、ダイレクト メソッドの受信時に呼び出されるコールバック ハンドラー関数またはコルーチンを作成します。 リスナーは、"reboot" などのメソッド名キーワードに関連付けられています。 メソッド名を IoT Hub またはバックエンド アプリケーションで使用して、デバイスのコールバック メソッドをトリガーできます。

コールバック ハンドラー関数は、response.send を呼び出して、呼び出し元のアプリケーションに応答確認メッセージを送信します。

この例では、"reboot" ダイレクト メソッド名が使用されたときに呼び出される、onReboot という名前のダイレクト メソッド ハンドラーを設定します。

client.onDeviceMethod('reboot', onReboot);

この例では、onReboot コールバック メソッドがデバイスにダイレクト メソッドを実装します。 このコードは、サービス アプリケーションから "reboot" ダイレクト メソッドが呼び出されたときに実行されます。 この関数は、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 デバイス サンプル

Azure IoT SDK for Node.js には、デバイス管理タスクを処理するデバイス アプリの作業サンプルが用意されています。 詳細については、以下を参照してください:

バックエンド アプリケーションを作成する

このセクションでは、デバイスでダイレクト メソッドを呼び出す方法について説明します。

サービス SDK パッケージをインストールする

次のコマンドを実行して、開発マシンに azure-iothub をインストールします。

npm install azure-iothub --save

IoT Hub に接続する

次の方法を使用して、バックエンド サービスを IoT Hub に接続できます。

  • 共有アクセス ポリシー
  • Microsoft Entra

重要

この記事では、Shared Access Signature を使用してサービスに接続する手順について説明しています。 この認証方法はテストと評価には便利ですが、サービスに対する認証方法としては、Microsoft Entra ID またはマネージド ID を使用する方が安全です。 詳細については、「セキュリティのベスト プラクティス」の「クラウドのセキュリティ」 を参照してください。>

共有アクセス ポリシーを使用して接続する

fromConnectionString を使用して IoT Hub に接続します。

IoT Hub を介してデバイス上で直接メソッドを呼び出すには、サービスにサービス接続アクセス許可が必要です。 既定では、どの IoT Hub も、このアクセス許可を付与する service という名前の共有アクセス ポリシーがある状態で作成されます。

CreateFromConnectionString に対するパラメーターとして、サービス 共有アクセス ポリシー接続文字列を指定します。 共有アクセス ポリシーの詳細については、「Shared Access Signature を使用して IoT Hub へのアクセスを制御する」を参照してください。

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 Hub に接続する前に、認証に成功してセキュリティ トークンの資格情報を取得する必要があります。 このトークンは、IoT Hub 接続メソッドに渡されます。 IoT Hub 用の Microsoft Entra の設定と使用に関する一般的な情報については、「Microsoft Entra ID を使用した IoT Hub へのアクセス制御」を参照してください。

Node.js SDK 認証の概要については、次を参照してください。

Microsoft Entra アプリを構成する

優先する認証資格情報用に構成された Microsoft Entra アプリを設定する必要があります。 このアプリには、バックエンド アプリケーションで認証に使用されるクライアント シークレットなどのパラメーターが含まれています。 使用可能なアプリ認証構成は次のとおりです。

  • クライアント シークレット
  • [証明書]
  • フェデレーション ID 資格情報

Microsoft Entra アプリでは、実行される操作に応じて、特定のロールのアクセス許可が必要になる場合があります。 たとえば、IoT Hub デバイスとモジュール ツインへの読み取りと書き込みアクセスを有効にするには、IoT Hub ツイン共同作成者が必要です。 詳細については、「Azure RBAC ロールの割り当てを使用して IoT Hub へのアクセスを管理する」を参照してください。

Microsoft Entra アプリの設定の詳細については、「クイック スタート: Microsoft ID プラットフォームにアプリケーションを登録する」を参照してください。

DefaultAzureCredential を使用して認証する

Microsoft Entra を使用してバックエンド アプリケーションを認証する最も簡単な方法は、DefaultAzureCredential を使用することですが、特定の TokenCredential や削減された ChainedTokenCredential など、運用環境では別の方法を使用することをお勧めします。 わかりやすくするために、このセクションでは、 DefaultAzureCredential とクライアント シークレットを使用した認証について説明します。 DefaultAzureCredential を使用する長所と短所の詳細については、「JavaScript 用 Azure ID クライアント ライブラリの資格情報チェーン」を参照してください

DefaultAzureCredential では、さまざまな認証メカニズムがサポートされ、実行されている環境に基づいて適切な資格情報の種類が決まります。 有効な資格情報が見つかるまで、複数の種類の資格情報の使用を順番に試みます。

Microsoft Entra には、次のパッケージが必要です。

npm install --save @azure/identity

この例では、Microsoft Entra アプリ登録のクライアント シークレット、クライアント ID、テナント ID が環境変数に追加されました。 これらの環境変数は、アプリケーションを認証するために DefaultAzureCredential で使用されます。 Microsoft Entra 認証が成功した結果、セキュリティ トークン資格情報が IoT Hub 接続メソッドに渡されます。

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

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

結果として得られる資格情報トークンは、Microsoft Entra 資格情報を受け入れる SDK クライアントの IoT Hub に接続するために fromTokenCredential に渡すことができます。

fromTokenCredential には、次の 2 つのパラメーターが必要です。

  • Azure サービス URL - Azure サービスの URL は、https:// プレフィックスのない {Your Entra domain URL}.azure-devices.net 形式にする必要があります。 たとえば、MyAzureDomain.azure-devices.net のようにします。
  • Azure 資格情報トークン

次の例では、Azure 資格情報は DefaultAzureCredential を使用して取得されます。 その後、Azure ドメインの URL と資格情報が Registry.fromTokenCredential に指定され、IoT Hub への接続が作成されます。

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 ID の例に関するページを参照してください。

デバイスのメソッドの呼び出し

invokeDeviceMethod を使用して、デバイス上で名前でダイレクト メソッドを呼び出します。 ダイレクト メソッドは、メソッド名パラメーターによって識別されます。

この例では、"reboot" メソッドを呼び出して、デバイスで再起動を開始します。 "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 サービスのサンプル

Azure IoT SDK for Node.js には、デバイス管理タスクを処理するサービス アプリの作業サンプルが用意されています。 詳細については、以下を参照してください: