任務裝置 MQTT API 操作

您可以發出任務裝置命令，方法為將 MQTT 訊息發佈至用於任務命令的保留主題。

您的裝置端用戶端必須訂閱這些命令的回應訊息主題。如果您使用 AWS IoT 裝置用户端，您的裝置會自動訂閱回應主題。這表示，無論您的用戶端是否已訂閱回應訊息主題，訊息代理程式都會將回應訊息主題發佈至發佈命令訊息的用戶端。這些回應訊息不會透過訊息代理程式傳遞，而且其他用戶端或規則無法訂閱這些訊息。

訂閱機群監控解決方案的任務和 jobExecution 事件主題時，首先啟用任務和任務執行事件來接收雲端的任何事件。透過訊息代理程式處理並可由 AWS IoT 規則使用的任務進度訊息會發佈為任務事件。由於訊息代理程式會發佈回應訊息，即使沒有明確地訂閱它們，您的用戶端也必須設定為接收並識別其所接收的訊息。您的用戶端也必須確認，在用戶端對訊息採取動作之前，內送訊息主題中的 thingName 套用至用戶端的物件名稱。

注意

AWS IoT 若傳送訊息，以回應 MQTT 任務 API 命令訊息，無論您是否明確地訂閱這些訊息，都會向您的帳戶收費。

以下說明 MQTT API 操作及其請求和回應語法。所有 MQTT API 操作均有下列參數：

clientToken: 用來關聯請求和回應的選用用戶端字符。在此輸入任意值，就會在回應中反映出來。
timestamp: 訊息傳送的 epoch 時間，以秒為單位。

針對特定物件，取得其所有未處於終止狀態之任務的清單。

欲呼叫此 API，請發佈訊息於 $aws/things/thingName/jobs/get。

請求酬載：


{ "clientToken": "string" }

訊息代理程式將發佈 $aws/things/thingName/jobs/get/accepted 和 $aws/things/thingName/jobs/get/rejected，即使沒有具體訂閱它們也一樣。不過，為了讓您的用戶端接收訊息，它必須正在接聽它們。如需詳細資訊，請參閱關於任務 API 訊息的注意事項。

回應酬載：


{
"inProgressJobs" : [ JobExecutionSummary ... ], 
"queuedJobs" : [ JobExecutionSummary ... ],
"timestamp" : 1489096425069,
"clientToken" : "client-001"
}

inProgressJobs 和 queuedJobs 回傳狀態為 IN_PROGRESS 或 QUEUED 的 JobExecutionSummary 物件清單。

取得並啟動物件的下一個待定任務執行 (狀態 IN_PROGRESS 或 QUEUED)。

狀態為 IN_PROGRESS 的任務執行會先傳回。
任務執行會依照其排入佇列的順序傳回。當您任務的目標群組中新增或移除物件時，請確認所有新任務執行相較於現有任務執行的推展順序。
如果下一個待定任務執行為 QUEUED，則其狀態會變更為 IN_PROGRESS，而任務執行狀態詳細資訊也會依指定設定。
如果下一個待定任務執行已經為 IN_PROGRESS，則其狀態詳細資訊不會變更。
如果沒有工作執行為待定，則回應不會包括 execution 欄位。
您也可以選擇透過設定 stepTimeoutInMinutes 的屬性來新增步驟計時器。如果您未透過執行 UpdateJobExecution 來更新此屬性的值，則步驟計時器逾期時，任務執行將逾時。

欲呼叫此 API，請發佈訊息於 $aws/things/thingName/jobs/start-next。

請求酬載：


{ 
"statusDetails": {
    "string": "job-execution-state"
    ...
},
"stepTimeoutInMinutes": long,
"clientToken": "string"
}

statusDetails: 名稱值對的集合，能夠描述任務執行的狀態。如果未指定，則 statusDetails 不會改變。
stepTimeOutInMinutes: 指定此裝置必須完成這項任務執行的時間。在此計時器到期或計時器重設之前 (藉由呼叫 UpdateJobExecution，將狀態設為 IN_PROGRESS，並在 stepTimeoutInMinutes 欄位中指定新的逾時值)，如果任務執行狀態未設定為結束狀態，任務執行狀態就會設為 TIMED_OUT。設定此逾時不會影響任務執行逾時，該任務執行逾時可能已在建立任務時加以指定 (使用欄位 timeoutConfig 的 CreateJob)。

訊息代理程式將發佈 $aws/things/thingName/jobs/start-next/accepted 和 $aws/things/thingName/jobs/start-next/rejected，即使沒有具體訂閱它們也一樣。不過，為了讓您的用戶端接收訊息，它必須正在接聽它們。如需詳細資訊，請參閱關於任務 API 訊息的注意事項。

回應酬載：


{
"execution" : JobExecutionData,
"timestamp" : timestamp,
"clientToken" : "string"
}

execution 為 JobExecution 物件。例如：


{
"execution" : {
    "jobId" : "022",
    "thingName" : "MyThing",
    "jobDocument" : "< contents of job document >",
    "status" : "IN_PROGRESS",
    "queuedAt" : 1489096123309,
    "lastUpdatedAt" : 1489096123309,
    "versionNumber" : 1,
    "executionNumber" : 1234567890
},
"clientToken" : "client-1",
"timestamp" : 1489088524284,
}

取得工作執行的詳細資訊。

您可以將 jobId 設定為 $next，傳回物件 (狀態為 IN_PROGRESS 或 QUEUED) 的下一個待定任務執行。

欲呼叫此 API，請發佈訊息於 $aws/things/thingName/jobs/jobId/get。

請求酬載：


{ 
"jobId" : "022",
"thingName" : "MyThing",
"executionNumber": long,
"includeJobDocument": boolean,
"clientToken": "string" 
}

thingName

與裝置關聯的物件名稱。

jobId

此工作在建立時被指派的獨特識別符。

或者使用 $next 傳回物件 (狀態為 IN_PROGRESS 或 QUEUED) 的下一個待定任務執行。在此情況下，狀態為 IN_PROGRESS 的任務執行會先傳回。工作執行會依照其建立的順序傳回。

executionNumber

(選用) 可識別在裝置上之任務執行的編號。如果未指定，則會傳回最新的工作執行。

includeJobDocument

(選用) 除非設為 false，否則回應會包含任務文件。預設值為 true。

訊息代理程式將發佈 $aws/things/thingName/jobs/jobId/get/accepted 和 $aws/things/thingName/jobs/jobId/get/rejected，即使沒有具體訂閱它們也一樣。不過，為了讓您的用戶端接收訊息，它必須正在接聽它們。如需詳細資訊，請參閱關於任務 API 訊息的注意事項。

回應酬載：


{
"execution" : JobExecutionData,
"timestamp": "timestamp",
"clientToken": "string"
}

execution 為 JobExecution 物件。

更新工作執行的狀態。您可以選擇透過設定 stepTimeoutInMinutes 的屬性來新增步驟計時器。如果您未透過再次執行 UpdateJobExecution 來更新此屬性的值，則步驟計時器逾期時，任務執行將逾時。

欲呼叫此 API，請發佈訊息於 $aws/things/thingName/jobs/jobId/update。

請求酬載：


{
"status": "job-execution-state",
"statusDetails": { 
    "string": "string"
    ...
},
"expectedVersion": "number",
"executionNumber": long,
"includeJobExecutionState": boolean,
"includeJobDocument": boolean,
"stepTimeoutInMinutes": long,
"clientToken": "string"
}

status: 任務執行的新狀態 (IN_PROGRESS、FAILED、SUCCEEDED 或 REJECTED)。這必須在每次更新時指定。
statusDetails: 名稱值對的集合，能夠描述任務執行的狀態。如果未指定，則 statusDetails 不會改變。
expectedVersion: 預期的目前工作執行版本。每次您更新工作執行，其版本編號就會增加。如果 AWS IoT 任務服務中儲存的任務執行版本不符，則會拒絕更新並顯示 VersionMismatch 錯誤。也會傳回 ErrorResponse，其中包含目前任務執行狀態資料。(這樣就不必另外執行 DescribeJobExecution 請求以獲得任務執行狀態資料。)
executionNumber: (選用) 可識別在裝置上之任務執行的編號。如果未指定，則會使用最新的工作執行。
includeJobExecutionState: (選用) 若被包括在內並設定為 true，則回應會包含 JobExecutionState 欄位。預設值為 false。
includeJobDocument: (選用) 若被包括在內並設定為 true，則回應會包含 JobDocument。預設值為 false。
stepTimeoutInMinutes: 指定此裝置必須完成這項任務執行的時間。如果任務執行狀態未在此計時器逾期之前，或未在計時器重設之前設定為終止狀態，任務執行狀態會設定為 TIMED_OUT。設定或重設此逾時不會影響任務執行逾時，該任務執行逾時可能已在建立任務時加以指定。

訊息代理程式將發佈 $aws/things/thingName/jobs/jobId/update/accepted 和 $aws/things/thingName/jobs/jobId/update/rejected，即使沒有具體訂閱它們也一樣。不過，為了讓您的用戶端接收訊息，它必須正在接聽它們。如需詳細資訊，請參閱關於任務 API 訊息的注意事項。

回應酬載：


{
"executionState": JobExecutionState,
"jobDocument": "string",
"timestamp": timestamp,
"clientToken": "string"
}

executionState: JobExecutionState 物件。
jobDocument: 工作文件物件。
timestamp: 訊息傳送的 epoch 時間，以秒為單位。
clientToken: 用於將請求和回應建立關聯的用戶端符記。

使用 MQTT 通訊協定時，也可以執行下列更新：

每當物件的待定任務執行清單新增或移除任務執行時就會傳送。

使用主題：

$aws/things/thingName/jobs/notify

訊息酬載：


{
"jobs" : {
    "JobExecutionState": [ JobExecutionSummary ... ]
         },
    "timestamp": timestamp
}

每當物件待定任務清單上的下一個任務執行變更就會傳送，亦即定義 DescribeJobExecution 時加上 jobId $next。當下一個任務的執行詳細資訊變更，此訊息並不會傳送，只有在加上 jobId $next 之 DescribeJobExecution 傳回的下一個任務變更時才會傳送。考量狀態為 QUEUED 的任務執行 J1 與 J2。J1 是下一個待定任務執行。如果 J2 的狀態變更為 IN_PROGRESS 而 J1 的狀態保持不變，則會傳送此通知並包含 J2 的詳細資訊。

使用主題：

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

訊息酬載：


{
"execution" : JobExecution,
"timestamp": timestamp,
}

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

任務裝置 MQTT、HTTPS API 操作和資料類型

任務裝置 HTTP API