次の方法で共有

複数のデバイスで Azure IoT Hub ジョブをスケジュールする

Azure IoT Hub を使用すると、デバイス ツインのプロパティやタグ、ダイレクト メソッドなど、さまざまな構成要素を実現できます。 通常、バックエンド アプリを使用すると、デバイス管理者とオペレーターは、スケジュールされた時刻に一括で IoT デバイスを更新および操作できます。 ジョブは、スケジュールされた時刻に一連のデバイスに対してデバイス ツインの更新とダイレクト メソッドを実行します。 たとえば、オペレーターは、ビル 43 とフロア 3 の一連のデバイスを一度に再起動するジョブを開始して追跡するバックエンド アプリを使用します。このアプリは、建物の操作に悪影響を及ぼしません。

注

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

一連のデバイスで次のいずれかのアクティビティをスケジュールして進行状況を追跡する必要がある場合は、ジョブの使用を検討してください。

  • 必要なプロパティを更新する
  • タグの更新
  • ダイレクト メソッドを呼び出す

ジョブのライフサイクル

ジョブはソリューション バックエンドによって開始され、IoT Hub によって管理されます。 サービス向け URI (PUT https://<iot hub>/jobs/v2/<jobID>?api-version=2021-04-12) を使用してジョブを開始し、サービス向け URI (GET https://<iot hub>/jobs/v2/<jobID?api-version=2021-04-12) を使用して実行中のジョブの進行状況を照会できます。 ジョブの開始後に実行中のジョブの状態を更新するには、ジョブ クエリを実行します。 ジョブ履歴の明示的な消去はありませんが、TTL は 30 日です。 

注

ジョブを開始すると、プロパティ名と値に含めることができるのは、印刷可能な英数字 US-ASCII のみです。ただし、次のセットを除きます。 $ ( ) < > @ , ; : \ " / [ ] ? = { } SP HT

注

jobIdフィールドは 64 文字以下にする必要があり、US-ASCII 文字、数字、ダッシュ (-) 文字のみを含めることができます。

ダイレクト メソッドを実行するジョブ

次のスニペットは、ジョブを使用して一連のデバイスで ダイレクト メソッド を実行するための HTTPS 1.1 要求の詳細を示しています。

PUT /jobs/v2/<jobId>?api-version=2021-04-12

Authorization: <config.sharedAccessSignature>
Content-Type: application/json; charset=utf-8

{
    "jobId": "<jobId>",
    "type": "scheduleDeviceMethod",
    "cloudToDeviceMethod": {
        "methodName": "<methodName>",
        "payload": <payload>,
        "responseTimeoutInSeconds": methodTimeoutInSeconds
    },
    "queryCondition": "<queryOrDevices>", // query condition
    "startTime": <jobStartTime>,          // as an ISO-8601 date string
    "maxExecutionTimeInSeconds": <maxExecutionTimeInSeconds>
}

クエリ条件は、次の例に示すように、1 つのデバイス ID またはデバイス ID の一覧に設定することもできます。

"queryCondition" = "deviceId = 'MyDevice1'"
"queryCondition" = "deviceId IN ['MyDevice1','MyDevice2']"
"queryCondition" = "deviceId IN ['MyDevice1']"

IoT Hub クエリ言語 では、IoT Hub クエリ言語についてさらに詳しく説明します。

次のスニペットは、contoso-hub-1 上のすべてのデバイスで testMethod という名前のダイレクト メソッドを呼び出すためにスケジュールされたジョブの要求と応答を示しています。

PUT https://contoso-hub-1.azure-devices.net/jobs/v2/job01?api-version=2021-04-12 HTTP/1.1
Authorization: SharedAccessSignature sr=contoso-hub-1.azure-devices.net&sig=68iv------------------------------------v8Hxalg%3D&se=1556849884&skn=iothubowner
Content-Type: application/json; charset=utf-8
Host: contoso-hub-1.azure-devices.net
Content-Length: 317

{
    "jobId": "job01",
    "type": "scheduleDeviceMethod",
    "cloudToDeviceMethod": {
        "methodName": "testMethod",
        "payload": {},
        "responseTimeoutInSeconds": 30
    },
    "queryCondition": "*",
    "startTime": "2019-05-04T15:53:00.077Z",
    "maxExecutionTimeInSeconds": 20
}

HTTP/1.1 200 OK
Content-Length: 65
Content-Type: application/json; charset=utf-8
Vary: Origin
Server: Microsoft-HTTPAPI/2.0
Date: Fri, 03 May 2019 01:46:18 GMT

{"jobId":"job01","type":"scheduleDeviceMethod","status":"queued"}

デバイス ツインのプロパティを更新するジョブ

次のスニペットは、ジョブを使用してデバイス ツインのプロパティを更新するための HTTPS 1.1 要求の詳細を示しています。

PUT /jobs/v2/<jobId>?api-version=2021-04-12

Authorization: <config.sharedAccessSignature>
Content-Type: application/json; charset=utf-8

{
    "jobId": "<jobId>",
    "type": "scheduleUpdateTwin",
    "updateTwin": <patch>                 // Valid JSON object
    "queryCondition": "<queryOrDevices>", // query condition
    "startTime": <jobStartTime>,          // as an ISO-8601 date string
    "maxExecutionTimeInSeconds": <maxExecutionTimeInSeconds>
}

注

updateTwin プロパティには、有効な etag 一致が必要です。たとえば、etag="*"。

次のスニペットは、contoso-hub-1 の test-device のデバイス ツイン プロパティを更新するようにスケジュールされたジョブの要求と応答を示しています。

PUT https://contoso-hub-1.azure-devices.net/jobs/v2/job02?api-version=2021-04-12 HTTP/1.1
Authorization: SharedAccessSignature sr=contoso-hub-1.azure-devices.net&sig=BN0U-------------------------------------RuA%3D&se=1556925787&skn=iothubowner
Content-Type: application/json; charset=utf-8
Host: contoso-hub-1.azure-devices.net
Content-Length: 339

{
    "jobId": "job02",
    "type": "scheduleUpdateTwin",
    "updateTwin": {
      "properties": {
        "desired": {
          "test1": "value1"
        }
      },
     "etag": "*"
     },
    "queryCondition": "deviceId = 'test-device'",
    "startTime": "2019-05-08T12:19:56.868Z",
    "maxExecutionTimeInSeconds": 20
}

HTTP/1.1 200 OK
Content-Length: 63
Content-Type: application/json; charset=utf-8
Vary: Origin
Server: Microsoft-HTTPAPI/2.0
Date: Fri, 03 May 2019 22:45:13 GMT

{"jobId":"job02","type":"scheduleUpdateTwin","status":"queued"}

ジョブの進行状況のクエリ

次のスニペットは、ジョブのクエリを実行するための HTTPS 1.1 要求の詳細を示しています。

GET /jobs/v2/query?api-version=2021-04-12[&jobType=<jobType>][&jobStatus=<jobStatus>][&pageSize=<pageSize>][&continuationToken=<continuationToken>]

Authorization: <config.sharedAccessSignature>
Content-Type: application/json; charset=utf-8

continuationToken は応答から提供されます。

デバイス ツイン、ジョブ 、メッセージ ルーティングの IoT Hub クエリ言語を使用して、各デバイスでジョブの実行状態を照会できます。

ジョブのプロパティ

次の一覧は、ジョブまたはジョブの結果を照会するときに使用できるプロパティと対応する説明を示しています。

プロパティ Description
jobId ジョブのアプリケーション指定 ID。
startTime ジョブのアプリケーション指定開始時刻 (ISO-8601)。
endTime ジョブが完了した時点の IoT Hub 提供日 (ISO-8601)。 ジョブが 'completed' 状態に達した後にのみ有効です。
maxExecutionTimeInSeconds アプリケーションは、ジョブが開始されてから完了するまでの最大許容合計時間を提供しました。
type ジョブの種類:
scheduleUpdateTwin: 必要なプロパティまたはタグのセットを更新するために使用されるジョブ。
scheduleDeviceMethod: 一連のデバイス ツインでデバイス メソッドを呼び出すために使用されるジョブ。
地位 ジョブの現在の状態。 状態に使用できる値:
保留中: ジョブ サービスによってスケジュールされ、取得されるのを待機しています。
スケジュール済み: 将来の時刻にスケジュールされます。
running: 現在アクティブなジョブ。
canceled: ジョブが取り消されました。
failed: ジョブが失敗しました。
完了: ジョブが完了しました。
deviceJobStatistics ジョブの実行に関する統計。
deviceJobStatistics プロパティ:
deviceJobStatistics.deviceCount: ジョブ内のデバイスの数。
deviceJobStatistics.failedCount: ジョブが失敗したデバイスの数。
deviceJobStatistics.succeededCount: ジョブが成功したデバイスの数。
deviceJobStatistics.runningCount: ジョブを現在実行しているデバイスの数。
deviceJobStatistics.pendingCount: ジョブの実行が保留中のデバイスの数。

その他の参考資料

IoT Hub 開発者ガイドのその他のリファレンス トピックは次のとおりです。

次のステップ

この記事で説明されている概念の一部を試すには、次の IoT Hub チュートリアルを参照してください。