デバイスとジョブ

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 を呼び出すことにより、保留中のジョブの実行リストを取得します。

• で DescribeJobExecution API を呼び出して、次の保留中のジョブの実行を取得しますjobId$next。

• StartNextPendingJobExecution API を呼び出して、保留中の次のジョブ実行を取得して開始します。

AWS IoT ジョブサービスは MQTT トピックで、成功と失敗のメッセージを発行します。このトピックは、rejected または accepted を、リクエストを行うために使用されたトピックに追加することで構成されます。たとえば、リクエストメッセージが $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 SDKsと CLI で使用されるメソッドです。これらのツールの詳細については、AWS CLI コマンドリファレンスの iot-jobs-data または AWS SDKs Tools と、使用する言語の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

1. デバイスが最初にオンラインになると、デバイスの notify-next トピックに登録する必要があります。

2. で DescribeJobExecution MQTT API jobId $next を呼び出して、次のジョブ、ジョブドキュメント、その他 の詳細 ( に保存されている状態など) statusDetails を取得します。 ジョブドキュメントにコードファイル署名がある場合、ジョブリクエストの処理を続行する前に、署名を確認する必要があります。

3. ジョブステータスを更新するには､UpdateJobExecution MQTT API を呼び出します｡ または、これと前のステップを 1 回の呼び出しで組み合わせるには、デバイスは StartNextPendingJobExecution を呼び出すことができます。

4. (オプション) ステップタイマーを追加するには、UpdateJobExecution または StartNextPendingJobExecution のいずれかを呼び出すときに stepTimeoutInMinutes の値を設定します。

5. UpdateJobExecution MQTT API を使用してジョブドキュメントで指定されたアクションを実行して、ジョブの進行状況を報告します。

6. この で DescribeJobExecution MQTT API を呼び出して、ジョブの実行のモニタリングを続行jobIdします。 ジョブの実行が削除されると、 DescribeJobExecutionは を返しますResourceNotFoundException。

   デバイスがジョブの実行中、ジョブの実行がキャンセルされたり、削除されたりした場合、デバイスは有効な状態に復旧できます。

7. ジョブが終了したら、UpdateJobExecution MQTT API を呼び出してジョブのステータスを更新し、成功または失敗を報告します。

8. このジョブの実行ステータスが終了状態に変更されたため、実行可能な次のジョブ (存在する場合) が変更されます。デバイスは、次の保留中のジョブ実行が変更されたことを通知されます。この時点で、デバイスはステップ 2 の説明に従って続行する必要があります。

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

Option b: Pick from available jobs

1. デバイスが最初にオンラインになると、モノの notify トピックに登録する必要があります。

2. GetPendingJobExecutionsMQTT API を呼び出して、保留中のジョブ実行のリストを取得します。

3. リストに 1 つ以上のジョブの実行が含まれている場合は、1 つのジョブを選択します。

4. DescribeJobExecution MQTT API を呼び出して、statusDetails に保存されている状態を含め、ジョブドキュメントおよびその他の詳細を取得します。

5. ジョブステータスを更新するには､UpdateJobExecution MQTT API を呼び出します｡ このコマンドで includeJobDocument フィールドが true に設定されている場合、デバイスは前のステップをスキップして、この時点でジョブドキュメントを取得できます。

6. オプションで、ステップタイマーを追加するには、UpdateJobExecution を呼び出すときに stepTimeoutInMinutes の値を設定します。

7. UpdateJobExecution MQTT API を使用してジョブドキュメントで指定されたアクションを実行して、ジョブの進行状況を報告します。

8. この で DescribeJobExecution MQTT API を呼び出して、ジョブの実行のモニタリングを続行jobIdします。 デバイスがジョブを実行している間にジョブ実行がキャンセルされたまたは削除された場合、デバイスは有効な状態に復旧することができる必要があります。

9. ジョブが終了したら、UpdateJobExecution MQTT API を呼び出してジョブのステータスを更新し、成功または失敗を報告します。

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

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

新しいジョブの開始

New job notification

新しいジョブが作成されると、AWS IoT ジョブサービスは各ターゲットデバイスの $aws/things/thing-name/jobs/notify トピックにメッセージを発行します。

More Information(1)

メッセージには、次に示す情報が含まれます。

{
    "timestamp":1476214217017,
    "jobs":{
        "QUEUED":[{
            "jobId":"0001",
            "queuedAt":1476214216981,
            "lastUpdatedAt":1476214216981,
            "versionNumber" : 1
        }]
    }
}

デバイスは、ジョブの実行がキューに入れられたときに、'$aws/things/thingName/jobs/notify' トピックでこのメッセージを受け取ります。

Get job information

ジョブの実行に関する詳細情報を取得するには、デバイスは includeJobDocument フィールドを true に設定して DescribeJobExecution 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 が含まれている場合、進捗タイマーが開始されます。また、 を呼び出すstepTimeoutInMinutesときに の値を設定することで、ジョブの実行にステップタイマーを設定することもできますUpdateJobExecution。 ステップタイマーは更新するジョブ実行にのみ適用されます。ジョブの実行を更新するたびに、このタイマーに新しい値を設定できます。ステップタイマーは、 を呼び出すときに作成することもできます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":{}
}

その他のジョブ

Additional jobs

デバイスに対して保留中の他のジョブの実行がある場合、それらは $aws/things/MyThing/jobs/notify に公開されたメッセージに含まれます。

More Information(5)

以下に例を示します。

{
    "timestamp":1476290692776,
    "jobs":{
        "QUEUED":[{
            "jobId":"0002",
            "queuedAt":1476290646230,
            "lastUpdatedAt":1476290646230
        }],
        "IN_PROGRESS":[{
            "jobId":"0003",
            "queuedAt":1476290646230,
            "lastUpdatedAt":1476290646230
        }]
    }
}

ジョブの通知

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
      }
    ]
  }
} 

キューの次のジョブ (job1) が変更されていないため、通知は jobs/notify-next トピックに発行されません。が実行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
      }
    ]
  }
} 

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

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
}