IoT Platform:カスタムタスクの作成

タスク管理プロセス

1. カスタムタスクを作成します。

   1. IoT Platform コンソール で、管理するインスタンスを見つけ、インスタンス名をクリックします。[インスタンスの詳細] ページの左側のナビゲーションウィンドウで、[メンテナンス] > [タスク] を選択します。[タスク] ページで、[タスクの作成] をクリックします。

   2. [タスクの作成] ページで、[タスクの作成] と [タスクスケジュール] の手順でパラメーターを構成します。次に、[完了] をクリックします。パラメーターに関する情報を表示するには、パラメーターの横にある アイコンにポインターを移動します。

      • タスクの作成

        パラメーター	説明
        タスク名	有効なタスク名を指定します。カスタム名を指定できます。
        タスクタイプ	パラメーターを [カスタムタスク] に設定します。
        タスクの説明	タスクの目的などの情報を指定します。これは、タスクを識別するために使用できます。
        デバイスタスクの宛先	タスクを実行するデバイスを選択します。個別のデバイス、プロダクト別のデバイス、またはグループ別のデバイスを選択できます。 重要 グループ別にデバイスを選択する場合、動的グループは選択できません。
        デバイスに発行されるタスク実行ルール	ルールファイルをアップロードします。ファイルは JSON 形式である必要があり、サイズは 64 KB を超えることはできません。 [テンプレートのダウンロード] をクリックして、ルールテンプレートを取得できます。次のコードは、ファイルの内容を示しています。 { // カスタムフィールドのID "key":"value" // keyに対応する値。値はJSON形式である必要があります。 } key: カスタムフィールドの ID。データ型: 文字列。 value: key に対応する値。値は JSON 形式である必要があります。
        ファイル署名アルゴリズム	署名アルゴリズム。有効な値: [MD5] および [SHA256]。 このパラメーターはオプションです。ファイル署名アルゴリズムパラメーターは、[デバイスに発行されるタスクファイル] パラメーターと一緒に使用できます。
        デバイスに発行されるタスクファイル	カスタムタスクのファイルをアップロードします。 このパラメーターはオプションです。デバイスに発行されるタスクファイルパラメーターは、[ファイル署名アルゴリズム] パラメーターと一緒に使用できます。 サポートされているファイル形式: .bin、.apk、.tar、.gz、.zip、.gzip、.tar.gz。ファイルサイズは 1,000 MB を超えることはできません。

        重要

        ビジネス要件に基づいて、カスタムルールファイルを作成し、デバイスファイルのカスタムコンテンツを指定できます。指定されたデバイスで、タスクルールのロジックとデバイスのコンテンツを実装する必要があります。

      • タスク設定

        パラメーター	説明
        ジョブ実行プッシュ設定	ビジネス要件に合わせて、1 分あたりにプッシュされるジョブの数を調整します。 運用ニーズに合わせて [1 分あたりのジョブ実行数] を設定します。 カスタムタスクと Pub バッチメッセージプッシュタスクの [プッシュメッセージタイプ] を選択します。 オプションは次のとおりです。 [qos0]: メッセージを最大 1 回配信します。 [qos1]: 少なくとも 1 回の配信を保証します。 QoS 1 メッセージの送信後に PUBACK 応答が受信されない場合、IoT Platform への再接続時にメッセージがデバイスに再送信されます。
        ジョブ実行タイムアウト設定	このオプションのパラメーターを使用すると、デバイスタスクのタイムアウトを設定できます。 設定しない場合、タスクはタイムアウトしません。 これは、カスタムタスクにのみ適用されます。 タイマーは、デバイスタスクが IN_PROGRESS 状態になったときに開始されます。 タスクが完了せずに設定されたタイムアウトを超えた場合、ジョブステータスは TIMED_OUT に変更され、ジョブの実行は停止します。

2. タスクを作成すると、IoT Platform は /sys/{productKey}/{deviceName}/thing/job/notify Topic を使用して、指定されたデバイスにタスク情報をプッシュします。

   メッセージ例:

   {
       "id": "7542940",
       "version": "1.0",
       "params": {
           "task": {
               "taskId": "i5Ks6***pF010101",
               "status": "SENT",
               "jobDocument": {},
               "jobFile":{
                   "signMethod":"Md5",
                   "sign":"wssxff56dhdsd***",
                   "fileUrl": "https://iotx-***.oss-cn-shanghai.aliyuncs.com/***.zip"
               }
           }
       }
   }

   jobDocument は、ルールファイルのコンテンツを指定します。

   表 1. リクエストパラメーターの説明

   パラメーター	タイプ	説明
   id	String	メッセージの ID。有効な値: 0 ～ 4294967295。各メッセージ ID は、現在のデバイスに対して一意である必要があります。
   version	String	プロトコルのバージョン。このパラメーターを 1.0 に設定します。
   params	Object	リクエストパラメーターのリスト。
   task	Object	サブタスクのパラメーター。
   taskId	String	サブタスクの ID。グローバルに一意の識別子です。
   status	String	サブタスクのステータス。 SENT: スケジュール済み。 REMOVED: 削除済み。 CANCELLED: キャンセル済み。
   jobDocument	Object	タスク実行ルールを記述したジョブドキュメント。 説明 status が REMOVED または CANCELLED の場合、このフィールドは空です。
   jobFile	Object	カスタムタスクの作成時にアップロードされたファイル情報。 signMethod: 署名方式。現在、Md5 と Sha256 をサポートしています。 sign: 対応する署名方式に従って生成された署名パラメーター。 fileUrl: タスクファイルのダウンロード URL。1 時間有効です。 説明 ```html status が REMOVED または CANCELLED の場合、このフィールドは空です。

3. デバイスは、カスタムタスクのロジックに基づいてルールファイルの内容を実装します。

   指定されたデバイスがオフラインでタスク情報を受信できない場合、デバイスはオンラインになった後に /sys/{productKey}/{deviceName}/thing/job/get Topic から実行可能なタスクをリクエストできます。その後、デバイスはカスタムタスクに関する情報をリクエストしてカスタムタスクを完了できます。

   実行可能なタスクを取得するために使用されるリクエストの例:

   {
       "id": "123",
       "version": "1.0",
       "params": {
           "taskId": "$list"
       }
   }

   タスクに関する情報を取得するために使用されるリクエストの例:

   {
       "id": "123",
       "version": "1.0",
       "params": {
           "taskId": "i5Ks***F010101"
       }
   }

   表 3. リクエストパラメータの説明

   パラメータ	タイプ	説明
   id	String	メッセージの ID。有効な値: 0 ～ 4294967295。各メッセージ ID は、現在のデバイスに対して一意である必要があります。
   version	String	プロトコルのバージョン。このパラメータを 1.0 に設定します。
   params	Object	リクエストパラメータのリスト。
   taskId	String	3 つの値メソッドは、異なるステータスでタスク情報を返すことができます。 サブタスクの ID: ジョブ ID に対応するタスクの詳細情報を返します。 $next: 実行可能なタスクに関する情報を返します。 $list: 実行可能なタスクのリストを返します。デフォルトでは最大 10 です。

   IoT Platform はリクエストを受信すると、/sys/{productKey}/{deviceName}/thing/job/get_reply Topic を使用して対応するデバイスに応答を送信します。

   返されたタスクを含むレスポンスの例:

   {
       "id": "1234",
       "code": 200,
       "data": {
           "statusDetails":{"devs":"test","status":"init"},
           "taskId": "$list",
           "task":[
               {
                   "taskId": "i5Ks***",
                   "status": "IN_PROGRESS"
               },
               {
                   "taskId": "i61s***",
                   "status": "IN_PROGRESS"
               }
           ]
       }
   }

   返されたタスク情報を含むレスポンスの例:

   {
       "id": "1234",
       "code": 200,
       "data": {
           "statusDetails":{"devs":"test","status":"init"},
           "taskId": "i5Ks***F010101",
           "task":{
               "taskId": "i5Ks***F010101",
               "status": "IN_PROGRESS",
               "jobDocument": {},
               "jobFile":{
                   "signMethod":"Md5",
                   "sign":"wssxff56dhdsd***",
                   "fileUrl": "https://iotx-***.oss-cn-shanghai.aliyuncs.com/***.zip"
               }
           }
       }
   }

4. タスクが実行されると、指定されたデバイスは /sys/{productKey}/{deviceName}/thing/job/update Topic を使用して、タスクの進捗状況を IoT Platform に送信します。

   メッセージ例:

   {
       "id": "123", // メッセージID
       "version": "1.0", // プロトコルバージョン
       "params": { // リクエストパラメータのリスト
           "taskId": "i5Ks***F010101", // サブタスクID
           "status": "IN_PROGRESS", // サブタスクのステータス
           "statusDetails": { // ユーザー定義のステータスの詳細
               "key": "value" // keyとvalueのペア
           },
           "progress": 50 // サブタスクの実行進捗状況（パーセント）
       }
   }

   表 5. リクエストパラメータの説明

   パラメータ	タイプ	説明
   id	String	メッセージの ID。有効な値: 0 ～ 4294967295。各メッセージ ID は、現在のデバイスに対して一意である必要があります。
   version	String	プロトコルのバージョン。このパラメータを 1.0 に設定します。
   params	Object	リクエストパラメータのリスト。
   taskId	String	グローバルに一意な識別子であるサブタスクの ID。
   status	String	サブタスクのステータス。有効な値: SUCCEEDED: 正常に完了しました。 FAILED: 実行に失敗しました。 IN_PROGRESS: 現在実行中です。 REJECTED: 実行が拒否されました。
   statusDetails	Object	カスタマイズ可能なユーザー定義のステータスの詳細。IoT Platform コンソールの [デバイス管理] > [タスク] > [タスクの詳細] ページで表示できます。
   progress	Integer	サブタスクの実行進捗状況（パーセント）。

5. IoT Platform コンソールで、タスクが属するインスタンスを見つけ、インスタンス名をクリックします。 [インスタンスの詳細] ページで、[メンテナンス] > [タスク] を選択します。 [タスク] ページで、作成したタスクのステータスなど、関連する詳細を表示できます。
   重要 [タイムアウト] 状態のタスクは、指定されたスケジュールに基づいて実行できなくなります。

   タスクの作成後 7 日以内にサブタスクが実行に失敗した場合、タスクは [タイムアウト] 状態になります。

   ビジネス要件に基づいて、次の操作のいずれかを実行できます。

   • [タスク] ページで、[処理中] 状態のタスクをキャンセルします。
   • 管理するタスクを見つけ、[アクション] 列の [表示] をクリックします。 タスク詳細ページで、タスク情報とタスク統計を表示します。

     タブ	説明
     [タスク情報]	タスク情報を表示し、タスクの説明とタスク構成を変更し、ルールファイルをダウンロードできます。
     [タスク概要]	ステータス別にサブタスクの統計を表示できます。 管理するデバイスを見つけ、[表示] をクリックして、[デバイスの詳細] ページに移動します。 [タスク] タブで、デバイスのすべてのタスクを表示できます。 [デバイスログ] タブで、[表示] をクリックします。 [デバイスログ] ページで、[クラウド実行ログ] をクリックします。 [クラウド実行ログ] タブで、検索バーのワークロードタイプドロップダウンリストから [クラウドツーデバイスメッセージ] を選択して、タスク関連のログを表示します。 サブタスクが実行に失敗した場合は、[アクション] 列の [実行の詳細] をクリックして、失敗の原因を表示します。 サブタスクがタイムアウトしたか、実行に失敗した場合は、[ステータス] 列の [タイムアウト] または [失敗] をクリックして、対応する状態のサブタスクを表示します。 [タスク] ページの上部にある [再実行] をクリックして、現在のタスクのタイムアウト状態と失敗状態にあるサブタスクを再実行します。

   • タスクの [アクション] 列の [削除] をクリックします。 表示されるメッセージで、[OK] をクリックします。
     警告 タスクを削除すると、タスクに関連するすべてのデータが削除されます。 ビジネスアプリケーションがタスクに基づいて実行されている場合、アプリケーションが使用できなくなり、ビジネスに影響を与える可能性があります。 慎重に行ってください。