複数デバイスでのジョブをスケジュール設定する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:
IoT Hub エンドポイント: 各 IoT Hub でランタイムと管理の操作のために公開される、さまざまなエンドポイントについて説明します。IoT Hub endpoints describes the various endpoints that each IoT hub exposes for run-time and management operations.
調整とクォータ: IoT Hub サービスに適用されるクォータと、サービスを使用するときに想定される調整の動作について説明します。Throttling and quotas describes the quotas that apply to the IoT Hub service and the throttling behavior to expect when you use the service.
Azure IoT device SDK とサービス SDK: IoT Hub とやりとりするデバイスとサービス アプリの両方を開発する際に使用できるさまざまな言語の SDK を紹介します。Azure IoT device and service SDKs lists the various language SDKs you can use when you develop both device and service apps that interact with IoT Hub.
デバイス ツイン、ジョブ、およびメッセージ ルーティングの IoT Hub クエリ言語: IoT Hub クエリ言語について説明します。IoT Hub query language for device twins, jobs, and message routing describes the IoT Hub query language. このクエリ言語を使用して、IoT Hub からデバイス ツインとジョブに関する情報を取得します。Use this query language to retrieve information from IoT Hub about your device twins and jobs.
IoT Hub の MQTT サポート: IoT Hub での MQTT プロトコルのサポートについて詳しく説明します。IoT Hub MQTT support provides more information about IoT Hub support for the MQTT protocol.
次のステップNext steps
この記事で説明した概念を試すには、次の IoT Hub のチュートリアルをご覧ください。To try out some of the concepts described in this article, see the following IoT Hub tutorial: