IoT Hub のモジュール ID とモジュール ID ツインの概要

[アーティクル]
12/04/2024

モジュール ID とモジュール ID ツインは、Azure IoT Hub のデバイス ID とデバイスツインに似ていますが、より細かい粒度を指定できます。 Azure IoT Hub のデバイス ID とデバイスツインを使用した場合、バックエンドアプリケーションからデバイスを構成し、デバイスの状態を可視化できるのに対し、モジュール ID とモジュール ID ツインでは、デバイスのコンポーネントごとにこれらの機能を実現できます。複数のコンポーネントで構成され、この機能をサポートしているデバイス (オペレーティングシステムデバイスやファームウェアデバイスなど) では、モジュール ID とモジュール ID ツインにより、各コンポーネントの構成と状態を分離することができます。詳細については、Azure IoT Hub モジュールツインについての記事を参照してください。

Note

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

この記事では、次の 2 種類のアプリケーションを開発する方法について説明します。

モジュール ID ツインの報告されたプロパティを表示および更新し、必要なプロパティを更新する要求を処理するデバイスアプリ。
モジュール ID の必要なプロパティを読み取って設定できるサービスアプリ。

Note

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

前提条件

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

Visual Studio が必要です

概要

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

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

このセクションでは、デバイスアプリケーションコードを使用して次のことを行う方法について説明します。

モジュール ID ツインを取得し、報告されたプロパティを確認する
報告されたモジュール ID ツインのプロパティを更新する
モジュールの必要なプロパティ更新コールバックハンドラーを作成する

重要

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

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

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

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

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

デバイスへの接続

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

CreateFromConnectionString メソッドをモジュール ID 接続文字列と一緒に使用して、デバイスに接続します。

トランスポートパラメーターを指定せずに CreateFromConnectionString を呼び出すと、既定の AMQP トランスポートを使用して接続されます。

この例では、既定の AMQP トランスポートを使用してデバイスに接続します。

static string ModuleConnectionString = "{Device module identity connection string}";
private static ModuleClient _moduleClient = null;

_moduleClient = ModuleClient.CreateFromConnectionString(ModuleConnectionString, null);

モジュール ID ツインを取得し、プロパティを確認する

GetTwinAsync を呼び出して、現在のモジュール ID ツインのプロパティを Twin オブジェクトに取得します。

この例では、モジュール ID ツインのプロパティを取得して JSON 形式で表示します。

Console.WriteLine("Retrieving twin...");
Twin twin = await _moduleClient.GetTwinAsync();
Console.WriteLine("\tModule identity twin value received:");
Console.WriteLine(JsonConvert.SerializeObject(twin.Properties));

モジュール ID ツインの報告されたプロパティを更新する

ツインの報告されたプロパティを更新するには:

報告されたプロパティの更新用に TwinCollection オブジェクトを作成します
TwinCollection オブジェクト内の報告されたプロパティを 1 つ以上更新します
UpdateReportedPropertiesAsync を使用して、報告されたプロパティの変更を IoT Hub サービスにプッシュします

次に例を示します。

try
{
  Console.WriteLine("Sending sample start time as reported property");
  TwinCollection reportedProperties = new TwinCollection();
  reportedProperties["DateTimeLastAppLaunch"] = DateTime.UtcNow;
  await _moduleClient.UpdateReportedPropertiesAsync(reportedProperties);
}
catch (Exception ex)
{
   Console.WriteLine();
   Console.WriteLine("Error in sample: {0}", ex.Message);
}

必要なプロパティ更新コールバックハンドラーを作成する

コールバックハンドラーメソッド名を SetDesiredPropertyUpdateCallbackAsync に渡して、必要なプロパティがモジュール ID ツインで変更されたときに実行される必要なプロパティ更新コールバックハンドラーを作成します。

たとえば、この呼び出しを使用して、必要なモジュールプロパティが変更されるたびに、OnDesiredPropertyChangedAsync というメソッドに通知するようにシステムを設定します。

await _moduleClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChangedAsync, null);

モジュール ID ツインのプロパティは、TwinCollection としてコールバックメソッドに渡され、KeyValuePair 構造体として調べることができます。

この例では、必要なプロパティの更新を TwinCollection として受け取り、ループ処理して KeyValuePair コレクションの更新を出力します。 KeyValuePair コレクションをループ処理した後、コードで UpdateReportedPropertiesAsync を呼び出して、報告された DateTimeLastDesiredPropertyChangeReceived プロパティを更新し、最終更新時刻を最新の状態に保ちます。

private async Task OnDesiredPropertyChangedAsync(TwinCollection desiredProperties, object userContext)
{
   var reportedProperties = new TwinCollection();

   Console.WriteLine("\tDesired properties requested:");
   Console.WriteLine($"\t{desiredProperties.ToJson()}");

   // For the purpose of this sample, we'll blindly accept all twin property write requests.
   foreach (KeyValuePair<string, object> desiredProperty in desiredProperties)
   {
         Console.WriteLine($"Setting {desiredProperty.Key} to {desiredProperty.Value}.");
         reportedProperties[desiredProperty.Key] = desiredProperty.Value;
   }

   Console.WriteLine("\tAlso setting current time as reported property");
   reportedProperties["DateTimeLastDesiredPropertyChangeReceived"] = DateTime.UtcNow;

   await _moduleClient.UpdateReportedPropertiesAsync(reportedProperties);
}

SDK モジュールのサンプル

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

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

このセクションでは、モジュール ID フィールドの読み取りと更新を行う方法について説明します。

RegistryManager クラスは、サービスからモジュール ID ツインと対話するバックエンドアプリケーションを作成するために必要なすべてのメソッドを公開しています。

必要なサービス 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 に接続します。

このセクションで使用する UpdateModuleAsync メソッドには、必要なプロパティをモジュールに追加するのに、サービス接続の共有アクセスポリシーアクセス許可が必要です。 CreateFromConnectionString のパラメーターとして、サービス接続アクセス許可を含む共有アクセスポリシーの接続文字列を指定します。共有アクセスポリシーの詳細については、「Shared Access Signature を使用して IoT Hub へのアクセスを制御する」を参照してください。

次に例を示します。

static RegistryManager registryManager;
static string connectionString = "{IoT hub shared access policy connection string}";
registryManager = RegistryManager.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 サービス認証の作業サンプルについては、ロールベースの認証のサンプルのページを参照してください。

モジュール ID フィールドの読み取りと更新

GetModuleAsync を呼び出して、現在のモジュール ID ツインフィールドを Module オブジェクトに取得します。

Module クラスには、モジュール ID ツインのセクションに対応する properties が含まれています。モジュール ID ツインフィールドを表示および更新するには、Module クラスのプロパティを使用します。 UpdateModuleAsync を使用してデバイスに更新を書き込む前に、Module オブジェクトのプロパティを使用して複数のフィールドを更新できます。

モジュール ID ツインフィールドを更新した後、UpdateModuleAsync を呼び出して、Module オブジェクトフィールドの更新をデバイスに書き込みます。 try と catch のロジックをエラーハンドラーと組み合わせて使用し、正しくない形式のパッチエラーを UpdateModuleAsync からキャッチします。

次の例では、モジュールを Module オブジェクトに取得し、module LastActivityTime プロパティを更新してから、UpdateModuleAsync を使用して IoT Hub のモジュールを更新します。

// Retrieve the module
var module = await registryManager.GetModuleAsync("myDeviceId","myModuleId");

// Update the module object
module.LastActivityTime = DateTime.Now;

// Apply the patch to update the device twin tags section
try
{
   await registryManager.UpdateModuleAsync(module);
}
catch (Exception e)
{
   console.WriteLine("Module update failed.", e.Message);
}

その他のモジュール API

GetModulesOnDeviceAsync - デバイス上のモジュール ID を取得します
RemoveModuleAsync - 以前に登録されたモジュールをデバイスから削除します

SDK サービスのサンプル

Azure IoT SDK for .NET には、モジュール ID ツインタスクを処理するサービスアプリの作業サンプルが用意されています。詳細については、レジストリマネージャー E2E テストのページを参照してください。

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

概要

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

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

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

pip install azure-iot-device

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

pip install azure-iot-hub

msrest ライブラリは、HTTPOperationError 例外をキャッチするために使用されます。

pip install msrest

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

このセクションでは、デバイスアプリケーションコードを使用して次のことを行う方法について説明します。

モジュール ID ツインを取得し、報告されたプロパティを確認する
モジュール ID ツインの報告されたプロパティを更新する
モジュール ID ツインの必要なプロパティ更新コールバックハンドラーを作成する

重要

Import ステートメント

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

# import the device client library
import asyncio
from azure.iot.device.aio import IoTHubDeviceClient

デバイスへの接続

IoTHubModuleClient クラスには、モジュール ID ツインを操作するために使用できるメソッドが含まれています。

アプリケーションをデバイスに接続するには:

create_from_connection_string を呼び出して、モジュール ID 接続文字列を追加します
connect を呼び出して、デバイスクライアントを Azure IoT Hub に接続します

# import the device client library
import asyncio
from azure.iot.device.aio import IoTHubDeviceClient

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

# connect the application to the device
await device_client.connect()

モジュール ID ツインを取得し、プロパティを確認する

get_twin を呼び出して、Azure IoT Hub サービスからモジュール ID ツインを取得します。ツイン情報は、確認できる変数に配置されます。

この例では、デバイスツインを取得し、print コマンドを使用して JSON 形式でデバイスツインを表示します。

# get the twin
twin = await device_client.get_twin()
print("Twin document:")
print("{}".format(twin))

モジュール ID ツインの報告されたプロパティを更新する

パッチを適用して、JSON 形式で報告されたモジュール ID ツインのプロパティを更新できます。

パッチを適用して報告されたプロパティを更新するには:

報告されたプロパティの JSON パッチを変数に割り当てます。
patch_twin_reported_properties を呼び出して、報告されたプロパティに JSON パッチを適用します。

次に例を示します。

# create the reported properties patch
reported_properties = {"temperature": random.randint(320, 800) / 10}
print("Setting reported temperature to {}".format(reported_properties["temperature"]))
# update the reported properties and wait for the result
await device_client.patch_twin_reported_properties(reported_properties)

モジュール ID ツインの必要なプロパティ更新コールバックハンドラーを作成する

on_twin_desired_properties_patch_received を呼び出して、モジュール ID ツインの必要なプロパティパッチを受信したときに呼び出されるハンドラー関数またはコルーチンを作成します。このハンドラーは引数を 1 つ受け取ります。これは、JSON ディクショナリオブジェクトの形式のツインパッチです。

この例では、twin_patch_handler という必要なプロパティパッチのハンドラーを設定します。

次に例を示します。

try:
    # Set handlers on the client
    device_client.on_twin_desired_properties_patch_received = twin_patch_handler
except:
    # Clean up in the event of failure
    client.shutdown()

twin_patch_handler は、必要な JSON プロパティの更新を受信して出力します。

    # Define behavior for receiving twin desired property patches
    def twin_patch_handler(twin_patch):
        print("Twin patch received:")
        print(twin_patch)

SDK デバイスサンプル

Azure IoT SDK for Python には、モジュール ID ツインタスクを処理するデバイスアプリの作業サンプルが用意されています。

get_twin - デバイスに接続し、ツイン情報を取得します。
update_twin_reported_properties - ツインの報告されたプロパティを更新します。
receive_twin_desired_properties - 必要なプロパティを受信して更新します。

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

このセクションでは、モジュール ID ツインの必要なプロパティを取得および更新するためにバックエンドアプリケーションを作成する方法について説明します。

IoTHubRegistryManager クラスは、サービスからモジュール ID ツインと対話するバックエンドアプリケーションを作成するために必要なすべてのメソッドを公開しています。

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

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

import sys
from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import Twin, TwinProperties, QuerySpecification, QueryResult

IoT Hub に接続する

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

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

重要

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

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

このセクションで使用する update_module_twin メソッドには、必要なプロパティをモジュールに追加するのに、サービス接続の共有アクセスポリシーアクセス許可が必要です。 from_connection_string のパラメーターとして、サービス接続アクセス許可を含む共有アクセスポリシーの接続文字列を指定します。共有アクセスポリシーの詳細については、「Shared Access Signature を使用して IoT Hub へのアクセスを制御する」を参照してください。

次に例を示します。

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

Microsoft Entra を使用して接続する

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

Microsoft Entra アプリを構成する

クライアントシークレット
[証明書]
フェデレーション 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 に渡すことができます。

Entra トークン資格情報を使用して IoT Hub へのサービス接続を作成するための IoTHubRegistryManager。
IoTHubJobManager
DigitalTwinClient
IoTHubHttpRuntimeManager
IoTHubConfigurationManager

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)」を参照してください。

モジュール ID ツインの必要なプロパティを取得および更新する

update_module_twin を使用して、バックエンドアプリケーションから必要なプロパティを更新できます。

モジュール ID ツインの必要なプロパティを取得および更新するには:

get_module_twin を呼び出して、モジュール ID ツインの現在のバージョンを取得します。
Twin クラスを使用して、JSON 形式で必要なプロパティを追加します。
update_module_twin を呼び出して、デバイスツインにパッチを適用します。 replace_module_twin を使用して、モジュール ID ツインの必要なプロパティとタグを置き換えることもできます。

次の例では、必要なプロパティ telemetryInterval を 122 に更新します。

try:
    module_twin = iothub_registry_manager.get_module_twin(DEVICE_ID, MODULE_ID)
    print ( "" )
    print ( "Module identity twin properties before update:" )
    print ( "{0}".format(module_twin.properties) )

    # Update twin
    twin_patch = Twin()
    twin_patch.properties = TwinProperties(desired={"telemetryInterval": 122})
    updated_module_twin = iothub_registry_manager.update_module_twin(
        DEVICE_ID, MODULE_ID, twin_patch, module_twin.etag
    )
    print ( "" )
    print ( "Module identity twin properties after update     :" )
    print ( "{0}".format(updated_module_twin.properties) )

except Exception as ex:
    print ( "Unexpected error {0}".format(ex) )
except KeyboardInterrupt:
    print ( "IoTHubRegistryManager sample stopped" )

SDK サービスのサンプル

Azure IoT SDK for Python には、デバイス ID モジュールツインタスクを処理するサービスアプリの作業サンプルが用意されています。詳細については、IoTHub レジストリマネージャーのテストのページを参照してください。

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

概要

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

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

このセクションでは、Azure IoT SDK for Node.js の azure-iot-device パッケージを使用して、次のことを行うデバイスアプリケーションを作成する方法について説明します。

モジュール ID ツインを取得し、報告されたプロパティを確認する
モジュール ID ツインの報告されたプロパティを更新する
モジュール ID ツインの必要なプロパティ変更の通知を受け取る

重要

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

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

npm install azure-iot-device --save

azure-iot-device パッケージには、IoT デバイスとやり取りするオブジェクトが含まれています。 Twin クラスには、ツイン固有のオブジェクトが含まれています。このセクションでは、デバイスモジュール ID ツインデータの読み取りと書き込みに使用される Client クラスコードについて説明します。

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

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 - IoT Hub ID モジュールの接続文字列。
transportCtor - トランスポートプロトコル。

この例では、Amqp トランスポートプロトコルを使用します。

const deviceConnectionString = "{IoT hub identity module 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);
  }
})

モジュール ID ツインを取得し、報告されたプロパティを確認する

getTwin を呼び出して、現在のモジュール ID ツイン情報を Twin オブジェクトに取得します。

その後、デバイスのコードで、モジュール ID ツインのプロパティにアクセスできます。

次に例を示します。

// Retrieve the current module identity twin
client.getTwin(function(err, twin))
if (err)
    console.error('could not get twin');

// Display the current properties
console.log('twin contents:');
console.log(twin.properties);

モジュール ID ツインの報告されたプロパティを更新する

update を使用して、デバイスの報告されたプロパティを更新します。 JSON 形式のパッチを 1 つ目のパラメーターとして、関数実行状態のコールバックメソッドを 2 つ目のパラメーターとしてメソッドに含めます。

この例では、JSON 形式のモジュール ID ツインパッチが patch 変数に格納されます。パッチには、モジュール ID ツイン connectivity の更新値 cellular が含まれています。パッチとエラーハンドラーは update メソッドに渡されます。エラーがある場合は、コンソールのエラーメッセージが表示されます。

// Create a patch to send to IoT Hub
var patch = {
  updateTime: new Date().toString(),
  firmwareVersion:'1.2.1',
  weather:{
    temperature: 72,
    humidity: 17
  }
};

// Apply the patch
twin.properties.reported.update(patch, function(err)
  {
    if (err)
      {
        console.error('could not update twin');
      } 
    else
      {
        console.log('twin state reported');
        process.exit();
      }
  });

モジュール ID ツインの必要なプロパティ変更の通知を受け取る

コールバックハンドラーメソッド名を twin.on に渡して、必要なプロパティが変更されたときに実行されるモジュール ID ツインの必要なプロパティ更新イベントリスナーを作成します。

必要なプロパティイベントリスナーは、次のような形式になります。

1 つのイベントハンドラーですべてのパッチを受信する
プロパティグループで何か変更があった場合にイベントを受信する
1 つのプロパティ変更のイベントを受信する

1 つのイベントハンドラーですべてのパッチを受信する

必要なプロパティの変更を受け取るリスナーを作成できます。

このコード例は、サービスから受信したプロパティを出力します。

twin.on('properties.desired', function (delta) {
    console.log('new desired properties received:');
    console.log(JSON.stringify(delta));
});

プロパティグループで何か変更があった場合にイベントを受信する

プロパティグループの何かが変更された場合にイベントを受信するリスナーを作成できます。

次に例を示します。

minTemperature と maxTemperature の各プロパティは、properties.desired.climate changes というプロパティグループに属します。
バックエンドサービスアプリケーションは、このパッチを適用して、minTemperature と maxTemperature という必要なプロパティを更新します。
```
const twinPatch1 = {
properties: {
   desired: {
    climate: { minTemperature: 68, maxTemperature: 76, },
    },
  },
 };
```
このコードを使用して、properties.desired.climate プロパティグループ内で変更があった場合にトリガーされる必要なプロパティ変更イベントリスナーを設定します。このグループ内で必要なプロパティの変更があった場合、最小と最大の温度の変更メッセージがコンソールに表示されます。
```
twin.on('properties.desired.climate', function (delta) {
    if (delta.minTemperature || delta.maxTemperature) {
        console.log('updating desired temp:');
        console.log('min temp = ' + twin.properties.desired.climate.minTemperature);
        console.log('max temp = ' + twin.properties.desired.climate.maxTemperature);
    }
});
```

1 つのプロパティ変更のイベントを受信する

1 つのプロパティ変更に対してリスナーを設定できます。この例では、このイベントのコードは、fanOn ブール値がパッチの一部である場合にのみ実行されます。このコードを使用して、必要な fanOn の新しい状態がサービスによって更新されるたびに出力します。

バックエンドアプリケーションは、この必要なプロパティパッチを適用します。

 const twinPatch2 = {
  properties: {
    desired: {
      climate: {
        hvac: {
          systemControl: { fanOn: true, },
        },
      },
    },
  },
};

リスナーは、fanOn プロパティが変更された場合にのみトリガーします。

 twin.on('properties.desired.climate.hvac.systemControl', function (fanOn) {
     console.log('setting fan state to ' + fanOn);
  });

コード例全体

この例では、複数レベルのコールバック関数の入れ子を含めて、このセクションの原則がカプセル化されています。

var Client = require('azure-iot-device').Client;
var Protocol = require('azure-iot-device-amqp').Amqp;
// Copy/paste your module connection string here.
var connectionString = 'HostName=xxx.azure-devices.net;DeviceId=myFirstDevice2;ModuleId=myFirstModule2;SharedAccessKey=xxxxxxxxxxxxxxxxxx';
// Create a client using the Amqp protocol.
var client = Client.fromConnectionString(connectionString, Protocol);
client.on('error', function (err) {
  console.error(err.message);
});
// connect to the hub
client.open(function(err) {
  if (err) {
    console.error('error connecting to hub: ' + err);
    process.exit(1);
  }
  console.log('client opened');
// Create device Twin
  client.getTwin(function(err, twin) {
    if (err) {
      console.error('error getting twin: ' + err);
      process.exit(1);
    }
    // Output the current properties
    console.log('twin contents:');
    console.log(twin.properties);
    // Add a handler for desired property changes
    twin.on('properties.desired', function(delta) {
        console.log('new desired properties received:');
        console.log(JSON.stringify(delta));
    });
    // create a patch to send to the hub
    var patch = {
      updateTime: new Date().toString(),
      firmwareVersion:'1.2.1',
      weather:{
        temperature: 75,
        humidity: 20
      }
    };
    // send the patch
    twin.properties.reported.update(patch, function(err) {
      if (err) throw err;
      console.log('twin state reported');
    });

  });
});

Device SDK のサンプル

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

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

このセクションでは、モジュール ID ツインを取得し、必要なプロパティを更新するバックエンドアプリケーションを作成する方法について説明します。

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

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

npm install azure-iothub --save

Registry オブジェクトを作成する

Registry クラスは、バックエンドアプリケーションからモジュール ID ツインと対話するために必要なすべてのメソッドを公開しています。

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

IoT Hub に接続する

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

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

重要

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

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

このセクションで使用する update メソッドには、必要なプロパティをモジュールに追加するのに、サービス接続の共有アクセスポリシーアクセス許可が必要です。 fromConnectionString のパラメーターとして、サービス接続アクセス許可を含む共有アクセスポリシーの接続文字列を指定します。共有アクセスポリシーの詳細については、「Shared Access Signature を使用して IoT Hub へのアクセスを制御する」を参照してください。

let connectionString = '{IoT hub shared access policy connection string}';
let registry = Registry.fromConnectionString(serviceConnectionString);

Microsoft Entra を使用して接続する

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

Microsoft Entra アプリを構成する

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

DefaultAzureCredential を使用して認証する

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

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

npm install --save @azure/identity

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

モジュール ID ツインを取得し、必要なプロパティを更新する

モジュール ID ツインの必要なプロパティの更新を含むパッチを作成できます。

モジュール ID ツインを更新するには:

getModuleTwin を呼び出して、デバイス Twin オブジェクトを取得します。
モジュール ID ツインの更新を含むパッチの書式を設定します。「Twin クラス」で説明されているように、パッチは JSON 形式です。バックエンドサービスパッチには、必要なプロパティの更新が含まれます。パッチ形式の詳細については、「タグやプロパティの形式」を参照してください。
update を呼び出して、モジュール ID ツインをパッチで更新します。

この例では、myDeviceId および myModuleId のモジュール ID ツインが取得されます。その後、climate 情報を含むパッチがツインに適用されます。

// Insert your device ID and moduleId here.
var deviceId = 'myFirstDevice2';
var moduleId = 'myFirstModule2';

// Retrieve the current module identity twin
registry.getModuleTwin(deviceId, moduleId, function (err, twin) {
  console.log('getModuleTwin returned ' + (err ? err : 'success'));
  if (err) {
    console.log(err);
  } else {
    console.log('success');
    console.log('Current twin:' + JSON.stringify(twin))

    // Format a desired property patch
    const twinPatch1 = {
      properties: {
        desired: {
          climate: { minTemperature: 69, maxTemperature: 77, },
        },
      },
    };

    // Send the desired property patch to IoT Hub
    twin.update(twinPatch1, function(err) {
    if (err) throw err;
    console.log('twin state reported');
    });
  }
});

Service SDK のサンプル

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

次の方法で共有

IoT Hub のモジュール ID とモジュール ID ツインの概要

前提条件

概要

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

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

デバイスへの接続

モジュール ID ツインを取得し、プロパティを確認する

モジュール ID ツインの報告されたプロパティを更新する

必要なプロパティ更新コールバック ハンドラーを作成する

SDK モジュールのサンプル

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

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

IoT Hub への接続

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

Microsoft Entra を使用して接続する

Microsoft Entra アプリを構成する

DefaultAzureCredential を使用して認証する

コード サンプル

モジュール ID フィールドの読み取りと更新

その他のモジュール API

SDK サービスのサンプル

概要

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

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

Import ステートメント

デバイスへの接続

モジュール ID ツインを取得し、プロパティを確認する

モジュール ID ツインの報告されたプロパティを更新する

モジュール ID ツインの必要なプロパティ更新コールバック ハンドラーを作成する

SDK デバイス サンプル

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

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

IoT Hub に接続する

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

Microsoft Entra を使用して接続する

Microsoft Entra アプリを構成する

DefaultAzureCredential を使用して認証する

コード サンプル

モジュール ID ツインの必要なプロパティを取得および更新する

SDK サービスのサンプル

概要

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

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

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

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

プロトコル オブジェクトを作成する

デバイスの接続文字列とトランスポート プロトコルを追加する

IoT Hub への接続を開く

モジュール ID ツインを取得し、報告されたプロパティを確認する

モジュール ID ツインの報告されたプロパティを更新する

モジュール ID ツインの必要なプロパティ変更の通知を受け取る

1 つのイベント ハンドラーですべてのパッチを受信する

プロパティ グループで何か変更があった場合にイベントを受信する

1 つのプロパティ変更のイベントを受信する

コード例全体

Device SDK のサンプル

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

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

Registry オブジェクトを作成する

IoT Hub に接続する

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

Microsoft Entra を使用して接続する

Microsoft Entra アプリを構成する

DefaultAzureCredential を使用して認証する

コード サンプル

モジュール ID ツインを取得し、必要なプロパティを更新する

Service SDK のサンプル

フィードバック

その他のリソース

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

必要なプロパティ更新コールバックハンドラーを作成する

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

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

コードサンプル

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

モジュール ID ツインの必要なプロパティ更新コールバックハンドラーを作成する

SDK デバイスサンプル

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

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

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

コードサンプル

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

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

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

プロトコルオブジェクトを作成する

デバイスの接続文字列とトランスポートプロトコルを追加する

1 つのイベントハンドラーですべてのパッチを受信する

プロパティグループで何か変更があった場合にイベントを受信する

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

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

コードサンプル