複数デバイスでのジョブをスケジュール設定するSchedule jobs on multiple devices

Azure IoT Hub では、デバイス ツインのプロパティとタグやダイレクト メソッドのような多数の構成要素を使用できます。Azure IoT Hub enables a number of building blocks like device twin properties and tags and direct methods. 通常、デバイス管理者とオペレーターは、バックエンド アプリを使用して、IoT デバイスの更新と対話を、指定した時刻に一括で実行できます。Typically, back-end apps enable device administrators and operators to update and interact with IoT devices in bulk and at a scheduled time. ジョブは、指定した時刻に一連のデバイスに対してデバイス ツインの更新とダイレクト メソッドを実行します。Jobs execute device twin updates and direct methods against a set of devices at a scheduled time. たとえば、オペレーターは、ビル 43 の 3 階にある一連のデバイスを、ビルの運用に悪影響を与えることがない時刻に再起動するジョブを開始して追跡するバックエンド アプリを使用します。For example, an operator would use a back-end app that initiates and tracks a job to reboot a set of devices in building 43 and floor 3 at a time that would not be disruptive to the operations of the building.

注意

この記事で説明されている機能は、Standard レベルの IoT Hub でのみ使用できます。The features described in this article are available only in the standard tier of IoT Hub. Basic および Standard または Free レベルの IoT Hub の詳細については、適切な IoT Hub レベルの選択に関するページを参照してください。For more information about the basic and standard/free IoT Hub tiers, see Choose the right IoT Hub tier.

一連のデバイスで次のアクティビティのスケジュールを設定し、その進行状況を追跡する必要があるときは、ジョブの使用を検討します。Consider using jobs when you need to schedule and track progress any of the following activities on a set of devices:

  • 必要なプロパティを更新するUpdate desired properties
  • タグを更新するUpdate tags
  • ダイレクト メソッドを呼び出すInvoke direct methods

ジョブのライフサイクルJob lifecycle

ジョブは、ソリューションのバック エンドによって開始され、IoT Hub によって管理されます。Jobs are initiated by the solution back end and maintained by IoT Hub. ジョブは、サービス向け URI (PUT https://<iot hub>/jobs/v2/<jobID>?api-version=2018-06-30) を通して開始でき、実行中のジョブの進行状況は、サービス向け URI (GET https://<iot hub>/jobs/v2/<jobID?api-version=2018-06-30) を通して照会できます。You can initiate a job through a service-facing URI (PUT https://<iot hub>/jobs/v2/<jobID>?api-version=2018-06-30) and query for progress on an executing job through a service-facing URI (GET https://<iot hub>/jobs/v2/<jobID?api-version=2018-06-30). ジョブが開始された後で実行中のジョブの状態を更新するには、ジョブ クエリを実行します。To refresh the status of running jobs once a job is initiated, run a job query.

注意

ジョブを呼び出すとき、プロパティ名と値には $ ( ) < > @ , ; : \ " / [ ] ? = { } SP HT を除く US-ASCII 印刷可能英数字のみを使用できます。When you initiate a job, property names and values can only contain US-ASCII printable alphanumeric, except any in the following set: $ ( ) < > @ , ; : \ " / [ ] ? = { } SP HT

ダイレクト メソッドを実行するジョブJobs to execute direct methods

次のスニペットでは、ジョブを使って一連のデバイス上でダイレクト メソッドを実行するための HTTPS 1.1 要求の詳細を示します。The following snippet shows the HTTPS 1.1 request details for executing a direct method on a set of devices using a job:

PUT /jobs/v2/<jobId>?api-version=2018-06-30

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 のリストに対するものであってもかまいません。The query condition can also be on a single device ID or on a list of device IDs as shown in the following examples:

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

IoT Hub クエリ言語の詳細については、IoT Hub クエリ言語に関するページをご覧ください。IoT Hub Query Language covers IoT Hub query language in additional detail.

次のスニペットは、contoso-hub-1 のすべてのデバイスで testMethod という名前のダイレクト メソッドを呼び出すようにスケジュールされたジョブの要求と応答を示しています。The following snippet shows the request and response for a job scheduled to call a direct method named testMethod on all devices on contoso-hub-1:

PUT https://contoso-hub-1.azure-devices.net/jobs/v2/job01?api-version=2018-06-30 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"}

デバイス ツインのプロパティを更新するジョブJobs to update device twin properties

次のスニペットでは、ジョブを使ってデバイス ツインのプロパティを更新するための HTTPS 1.1 要求の詳細を示します。The following snippet shows the HTTPS 1.1 request details for updating device twin properties using a job:

PUT /jobs/v2/<jobId>?api-version=2018-06-30

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 と一致する必要があります。The updateTwin property requires a valid etag match; for example, etag="*".

次のスニペットは、contoso-hub-1 の test-device のデバイス ツイン プロパティを更新するようにスケジュールされたジョブの要求と応答を示しています。The following snippet shows the request and response for a job scheduled to update device twin properties for test-device on contoso-hub-1:

PUT https://contoso-hub-1.azure-devices.net/jobs/v2/job02?api-version=2018-06-30 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"}

ジョブの進行状況の照会Querying for progress on jobs

次のスニペットでは、ジョブを照会するための HTTPS 1.1 要求の詳細を示します。The following snippet shows the HTTPS 1.1 request details for querying for jobs:

GET /jobs/v2/query?api-version=2018-06-30[&jobType=<jobType>][&jobStatus=<jobStatus>][&pageSize=<pageSize>][&continuationToken=<continuationToken>]

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

ContinuationToken は、応答から提供されます。The continuationToken is provided from the response.

それぞれのデバイスにおけるジョブの実行状態は、デバイス ツイン、ジョブ、メッセージ ルーティングの IoT Hub クエリ言語を使用してクエリを実行することができます。You can query for the job execution status on each device using the IoT Hub query language for device twins, jobs, and message routing.

ジョブのプロパティJobs Properties

次の一覧は、ジョブまたはジョブの結果を照会するときに使うことができるプロパティとその説明です。The following list shows the properties and corresponding descriptions, which can be used when querying for jobs or job results.

プロパティProperty 説明Description
jobIdjobId アプリケーションが提供するジョブの ID。Application provided ID for the job.
startTimestartTime アプリケーションが提供するジョブの開始時刻 (ISO 8601)。Application provided start time (ISO-8601) for the job.
endTimeendTime IoT Hub が提供するジョブの完了時の日付 (ISO 8601)。IoT Hub provided date (ISO-8601) for when the job completed. ジョブが 'completed' 状態に達した後でのみ有効です。Valid only after the job reaches the 'completed' state.
typetype ジョブの種類:Types of jobs:
scheduleUpdateTwin:必要なプロパティまたはタグのセットを更新するために使用するジョブ。scheduleUpdateTwin: A job used to update a set of desired properties or tags.
scheduleDeviceMethod:デバイス ツインのセットに対してデバイス メソッドを呼び出すために使用するジョブ。scheduleDeviceMethod: A job used to invoke a device method on a set of device twins.
statusstatus ジョブの現在の状態。Current state of the job. 状態の可能値:Possible values for status:
pending: スケジュールが設定され、ジョブ サービスによって選択されるのを待機しています。pending: Scheduled and waiting to be picked up by the job service.
scheduled: 将来の時刻のスケジュールが設定されています。scheduled: Scheduled for a time in the future.
running: 現在アクティブなジョブです。running: Currently active job.
canceled: ジョブが取り消されました。canceled: Job has been canceled.
failed: ジョブが失敗しました。failed: Job failed.
completed: ジョブが完了しました。completed: Job has completed.
deviceJobStatisticsdeviceJobStatistics ジョブの実行に関する統計情報。Statistics about the job's execution.
deviceJobStatistics プロパティ:deviceJobStatistics properties:
deviceJobStatistics.deviceCount: ジョブ内のデバイスの数。deviceJobStatistics.deviceCount: Number of devices in the job.
deviceJobStatistics.failedCount: ジョブが失敗したデバイスの数。deviceJobStatistics.failedCount: Number of devices where the job failed.
deviceJobStatistics.succeededCount: ジョブが成功したデバイスの数。deviceJobStatistics.succeededCount: Number of devices where the job succeeded.
deviceJobStatistics.runningCount: 現在ジョブが実行中であるデバイスの数。deviceJobStatistics.runningCount: Number of devices that are currently running the job.
deviceJobStatistics.pendingCount: 現在ジョブの実行が保留されているデバイスの数。deviceJobStatistics.pendingCount: Number of devices that are pending to run the job.

参考資料Additional reference material

IoT Hub 開発者ガイド内の他の参照トピックは次のとおりです。Other reference topics in the IoT Hub developer guide include:

次のステップNext steps

この記事で説明した概念を試すには、次の IoT Hub のチュートリアルをご覧ください。To try out some of the concepts described in this article, see the following IoT Hub tutorial: