翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# ジョブデバイス MQTT API オペレーション
ジョブデバイスコマンドは、[ジョブコマンドに使用される予約済みトピック](reserved-topics.md#reserved-topics-job)に MQTT メッセージを発行することで発行できます。
デバイス側のクライアントは、これらのコマンドの応答メッセージトピックにサブスクライブする必要があります。 AWS IoT Device Client を使用する場合、デバイスはレスポンストピックに自動的にサブスクライブします。つまり、クライアントが応答メッセージトピックをサブスクライブしているかどうかにかかわらず、メッセージブローカーはコマンドメッセージを発行したクライアントに応答メッセージトピックを発行することになります。これらの応答メッセージはメッセージブローカーを通過せず、他のクライアントまたはルールによってサブスクライブする事はできません。
フリートモニタリングソリューション用のジョブと `jobExecution` イベントトピックをサブスクライブする際は、まず[ジョブおよびジョブ実行イベント](iot-events.md)を有効にして、クラウド側でイベント受信します。メッセージブローカーを介して処理され、 AWS IoT ルールで使用できるジョブ進行状況メッセージは [ジョブイベント](events-jobs.md) として発行されます。メッセージブローカーは、応答メッセージを発行するため、明示的なサブスクリプションがない場合でも、クライアントは、メッセージを受信し、受信したメッセージを識別するように設定される必要があります。また、クライアントは、クライアントがメッセージを処理する前に、受信メッセージトピックの *thingName* がクライアントの Thing 名に適用されることを確認する必要もあります。
**注記**
MQTT Jobs API コマンドメッセージに応答して が AWS IoT 送信するメッセージは、明示的にサブスクライブしたかどうかにかかわらず、アカウントに課金されます。
以下は、MQTT API オペレーションとそのリクエストとレスポンスの構文を示しています。すべての MQTT API オペレーションには次のパラメータがあります。
clientToken
リクエストとレスポンスを関連付けるために使用されるオプションのクライアントトークン。ここに任意の値を入力すると、レスポンスに反映されます。
`timestamp`
メッセージが送信されたときの、エポックからの秒単位の時間。
## GetPendingJobExecutions
特定のモノについて、ターミナル状態にないすべてのジョブのリストを取得します。
この API を呼び出すには、`$aws/things/thingName/jobs/get` にメッセージを発行します。
リクエストペイロード:
```
{ "clientToken": "string" }
```
メッセージブローカーは、特定のサブスクリプションがなくても `$aws/things/thingName/jobs/get/accepted` および `$aws/things/thingName/jobs/get/rejected` を発行します。ただし、クライアントがメッセージを受信するには、それらをリッスンしている必要があります。詳細については、[[the note about Jobs API messages](#jobs-mqtt-note)](Jobs API メッセージに関する注記) を参照してください。
レスポンスペイロード:
```
{
"inProgressJobs" : [ JobExecutionSummary ... ],
"queuedJobs" : [ JobExecutionSummary ... ],
"timestamp" : 1489096425069,
"clientToken" : "client-001"
}
```
ここで、`inProgressJobs` と `queuedJobs` は、`IN_PROGRESS` または `QUEUED` のステータスを持つ [JobExecutionSummary](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-summary) オブジェクトのリストを返します。
## StartNextPendingJobExecution
モノの次の保留中のジョブ実行を取得し、開始します (ステータスが `IN_PROGRESS` または `QUEUED`)。
+ ステータスが `IN_PROGRESS` のジョブの実行が最初に返されます。
+ ジョブの実行は、キューに保存された順に返されます。ジョブのターゲットグループにモノが追加または削除された場合は、既存のジョブ実行と比較して、新しいジョブ実行のロールアウト順序を確認します。
+ 次の保留中のジョブの実行が `QUEUED` の場合、そのステータスは `IN_PROGRESS` に変更され、ジョブの実行の詳細は指定どおりに設定されます。
+ 次の保留中のジョブの実行がすでに `IN_PROGRESS` である場合、そのステータスの詳細は変更されません。
+ 保留中のジョブの実行がない場合、レスポンスに `execution` フィールドは含まれません。
+ オプションで、`stepTimeoutInMinutes` プロパティの値を設定してステップタイマーを作成できます。`UpdateJobExecution` を実行してこのプロパティの値を更新しない場合、ステップタイマーが時間切れになると、ジョブの実行がタイムアウトになります。
この API を呼び出すには、`$aws/things/thingName/jobs/start-next` にメッセージを発行します。
リクエストペイロード:
```
{
"statusDetails": {
"string": "job-execution-state"
...
},
"stepTimeoutInMinutes": long,
"clientToken": "string"
}
```
`statusDetails`
ジョブ実行のステータスについて説明する名前と値のペアの集合。指定しない場合、`statusDetails` は変更されません。
`stepTimeOutInMinutes`
このデバイスがこのジョブの実行を終了する必要のある時間を指定します。このタイマーが時間切れになるか、再設定される (`UpdateJobExecution` を呼び出し、ステータスを `IN_PROGRESS` に設定して、`stepTimeoutInMinutes` フィールドで新しいタイムアウト値を指定する) までに、ジョブの実行ステータスが終了状態に設定されない場合、ジョブの実行ステータスは `TIMED_OUT` に設定されます。このタイムアウトを設定しても、ジョブの作成時に指定したジョブの実行タイムアウト (`CreateJob` で `timeoutConfig` フィールドを使用することにより) には影響を与えません。
このパラメータの有効な値の範囲は 1 〜 10,080 (1 分〜 7 日) です。-1 の値も有効で、現在のステップタイマー (先ほど UpdateJobExecutionRequest を使用して作成したもの) をキャンセルします。
メッセージブローカーは、特定のサブスクリプションがなくても `$aws/things/thingName/jobs/start-next/accepted` および `$aws/things/thingName/jobs/start-next/rejected` を発行します。ただし、クライアントがメッセージを受信するには、それらをリッスンしている必要があります。詳細については、[[the note about Jobs API messages](#jobs-mqtt-note)](Jobs API メッセージに関する注記) を参照してください。
レスポンスペイロード:
```
{
"execution" : JobExecutionData,
"timestamp" : timestamp,
"clientToken" : "string"
}
```
ここで、`execution` は [JobExecution](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-data) オブジェクトです。例:
```
{
"execution" : {
"jobId" : "022",
"thingName" : "MyThing",
"jobDocument" : "< contents of job document >",
"status" : "IN_PROGRESS",
"queuedAt" : 1489096123309,
"lastUpdatedAt" : 1489096123309,
"versionNumber" : 1,
"executionNumber" : 1234567890
},
"clientToken" : "client-1",
"timestamp" : 1489088524284,
}
```
## DescribeJobExecution
ジョブの実行に関する詳細情報を取得します。
`jobId` を `$next` に設定して、モノ (ステータスが `IN_PROGRESS` または `QUEUED` のもの) に対して保留中の次のジョブ実行を返すことができます。
この API を呼び出すには、`$aws/things/thingName/jobs/jobId/get` にメッセージを発行します。
リクエストペイロード:
```
{
"jobId" : "022",
"thingName" : "MyThing",
"executionNumber": long,
"includeJobDocument": boolean,
"clientToken": "string"
}
```
`thingName`
デバイスに関連付けられたモノの名前。
`jobId`
作成時にこのジョブに割り当てた一意の識別子。
または、`$next` を使用して、モノ (ステータスが `IN_PROGRESS` または `QUEUED` のもの) に対して保留中の次のジョブ実行を返すことができます。この場合は､ステータスが `IN_PROGRESS` のジョブの実行が最初に返されます。ジョブの実行は、作成された順に返されます。
`executionNumber`
(オプション) デバイスでジョブの実行を識別する番号。指定しない場合、最新のジョブ実行が返されます。
`includeJobDocument`
(オプション) `false` に設定しない限り、レスポンスにはジョブドキュメントが含まれます。デフォルトは `true` です。
メッセージブローカーは、特定のサブスクリプションがなくても `$aws/things/thingName/jobs/jobId/get/accepted` および `$aws/things/thingName/jobs/jobId/get/rejected` を発行します。ただし、クライアントがメッセージを受信するには、それらをリッスンしている必要があります。詳細については、[[the note about Jobs API messages](#jobs-mqtt-note)](Jobs API メッセージに関する注記) を参照してください。
レスポンスペイロード:
```
{
"execution" : JobExecutionData,
"timestamp": "timestamp",
"clientToken": "string"
}
```
ここで、`execution` は [JobExecution](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-data) オブジェクトです。
## UpdateJobExecution
ジョブ実行のステータスを更新します。オプションで、ステップタイマーを作成するには、`stepTimeoutInMinutes` プロパティの値を設定します。`UpdateJobExecution` を再び実行してこのプロパティの値を更新しない場合、ステップタイマーが時間切れになると、ジョブの実行がタイムアウトになります。
この API を呼び出すには、`$aws/things/thingName/jobs/jobId/update` にメッセージを発行します。
リクエストペイロード:
```
{
"status": "job-execution-state",
"statusDetails": {
"string": "string"
...
},
"expectedVersion": "number",
"executionNumber": long,
"includeJobExecutionState": boolean,
"includeJobDocument": boolean,
"stepTimeoutInMinutes": long,
"clientToken": "string"
}
```
`status`
ジョブ実行の新しいステータス (`IN_PROGRESS`、`FAILED`、`SUCCEEDED`、または `REJECTED`)。これはすべての更新時に指定する必要があります。
`statusDetails`
ジョブ実行のステータスについて説明する名前と値のペアの集合。指定しない場合、`statusDetails` は変更されません。
`expectedVersion`
ジョブ実行の予想される現在のバージョン。ジョブの実行を更新するたびに、そのバージョンがインクリメントされます。 AWS IoT Jobs サービスに保存されているジョブ実行のバージョンが一致しない場合、更新は`VersionMismatch`エラーで拒否されます。現在のジョブ実行ステータスデータを含む [ErrorResponse](jobs-api.md#jobs-mqtt-error-response) も返されます。(これにより、ジョブ実行ステータスデータを取得するために別の `DescribeJobExecution` リクエストを実行する必要はありません。)
`executionNumber`
(オプション) デバイスでジョブの実行を識別する番号。指定しない場合、最新のジョブ実行が使用されます。
`includeJobExecutionState`
(オプション) これが含まれ、`true` に設定されている場合、レスポンスには `JobExecutionState` フィールドが含まれます。デフォルトは `false` です。
`includeJobDocument`
(オプション) これが含まれ、`true` に設定されている場合、レスポンスには `JobDocument` が含まれます。デフォルトは`false`です。
`stepTimeoutInMinutes`
このデバイスがこのジョブの実行を終了する必要のある時間を指定します。タイマーが期限切れになるかタイマーがリセットされる前にジョブ実行ステータスが終了状態に設定されない場合、ジョブ実行ステータスは `TIMED_OUT` に設定されます。このタイムアウトを設定または再設定しても、ジョブの作成時に指定したジョブの実行タイムアウトには影響を与えません。
メッセージブローカーは、特定のサブスクリプションがなくても `$aws/things/thingName/jobs/jobId/update/accepted` および `$aws/things/thingName/jobs/jobId/update/rejected` を発行します。ただし、クライアントがメッセージを受信するには、それらをリッスンしている必要があります。詳細については、[[the note about Jobs API messages](#jobs-mqtt-note)](Jobs API メッセージに関する注記) を参照してください。
レスポンスペイロード:
```
{
"executionState": JobExecutionState,
"jobDocument": "string",
"timestamp": timestamp,
"clientToken": "string"
}
```
`executionState`
[JobExecutionState](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-state) オブジェクト。
`jobDocument`
[ジョブドキュメント](key-concepts-jobs.md)オブジェクト。
MQTT レスポンスでは、`jobDocument` フィールドは JSON オブジェクトです。HTTP レスポンスの場合は、JSON オブジェクトの文字列表現です。
`timestamp`
メッセージが送信されたときの、エポックからの秒単位の時間。
`clientToken`
リクエストとレスポンスを相関させるために使用されるクライアントトークン。
MQTT プロトコルを使用する場合、以下の更新を実行することもできます。
## JobExecutionsChanged
あるジョブの実行中のジョブのリストに､ジョブの実行が追加または削除されるたびに送信されます。
トピックを使用します。
`$aws/things/thingName/jobs/notify`
メッセージペイロード:
```
{
"jobs" : {
"JobExecutionState": [ [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummary.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummary.html) ... ]
},
"timestamp": timestamp
}
```
## NextJobExecutionChanged
[https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html) に対して `jobId` `$next` で定義されている、モノに対する保留されているジョブ実行のリストで、次の順番のジョブに変更があったときに送信されます。このメッセージは、次のジョブの実行の詳細が変更されたときには送信されません。これは､`jobId` `$next` とともに `DescribeJobExecution` で返される次のジョブが変更されたときだけです。ステータスが `QUEUED` のジョブ実行 J1 と J2 を考えてみましょう。保留中のジョブの実行リストの次に J1 が表示されます。J1 の状態が変更されないまま J2 のステータスが `IN_PROGRESS` に変更された場合、この通知が送信され、J2 の詳細が含まれます。
トピックを使用します。
`$aws/things/thingName/jobs/notify-next`
メッセージペイロード:
```
{
"execution" : [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecution.html),
"timestamp": timestamp,
}
```