任務管理和控制API以及資料類型 - AWS IoT Core
任務管理和控制資料類型任務管理和控制API操作

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

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

下列命令可用於 和 CLI HTTPS通訊協定中的任務管理和控制。

若要判斷CLI命令的 endpoint-url 參數，請執行此命令。

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

此命令會傳回下列輸出。


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

任務端點不支援 ALPN x-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 欄位。若要取得此資訊，您可以使用 GetJobDocumentAPI操作或 get-job-documentCLI命令。

{
    "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 物件包含特定物件上任務執行的相關資訊摘要。FThe下列範例顯示語法：

{
    "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 個。

HTTPS request
POST /jobs/jobId/targets
 
{ 
"targets": [ "string" ],
"comment": "string"
}

如需詳細資訊，請參閱AssociateTargetsWithJob。

CLI syntax
aws iot  associate-targets-with-job \
--targets <value> \
--job-id <value> \
[--comment <value>]  \
[--cli-input-json <value>] \
[--generate-cli-skeleton]

cli-input-json 格式：

{
"targets": [
"string"
],
"jobId": "string",
"comment": "string"
}

如需詳細資訊，請參閱associate-targets-with-job。

取消任務。

HTTPS request
PUT /jobs/jobId/cancel
 
{ 
"force": boolean,
"comment": "string",
"reasonCode": "string"
}

如需詳細資訊，請參閱CancelJob。

CLI syntax
aws iot cancel-job \
    --job-id <value> \
    [--force <value>]  \
    [--comment <value>]  \
    [--reasonCode <value>]  \
    [--cli-input-json <value>] \
    [--generate-cli-skeleton]

cli-input-json 格式：

{
    "jobId": "string",
    "force": boolean,
    "comment": "string"
}

如需詳細資訊，請參閱cancel-job。

取消裝置上的任務執行。

HTTPS request
PUT /things/thingName/jobs/jobId/cancel
 
{ 
"force": boolean,
"expectedVersion": "string",
"statusDetails": {
    "string": "string"
    ...
}
}

如需詳細資訊，請參閱CancelJobExecution。

CLI syntax
aws iot cancel-job-execution \
--job-id <value> \
--thing-name <value> \
[--force | --no-force] \
[--expected-version <value>] \
[--status-details <value>]  \
[--cli-input-json <value>] \
[--generate-cli-skeleton]

cli-input-json 格式：

{
"jobId": "string",
"thingName": "string",
"force": boolean,
"expectedVersion": long,
"statusDetails": {
"string": "string"
}
}

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

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

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

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

對 CreateJob 的引數執行下列驗證API：

  • targets 引數必須是有效物件或物件群組 的清單ARNs。所有物件和物件群組都必須位於您的 中 AWS 帳戶。

  • documentSource 引數必須是URL任務文件的有效 Amazon S3。Amazon S3 的格式URLs為：https://s3.amazonaws.com/bucketName/objectName。

  • 儲存在 中由documentSource引數URL指定的文件必須是 UTF-8 編碼JSON的文件。

  • 由於MQTT訊息大小 (128 KB) 和加密的限制，任務文件的大小限制為 32 KB。

  • 在您的 中jobId必須是唯一的 AWS 帳戶。

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" 的任務會導致錯誤。

HTTPS request
DELETE /jobs/jobId?force=force

如需詳細資訊，請參閱DeleteJob。

CLI syntax
aws iot  delete-job \
--job-id <value> \
[--force | --no-force]  \
[--cli-input-json <value>] \
[--generate-cli-skeleton]

cli-input-json 格式：

{
"jobId": "string",
"force": boolean
}

如需詳細資訊，請參閱delete-job。

刪除任務執行。

HTTPS request
DELETE /things/thingName/jobs/jobId/executionNumber/executionNumber?force=force

如需詳細資訊，請參閱DeleteJobExecution。

CLI syntax
aws iot  delete-job-execution \
--job-id <value> \
--thing-name <value> \
--execution-number <value> \
[--force | --no-force]  \
[--cli-input-json <value>] \
[--generate-cli-skeleton]

cli-input-json 格式：

{
"jobId": "string",
"thingName": "string",
"executionNumber": long,
"force": boolean
}

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

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

HTTPS request
GET /jobs/jobId

如需詳細資訊，請參閱DescribeJob。

CLI syntax
aws iot describe-job \
--job-id <value>  \
[--cli-input-json <value>] \
[--generate-cli-skeleton]

cli-input-json 格式：

{
"jobId": "string"
}

如需詳細資訊，請參閱describe-job。

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

HTTPS request
GET /things/thingName/jobs/jobId?executionNumber=executionNumber

如需詳細資訊，請參閱DescribeJobExecution。

CLI syntax
aws iot  describe-job-execution \
--job-id <value> \
--thing-name <value> \
[--execution-number <value>]  \
[--cli-input-json <value>] \
[--generate-cli-skeleton]

cli-input-json 格式：

{
"jobId": "string",
"thingName": "string",
"executionNumber": long
}

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

取得工作的工作文件。

注意

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

HTTPS request
GET /jobs/jobId/job-document

如需詳細資訊，請參閱GetJobDocument。

CLI syntax
aws iot get-job-document \
--job-id <value>  \
[--cli-input-json <value>] \
[--generate-cli-skeleton]

cli-input-json 格式：

{
"jobId": "string"
}

如需詳細資訊，請參閱get-job-document。

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

HTTPS request
GET /jobs/jobId/things?status=status&maxResults=maxResults&nextToken=nextToken

如需詳細資訊，請參閱ListJobExecutionsForJob。

CLI syntax
aws iot  list-job-executions-for-job \
--job-id <value> \
[--status <value>] \
[--max-results <value>] \
[--next-token <value>]  \
[--cli-input-json <value>] \
[--generate-cli-skeleton]

cli-input-json 格式：

{
"jobId": "string",
"status": "string",
"maxResults": "integer",
"nextToken": "string"
}

如需詳細資訊，請參閱list-job-executions-for-job。

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

HTTPS request
GET /things/thingName/jobs?status=status&maxResults=maxResults&nextToken=nextToken

如需詳細資訊，請參閱ListJobExecutionsForThing。

CLI syntax
aws iot list-job-executions-for-thing \
--thing-name <value> \
[--status <value>] \
[--max-results <value>] \
[--next-token <value>]  \
[--cli-input-json <value>] \
[--generate-cli-skeleton]

cli-input-json 格式：

{
"thingName": "string",
"status": "string",
"maxResults": "integer",
"nextToken": "string"
}

如需詳細資訊，請參閱list-job-executions-for-thing。

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

HTTPS request
GET /jobs?status=status&targetSelection=targetSelection&thingGroupName=thingGroupName&thingGroupId=thingGroupId&maxResults=maxResults&nextToken=nextToken

如需詳細資訊，請參閱ListJobs。

CLI syntax
aws iot list-jobs \
[--status <value>] \
[--target-selection <value>] \
[--max-results <value>] \
[--next-token <value>] \
[--thing-group-name <value>] \
[--thing-group-id <value>]  \
[--cli-input-json <value>] \
[--generate-cli-skeleton]

cli-input-json 格式：

{
"status": "string",
"targetSelection": "string",
"maxResults": "integer",
"nextToken": "string",
"thingGroupName": "string",
"thingGroupId": "string"
}

如需詳細資訊，請參閱list-jobs。

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

HTTPS request
PATCH /jobs/jobId
{
"description": "string",
"presignedUrlConfig": { 
  "expiresInSec": number,
  "roleArn": "string"
},
"jobExecutionsRolloutConfig": { 
  "exponentialRate": { 
     "baseRatePerMinute": number,
     "incrementFactor": number,
     "rateIncreaseCriteria": { 
        "numberOfNotifiedThings": number,
        "numberOfSucceededThings": number
     }, 
  "maximumPerMinute": number
  },
"abortConfig": { 
  "criteriaList": [ 
     { 
        "action": "string",
        "failureType": "string",
        "minNumberOfExecutedThings": number,
        "thresholdPercentage": number
     }
  ]
},
"timeoutConfig": { 
  "inProgressTimeoutInMinutes": number
}
}

如需詳細資訊，請參閱UpdateJob。

CLI syntax
aws iot  update-job \
--job-id <value> \
[--description <value>] \
[--presigned-url-config <value>] \
[--job-executions-rollout-config <value>] \
[--abort-config <value>] \
[--timeout-config <value>] \
[--cli-input-json <value>] \
[--generate-cli-skeleton]

cli-input-json 格式：

{
"description": "string",
"presignedUrlConfig": { 
  "expiresInSec": number,
  "roleArn": "string"
},
"jobExecutionsRolloutConfig": { 
  "exponentialRate": { 
     "baseRatePerMinute": number,
     "incrementFactor": number,
     "rateIncreaseCriteria": { 
        "numberOfNotifiedThings": number,
        "numberOfSucceededThings": number
     }
  },
  "maximumPerMinute": number
},
"abortConfig": { 
  "criteriaList": [ 
     { 
        "action": "string",
        "failureType": "string",
        "minNumberOfExecutedThings": number,
        "thresholdPercentage": number
     }
  ]
},
"timeoutConfig": { 
  "inProgressTimeoutInMinutes": number
}
}

如需詳細資訊，請參閱update-job。