CreateDeviceDistributeJob - IoT Platform

使用說明

您可參考以下步驟，完成裝置分發。

1. 調用本介面發起裝置分發任務（非同步呼叫），擷取返回參數JobId。

2. 將上一步的返回參數JobId作為請求參數，重複調用介面QueryDeviceDistributeJob，查看返回參數Status。

說明您需根據介面的QPS限制，控制重複調用介面的頻率。

Status值如下，表示分發任務已處於最終態：

2：裝置分發任務正常執行完成。此時，不代表所有裝置分發成功，每個裝置的具體分髮結果，請執行下一步擷取。
3：分發異常中斷。處理異常流後，可重新發起裝置分發任務。

3. 將第一步的返回參數JobId作為請求參數，調用介面QueryDeviceDistributeDetail，擷取返回參數File，即分髮結果的檔案URL。

說明檔案URL的有效期間為10分鐘。

4. 通過檔案URL擷取分髮結果詳情，其中每個裝置對應一個分髮結果Code，當Code為200時，表示該裝置分發成功。

如果裝置分發失敗，您可按照以上操作，重新進行裝置分發。

限制說明

調用雲端服務的接入地址Endpoint僅支援華東2（上海），即iot.cn-shanghai.aliyuncs.com。
不支援調用本介面建立跨帳號的分發任務。
單個阿里雲帳號下，產品分發和裝置分發的任務總數不超過10個。建立產品分發任務，請參見CreateProductDistributeJob。
單個阿里雲帳號調用該介面的每秒請求數（QPS）最大限制為2。
說明 RAM使用者共用阿里雲帳號配額。

調試

您可以在OpenAPI Explorer中直接運行該介面，免去您計算簽名的困擾。運行成功後，OpenAPI Explorer可以自動產生SDK程式碼範例。

請求參數

名稱	類型	是否必選	樣本值	描述
Action	String	是	CreateDeviceDistributeJob	系統規定參數。取值：CreateDeviceDistributeJob。
DeviceName.N	RepeatList	是	RepeatList	待分發的裝置名稱列表。最多包含10,000個裝置名稱。
ProductKey	String	是	a1BwAGV****	裝置所屬產品的ProductKey。
SourceInstanceId	String	是	iot-060***	裝置所屬的源執行個體ID。各地區公用執行個體ID：華東2（上海）：iotx-oxssharez200。日本：iotx-oxssharez300。新加坡：iotx-oxssharez400。美國（矽谷）：iotx-oxssharez500。美國（維吉尼亞）：iotx-oxssharez600。德國（法蘭克福）：iotx-oxssharez700。企業版執行個體ID： 1. 登入物聯網平台控制台，從頂部導覽列左上方的下拉式功能表選擇地區。 2. 在執行個體概覽頁面，找到目標執行個體名稱，查看ID。
Strategy	Integer	是	0	分發策略。預設值為0。 0：指定地區，將裝置分發到指定地區的一個執行個體中。 1：就近接入，配置多個地區的執行個體ID，裝置將根據裝置的IP位置動態接入其中距離最近的地區。
TargetInstanceConfig.N.TargetInstanceId	String	是	iot-cn-6ja***	裝置分發的目標執行個體配置。執行個體ID詳情，請參見參數SourceInstanceId描述。當參數Strategy為1時，此處可傳入多個執行個體ID。當參數Strategy為0時，此處傳入一個執行個體ID。
TargetUid	String	否	198***	裝置所屬的阿里雲帳號ID。可登入物聯網平台控制台，單擊帳號頭像，跳轉至安全設定頁面查看。 TargetUid與TargetAliyunId參數至少傳入一個。
TargetAliyunId	String	否	io****@example.com	裝置所屬的阿里雲帳號。可登入物聯網平台控制台，單擊帳號頭像，跳轉至安全設定頁面查看。 TargetUid與TargetAliyunId參數至少傳入一個。

調用API時，除了本文介紹的該API的特有請求參數，還需傳入公用請求參數。公用請求參數說明，請參見公用參數文檔。

返回資料

名稱	類型	樣本值	描述
Code	String	iot.system.SystemException	調用失敗時，返回的錯誤碼。更多資訊，請參見錯誤碼。
ErrorMessage	String	系統異常	調用失敗時，返回的出錯資訊。
JobId	String	UbmsMHmkqv0PiAG****010001	調用成功後，返回的任務ID。任務的通用唯一識別碼。
RequestId	String	E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565	阿里雲為該請求產生的唯一識別碼。
Success	Boolean	true	表示是否調用成功。 true：調用成功。 false：調用失敗。

樣本

請求樣本

http(s)://iot.cn-shanghai.aliyuncs.com/?Action=CreateDeviceDistributeJob
&DeviceName.1=RepeatList
&ProductKey=a1BwAGV****
&SourceInstanceId=iot-060***
&Strategy=0
&TargetInstanceConfig.1.TargetInstanceId=iot-cn-6ja***
&TargetAliyunId=io****@example.com
&<公用請求參數>

正常返回樣本

XML格式

<CreateDeviceDistributeJobResponse>
  <RequestId>E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565</RequestId>
  <JobId>UbmsMHmkqv0PiAG****010001</JobId>
  <Success>true</Success>
</CreateDeviceDistributeJobResponse>

JSON格式

{
    "RequestId": "E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565",
    "JobId": "UbmsMHmkqv0PiAG****010001",
    "Success": true
}

錯誤碼

訪問錯誤中心查看更多錯誤碼。