IoT Platform：添加自訂任務

任務管理流程

1. 建立自訂任務。
   1. 在物聯網平台控制台對應執行個體下的監控營運 > 任務管理頁面，單擊建立任務。
   2. 在建立任務頁面，單擊以下參數名稱右側的協助表徵圖，根據頁面提示，配置任務和作業，單擊完成。
      • 任務配置

        參數	說明
        任務名稱	輸入符合規則的任務名稱。可自訂。
        任務類型	選擇類型：自訂任務。
        任務描述	輸入該任務的用途等資訊，便於您區分不同的任務。
        目標裝置、產品或分組	從裝置、產品或分組維度選擇可執行任務的裝置。 重要 從分組維度選擇裝置時，不支援選擇動態分組。
        下發給裝置的任務執行規則	上傳規則檔案。僅支援.json格式檔案，檔案大小不能超過64 KB。 您可單擊下載模板，擷取規則檔案模板。內容如下： { "key":"value" } key：識別欄位，自訂的String資料。 value：key對應的值，資料格式滿足JSON要求即可。 您需根據模板格式，自訂規則內容。使用樣本，請參見裝置的自訂任務樣本。
        檔案簽名演算法	支援MD5和SHA256。 可選配置，與任務中下發給裝置的檔案結合使用。
        任務中下發給裝置的檔案	上傳自訂任務的檔案。 選擇性參數，與檔案簽名演算法結合使用。 支援.bin、.apk、.tar、.gz、.zip、.gzip、.tar.gz格式檔案，檔案大小不能超過1,000 MB。

        重要 您需根據實際需求，自訂規則和裝置檔案內容。任務規則和裝置檔案內容的實現邏輯，需您在裝置端完成開發。
      • 作業配置

        參數	說明
        作業執行推送配置	每分鐘作業執行數量：根據您的業務需要，設定每分鐘作業推送數量。 推送訊息類型：僅對自訂任務和Pub批量訊息推送任務生效。 可選： QoS0：最多發送一次。 QoS1：最少發送一次。如果QoS1訊息未接收到PUBACK訊息，會在裝置重連時，重新推送給裝置。
        作業執行的逾時配置	可選配置。不設定表示不會逾時。僅對自訂任務生效。 從裝置任務進入IN_PROGRESS狀態，開始計算時間。如果超過了逾時時間，任務下作業仍未執行完成，作業狀態將被自動化佈建為TIMED_OUT，作業停止執行。
        作業開始調度時間	可選配置。 從當前設定作業的時間，開始計算時間。 裝置任務建立成功後，先初始化，直至到達調度時間，才會開始調度執行。

2. 任務建立完成後，物聯網平台通過Topic：/sys/{productKey}/{deviceName}/thing/job/notify，將任務資訊推送給裝置。
   訊息格式如下：

   {
       "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號。String類型的數字，取值範圍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：任務檔案的下載地址，有效期間1小時。 說明 status為REMOVED或CANCELLED時，該欄位值為空白。

3. 裝置端根據自訂任務邏輯，實現規則內容。
   如果當前裝置處於離線狀態，無法接收任務資訊，裝置上線後，可通過Topic：/sys/{productKey}/{deviceName}/thing/job/get先擷取可執行檔工作清單，然後擷取一個可執行任務資訊，來完成任務。

   擷取工作清單的訊息格式如下：

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

   擷取任務資訊的訊息格式：

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

   表 3. 請求參數說明

   參數	類型	說明
   id	String	訊息ID號。String類型的數字，取值範圍0~4294967295，且每個訊息ID在當前裝置中具有唯一性。
   version	String	協議版本號碼，目前協議版本號碼唯一取值為1.0。
   params	Object	請求業務參數。
   taskId	String	三種取值方式，可返回不同狀態的任務資訊。 任務下作業的ID：返回作業ID對應任務的詳細資料。 $next：返回一個可執行任務的資訊。 $list：返回可執行檔工作清單，預設最多返回10個。

   物聯網平台收到請求後，通過響應Topic：/sys/{productKey}/{deviceName}/thing/job/get_reply，向裝置端返回結果。

   返回工作清單資料格式如下：

   {
       "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. 任務進行過程中，裝置端通過Topic：/sys/{productKey}/{deviceName}/thing/job/update，向物聯網平台上報任務進度。
   訊息格式如下：

   {
       "id": "123",
       "version": "1.0",
       "params": {
           "taskId": "i5Ks***F010101",
           "status": "IN_PROGRESS",
           "statusDetails": {
               "key": "value"
           },
           "progress": 50
       }
   }

   表 5. 請求參數說明

   參數	類型	說明
   id	String	訊息ID號。String類型的數字，取值範圍0~4294967295，且每個訊息ID在當前裝置中具有唯一性。
   version	String	協議版本號碼，目前協議版本號碼唯一取值為1.0。
   params	Object	請求業務參數。
   taskId	String	任務下作業的ID。為通用唯一識別碼。
   status	String	任務下作業的狀態。可取值： SUCCEEDED：成功。 FAILED：失敗。 IN_PROGRESS：執行中。 REJECTED：已拒絕。
   statusDetails	Object	使用者自訂的狀態詳情，內容可自訂。可在物聯網平台控制台的裝置管理 > 任務 > 任務詳情頁面查看。
   progress	Integer	任務下作業執行進度的百分數。

5. 在物聯網平台對應執行個體下的監控營運 > 任務管理頁面，查看已建立任務及目前狀態。
   重要 狀態為已逾時的任務，不可再被調度執行。

   從任務建立完成開始計時，如果任務下作業未在7天內全部執行完成，任務狀態顯示為已逾時。

   您可根據實際情境需要，執行以下操作：

   • 在工作清單中，取消執行中狀態的任務。
   • 單擊目標任務對應的查看，在任務詳情頁面，查看任務資訊和作業執行統計。

     功能頁簽	說明
     任務資訊	您可以查看任務資訊，修改任務描述和作業配置，下載裝置任務檔案。
     作業概覽	您可以查看任務下各狀態的作業統計。 您可以單擊目標裝置的查看，在裝置詳情頁面： 單擊任務頁簽，查看該裝置下的所有工作清單。 單擊Log Service的前往查看，在雲端作業記錄頁簽的搜尋欄，選擇業務類型為雲到裝置訊息，查看裝置任務相關日誌。 如果作業未執行成功，單擊執行詳情，可查看失敗原因。 如果作業執行已逾時或失敗，單擊已逾時或失敗的狀態按鈕，可查看對應狀態的作業列表。 您可以單擊列表上方的重新執行，重新執行當前任務下所有已逾時和失敗的作業。

   • 單擊目標任務對應的刪除，然後單擊確認。
     警告 刪除裝置任務後，與該任務相關的資料被清除，如果有依賴該任務的業務，可能導致服務不可用或影響使用者的業務。請謹慎操作。