任务管理和控制 API 以及数据类型 - Amazon IoT Core
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

任务管理和控制 API 以及数据类型

以下命令可供 CLI 中的 Job 管理和控制和通过 HTTPS 协议使用。

要确定 CLI 命令的 endpoint-url 参数,请运行此命令。

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

此命令将返回以下输出。

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

Jobs 终端节点不支持 ALPN z-amzn-http-ca

任务管理和控制数据类型

管理和控制应用程序使用以下数据类型与 Amazon IoT Jobs 进行通信。

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 } ] }, "timeoutConfig": { "inProgressTimeoutInMinutes": long } }

有关更多信息,请参阅 Jobjob

JobSummary 对象包含任务摘要。下面显示语法:

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

有关更多信息,请参阅 JobSummaryjob-summary

JobExecution 对象表示设备上的任务执行。下面显示语法:

{ "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 }

有关更多信息,请参阅 JobExecutionjob-execution

JobExecutionSummary 对象包含任务执行摘要信息。下面显示语法:

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

有关更多信息,请参阅 JobExecutionSummaryjob-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 } }, ... ] }

有关更多信息,请参阅 JobExecutionSummaryForJobjob-execution-summary-for-job

JobExecutionSummaryForThing 对象包含有关特定事物上的任务执行的信息摘要。下面显示语法:

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

有关更多信息,请参阅 JobExecutionSummaryForThingjob-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 参数必须是有效事物或事物组 ARN 的列表。所有事物和事物组必须在您的Amazon Web Services 账户中。

  • documentSource 参数必须是指向任务文档的有效 Amazon S3 URL。Amazon S3 URL 的格式为:https://s3.amazonaws.com/bucketName/objectName

  • 存储在由 documentSource 参数指定的 URL 中的文档必须是 UTF-8 编码的 JSON 文档。

  • 由于 MQTT 消息大小限制 (128 KB) 和加密的原因,任务文档的大小限制为 32 KB。

  • jobId 必须在您的Amazon Web Services 账户中是唯一的。

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 } ] }, "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

获取任务执行的详细信息。任务的执行状态必须为 SUCCEEDEDFAILED

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

获取任务的任务文档。

注意

占位符 URL 不会替换为返回文档中的预签名 Amazon S3 URL。仅在 Amazon IoT Jobs 服务通过 MQTT 接收请求时生成预签名 URL。

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

获取 Amazon Web Services 账户中的任务列表。

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