ジョブデバイス MQTT API オペレーション

ジョブデバイスコマンドは、ジョブコマンドに使用される予約済みトピックに MQTT メッセージを発行することで発行できます。

デバイス側のクライアントは、これらのコマンドの応答メッセージトピックにサブスクライブする必要があります。AWS IoT デバイスクライアントを使用している場合、デバイスは応答トピックに自動的にサブスクライブします。つまり、クライアントが応答メッセージトピックをサブスクライブしているかどうかにかかわらず、メッセージブローカーはコマンドメッセージを発行したクライアントに応答メッセージトピックを発行することになります。これらの応答メッセージはメッセージブローカーを通過せず、他のクライアントまたはルールによってサブスクライブする事はできません。

フリートモニタリングソリューション用のジョブと jobExecution イベントトピックをサブスクライブする際は、まずジョブおよびジョブ実行イベントを有効にして、クラウド側でイベント受信します。メッセージブローカーを介して処理され、AWS IoT ルールで使用できるジョブ進行状況メッセージはジョブイベントとして発行されます。メッセージブローカーは、応答メッセージを発行するため、明示的なサブスクリプションがない場合でも、クライアントは、メッセージを受信し、受信したメッセージを識別するように設定される必要があります。また、クライアントは、クライアントがメッセージを処理する前に、受信メッセージトピックの thingName がクライアントの Thing 名に適用されることを確認する必要もあります。

注記

AWS IoT が MQTT Jobs API コマンドメッセージに応答して送信するメッセージは、明示的にサブスクライブしたかどうかにかかわらず、課金され、アカウントに請求されます。

以下は、MQTT API オペレーションとそのリクエストとレスポンスの構文を示しています。すべての MQTT API オペレーションには次のパラメータがあります。

clientToken: リクエストとレスポンスを関連付けるために使用されるオプションのクライアントトークン。ここに任意の値を入力すると、レスポンスに反映されます。
timestamp: メッセージが送信されたときの、エポックからの秒単位の時間。

特定のモノについて、ターミナル状態にないすべてのジョブのリストを取得します。

この 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 API メッセージに関する注記) を参照してください。

レスポンスペイロード:


{
"inProgressJobs" : [ JobExecutionSummary ... ], 
"queuedJobs" : [ JobExecutionSummary ... ],
"timestamp" : 1489096425069,
"clientToken" : "client-001"
}

ここで、inProgressJobs と queuedJobs は、IN_PROGRESS または QUEUED のステータスを持つ JobExecutionSummary オブジェクトのリストを返します。

モノの次の保留中のジョブ実行を取得し、開始します (ステータスが 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 フィールドを使用することにより) には影響を与えません。

メッセージブローカーは、特定のサブスクリプションがなくても $aws/things/thingName/jobs/start-next/accepted および $aws/things/thingName/jobs/start-next/rejected を発行します。ただし、クライアントがメッセージを受信するには、それらをリッスンしている必要があります。詳細については、[the note about Jobs API messages](Jobs API メッセージに関する注記) を参照してください。

レスポンスペイロード:


{
"execution" : JobExecutionData,
"timestamp" : timestamp,
"clientToken" : "string"
}

ここで、execution は JobExecution オブジェクトです。例:


{
"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,
}

ジョブの実行に関する詳細情報を取得します。

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 API メッセージに関する注記) を参照してください。

レスポンスペイロード:


{
"execution" : JobExecutionData,
"timestamp": "timestamp",
"clientToken": "string"
}

ここで、execution は JobExecution オブジェクトです。

ジョブ実行のステータスを更新します。オプションで、ステップタイマーを作成するには、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 ジョブサービスに保管されているジョブ実行のバージョンが一致しない場合、VersionMismatch エラーが表示されて更新が拒否されます。現在のジョブ実行ステータスデータを含む ErrorResponse も返されます。(これにより、ジョブ実行ステータスデータを取得するために別の 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 API メッセージに関する注記) を参照してください。

レスポンスペイロード:


{
"executionState": JobExecutionState,
"jobDocument": "string",
"timestamp": timestamp,
"clientToken": "string"
}

executionState: JobExecutionState オブジェクト。
jobDocument: ジョブドキュメントオブジェクト。
timestamp: メッセージが送信されたときの、エポックからの秒単位の時間。
clientToken: リクエストとレスポンスを相関させるために使用されるクライアントトークン。

MQTT プロトコルを使用する場合、以下の更新を実行することもできます。

あるジョブの実行中のジョブのリストに､ジョブの実行が追加または削除されるたびに送信されます。

トピックを使用します。

$aws/things/thingName/jobs/notify

メッセージペイロード:


{
"jobs" : {
    "JobExecutionState": [ JobExecutionSummary ... ]
         },
    "timestamp": timestamp
}

DescribeJobExecution に対して jobId $next で定義されている、モノに対する保留されているジョブ実行のリストで、次の順番のジョブに変更があったときに送信されます。このメッセージは、次のジョブの実行の詳細が変更されたときには送信されません。これは､jobId $next とともに DescribeJobExecution で返される次のジョブが変更されたときだけです。ステータスが QUEUED のジョブ実行 J1 と J2 を考えてみましょう。保留中のジョブの実行リストの次に J1 が表示されます。J1 の状態が変更されないまま J2 のステータスが IN_PROGRESS に変更された場合、この通知が送信され、J2 の詳細が含まれます。

トピックを使用します。

$aws/things/thingName/jobs/notify-next

メッセージペイロード:


{
"execution" : JobExecution,
"timestamp": timestamp,
}

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

ジョブデバイス MQTT および HTTPS API オペレーションとデータ型

ジョブデバイス MQTT API