ジョブをスケジュールしてブロードキャストする方法

• Visual Studio が必要です

概要

この記事では、Azure IoT SDK for .NET を使用してバックエンド サービス アプリケーション コードを作成し、ダイレクト メソッドを呼び出すか、1 つ以上のデバイスでデバイス ツインの更新を実行するためのジョブをスケジュールする方法について説明します。

サービス NuGet パッケージを追加する

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

ステートメントの使用

次の using ステートメントを追加します。

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

using System.Threading;
using System.Threading.Tasks;

IoT Hub に接続する

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

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

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

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

この記事では、ダイレクト メソッドを呼び出すジョブをスケジュールし、デバイス ツインを更新するジョブをスケジュールし、1 つ以上のデバイスのジョブの進行状況を監視できるバックエンド コードについて説明します。 これらの操作を実行するには、サービスにレジストリ読み取りおよびレジストリ書き込みのアクセス許可が必要です。 既定では、すべての IoT ハブは、これらのアクセス許可を付与する registryReadWrite という名前の共有アクセス ポリシーがある状態で作成されます。

共有アクセス ポリシーの詳細については、「Shared Access Signature を使用して IoT Hub へのアクセスを制御する」を参照してください。

static JobClient jobClient;
static string connectionString = "{Shared access policy connection string}";
jobClient = JobClient.CreateFromConnectionString(connString);

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

• JobClient
• RegistryManager
• DigitalTwinClient
• ServiceClient

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

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

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

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

コード サンプル

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

ダイレクト メソッド ジョブをスケジュールする

ScheduleDeviceMethodAsync を使用して、1 つまたは複数のデバイスでダイレクト メソッドを実行するようにジョブをスケジュールします。

CloudToDeviceMethod オブジェクトを使用して、ダイレクト メソッド名とデバイス接続タイムアウト値を指定します。

次に例を示します。

// The CloudToDeviceMethod record specifies the direct method name and device connection time-out
CloudToDeviceMethod directMethod = 
new CloudToDeviceMethod("LockDoor", TimeSpan.FromSeconds(5), 
TimeSpan.FromSeconds(5));

次の例は、"Device-1" という名前の 1 つのデバイスで、"LockDoor" という名前のダイレクト メソッドのジョブをスケジュールします。 スケジュールされたジョブに含まれるデバイスは、クエリ条件として 2 番目のパラメーターに含まれています。 クエリ条件の詳細については、「デバイス ツイン、モジュール ツイン、ジョブ、メッセージ ルーティングの IoT Hub クエリ言語」を参照してください。

string methodJobId = Guid.NewGuid().ToString();  // a unique job ID
static string deviceId = "Device-1";             // In this example, there is only one device affected
JobResponse result = await jobClient.ScheduleDeviceMethodAsync(methodJobId,
   $"DeviceId IN ['{deviceId}']",
   directMethod,
   DateTime.UtcNow,
   (long)TimeSpan.FromMinutes(2).TotalSeconds);

デバイス ツインの更新ジョブをスケジュールする

ScheduleTwinUpdateAsync を使用して、新しいデバイス ツインの目的のプロパティとタグの更新ジョブを 1 つ以上のデバイスで実行するようにスケジュールします。

まず、更新プログラムのデバイス ツイン オブジェクトを作成して事前設定します。 次に例を示します。

static string deviceId = "Device-1";

Twin twin = new Twin(deviceId);
twin.Tags = new TwinCollection();
twin.Tags["Building"] = "43";
twin.Tags["Floor"] = "3";
twin.ETag = "*";
twin.Properties.Desired["LocationUpdate"] = DateTime.UtcNow;

次に、ScheduleTwinUpdateAsync を呼び出します。 2 番目のパラメーターで、更新するデバイスをクエリとして指定します。 クエリ条件の詳細については、「デバイス ツイン、モジュール ツイン、ジョブ、メッセージ ルーティングの IoT Hub クエリ言語」を参照してください。

string twinJobId = Guid.NewGuid().ToString();

JobResponse createJobResponse = jobClient.ScheduleTwinUpdateAsync(
   twinJobId,
   $"DeviceId IN ['{deviceId}']", 
   twin, 
   DateTime.UtcNow, 
   (long)TimeSpan.FromMinutes(2).TotalSeconds).Result;

ジョブを監視する

GetJobAsync を使用して、特定のジョブ ID のジョブの状態を監視します。

この例では、ジョブの状態が完了または失敗になるまで、ジョブ ID のジョブの状態を定期的に調べます。 次に例を示します。

JobResponse result;
do
{
   result = await jobClient.GetJobAsync(jobId);
   Console.WriteLine("Job Status : " + result.Status.ToString());
   Thread.Sleep(2000);
} while ((result.Status != JobStatus.Completed) && (result.Status != JobStatus.Failed));

SDK スケジュール ジョブの例

Azure IoT SDK for .NET には、ジョブ スケジュール タスクを処理するサービス アプリの実践的なサンプルが用意されています。 詳細については、以下を参照してください:

• ツイン更新のスケジュールのサンプル
• E2E ツイン更新のスケジュールのサンプル。

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

概要

この記事では、Azure IoT SDK for Java を使用してバックエンド サービス アプリケーション コードを作成し、ダイレクト メソッドを呼び出すか、1 つ以上のデバイスでデバイス ツインの更新を実行するためのジョブをスケジュールする方法について説明します。

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

JobClient クラスには、サービスがジョブのスケジュールに使用できるメソッドが含まれています。

次のサービス インポート ステートメントを使用して、Azure IoT SDK for Java にアクセスします。

import com.microsoft.azure.sdk.iot.service.devicetwin.DeviceTwinDevice;
import com.microsoft.azure.sdk.iot.service.devicetwin.Pair;
import com.microsoft.azure.sdk.iot.service.devicetwin.Query;
import com.microsoft.azure.sdk.iot.service.devicetwin.SqlQuery;
import com.microsoft.azure.sdk.iot.service.jobs.JobClient;
import com.microsoft.azure.sdk.iot.service.jobs.JobResult;
import com.microsoft.azure.sdk.iot.service.jobs.JobStatus;

import java.util.Date;
import java.time.Instant;
import java.util.HashSet;
import java.util.Set;
import java.util.UUID;

IoT ハブに接続します

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

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

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

JobClient コンストラクターを使用して、IoT Hub への接続を作成します。 JobClient オブジェクトは、IoT Hub との通信を処理します。

この記事では、ダイレクト メソッドを呼び出すジョブをスケジュールし、デバイス ツインを更新するジョブをスケジュールし、1 つ以上のデバイスのジョブの進行状況を監視できるバックエンド コードについて説明します。 これらの操作を実行するには、サービスにレジストリ読み取りおよびレジストリ書き込みのアクセス許可が必要です。 既定では、すべての IoT ハブは、これらのアクセス許可を付与する registryReadWrite という名前の共有アクセス ポリシーがある状態で作成されます。

共有アクセス ポリシーの詳細については、「Shared Access Signature を使用して IoT Hub へのアクセスを制御する」を参照してください。

次に例を示します。

public static final String iotHubConnectionString = "{Shared access policy connection string}";
JobClient jobClient = new JobClient(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 でバックエンド アプリを認証する次のクラスも含まれています。

• AuthorizationCodeCredential
• AzureCliCredential
• AzureDeveloperCliCredential
• AzurePipelinesCredential
• ChainedTokenCredential
• ClientAssertionCredential
• ClientCertificateCredential
• DeviceCodeCredential
• EnvironmentCredential
• InteractiveBrowserCredential
• ManagedIdentityCredential
• OnBehalfOfCredential

コード サンプル

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

ダイレクト メソッドの更新ジョブをスケジュールする

scheduleDeviceMethod を使用して、1 つまたは複数のデバイスでダイレクト メソッドを実行します。

次のメソッドの例は、"Device-1" という名前の 1 つのデバイスで、"lockDoor" という名前のダイレクト メソッドのジョブをスケジュールします。

// Schedule a job now to call the lockDoor direct method
// against a single device. Response and connection
// timeouts are set to 5 seconds.
String deviceId = "Device-1";
String jobId = "DMCMD" + UUID.randomUUID();  //Job ID must be unique

// How long the job is permitted to run without
// completing its work on the set of devices
private static final long maxExecutionTimeInSeconds = 30;

System.out.println("Schedule job " + jobId + " for device " + deviceId);
try {
  JobResult jobResult = jobClient.scheduleDeviceMethod(jobId,
    "deviceId='" + deviceId + "'",
    "lockDoor",
    5L, 5L, null,
    new Date(),
    maxExecutionTimeInSeconds);
} catch (Exception e) {
  System.out.println("Exception scheduling direct method job: " + jobId);
  System.out.println(e.getMessage());
}

デバイス ツインの更新ジョブをスケジュールする

scheduleUpdateTwin を使用して、1 つまたは複数のデバイスでデバイス ツインの更新を実行するジョブをスケジュールします。

まず、デバイス ツインの更新用に DeviceTwinDevice レコードを準備します。 次に例を示します。

String deviceId = "Device-1";

//Create a device twin desired properties update object
DeviceTwinDevice twin = new DeviceTwinDevice(deviceId);
Set<Pair> desiredProperties = new HashSet<Pair>();
desiredProperties.add(new Pair("Building", 43));
desiredProperties.add(new Pair("Floor", 3));
twin.setDesiredProperties(desiredProperties);
// Optimistic concurrency control
twin.setETag("*");

次に、scheduleUpdateTwin を呼び出して更新ジョブをスケジュールします。 次に例を示します。

String jobId = "DPCMD" + UUID.randomUUID();  //Unique job ID

// How long the job is permitted to run without
// completing its work on the set of devices
private static final long maxExecutionTimeInSeconds = 30;

// Schedule the update twin job to run now for a single device
System.out.println("Schedule job " + jobId + " for device " + deviceId);
try {
  JobResult jobResult = jobClient.scheduleUpdateTwin(jobId, 
    "deviceId='" + deviceId + "'",
    twin,
    new Date(),
    maxExecutionTimeInSeconds);
} catch (Exception e) {
  System.out.println("Exception scheduling desired properties job: " + jobId);
  System.out.println(e.getMessage());
}

ジョブを監視する

getJob を使用して、特定のジョブ ID に基づいてジョブ情報を取得します。 getJob は、実行中の状態を含むジョブ情報の確認に使用できるメソッドとプロパティが含まれている JobResult オブジェクトを返します。

次に例を示します。

try {
  JobResult jobResult = jobClient.getJob(jobId);
  if(jobResult == null)
  {
    System.out.println("No JobResult for: " + jobId);
    return;
  }
  // Check the job result until it's completed
  while(jobResult.getJobStatus() != JobStatus.completed)
  {
    Thread.sleep(100);
    jobResult = jobClient.getJob(jobId);
    System.out.println("Status " + jobResult.getJobStatus() + " for job " + jobId);
  }
  System.out.println("Final status " + jobResult.getJobStatus() + " for job " + jobId);
} catch (Exception e) {
  System.out.println("Exception monitoring job: " + jobId);
  System.out.println(e.getMessage());
  return;
}

ジョブの状態のクエリを実行する

queryDeviceJob を使用して、1 つ以上のジョブの状態を問い合わせる。

次に例を示します。

private static void queryDeviceJobs(JobClient jobClient, String start) throws Exception {
  System.out.println("\nQuery device jobs since " + start);

  // Create a jobs query using the time the jobs started
  Query deviceJobQuery = jobClient
      .queryDeviceJob(SqlQuery.createSqlQuery("*", SqlQuery.FromType.JOBS, "devices.jobs.startTimeUtc > '" + start + "'", null).getQuery());

  // Iterate over the list of jobs and print the details
  while (jobClient.hasNextJob(deviceJobQuery)) {
    System.out.println(jobClient.getNextJob(deviceJobQuery));
  }
}

SDK スケジュール ジョブの例

Azure IoT SDK for Java には、ジョブ スケジュール タスクを処理するサービス アプリの実践的なサンプルが用意されています。 詳細については、Job クライアントのサンプルに関するページを参照してください。

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

概要

この記事では、Azure IoT SDK for Python を使用してバックエンド サービス アプリケーション コードを作成し、ダイレクト メソッドを呼び出すか、1 つ以上のデバイスでデバイス ツインの目的のプロパティ更新を実行するためのジョブをスケジュールする方法について説明します。

パッケージのインストール

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

pip install azure-iot-hub

import ステートメント

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

次の import ステートメントを追加します。

import os
import sys
import datetime
import time
import threading
import uuid
import msrest

from azure.iot.hub import IoTHubJobManager
from azure.iot.hub.models import JobProperties, JobRequest, Twin, TwinProperties, CloudToDeviceMethod

IoT Hub に接続する

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

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

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

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

この記事では、ダイレクト メソッドを呼び出すジョブをスケジュールし、デバイス ツインを更新するジョブをスケジュールし、1 つ以上のデバイスのジョブの進行状況を監視できるバックエンド コードについて説明します。 これらの操作を実行するには、サービスにレジストリ読み取りおよびレジストリ書き込みのアクセス許可が必要です。 既定では、すべての IoT ハブは、これらのアクセス許可を付与する registryReadWrite という名前の共有アクセス ポリシーがある状態で作成されます。

共有アクセス ポリシーの詳細については、「Shared Access Signature を使用して IoT Hub へのアクセスを制御する」を参照してください。

次に例を示します。

IoTHubConnectionString = "{Shared access policy connection string}"
iothub_job_manager = IoTHubJobManager.from_connection_string(IoTHubConnectionString)

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

• JobClient
• RegistryManager
• DigitalTwinClient
• ServiceClient

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

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

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

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

コード サンプル

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

ダイレクト メソッド ジョブをスケジュールする

create_scheduled_job を使用して、1 つまたは複数のデバイスでダイレクト メソッドを実行するように新しいダイレクト メソッドをスケジュールします。

create_scheduled_job パラメーターの注意事項:

• job_id は一意である必要があります
• type を scheduleDeviceMethodに設定する
• cloud_to_device_method を使用してダイレクト メソッドの名前とペイロードを設定します
• max_execution_time_in_seconds を使用して実行時間を秒単位で指定します
• query_condition を使用して、ダイレクト メソッド呼び出しに含めるデバイスを指定します。 クエリ条件の詳細については、「デバイス ツイン、モジュール ツイン、ジョブ、メッセージ ルーティングの IoT Hub クエリ言語」を参照してください。

次に例を示します。

METHOD_NAME = "lockDoor"
METHOD_PAYLOAD = "{\"lockTime\":\"10m\"}"
job_id = uuid.uuid4()
DEVICE_ID = "Device-1"
TIMEOUT = 60

job_request = JobRequest()
job_request.job_id = job_id
job_request.type = "scheduleDeviceMethod"
job_request.start_time = datetime.datetime.utcnow().isoformat()
job_request.cloud_to_device_method = CloudToDeviceMethod(method_name=METHOD_NAME, payload=METHOD_PAYLOAD)
job_request.max_execution_time_in_seconds = TIMEOUT
job_request.query_condition = "DeviceId in ['{}']".format(device_id)

new_job_response = iothub_job_manager.create_scheduled_job(job_id, job_request)

デバイス ツインの更新ジョブをスケジュールする

create_scheduled_job を使用して、1 つまたは複数のデバイスでデバイス ツインの目的のプロパティの更新を実行する新しいジョブを作成します。

create_scheduled_job パラメーターの注意事項:

• job_id は一意である必要があります
• type を scheduleUpdateTwinに設定する
• update_twin を使用してダイレクト メソッドの名前とペイロードを設定します
• max_execution_time_in_seconds を使用して実行時間を秒単位で指定します
• query_condition を使用して、ダイレクト メソッド呼び出しがある 1 つ以上のデバイスの条件を指定します。 クエリ条件の詳細については、「デバイス ツイン、モジュール ツイン、ジョブ、メッセージ ルーティングの IoT Hub クエリ言語」を参照してください。

次に例を示します。

UPDATE_PATCH = {"building":43,"floor":3}
job_id = uuid.uuid4()
TIMEOUT = 60

job_request = JobRequest()
job_request.job_id = job_id
job_request.type = "scheduleUpdateTwin"
job_request.start_time = datetime.datetime.utcnow().isoformat()
job_request.update_twin = Twin(etag="*", properties=TwinProperties(desired=UPDATE_PATCH))
job_request.max_execution_time_in_seconds = TIMEOUT
job_request.query_condition = "DeviceId in ['{}']".format(device_id)

new_job_response = iothub_job_manager.create_scheduled_job(job_id, job_request)

ジョブを監視する

get_scheduled_job を使用して、IoT Hub 上の特定のジョブの詳細を取得します。

この例では、ジョブが完了するまで 5 秒ごとに特定のジョブ ID のジョブの状態を確認します。

while True:
    get_job_response = iothub_job_manager.get_scheduled_job(job_request.job_id)
    print_job_response("Get job response: ", get_job_response)
    if get_job_response.status == "completed":
      print ( "Job is completed." )
    time.sleep(5)

SDK スケジュール ジョブの例

Azure IoT SDK for Python には、ジョブ スケジュール タスクを処理するサービス アプリの実践的なサンプルが用意されています。 詳細については、以下を参照してください:

• ダイレクト メソッド ジョブをスケジュールする
• デバイス ツインの更新をスケジュールする。

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

概要

この記事では、Azure IoT SDK for Node.js を使用してバックエンド サービス アプリケーション コードを作成し、ダイレクト メソッドを呼び出すか、1 つ以上のデバイスでデバイス ツインの更新を実行するためのジョブをスケジュールする方法について説明します。

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

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

npm install azure-iothub --save

JobClient クラスは、バックエンド アプリケーションからジョブ スケジュールを操作するために必要なすべてのメソッドを公開します。

IoT Hub に接続する

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

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

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

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

この記事では、ダイレクト メソッドを呼び出すジョブをスケジュールし、デバイス ツインを更新するジョブをスケジュールし、1 つ以上のデバイスのジョブの進行状況を監視できるバックエンド コードについて説明します。 これらの操作を実行するには、サービスにレジストリ読み取りおよびレジストリ書き込みのアクセス許可が必要です。 既定では、すべての IoT ハブは、これらのアクセス許可を付与する registryReadWrite という名前の共有アクセス ポリシーがある状態で作成されます。

共有アクセス ポリシーの詳細については、「Shared Access Signature を使用して IoT Hub へのアクセスを制御する」を参照してください。

次に例を示します。

'use strict';
var JobClient = require('azure-iothub').JobClient;
var connectionString = '{Shared access policy connection string}';
var jobClient = JobClient.fromConnectionString(connectionString);

Microsoft Entra を使用して接続する

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

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

• Azure でのユーザー認証の概要
• JavaScript 用 Azure ID クライアント ライブラリ

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 に渡すことができます。

• レジストリ
• クライアント
• JobClient

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

• Azure サービス URL - Azure サービスの URL は、{Your Entra ___domain URL}.azure-devices.net プレフィックスのない https:// 形式にする必要があります。 たとえば、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 の例に関するページを参照してください。

ダイレクト メソッド ジョブを作成する

scheduleDeviceMethod を使用して、1 つまたは複数のデバイスでダイレクト メソッドを実行するようにジョブをスケジュールします。

まず、メソッド名、ペイロード、応答タイムアウト情報を含むダイレクト メソッド更新変数を作成します。 次に例を示します。

var methodParams = {
    methodName: 'lockDoor',
    payload: null,
    responseTimeoutInSeconds: 15 // Time-out after 15 seconds if device is unable to process method
};

次に、scheduleDeviceMethod を呼び出して、ダイレクト メソッド呼び出しジョブをスケジュールします。

• 各ジョブには、一意のジョブ ID が必要です。 このジョブ ID を使用して、この記事の「ジョブを監視する」セクションの説明に従ってジョブを監視できます。
• ジョブを実行するデバイスを評価する queryCondition パラメーターを指定します。 クエリ条件の詳細については、「デバイス ツイン、モジュール ツイン、ジョブ、メッセージ ルーティングの IoT Hub クエリ言語」を参照してください。
• ジョブ スケジュールの結果の jobResult コールバックを確認します。 ジョブが正常にスケジュールされている場合は、この記事の「ジョブを監視する」セクションに示すように、ジョブの状態を監視できます。

次に例を示します。

var methodJobId = uuid.v4();
var queryCondition = "deviceId IN ['myDeviceId']";
var startTime = new Date();
var maxExecutionTimeInSeconds =  300;

jobClient.scheduleDeviceMethod(methodJobId,
                            queryCondition,
                            methodParams,
                            startTime,
                            maxExecutionTimeInSeconds,
                            function(err) {
    if (err) {
        console.error('Could not schedule direct method job: ' + err.message);
    } else {
        monitorJob(methodJobId, function(err, result) {
            if (err) {
                console.error('Could not monitor direct method job: ' + err.message);
            } else {
                console.log(JSON.stringify(result, null, 2));
            }
        });
    }
});

デバイス ツインの更新ジョブをスケジュールする

scheduleTwinUpdate を使用して、1 つまたは複数のデバイスでデバイス ツインの更新を実行する新しいジョブを作成します。

まず、デバイス ツインの「望ましいプロパティ更新用の変数」を作成します。

var twinPatch = {
   etag: '*',
   properties: {
       desired: {
           building: '43',
           floor: 3
       }
   }
};

次に、scheduleTwinUpdate を呼び出して、デバイス ツインの目的のプロパティ更新ジョブをスケジュールします。

• 各ジョブには、一意のジョブ ID が必要です。 このジョブ ID を使用して、この記事の「ジョブを監視する」セクションの説明に従ってジョブを監視できます。
• ジョブを実行するデバイスを評価する queryCondition パラメーターを指定します。 クエリ条件の詳細については、「デバイス ツイン、モジュール ツイン、ジョブ、メッセージ ルーティングの IoT Hub クエリ言語」を参照してください。
• jobResult コールバックでジョブ スケジュールの結果を調べます。 ジョブが正常にスケジュールされている場合は、この記事の「ジョブを監視する」セクションに示すように、ジョブの状態を監視できます。

次に例を示します。

var twinJobId = uuid.v4();
var queryCondition = "deviceId IN ['myDeviceId']";
var startTime = new Date();
var maxExecutionTimeInSeconds =  300;

console.log('scheduling Twin Update job with id: ' + twinJobId);
jobClient.scheduleTwinUpdate(twinJobId,
                            queryCondition,
                            twinPatch,
                            startTime,
                            maxExecutionTimeInSeconds,
                            function(err) {
    if (err) {
        console.error('Could not schedule twin update job: ' + err.message);
    } else {
        monitorJob(twinJobId, function(err, result) {
            if (err) {
                console.error('Could not monitor twin update job: ' + err.message);
            } else {
                console.log(JSON.stringify(result, null, 2));
            }
        });
    }
});

ジョブを監視する

getJob を使用して、特定のジョブ ID のジョブの状態を監視します。

この例の関数では、ジョブが [完了] または [失敗] になるまで、特定のジョブ ID のジョブの状態を定期的に確認します。

function monitorJob (jobId, callback) {
    var jobMonitorInterval = setInterval(function() {
        jobClient.getJob(jobId, function(err, result) {
        if (err) {
            console.error('Could not get job status: ' + err.message);
        } else {
            console.log('Job: ' + jobId + ' - status: ' + result.status);
            if (result.status === 'completed' || result.status === 'failed' || result.status === 'cancelled') {
            clearInterval(jobMonitorInterval);
            callback(null, result);
            }
        }
        });
    }, 5000);
}

SDK スケジュール ジョブの例

Azure IoT SDK for Node.js には、ジョブ スケジュール タスクを処理するサービス アプリの実践的なサンプルが用意されています。 詳細については、ジョブ クライアントの E2E テストに関するページを参照してください。