デバイスとジョブ

Device communication with jobs

デバイスは次の 3 つのメソッドを通じて AWS IoT ジョブサービスと通信できます。

MQTT
HTTP 署名バージョン 4
HTTP TLS

Using the MQTT protocol

AWS IoT ジョブサービスとデバイス間の通信は、MQTT プロトコル上で行うことができます。デバイスは MQTT トピックに登録して新規ジョブの通知を受け、AWS IoT ジョブサービスからのレスポンスを受け取ります。デバイスは、MQTT トピックを発行して、ジョブの実行状態をクエリまたは更新します。各デバイスには、全般的な MQTT トピックがあります。MQTT トピックのパブリッシュとサブスクライブの詳細については、「デバイス通信プロトコル」を参照してください。

注記

MQTT を通じて AWS IoT ジョブサービスと通信するときは、正しいエンドポイントを使用する必要があります。DescribeEndpoint コマンドを使用して検索します。たとえば、次のコマンドを実行するとします。


aws iot describe-endpoint --endpoint-type iot:Data-ATS

以下のような応答が得られます。


{
    "endpointAddress": "a1b2c3d4e5f6g7-ats.iot.us-west-2.amazonaws.com"
}

この方法では、デバイスはデバイス固有の証明書とプライベートキーを使用して、AWS IoT ジョブサービスに対して認証します。

デバイスは次のことが可能です｡

$aws/things/thing-name/jobs/notify MQTT トピックにサブスクライブすることによって、ジョブ実行がデバイスの保留中のジョブ実行リストに追加または削除されるたびに通知されます。ここで､thing-name は、デバイスに関連付けられているモノの名前です。
$aws/things/thing-name/jobs/notify-next MQTT トピックをサブスクライブすることによって､次の保留中のジョブ実行が変更されたときに通知されます。ここで､thing-name は、デバイスに関連付けられているものの名前です。
UpdateJobExecution API を呼び出してジョブの実行状況を更新します。
DescribeJobExecution API を呼び出してジョブの実行状況をクエリします。
GetPendingJobExecutions API を呼び出すことにより、保留中のジョブの実行リストを取得します。
jobId DescribeJobExecution で $next API を呼び出して、保留中の次のジョブの実行を取得します。
StartNextPendingJobExecution API を呼び出して、保留中の次のジョブ実行を取得して開始します。

AWS IoT ジョブサービスは MQTT トピックで、成功と失敗のメッセージを発行します。このトピックは、accepted または rejected を、リクエストを行うために使用されたトピックに追加することで構成されます。たとえば、リクエストメッセージが $aws/things/myThing/jobs/get トピックに発行された場合､AWS IoT ジョブサービスは成功メッセージを $aws/things/myThing/jobs/get/accepted トピックに、却下メッセージを $aws/things/myThing/jobs/get/rejected トピックに発行します。

Using HTTP Signature Version 4

AWS IoT ジョブサービスとデバイス間の通信は、HTTP 署名バージョン 4 (ポート 443) 経由で行うことができます。これは、AWS SDK と CLI で使用されるメソッドです。これらのツールの詳細については、AWS CLI コマンドリファレンス: iot-jobs-data またはAWS SDK とツール、および希望する言語の IotJobsDataPlane セクションを参照してください。

注記

AWS IoT ジョブサービスと、HTTP 署名バージョン 4 を通じて、または AWS SDK や CLI IotJobsDataPlane コマンドを使用して通信する際は、正しいエンドポイントを使用する必要があります。DescribeEndpoint コマンドを使用して検索します。たとえば、次のコマンドを実行するとします。


aws iot describe-endpoint --endpoint-type iot:Jobs

以下のような応答が得られます。


{
    "endpointAddress": "a1b2c3d4e5f6g7.jobs.iot.us-west-2.amazonaws.com"
}

この通信方法では、デバイスは IAM 認証情報を使用して AWS IoT ジョブサービスに対して認証します。

この方法では次のコマンドを使用できます。

DescribeJobExecution

aws iot-jobs-data describe-job-execution ...
GetPendingJobExecutions

aws iot-jobs-data get-pending-job-executions ...
StartNextPendingJobExecution

aws iot-jobs-data start-next-pending-job-execution ...
UpdateJobExecution

aws iot-jobs-data update-job-execution ...

Using HTTP TLS

AWS IoT ジョブサービスとデバイス間の通信は、このプロトコルをサポートするサードパーティーのソフトウェアを使用して、HTTP TLS (ポート 8443) を介して行われます。

注記

HTTP TLS を介して AWS IoT ジョブサービスと通信するときは、正しいエンドポイントを使用する必要があります。DescribeEndpoint コマンドを使用して検索します。たとえば、次のコマンドを実行するとします。


aws iot describe-endpoint --endpoint-type iot:Jobs

以下のような応答が得られます。


{
    "endpointAddress": "a1b2c3d4e5f6g7.jobs.iot.us-west-2.amazonaws.com"
}

この方法では、デバイスは X.509 証明書ベースの認証 (たとえば、デバイス固有の証明書とプライベートキー) を使用します。

この方法では次のコマンドを使用できます。

DescribeJobExecution
GetPendingJobExecutions
StartNextPendingJobExecution
UpdateJobExecution

ジョブを処理するデバイスのプログラミング

このセクションの例では、MQTT を使用してデバイスと AWS IoT ジョブサービスの連携を示します。または、対応する API または CLI コマンドを使用できます。これらの例では、MyThing と呼ばれるデバイスが以下の MQTT トピックにサブスクライブすることを想定しています。

$aws/things/MyThing/jobs/notify または $aws/things/MyThing/jobs/notify-next *
$aws/things/MyThing/jobs/get/accepted
$aws/things/MyThing/jobs/get/rejected
$aws/things/MyThing/jobs/jobId/get/accepted
$aws/things/MyThing/jobs/jobId/get/rejected

AWS IoT のコード署名を使用している場合は、デバイスコードでコードファイルの署名を確認する必要があります。署名は codesign プロパティのジョブドキュメントにあります。コードファイル署名の検証の詳細については、「Device Agent Sample」を参照してください。

デバイスのワークフロー

実行するために与えられたジョブをデバイスが処理できる方法は 2 つあります。

Option a: Get the next job

デバイスが最初にオンラインになると、デバイスの notify-next トピックに登録する必要があります。
次のジョブを取得するには、jobId DescribeJobExecution を使用して $next MQTT API を呼び出して、statusDetails に保存されている状態を含め、次のジョブ、ジョブドキュメント、その他の詳細を取得します。ジョブドキュメントにコードファイル署名がある場合、ジョブリクエストの処理を続行する前に、署名を確認する必要があります。
ジョブステータスを更新するには､UpdateJobExecution MQTT API を呼び出します｡または、これと前のステップを 1 回の呼び出しで組み合わせるには、デバイスは StartNextPendingJobExecution を呼び出すことができます。
(オプション) ステップタイマーを追加するには、stepTimeoutInMinutes または UpdateJobExecution のいずれかを呼び出すときに StartNextPendingJobExecution の値を設定します。
UpdateJobExecution MQTT API を使用してジョブドキュメントで指定されたアクションを実行して、ジョブの進行状況を報告します。
この jobId で DescribeJobExecutionMQTT API を呼び出して、ジョブ実行のモニタリングを続行します。ジョブ実行が削除された場合、DescribeJobExecution は ResourceNotFoundException を返します。

デバイスがジョブを実行中にジョブ実行がキャンセルされたまたは削除された場合、このデバイスは有効な状態に復旧することができる必要があります。
ジョブが終了したら、UpdateJobExecution MQTT API を呼び出してジョブのステータスを更新し、成功または失敗を報告します。
このジョブの実行ステータスが終了状態に変更されたため、実行可能な次のジョブ (存在する場合) が変更されます。デバイスは、次の保留中のジョブ実行が変更されたことを通知されます。この時点で、デバイスはステップ 2 の説明に従って続行する必要があります。

デバイスがオンラインのままであれば、ジョブが完了する、または保留中の新しいジョブ実行が追加されたときに、そのジョブ実行データを含む後続の保留中のジョブ実行の通知を引き続き受信します。これが発生すると、デバイスはステップ 2 の説明に従って続行されます。

Option b: Pick from available jobs

デバイスが最初にオンラインになると、モノの notify トピックに登録する必要があります。
GetPendingJobExecutionsMQTT API を呼び出して、保留中のジョブ実行のリストを取得します。
リストに 1 つ以上のジョブの実行が含まれている場合は、1 つのジョブを選択します。
DescribeJobExecution MQTT API を呼び出して、statusDetails に保存されている状態を含め、ジョブドキュメントおよびその他の詳細を取得します。
ジョブステータスを更新するには､UpdateJobExecution MQTT API を呼び出します｡このコマンドで includeJobDocument フィールドが true に設定されている場合、デバイスは前のステップをスキップして、この時点でジョブドキュメントを取得できます。
オプションで、ステップタイマーを追加するには、stepTimeoutInMinutes を呼び出すときに UpdateJobExecution の値を設定します。
UpdateJobExecution MQTT API を使用してジョブドキュメントで指定されたアクションを実行して、ジョブの進行状況を報告します。
この jobId で DescribeJobExecutionMQTT API を呼び出して、ジョブ実行のモニタリングを続行します。デバイスがジョブを実行中にジョブ実行がキャンセルされたまたは削除された場合、このデバイスは有効な状態に復旧することができる必要があります。
ジョブが終了したら、UpdateJobExecution MQTT API を呼び出してジョブのステータスを更新し、成功または失敗を報告します。

デバイスがオンラインのままになると、新しい保留中のジョブ実行が利用可能になるとき、保留中のジョブの実行がすべて通知されます。これが発生すると、デバイスはステップ 2 の説明に従って続行できます。

デバイスがジョブを実行できない場合は、UpdateJobExecution MQTT API を呼び出してジョブのステータスを REJECTED に更新する必要があります｡

新しいジョブの開始

Get job information

ジョブの実行に関する詳細情報を取得するには、デバイスは DescribeJobExecution フィールドを includeJobDocument に設定して true MQTT API を呼び出します (デフォルト)。

More Information(2)

リクエストが成功した場合、AWS IoT ジョブサービスは $aws/things/MyThing/jobs/0023/get/accepted トピックにメッセージを発行します｡


{
    "clientToken" : "client-001",
    "timestamp" : 1489097434407,
    "execution" : {
        "approximateSecondsBeforeTimedOut": number,
        "jobId" : "023",
        "status" : "QUEUED",
        "queuedAt" : 1489097374841,
        "lastUpdatedAt" : 1489097374841,
        "versionNumber" : 1,
        "jobDocument" : {
            < contents of job document >
        }
    }
}

注記

リクエストが失敗した場合、AWS IoT ジョブサービスは $aws/things/MyThing/jobs/0023/get/rejected トピックにメッセージを発行します｡

デバイスにはジョブドキュメントがあるようになり、これを使用してジョブのリモートオペレーションを実行できます。ジョブドキュメントに Amazon S3 の署名付き URL が含まれている場合、デバイスはその URL を使用してジョブに必要なファイルをダウンロードできます。

ジョブの実行ステータスレポート

Update execution status

デバイスがジョブを実行しているときに、UpdateJobExecution MQTT API を呼び出してジョブの実行ステータスを更新できます。

More information (3)

たとえば、デバイスは、IN_PROGRESS トピックに次のメッセージを公開することによって、ジョブの実行ステータスを $aws/things/MyThing/jobs/0023/update に更新することができます。


{
    "status":"IN_PROGRESS",
    "statusDetails": {
        "progress":"50%"
    },
    "expectedVersion":"1",
    "clientToken":"client001"
}

ジョブは、$aws/things/MyThing/jobs/0023/update/accepted トピックまたは $aws/things/MyThing/jobs/0023/update/rejected トピックにメッセージを公開して応答します｡


{
    "clientToken":"client001",
    "timestamp":1476289222841
}

デバイスは、StartNextPendingJobExecution を呼び出すことによって以前の 2 つのリクエストを組み合わせることができます。これは､次の保留中のジョブ実行を取得して開始し、デバイスがジョブ実行ステータスを更新できるようにします。このリクエストは、ジョブの実行が保留中の場合にもジョブドキュメントを返します。

ジョブに TimeoutConfig が含まれている場合、進捗タイマーが開始されます。UpdateJobExecution を呼び出すときの stepTimeoutInMinutes の値を設定することで、ジョブ実行のステップタイマーを設定することもできます。ステップタイマーは更新するジョブ実行にのみ適用されます。ジョブの実行を更新するたびに、このタイマーに新しい値を設定できます。StartNextPendingJobExecution を呼び出すときに、ステップタイマーを作成することもできます。ジョブの実行がステップタイマーの間隔より長い間、IN_PROGRESS ステータスのままになる場合、ジョブの実行は失敗し、終了ステータス TIMED_OUT に切り替わります。ステップタイマーは、ジョブの作成時に設定した進捗タイマーには影響を与えません。

status フィールドは、IN_PROGRESS､SUCCEEDED､または FAILED に設定できます。すでにターミナル状態になっているジョブの実行ステータスは更新できません。

Report execution completed

ジョブの実行が終了すると、デバイスは UpdateJobExecution MQTT API を呼び出します。ジョブが正常に行われた場合は、status を SUCCEEDED に設定し､メッセージペイロードの statusDetails にジョブに関する他の情報を名前と値のペアとして追加します。ジョブの実行が完了すると、進捗タイマーとステップタイマーが終了します。

More Information(4)

以下に例を示します。


{
    "status":"SUCCEEDED",
    "statusDetails": {
        "progress":"100%"
    },
    "expectedVersion":"2",
    "clientToken":"client-001"
}

ジョブが失敗した場合は、status を FAILED に設定し、statusDetails に発生したエラーに関する情報を追加します。


{
    "status":"FAILED",
    "statusDetails": {
        "errorCode":"101",
        "errorMsg":"Unable to install update"
    },
    "expectedVersion":"2",
    "clientToken":"client-001"
}

注記

statusDetails 属性には、任意の数の名前と値のペアを含めることができます。

AWS IoT ジョブサービスがこの更新を受け取ると、$aws/things/MyThing/jobs/notify トピックにメッセージを発行し、ジョブの実行が完了したことを示します。


{
    "timestamp":1476290692776,
    "jobs":{}
}

その他のジョブ

ジョブの通知

AWS IoT ジョブサービスは、ジョブが保留中の場合や、リスト内の最初のジョブ実行が変更された場合、MQTT メッセージを予約済みトピックに発行します。デバイスは、これらのトピックにサブスクライブすることによって、保留中のジョブを追跡できます。

ジョブ通知は、MQTT トピックに JSON ペイロードとして発行されます。通知は 2 種類あります。

ListNotification には、10 を超えない保留中のジョブの実行リストが含まれます。このリスト内のジョブ実行のステータス値は IN_PROGRESS または QUEUED です。ステータスによってソートされた後 (IN_PROGRESS ジョブ実行の前に QUEUED ジョブ実行)、キューに入れられた時刻によってソートされます。

ListNotification は、次のいずれかの条件が満たされると必ず発行されます。
- 新しいジョブ実行がキューに登録されたか、非ターミナルステータス (IN_PROGRESS または QUEUED) に変わった。
- 古いジョブの実行が終了ステータスに変わった (FAILED、SUCCEEDED、CANCELED、TIMED_OUT、REJECTED、または REMOVED)。
NextNotification には、キュー内の次の 1 つのジョブ実行に関する概要が含まれています。

NextNotification は、リスト内の最初のジョブ実行が変更されると必ず発行されます。
- 新しいジョブ実行は QUEUED としてリストに追加され、リスト内の最初の項目になります。
- リスト内の最初の項目でない既存のジョブ実行のステータスは、QUEUED から IN_PROGRESS に変わり、リストにある最初の項目になります。(これは、リスト内に他の IN_PROGRESS ジョブ実行がない場合や、ステータスが QUEUED から IN_PROGRESS に変わったジョブ実行がリスト内の他の IN_PROGRESS ジョブ実行より早くキューに登録された場合に発生します)。
- リスト内の最小にあるジョブ実行のステータスがターミナルステータスに変更され、リストから削除されます。

MQTT トピックのパブリッシュとサブスクライブの詳細については、「デバイス通信プロトコル」を参照してください。

注記

ジョブとの通信に HTTP 署名バージョン 4 あるいは HTTP TLS を使用する場合、通知は利用できません。

Job pending

AWS IoT ジョブサービスは、あるジョブの保留中のジョブ実行リストにジョブが追加されたり削除されたりするか、リスト内の最初のジョブ実行が変化すると、MQTT トピックにメッセージを発行します。

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

More Information(6)

メッセージには、次のペイロード例が含まれています。

$aws/things/thingName/jobs/notify:


{
  "timestamp" : 10011,
  "jobs" : {
    "IN_PROGRESS" : [ {
      "jobId" : "other-job",
      "queuedAt" : 10003,
      "lastUpdatedAt" : 10009,
      "executionNumber" : 1,
      "versionNumber" : 1
    } ],
    "QUEUED" : [ {
      "jobId" : "this-job",
      "queuedAt" : 10011,
      "lastUpdatedAt" : 10011,
      "executionNumber" : 1,
      "versionNumber" : 0
    } ]
  }
}

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


{
  "timestamp" : 10011,
  "execution" : {
    "jobId" : "other-job",
    "status" : "IN_PROGRESS",
    "queuedAt" : 10009,
    "lastUpdatedAt" : 10009,
    "versionNumber" : 1,
    "executionNumber" : 1,
    "jobDocument" : {"c":"d"}
  }
}

有効なジョブの実行ステータス値は QUEUED、IN_PROGRESS、FAILED、SUCCEEDED、CANCELED、TIMED_OUT、REJECTED、REMOVED です。

以下の一連の例では、ジョブ実行が作成、および 1 つの状態から別の状態に変更される各トピックに発行される通知を示しています。

まず、job1 という名の 1 つのジョブが作成されます。この通知は、jobs/notify トピックに発行されます。


{
  "timestamp": 1517016948,
  "jobs": {
    "QUEUED": [
      {
        "jobId": "job1",
        "queuedAt": 1517016947,
        "lastUpdatedAt": 1517016947,
        "executionNumber": 1,
        "versionNumber": 1
      }
    ]
  }
}

この通知は、jobs/notify-next トピックに発行されます。


{
  "timestamp": 1517016948,
  "execution": {
    "jobId": "job1",
    "status": "QUEUED",
    "queuedAt": 1517016947,
    "lastUpdatedAt": 1517016947,
    "versionNumber": 1,
    "executionNumber": 1,
    "jobDocument": {
      "operation": "test"
    }
  }
}

別のジョブが作成されると (job2)、この通知が jobs/notify トピックに発行されます。


{
  "timestamp": 1517017192,
  "jobs": {
    "QUEUED": [
      {
        "jobId": "job1",
        "queuedAt": 1517016947,
        "lastUpdatedAt": 1517016947,
        "executionNumber": 1,
        "versionNumber": 1
      },
      {
        "jobId": "job2",
        "queuedAt": 1517017191,
        "lastUpdatedAt": 1517017191,
        "executionNumber": 1,
        "versionNumber": 1
      }
    ]
  }
}

キューの次のジョブ (jobs/notify-next) が変更されていないため、通知は job1 トピックに発行されません。job1 が実行を開始した場合、そのステータスは IN_PROGRESS に変わります。ジョブのリストおよびキューの次のジョブが変更されないため、通知は発行されません。

3 番目のジョブが追加されると (job3)、この通知が jobs/notify トピックに発行されます。


{
  "timestamp": 1517017906,
  "jobs": {
    "IN_PROGRESS": [
      {
        "jobId": "job1",
        "queuedAt": 1517016947,
        "lastUpdatedAt": 1517017472,
        "startedAt": 1517017472,
        "executionNumber": 1,
        "versionNumber": 2
      }
    ],
    "QUEUED": [
      {
        "jobId": "job2",
        "queuedAt": 1517017191,
        "lastUpdatedAt": 1517017191,
        "executionNumber": 1,
        "versionNumber": 1
      },
      {
        "jobId": "job3",
        "queuedAt": 1517017905,
        "lastUpdatedAt": 1517017905,
        "executionNumber": 1,
        "versionNumber": 1
      }
    ]
  }
}

キューの次のジョブがまだ jobs/notify-next であるため、通知は job1 トピックに発行されません。

job1 が完了すると、そのステータスは SUCCEEDED に変わり、この通知は jobs/notify トピックに発行されます。


{
  "timestamp": 1517186269,
  "jobs": {
    "QUEUED": [
      {
        "jobId": "job2",
        "queuedAt": 1517017191,
        "lastUpdatedAt": 1517017191,
        "executionNumber": 1,
        "versionNumber": 1
      },
      {
        "jobId": "job3",
        "queuedAt": 1517017905,
        "lastUpdatedAt": 1517017905,
        "executionNumber": 1,
        "versionNumber": 1
      }
    ]
  }
}

この時点で、job1 はキューから削除され、実行する次のジョブが job2 になります。この通知は、jobs/notify-next トピックに発行されます。


{
  "timestamp": 1517186269,
  "execution": {
    "jobId": "job2",
    "status": "QUEUED",
    "queuedAt": 1517017191,
    "lastUpdatedAt": 1517017191,
    "versionNumber": 1,
    "executionNumber": 1,
    "jobDocument": {
      "operation": "test"
    }
  }
}

job3 よりも前に job2 の実行を開始する必要がある場合 (非推奨)、job3 のステータスを IN_PROGRESS に変更できます。この場合、job2 はキューの次のジョブではなくなり、この通知が jobs/notify-next トピックに発行されます。


{
  "timestamp": 1517186779,
  "execution": {
    "jobId": "job3",
    "status": "IN_PROGRESS",
    "queuedAt": 1517017905,
    "startedAt": 1517186779,
    "lastUpdatedAt": 1517186779,
    "versionNumber": 2,
    "executionNumber": 1,
    "jobDocument": {
      "operation": "test"
    }
  }
}

追加あるいは削除されたジョブがないため、jobs/notify トピックに発行される通知はありません。

デバイスが job2 を拒否し、そのステータスを REJECTED に変更した場合、この通知は jobs/notify トピックに発行されます。


{
  "timestamp": 1517189392,
  "jobs": {
    "IN_PROGRESS": [
      {
        "jobId": "job3",
        "queuedAt": 1517017905,
        "lastUpdatedAt": 1517186779,
        "startedAt": 1517186779,
        "executionNumber": 1,
        "versionNumber": 2
      }
    ]
  }
}

job3 (まだ進行中) が強制的に削除される場合、この通知は jobs/notify トピックに発行されます。


{
  "timestamp": 1517189551,
  "jobs": {}
}

この時点で、キューは空です。この通知は、jobs/notify-next トピックに発行されます。


{
  "timestamp": 1517189551
}

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

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

ドキュメントの表記規則

ジョブテンプレートの作成と管理 (CLI)

AWS IoT ジョブ API の使用