任務管理、控制 API 和控制資料類型

以下命令可透過 HTTPS 通訊協定在 CLI 中用於任務管理和控制。

任務管理和控制資料類型
任務管理和控制 API 操作

執行這個命令，為 CLI 命令確定 endpoint-url 參數。


aws iot describe-endpoint --endpoint-type=iot:Jobs

此命令會傳回下列輸出。



{
"endpointAddress": "account-specific-prefix.jobs.iot.aws-region.amazonaws.com"
}

注意

任務端點不支援 ALPN z-amzn-http-ca。

任務管理和控制資料類型

管理和控制應用程式會使用下列資料類型與 AWS IoT 任務通訊。

Job物件包含了工作的詳細資訊。語法如下列範例所示。


{
    "jobArn": "string", 
    "jobId": "string", 
    "status": "IN_PROGRESS|CANCELED|SUCCEEDED", 
    "forceCanceled": boolean,
    "targetSelection": "CONTINUOUS|SNAPSHOT",
    "comment": "string",
    "targets": ["string"], 
    "description": "string",
    "createdAt": timestamp,
    "lastUpdatedAt": timestamp,
    "completedAt": timestamp,
    "jobProcessDetails": {
        "processingTargets": ["string"],
        "numberOfCanceledThings": long, 
        "numberOfSucceededThings": long, 
        "numberOfFailedThings": long,
        "numberOfRejectedThings": long, 
        "numberOfQueuedThings": long, 
        "numberOfInProgressThings": long, 
        "numberOfRemovedThings": long, 
        "numberOfTimedOutThings": long
    }, 
    "presignedUrlConfig": {
        "expiresInSec": number, 
        "roleArn": "string"
    }, 
    "jobExecutionsRolloutConfig": { 
        "exponentialRate": { 
           "baseRatePerMinute": integer,
           "incrementFactor": integer,
           "rateIncreaseCriteria": { 
              "numberOfNotifiedThings": integer, // Set one or the other
              "numberOfSucceededThings": integer // of these two values.
           },
           "maximumPerMinute": integer
      }
    },    
    "abortConfig": { 
       "criteriaList": [ 
          { 
             "action": "string",
             "failureType": "string",
             "minNumberOfExecutedThings": integer,
             "thresholdPercentage": integer
          }
       ]
    },
    "SchedulingConfig": { 
      "startTime": string
      "endTime": string
      "timeZone": string


      "endTimeBehavior": string

   },
    "timeoutConfig": {
        "inProgressTimeoutInMinutes": long
    }
}

如需詳細資訊，請參閱Job或job。

JobSummary物件包含了工作摘要。語法如下列範例所示。


{
    "jobArn": "string", 
    "jobId": "string",
    "status": "IN_PROGRESS|CANCELED|SUCCEEDED|SCHEDULED", 
    "targetSelection": "CONTINUOUS|SNAPSHOT",
    "thingGroupId": "string",
    "createdAt": timestamp, 
    "lastUpdatedAt": timestamp, 
    "completedAt": timestamp
}

如需詳細資訊，請參閱JobSummary或job-summary。

JobExecution 物件代表在裝置上執行任務。語法如下列範例所示。

注意

當您使用控制平面 API 操作時，JobExecution 資料類型不包含 JobDocument 欄位。若要取得此資訊，您可以使用 GetJobDocument API 操作或 get-job-document CLI 命令。


{
    "approximateSecondsBeforeTimedOut": 50,
    "executionNumber": 1234567890,
    "forceCanceled": true|false,
    "jobId": "string",
    "lastUpdatedAt": timestamp, 
    "queuedAt": timestamp,
    "startedAt": timestamp,
    "status": "QUEUED|IN_PROGRESS|FAILED|SUCCEEDED|CANCELED|TIMED_OUT|REJECTED|REMOVED",
    "forceCanceled": boolean,
    "statusDetails": {
        "detailsMap": { 
            "string": "string" ...
        },
        "status": "string"
    }, 
    "thingArn": "string", 
    "versionNumber": 123
}

如需詳細資訊，請參閱JobExecution或job-execution。

JobExecutionSummary 物件包含了任務執行摘要的資訊。語法如下列範例所示。


{
    "executionNumber": 1234567890,
    "queuedAt": timestamp,
    "lastUpdatedAt": timestamp,
    "startedAt": timestamp,
    "status": "QUEUED|IN_PROGRESS|FAILED|SUCCEEDED|CANCELED|TIMED_OUT|REJECTED|REMOVED"
}

如需詳細資訊，請參閱JobExecutionSummary或job-execution-summary。

JobExecutionSummaryForJob物件包含了關於特定工作之工作執行的資訊摘要。語法如下列範例所示。


{
    "executionSummaries": [
        {
            "thingArn": "arn:aws:iot:us-west-2:123456789012:thing/MyThing", 
            "jobExecutionSummary": {
                "status": "IN_PROGRESS", 
                "lastUpdatedAt": 1549395301.389, 
                "queuedAt": 1541526002.609, 
                "executionNumber": 1
            }
        }, 
        ...
    ]
}

如需詳細資訊，請參閱JobExecutionSummaryForJob或job-execution-summary-for-job。

JobExecutionSummaryForThing物件包含了關於特定物件之工作執行的資訊摘要。語法如下列範例所示：


{
    "executionSummaries": [
        {
            "jobExecutionSummary": {
                "status": "IN_PROGRESS", 
                "lastUpdatedAt": 1549395301.389, 
                "queuedAt": 1541526002.609, 
                "executionNumber": 1
            }, 
            "jobId": "MyThingJob"
        },
        ...
    ]
}

如需詳細資訊，請參閱JobExecutionSummaryForThing或job-execution-summary-for-thing。

任務管理和控制 API 操作

使用下列 API 操作或 CLI 命令：

將群組與持續性任務建立關聯。必須符合以下條件：

建立任務時必須將 targetSelection 欄位設定為「CONTINUOUS」。
任務狀態目前必須是「IN_PROGRESS」。
與工作關聯的目標總數不得超過 100 個。

取消任務。

取消裝置上的任務執行。

建立任務。您可以將 Amazon S3 儲存貯體 (documentSource 參數) 或請求本文 (document 參數) 中的檔案連結提供給任務文件。

您可以將選用 targetSelection 參數設定為 CONTINUOUS (預設為 SNAPSHOT) 以讓任務「持續」執行。持續任務可以用來在新增至群組時加入或升級裝置，因為它會持續執行，並在新增的項目上啟動。即使在建立任務時群組中的物件已完成任務之後，仍可能發生這種情況。

任務可以有一個選用 TimeoutConfig，其會設定進行中計時器的值。進行中計時器無法更新，並會套用到任務的所有執行。

以下驗證會在 CreateJobAPI 的引數上執行：

targets引數必須是有效物件或物件群組 ARN 的清單。所有物件和物件群組都必須在您的 AWS 帳戶中。
documentSource 引數必須是連結至任務文件的有效 Amazon S3 URL。Amazon S3 URL 的格式為：https://s3.amazonaws.com/bucketName/objectName。
由 documentSource引數指定存放文件的 URL 必須是 UTF-8 編碼的 JSON 文件。
由於 MQTT 訊息大小限制 (128 KB) 與加密因素，因此工作文件的大小限制為 32 KB。
在您的 AWS 帳戶中，jobId 必須是唯一的。

HTTPS request


PUT /jobs/jobId
 
{
"targets": [ "string" ],
"document": "string",
"documentSource": "string",
"description": "string",
"jobTemplateArn": "string",
"presignedUrlConfigData": {
    "roleArn": "string", 
    "expiresInSec": "integer" 
},
"targetSelection": "CONTINUOUS|SNAPSHOT",
"jobExecutionsRolloutConfig": { 
    "exponentialRate": { 
       "baseRatePerMinute": integer,
       "incrementFactor": integer,
       "rateIncreaseCriteria": { 
          "numberOfNotifiedThings": integer, // Set one or the other
          "numberOfSucceededThings": integer // of these two values.
       },
       "maximumPerMinute": integer
  }
},
"abortConfig": { 
   "criteriaList": [ 
      { 
         "action": "string",
         "failureType": "string",
         "minNumberOfExecutedThings": integer,
         "thresholdPercentage": integer
      }
   ]
},
"SchedulingConfig": { 
    "startTime": string
    "endTime": string
    "timeZone": string


    "endTimeBehavior": string

   }
"timeoutConfig": { 
  "inProgressTimeoutInMinutes": long
}
}

如需更多詳細資訊，請參閱 CreateJob。

CLI syntax


aws iot create-job \
    --job-id <value> \
    --targets <value> \
    [--document-source <value>] \
    [--document <value>] \
    [--description <value>] \
    [--job-template-arn <value>] \
    [--presigned-url-config <value>] \
    [--target-selection <value>] \
    [--job-executions-rollout-config <value>] \
    [--abort-config <value>] \
    [--timeout-config <value>] \
    [--document-parameters <value>]  \
    [--cli-input-json <value>] \
    [--generate-cli-skeleton]

cli-input-json 格式：


{
    "jobId": "string",
    "targets": [ "string" ],
    "documentSource": "string",
    "document": "string",
    "description": "string",
    "jobTemplateArn": "string",
    "presignedUrlConfig": {
        "roleArn": "string",
        "expiresInSec": long
     },
    "targetSelection": "string",
    "jobExecutionsRolloutConfig": { 
          "exponentialRate": { 
              "baseRatePerMinute": integer,
              "incrementFactor": integer,
              "rateIncreaseCriteria": { 
                 "numberOfNotifiedThings": integer, // Set one or the other
                 "numberOfSucceededThings": integer // of these two values.
              },
      "maximumPerMinute": integer
      }
    }, 
    "abortConfig": { 
    "criteriaList": [ 
        { 
           "action": "string",
           "failureType": "string",
           "minNumberOfExecutedThings": integer,
           "thresholdPercentage": integer
         }
      ]
    },
    "timeoutConfig": { 
          "inProgressTimeoutInMinutes": long
    },
    "documentParameters": {
    "string": "string"
    }
}

如需更多詳細資訊，請參閱 create-job。

刪除任務及其相關的任務執行。

刪除任務可能會需要時間，根據為任務與各種其他因素所建立的任務執行數量而定。雖然任務被刪除，任務狀態將顯示為「DELETION_IN_PROGRESS」。嘗試刪除或取消狀態已為「DELETION_IN_PROGRESS」的任務將會導致錯誤。

刪除任務執行。

取得任務執行的詳細資訊。

取得工作執行的詳細資訊。任務的執行狀態必須為 SUCCEEDED或 FAILED。

取得工作的工作文件。

注意

在傳回的文件中，預留位置 URL 不會被預先簽章的 Amazon S3 URL 取代。預先簽章的 URL 只有在 AWS IoT 任務服務透過 MQTT 收到請求時才會產生。

取得工作的工作執行清單。

取得物件的工作執行清單。

取得您 AWS 帳戶中的任務清單。

更新指定任務的支援欄位。timeoutConfig 的更新值僅對新進行中的啟動生效。目前，進行中的啟動會繼續以先前的逾時組態啟動。

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

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

文件慣用形式

AWS IoT 任務 API 操作

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