AWS IoT
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 Amazon AWS 入门

使用 AWS IoT Jobs API

有两类在 AWS IoT Jobs 中使用的 API:

  • 用于管理和控制任务的 API。

  • 由执行这些任务的设备使用的 API。

通常,任务的管理和控制操作将使用 HTTPS 协议 API。设备可以使用 MQTT 或 HTTPS 协议 API。(HTTPS API 旨在用于通常在创建和跟踪任务时进行的少量调用。它通常会为一个请求打开一个连接,然后在收到响应后关闭此连接。MQTT API 允许长轮询。它旨在用于可扩展至数百万台设备的大量流量。)

注意

每个 Jobs HTTPS API 均有一个对应的命令,您可使用该命令从 AWS CLI 调用该 API。命令采用小写形式,并且在构成 API 名称的单词之间使用连字符。例如,您可以通过键入以下内容,在 CLI 上调用 CreateJob API:

aws iot create-job ...

任务管理和控制 API

任务管理和控制数据类型

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

任务

Job 数据类型语法 (1)描述 (1)
Job 数据类型

Job 对象包含有关任务的详细信息。

语法 (1)
{ "jobArn": "string", "jobId": "string", "status": "IN_PROGRESS|CANCELED|COMPLETED", "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", }, "presignedUrlConfig": { "expiresInSec": number, "roleArn": "string" }, "jobExecutionRolloutConfig": { "maximumPerMinute": "integer" } }
描述 (1)
jobArn

一个标识任务的 ARN,格式为“arn:aws:iot:region:account:job/jobId”。

jobId

您在创建此任务时向其分配的唯一标识符。

status

任务的状态,为 IN_PROGRESSCANCELEDCOMPLETED 之一。

targetSelection

指定任务是继续运行 (CONTINUOUS),还是在指定作为目标的事物完成任务后完成 (SNAPSHOT)。如果为 CONTINUOUS,则在目标中检测到更改时,任务也可能会在事物上运行。例如,在将一个事物添加到目标组时,任务会在该事物上运行,甚至在组中原有的所有事物都完成任务后也是如此。

comment

如果任务已更新,介绍更新原因。

targets

任务应发送到的 AWS IoT 事物和事物组的列表。

description

任务的简短文本描述。

createdAt

创建任务的时间,用从纪元开始的毫秒数表示。

lastUpdatedAt

上次更新任务的时间,用从纪元开始的毫秒数表示。

completedAt

完成任务的时间,用从纪元开始的毫秒数表示。

jobProcessDetails

有关任务流程的详细信息:

processingTargets

当前正在执行任务的 AWS IoT 事物和事物组的列表。

numberOfCanceledThings

已取消任务的 AWS IoT 事物的数量。

numberOfSucceededThings

已成功完成任务的 AWS IoT 事物的数量。

numberOfFailedThings

未能完成任务的 AWS IoT 事物的数量。

numberOfRejectedThings

已拒绝任务的 AWS IoT 事物的数量。

numberOfQueuedThings

正在等待任务执行的 AWS IoT 事物的数量。

numberOfInProgressThings

当前正在执行任务的 AWS IoT 事物的数量。

numberOfRemovedThings

因其已从作为任务目标的组中被删除或移除而不再计划执行的 AWS IoT 事物的数量。

presignedUrlConfig

预签名 Amazon S3 URL 的配置信息。

expiresInSec

预签名 URL 的有效期时间长度 (以秒为单位)。有效值为 60-3600。默认值为 3600 秒。在 Jobs 收到任务文档的 MQTT 请求时会生成预签名 URL。

roleArn

授予从 Amazon S3 存储桶下载文件的权限的 IAM 角色的 ARN。该角色还必须向 AWS IoT 授予下载文件的权限。有关如何创建和配置角色的更多信息,请参阅创建任务

jobExecutionRolloutConfig

允许您创建任务的分段部署。

maximumPerMinute

每分钟将任务发送到的用于执行任务的事物 (设备) 的最大数量。

JobSummary

JobSummary 数据类型语法 (2)描述 (2)
JobSummary 数据类型

JobSummary 对象包含任务摘要。

语法 (2)
{ "jobArn": "string", "jobId": "string", "status": "IN_PROGRESS|CANCELED|COMPLETED", "targetSelection": "CONTINUOUS|SNAPSHOT", "thingGroupId": "string", "createdAt": timestamp, "lastUpdatedAt": timestamp, "completedAt": timestamp }
描述 (2)
jobArn

一个标识任务的 ARN。

jobId

您在创建此任务时向其分配的唯一标识符。

status

任务状态。可以为以下值之一:IN_PROGRESSCANCELEDCOMPLETED

targetSelection

指定任务是继续运行 (CONTINUOUS),还是在指定作为目标的所有事物完成任务后完成 (SNAPSHOT)。如果为 CONTINUOUS,则在目标中检测到更改时,任务也可能会在事物上运行。例如,在将一个事物添加到目标组时,任务会在该事物上运行,甚至在组中原有的所有事物都完成任务后也是如此。

thingGroupId

事物组的 ID。

createdAt

创建任务的时间的 UNIX 时间戳。

lastUpdatedAt

上次更新任务的时间的 UNIX 时间戳。

completedAt

完成任务的时间的 UNIX 时间戳。

JobExecution

JobExection 数据类型语法 (3)描述 (3)
JobExection 数据类型

JobExecution 对象表示特定设备上的任务执行。

语法 (3)
{ "executionNumber": 1234567890, "forceCanceled": true|false, "jobId": "string", "lastUpdatedAt": timestamp, "queuedAt": timestamp, "startedAt": timestamp, "status": "QUEUED|IN_PROGRESS|FAILED|SUCCESS|CANCELED|REJECTED|REMOVED", "forceCanceled": boolean, "statusDetails": { "detailsMap": { "string": "string" ... }, "status": "string" }, "thingArn": "string", "versionNumber": 123 }
描述 (3)
jobId

您在创建此任务时向其分配的唯一标识符。

executionNumber

一个标识该特定设备上的此任务执行的数字。它可随后在返回或更新任务执行信息的命令中使用。

thingArn

AWS IoT 事物 ARN。

queuedAt

任务执行入队的时间,用从纪元开始的毫秒数表示。

lastUpdatedAt

上次更新任务执行的时间,用从纪元开始的毫秒数表示。

startedAt

任务执行开始的时间,用从纪元开始的毫秒数表示。

status

任务执行的状态。可以为以下值之一:“QUEUED”、“IN_PROGRESS”、“FAILED”、“SUCCESS”、“CANCELED”、“REJECTED”或“REMOVED”。

statusDetails

描述任务执行状态的名称/值对的集合。

JobExecutionSummary

JobExecutionSummary 数据类型语法 (4)描述 (4)
JobExecutionSummary 数据类型

JobExecutionSummary 对象包含任务执行摘要信息:

语法 (4)
{ "executionNumber": 1234567890, "queuedAt": timestamp, "lastUpdatedAt": timestamp, "startedAt": timestamp, "status": "QUEUED|IN_PROGRESS|FAILED|SUCCESS|CANCELED|REJECTED|REMOVED" }
描述 (4)
executionNumber

标识特定设备上的特定任务执行的数字。它可随后在返回或更新任务执行信息的命令中使用。

queuedAt

任务执行入队的时间,用从纪元开始的毫秒数表示。

lastUpdatedAt

上次更新任务执行的时间,用从纪元开始的毫秒数表示。

startAt

任务执行开始的时间,用从纪元开始的毫秒数表示。

status

任务执行的状态:QUEUED、IN_PROGRESS、FAILED、SUCCESS、CANCELED、REJECTED 或 REMOVED。

JobExecutionSummaryForJob

JobExecutionSummaryForJob 数据类型语法 (5)描述 (5)
JobExecutionSummaryForJob 数据类型

JobExecutionSummaryForJob 对象包含有关特定任务的任务执行的信息摘要。

语法 (5)
{ "executionSummary": [ { "thingArn": "string", "jobExecutionSummary": { JobExecutionSummary } } ... ] }
描述 (5)
thingArn

AWS IoT 事物 ARN。

jobExecutionSummary

一个 JobExecutionSummary 对象。

JobExecutionSummaryForThing

JobExecutionSummaryForThing 数据类型语法 (6)描述 (6)
JobExecutionSummaryForThing 数据类型

JobExecutionSummaryForThing 对象包含有关特定事物上的任务执行的信息摘要。

语法 (6)
{ "jobId": "string", "jobExecutionSummary": { JobExecutionSummary } }
描述 (6)
jobId

您在创建此任务时向其分配的唯一标识符。

jobExecutionSummary

一个 JobExecutionSummary 对象。

任务管理和控制 HTTPS 命令

以下命令可供管理和控制应用程序通过 HTTPS 协议使用。

AssociateTargetsWithJob

AssociateTargetsWithJob 命令HTTPS (1)CLI (1)MQTT (1)
AssociateTargetsWithJob 命令

将组与持续任务关联。有关更多信息,请参阅 CreateJob。必须满足以下标准:

  • 创建任务时必须将 targetSelection 字段设置为“CONTINUOUS”。

  • 任务状态当前必须为“IN_PROGRESS”。

  • 与任务关联的目标总数不能超过 100。

HTTPS (1)

请求:

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

您在创建此任务时向其分配的唯一标识符。

targets

定义任务目标的事物组 ARN 列表。

comment

可选。一个备注字符串,描述将任务与目标关联的原因。

响应:

{ "jobArn": "string", "jobId": "string", "description": "string" }
jobArn

标识任务的 ARN。

jobId

您在创建此任务时向其分配的唯一标识符。

description

任务的简短文本描述。

CLI (1)

摘要:

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

cli-input-json format:

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

cli-input-json 字段:

名称

类型

描述

目标

列表

成员:TargetArn

定义任务目标的事物组 ARN 列表。

TargetArn

字符串

jobId

字符串

最大长度:64,最小长度:1

模式:[a-zA-Z0-9_-]+

您在创建此任务时向其分配的唯一标识符。

comment

字符串

最大长度:2028

模式:[^\\p{C}]+

一个可选的备注字符串,用于描述为什么将任务与目标关联。

输出:

{ "jobArn": "string", "jobId": "string", "description": "string" }

cli 输出字段:

名称

类型

描述

jobArn

字符串

标识任务的 ARN。

jobId

字符串

最大长度:64,最小长度:1

模式:[a-zA-Z0-9_-]+

您在创建此任务时向其分配的唯一标识符。

description

字符串

最大长度:2028

模式:[^\\p{C}]+

任务的简短文本描述。

MQTT (1)

不可用。

CancelJob

CancelJob 命令HTTPS (2)CLI (2)MQTT (2)
CancelJob 命令

取消任务。

HTTPS (2)

请求:

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

您在创建此任务时向其分配的唯一标识符。

force

[可选] 如果为 true,则取消状态为“IN_PROGRESS”和“QUEUED”的任务执行,否则仅取消状态为“QUEUED”的任务执行。默认为 false

警告

取消状态为“IN_PROGRESS”的任务将导致执行该任务的设备无法更新任务执行状态。请谨慎使用,并且确保执行已取消的任务的每个设备能够恢复到有效状态。

comment

[可选] 一个备注字符串,描述取消任务的原因。

响应:

{ "jobArn": "string", "jobId": "string", "description": "string" }
jobArn

任务 ARN。

jobId

您在创建此任务时向其分配的唯一标识符。

description

任务的简短文本描述。

CLI (2)

摘要:

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

cli-input-json format:

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

cli-input-json 字段:

名称

类型

描述

jobId

字符串

最大长度:64,最小长度:1

模式:[a-zA-Z0-9_-]+

您在创建此任务时向其分配的唯一标识符。

force

布尔值

如果为 true,则将取消状态为 QUEUED 和 IN_PROGRESS 的任务,否则将仅取消状态为 QUEUED 的任务。

警告

取消状态为“IN_PROGRESS”的任务将导致执行该任务的设备无法更新任务执行状态。请谨慎使用,并且确保执行已取消的任务的每个设备能够恢复到有效状态。

comment

字符串

最大长度:2028

模式:[^\\p{C}]+

一个可选的备注字符串,用于描述为什么取消任务。

输出:

{ "jobArn": "string", "jobId": "string", "description": "string" }

cli 输出字段:

名称

类型

描述

jobArn

字符串

任务 ARN。

jobId

字符串

最大长度:64,最小长度:1

模式:[a-zA-Z0-9_-]+

您在创建此任务时向其分配的唯一标识符。

description

字符串

最大长度:2028

模式:[^\\p{C}]+

任务的简短文本描述。

MQTT (2)

不可用。

CancelJobExecution

CancelJobExecution 命令HTTPS (3)CLI (3)MQTT (3)
CancelJobExecution 命令

取消特定设备上的任务执行。

HTTPS (3)

请求:

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

将取消其任务执行的事物的名称。

jobId

您在创建任务时向其分配的唯一标识符。

force

可选。如果为 true,则可以取消状态为“IN_PROGRESS”或“QUEUED”的任务执行,否则只能取消状态为“QUEUED”的任务执行。如果您尝试取消状态为“IN_PROGRESS”的任务执行,并且未将 force 设置为 true,则会引发 InvalidStateTransitionException。默认为 false

警告

取消状态为“IN_PROGRESS”的任务将导致执行该任务的设备无法更新任务执行状态。请谨慎使用,并且确保执行已取消的任务的每个设备能够恢复到有效状态。

expectedVersion

可选。任务执行的预期当前版本。每次更新任务执行时,其版本将递增。如果存储在 Jobs 中的任务执行版本不匹配,则更新将被拒绝并出现 VersionConflictException 错误,并且将返回包含当前任务执行状态数据的 ErrorResponse。(这样就不再需要执行单独的 DescribeJobExecution 请求来获取任务执行状态数据。)

statusDetails

可选。描述任务执行状态的名称/值对的集合。

响应:

{ }
CLI (3)

摘要:

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 format:

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

cli-input-json 字段:

名称

类型

描述

jobId

字符串

最大长度:64,最小长度:1

模式:[a-zA-Z0-9_-]+

要取消的任务。

thingName

字符串

最大长度:128,最小长度:1

模式:[a-zA-Z0-9:_-]+

将取消其任务执行的事物的名称。

force

布尔值

可选。如果为 true,则取消状态为 IN_PROGRESS 或 QUEUED 的任务执行,否则仅取消状态为 QUEUED 的任务执行。不过,如果您尝试取消状态为 IN_PROGRESS 的任务执行,并且未将 --force 设置为 true,则会引发 InvalidStateTransitionException。默认为 false

警告

取消状态为“IN_PROGRESS”的任务将导致执行该任务的设备无法更新任务执行状态。请谨慎使用,并且确保执行已取消的任务的每个设备能够恢复到有效状态。

expectedVersion

long

java 类:java.lang.Long

可选。任务执行的预期当前版本。每次更新任务执行时,其版本将递增。如果存储在 Jobs 中的任务执行版本不匹配,则更新将被拒绝并出现 VersionMismatch 错误,并且将返回包含当前任务执行状态数据的 ErrorResponse。(这样就不再需要执行单独的 DescribeJobExecution 请求来获取任务执行状态数据。)

statusDetails

map

键:DetailsKey

值:DetailsValue

描述任务执行状态的名称/值对的集合。如果未指定,则 statusDetails 保持不变。

DetailsKey

字符串

最大长度:128,最小长度:1

模式:[a-zA-Z0-9:_-]+

DetailsValue

字符串

最大长度:1024,最小长度:1

模式:[^\\p{C}]*+

输出:

MQTT (3)

不可用。

CreateJob

CreateJob 命令HTTPS (4)CLI (4)MQTT (4)
CreateJob 命令

创建任务。您可以通过指向 Amazon S3 存储桶中文件的链接 (documentSource 参数) 的方式来提供任务文档,或者在请求正文 (document 参数) 中提供任务文档。

可通过将可选的 targetSelection 参数设置为“CONTINUOUS”,使任务成为持续 任务。(默认值为“SNAPSHOT”。) 持续任务可用于在将设备添加到组时加入或升级设备,因为它将继续运行并在新添加的事物上执行,甚至在组中的事物在创建任务期间完成任务后也是如此。

CreateJob API 的参数执行以下验证:

  • 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。

  • jobId 在您的 AWS 账户内必须是唯一的。

HTTPS (4)

请求:

PUT /jobs/jobId { "targets": [ "string" ], "document": "string", "documentSource": "string", "description": "string", "presignedUrlConfigData": { "roleArn": "string", "expiresInSec": "integer" }, "targetSelection": "CONTINUOUS|SNAPSHOT", "jobExecutionsRolloutConfig": { "maximumPerMinute": "integer" } }
jobId

一个任务标识符,它对您的 AWS 账户必须是唯一的。我们建议使用 UUID。字母数字字符,此处可使用“-”和“_”。

targets

定义任务目标的事物或事物组 ARN 的列表。

document

可选。任务文档。

documentSource

可选。指向任务文档的 Amazon S3 链接。

description

可选。任务的简短文本描述。

presignedUrlConfigData

可选。预签名 Amazon S3 URL 的配置信息。

roleArn

包含 Amazon S3 存储桶的访问权限的 IAM 角色的 ARN。这是包含设备通过预签名 Amazon S3 URL 下载的数据的存储桶。该角色还必须向 AWS IoT 授予代入角色的权限。有关更多信息,请参阅 创建任务

expiresInSec

预签名 URL 的有效期时间长度 (以秒为单位)。有效值为 60-3600。默认值为 3600 秒。在 Jobs 收到任务文档的 MQTT 请求时会生成预签名 URL。

targetSelection

可选。指定任务是继续运行 (CONTINUOUS),还是在指定作为目标的所有事物完成任务后完成 (SNAPSHOT)。如果为 CONTINUOUS,则在目标中检测到更改时,也可能会计划在事物上运行任务。例如,在将一个事物添加到目标组时,会计划在该事物上运行任务,甚至在组中原有的所有事物都完成任务后也是如此。

jobExecutionRolloutConfig

可选。允许您创建任务的分段部署。

maximumPerMinute

每分钟将任务发送到用于执行任务的事物的最大数量。有效值为 1 到 1000. 如果未指定,默认值为 1000。在任何特定的分钟间隔内接收任务的事物的实际数量可能会少一些 (由于系统延迟),但不会超过指定的值。

响应:

{ "jobArn": "string", "jobId": "string", "description": "string" }
jobArn

任务的 ARN。

jobId

您分配给此任务的唯一标识符。

description

任务的可选简短文本描述。

CLI (4)

摘要:

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

cli-input-json format:

{ "jobId": "string", "targets": [ "string" ], "documentSource": "string", "document": "string", "description": "string", "presignedUrlConfig": { "roleArn": "string", "expiresInSec": "long" }, "targetSelection": "string", "jobExecutionsRolloutConfig": { "maximumPerMinute": "integer" }, "documentParameters": { "string": "string" } }

cli-input-json 字段:

名称

类型

描述

jobId

字符串

最大长度:64,最小长度:1

模式:[a-zA-Z0-9_-]+

任务的标识符,必须是您的 AWS 账户的唯一标识符。我们建议使用 UUID。此处可以使用字母数字字符、“-”和“_”。

targets

列表

成员:TargetArn

任务应发送到的事物和事物组的列表。

TargetArn

字符串

documentSource

字符串

最大长度:1350,最小长度:1

指向任务文档的 S3 链接。

文档

字符串

最大长度:32768

任务文档。

description

字符串

最大长度:2028

模式:[^\\p{C}]+

任务的简短文本描述。

presignedUrlConfig

PresignedUrlConfig

预签名 S3 URL 的配置信息。

roleArn

字符串

最大长度:2048,最小长度:20

IAM 角色的 ARN,该角色授予权限以从存储任务数据/更新的 S3 存储桶下载文件。该角色还必须授予 IoT 下载文件的权限。

expiresInSec

long

java 类:java.lang.Long

范围 – 最大值:3600,最小值:60

预签名 URL 的有效时间长度 (以秒为单位)。有效值为 60 – 3600,默认值为 3600 秒。预签名 URL 在 Jobs 接收任务文档的 MQTT 请求时生成。

targetSelection

字符串

枚举:CONTINUOUS | SNAPSHOT

java 类:com.amazonaws.iot.laser.TargetSelection

指定任务将继续运行 (CONTINUOUS),还是在指定作为目标的所有事物完成任务之后完成 (SNAPSHOT)。如果继续运行,则在检测到目标中出现更改时,任务也会在事物上运行。例如,当某个事物添加到目标组时会在该事物上运行任务,即使是组中原有的全部事物已经完成了任务。

jobExecutionsRolloutConfig

JobExecutionsRolloutConfig

允许您创建任务的分段部署。

maximumPerMinute

integer

java 类:java.lang.Integer

范围 – 最大值:1000,最小值:1

待处理任务每分钟通知事物的最大数量。此参数允许您创建分段部署。

documentParameters

map

键:ParameterKey

值:ParameterValue

任务文档的参数。

ParameterKey

字符串

最大长度:128,最小长度:1

模式:[a-zA-Z0-9:_-]+

ParameterValue

字符串

最大长度:1024,最小长度:1

模式:[^\\p{C}]+

输出:

{ "jobArn": "string", "jobId": "string", "description": "string" }

cli 输出字段:

名称

类型

描述

jobArn

字符串

任务 ARN。

jobId

字符串

最大长度:64,最小长度:1

模式:[a-zA-Z0-9_-]+

您分配给此任务的唯一标识符。

description

字符串

最大长度:2028

模式:[^\\p{C}]+

任务描述。

MQTT (4)

不可用。

DeleteJob

DeleteJob 命令HTTPS (4)CLI (4)MQTT (4)
DeleteJob 命令

删除任务及其相关的任务执行。

删除任务可能需要一些时间,具体取决于为该任务创建的任务执行的数量以及其他各种因素。正在删除任务时,任务的状态将显示为“DELETION_IN_PROGRESS”。尝试删除或取消其状态已为“DELETION_IN_PROGRESS”的任务将导致错误。

HTTPS (4)

请求语法:

DELETE /jobs/jobId?force=force

URI 请求参数:

名称

类型

请求?

描述

jobId

JobId

要删除的任务的 ID。

force

ForceFlag

(可选) 当为 true 时,您可以删除状态为“IN_PROGRESS”的任务。否则,您只能删除处于最终状态 (“COMPLETED”或“CANCELED”) 的任务,否则会出现异常。默认为 false。

注意

删除状态为“IN_PROGRESS”的任务将导致执行该任务的设备无法访问任务信息或更新任务执行状态。请谨慎使用,并且确保执行已删除的任务的每个设备能够恢复到有效状态。

错误:

InvalidRequestException

请求的内容无效。例如,UpdateJobExecution 请求包含无效状态详细信息时,将返回此代码。消息包含有关错误的详细信息。

HTTP 响应代码:400

InvalidStateTransitionException

更新尝试将任务或任务执行更改为某个状态,但该状态由于其当前状态而无效 (例如,尝试将处于 SUCCESS 状态的请求更改为 IN_PROGRESS 状态)。在这种情况下,错误消息的正文还包含 executionState 字段。

HTTP 响应代码:409

ResourceNotFoundException

指定的资源不存在。

HTTP 响应代码:404

ThrottlingException

速率超过限制。

HTTP 响应代码:429

ServiceUnavailableException

服务暂时不可用。

HTTP 响应代码:503

CLI (4)

摘要:

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

cli-input-json format:

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

cli-input-json 字段:

名称

类型

描述

jobId

字符串

最大长度:64,最小长度:1

模式:[a-zA-Z0-9_-]+

要删除的任务的 ID。

force

布尔值

(可选) 当为 true 时,您可以删除状态为“IN_PROGRESS”的任务。否则,您只能删除处于最终状态 (“COMPLETED”或“CANCELED”) 的任务,否则会出现异常。默认为 false。

注意

删除状态为“IN_PROGRESS”的任务将导致执行该任务的设备无法访问任务信息或更新任务执行状态。请谨慎使用,并且确保执行已删除的任务的每个设备能够恢复到有效状态。

输出:

MQTT (4)

不可用。

DeleteJobExecution

DeleteJobExecution 命令HTTPS (5)CLI (5)MQTT (5)
DeleteJobExecution 命令

删除任务执行。

HTTPS (5)

请求语法:

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

URI 请求参数:

名称

类型

请求?

描述

jobId

JobId

将删除其执行的任务的 ID。

thingName

ThingName

将删除其任务执行的事物的名称。

executionNumber

ExecutionNumber

要删除的任务执行的 ID。

force

ForceFlag

当为 true 时,您可以删除状态为“IN_PROGRESS”的任务执行。否则,您只能删除处于最终状态 (“SUCCEEDED”、“FAILED”、“REJECTED”、“REMOVED”或“CANCELED”) 的任务执行,否则会出现异常。默认为 false。

注意

删除状态为“IN_PROGRESS”的任务执行将导致设备无法访问任务信息或更新任务执行状态。请谨慎使用,并且确保设备能够恢复到有效状态。

错误:

InvalidRequestException

请求的内容无效。例如,UpdateJobExecution 请求包含无效状态详细信息时,将返回此代码。消息包含有关错误的详细信息。

HTTP 响应代码:400

InvalidStateTransitionException

更新尝试将任务执行更改为某个状态,但该状态由于任务执行的当前状态而无效 (例如,尝试将处于 SUCCESS 状态的请求更改为 IN_PROGRESS 状态)。在这种情况下,错误消息的正文还包含 executionState 字段。

HTTP 响应代码:409

ResourceNotFoundException

指定的资源不存在。

HTTP 响应代码:404

ThrottlingException

速率超过限制。

HTTP 响应代码:429

ServiceUnavailableException

服务暂时不可用。

HTTP 响应代码:503

CLI (5)

摘要:

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 format:

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

cli-input-json 字段:

名称

类型

描述

jobId

字符串

最大长度:64,最小长度:1

模式:[a-zA-Z0-9_-]+

将删除其执行的任务的 ID。

thingName

字符串

最大长度:128,最小长度:1

模式:[a-zA-Z0-9:_-]+

将删除其任务执行的事物的名称。

executionNumber

long

java 类:java.lang.Long

要删除的任务执行的 ID。

force

布尔值

当为 true 时,您可以删除状态为“IN_PROGRESS”的任务执行。否则,您只能删除处于最终状态 (“SUCCEEDED”、“FAILED”、“REJECTED”、“REMOVED”或“CANCELED”) 的任务执行,否则会出现异常。默认为 false。

注意

删除状态为“IN_PROGRESS”的任务执行将导致设备无法访问任务信息或更新任务执行状态。请谨慎使用,并且确保设备能够恢复到有效状态。

输出:

MQTT (5)

不可用。

DescribeJob

DescribeJob 命令HTTPS (6)CLI (6)MQTT (6)
DescribeJob 命令

获取指定任务的详细信息。

HTTPS (6)

请求:

GET /jobs/jobId
jobId

您在创建此任务时向其分配的唯一标识符。

响应:

{ "documentSource": "string", "job": Job }
documentSource

指向任务文档的 Amazon S3 链接。

job

一个 任务 对象。

CLI (6)

摘要:

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

cli-input-json format:

{ "jobId": "string" }

cli-input-json 字段:

名称

类型

描述

jobId

字符串

最大长度:64,最小长度:1

模式:[a-zA-Z0-9_-]+

您在创建此任务时向其分配的唯一标识符。

输出:

{ "documentSource": "string", "job": { "jobArn": "string", "jobId": "string", "targetSelection": "string", "status": "string", "forceCanceled": "boolean", "comment": "string", "targets": [ "string" ], "description": "string", "presignedUrlConfig": { "roleArn": "string", "expiresInSec": "long" }, "jobExecutionsRolloutConfig": { "maximumPerMinute": "integer" }, "createdAt": "timestamp", "lastUpdatedAt": "timestamp", "completedAt": "timestamp", "jobProcessDetails": { "processingTargets": [ "string" ], "numberOfCanceledThings": "integer", "numberOfSucceededThings": "integer", "numberOfFailedThings": "integer", "numberOfRejectedThings": "integer", "numberOfQueuedThings": "integer", "numberOfInProgressThings": "integer", "numberOfRemovedThings": "integer" }, "documentParameters": { "string": "string" } } }

cli 输出字段:

名称

类型

描述

documentSource

字符串

最大长度:1350,最小长度:1

指向任务文档的 S3 链接。

任务

任务

该任务的相关信息。

jobArn

字符串

标识任务的 ARN,格式为“arn:aws:iot:region:account:job/jobId”。

jobId

字符串

最大长度:64,最小长度:1

模式:[a-zA-Z0-9_-]+

您在创建此任务时向其分配的唯一标识符。

targetSelection

字符串

枚举:CONTINUOUS | SNAPSHOT

java 类:com.amazonaws.iot.laser.TargetSelection

指定任务将继续运行 (CONTINUOUS),还是在指定作为目标的所有事物完成任务之后完成 (SNAPSHOT)。如果继续运行,则在检测到目标中出现更改时,任务也会在事物上运行。例如,当代表设备的某个事物添加到目标组时,会在该设备上运行任务,即使是组中原有的全部事物已经完成了任务。

status

字符串

枚举:IN_PROGRESS | CANCELED | COMPLETED

java 类:ccom.amazonaws.iot.laser.common.JobStatus

任务的状态,为 IN_PROGRESSCANCELEDCOMPLETED 之一。

forceCanceled

布尔值

java 类:java.lang.Boolean

如果在取消任务时将可选的 force 参数设置为 true,则将为 true

comment

字符串

最大长度:2028

模式:[^\\p{C}]+

如果任务已更新,介绍更新原因。

targets

列表

成员:TargetArn

任务应发送到的 IoT 事物和事物组的列表。

TargetArn

字符串

description

字符串

最大长度:2028

模式:[^\\p{C}]+

任务的简短文本描述。

presignedUrlConfig

PresignedUrlConfig

预签名 S3 URL 的配置。

roleArn

字符串

最大长度:2048,最小长度:20

IAM 角色的 ARN,该角色授予权限以从存储任务数据/更新的 S3 存储桶下载文件。该角色还必须授予 IoT 下载文件的权限。

expiresInSec

long

java 类:java.lang.Long

范围 – 最大值:3600,最小值:60

预签名 URL 的有效时间长度 (以秒为单位)。有效值为 60 – 3600,默认值为 3600 秒。预签名 URL 在 Jobs 接收任务文档的 MQTT 请求时生成。

jobExecutionsRolloutConfig

JobExecutionsRolloutConfig

允许您创建任务的分段部署。

maximumPerMinute

integer

java 类:java.lang.Integer

范围 – 最大值:1000,最小值:1

待处理任务每分钟通知事物的最大数量。此参数允许您创建分段部署。

createdAt

timestamp

创建任务的时间,用从纪元开始的毫秒数表示。

lastUpdatedAt

timestamp

上次更新任务的时间,用从纪元开始的毫秒数表示。

completedAt

timestamp

完成任务的时间,用从纪元开始的毫秒数表示。

jobProcessDetails

JobProcessDetails

任务流程的详细信息。

processingTargets

列表

成员:ProcessingTargetName

java 类:java.util.List

执行任务的设备。

ProcessingTargetName

字符串

numberOfCanceledThings

integer

java 类:java.lang.Integer

取消了任务的事物数。

numberOfSucceededThings

integer

java 类:java.lang.Integer

成功完成任务的事物数。

numberOfFailedThings

integer

java 类:java.lang.Integer

任务执行失败的事物数。

numberOfRejectedThings

integer

java 类:java.lang.Integer

拒绝了任务的事物数。

numberOfQueuedThings

integer

java 类:java.lang.Integer

等待任务执行的事物数。

numberOfInProgressThings

integer

java 类:java.lang.Integer

当前正在执行任务的事物数。

numberOfRemovedThings

integer

java 类:java.lang.Integer

因其已从作为任务目标的组中被删除或移除而不再计划执行的事物的数量。

documentParameters

map

键:ParameterKey

值:ParameterValue

为任务文档指定的参数。

ParameterKey

字符串

最大长度:128,最小长度:1

模式:[a-zA-Z0-9:_-]+

ParameterValue

字符串

最大长度:1024,最小长度:1

模式:[^\\p{C}]+

MQTT (6)

不可用。

DescribeJobExecution

DescribeJobExecution 命令HTTPS (7)CLI (7)MQTT (7)
DescribeJobExecution 命令

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

HTTPS (7)

请求:

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

您在创建此任务时向其分配的唯一标识符。

thingName

与正在运行任务执行的设备关联的事物名称。

executionNumber

可选。一个用于指定特定设备上的特定任务执行的数字。(请参阅 JobExecution.) 如果未指定,则返回最新的任务执行。

响应:

{ "execution": { JobExecution } }
execution

一个 JobExecution 对象。

CLI (7)

摘要:

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

cli-input-json format:

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

cli-input-json 字段:

名称

类型

描述

jobId

字符串

最大长度:64,最小长度:1

模式:[a-zA-Z0-9_-]+

您在创建此任务时向其分配的唯一标识符。

thingName

字符串

最大长度:128,最小长度:1

模式:[a-zA-Z0-9:_-]+

正在运行任务执行的事物的名称。

executionNumber

long

java 类:java.lang.Long

一个由从“0”到“9”的数字组成的字符串,用于指定特定设备上的特定任务执行。

输出:

{ "execution": { "jobId": "string", "status": "string", "forceCanceled": "boolean", "statusDetails": { "detailsMap": { "string": "string" } }, "thingArn": "string", "queuedAt": "timestamp", "startedAt": "timestamp", "lastUpdatedAt": "timestamp", "executionNumber": "long", "versionNumber": "long" } }

cli 输出字段:

名称

类型

描述

execution

JobExecution

任务执行的相关信息。

jobId

字符串

最大长度:64,最小长度:1

模式:[a-zA-Z0-9_-]+

您在创建任务时向其分配的唯一标识符。

status

字符串

枚举:QUEUED | IN_PROGRESS | SUCCEEDED | FAILED | REJECTED | REMOVED | CANCELED

java 类:com.amazonaws.iot.laser.common.JobExecutionStatus

任务执行的状态 (IN_PROGRESS、QUEUED、FAILED、SUCCESS、CANCELED 或 REJECTED)。

forceCanceled

布尔值

java 类:java.lang.Boolean

如果在取消任务执行时将可选的 force 参数设置为 true,则将为 true

statusDetails

JobExecutionStatusDetails

描述任务执行状态的名称/值对的集合。

detailsMap

map

键:DetailsKey

值:DetailsValue

任务执行状态。

DetailsKey

字符串

最大长度:128,最小长度:1

模式:[a-zA-Z0-9:_-]+

DetailsValue

字符串

最大长度:1024,最小长度:1

模式:[^\\p{C}]*+

thingArn

字符串

正在运行任务执行的事物的 ARN。

queuedAt

timestamp

任务执行入队的时间,用从纪元开始的毫秒数表示。

startedAt

timestamp

任务执行开始的时间,用从纪元开始的毫秒数表示。

lastUpdatedAt

timestamp

上次更新任务执行的时间,用从纪元开始的毫秒数表示。

executionNumber

long

java 类:java.lang.Long

一个由从“0”到“9”的数字组成的字符串,用于标识此特定设备上的该特定任务执行。它可在返回或更新任务执行信息的命令中使用。

versionNumber

long

任务执行的版本。每次设备更新任务执行版本时,版本将递增。

MQTT (7)

不可用。

GetJobDocument

GetJobDocument 命令HTTPS (8)CLI (8)MQTT (8)
GetJobDocument 命令

获取任务的任务文档。

注意

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

HTTPS (8)

请求:

GET /jobs/jobId/job-document
jobId

您在创建此任务时向其分配的唯一标识符。

响应:

{ "document": "string" }
document

任务文档内容。

CLI (8)

摘要:

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

cli-input-json format:

{ "jobId": "string" }

cli-input-json 字段:

名称

类型

描述

jobId

字符串

最大长度:64,最小长度:1

模式:[a-zA-Z0-9_-]+

您在创建此任务时向其分配的唯一标识符。

输出:

{ "document": "string" }

cli 输出字段:

名称

类型

描述

文档

字符串

最大长度:32768

任务文档内容。

MQTT (8)

不可用。

ListJobExecutionsForJob

ListExecutionsForJob 命令HTTPS (9)CLI (9)MQTT (9)
ListExecutionsForJob 命令

获取任务的任务执行的列表。

HTTPS (9)

请求:

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

您在创建此任务时向其分配的唯一标识符。

status

可选。可用于搜索具有指定状态的任务的筛选条件:QUEUED、IN_PROGRESS、SUCCESS、FAILED、REJECTED、REMOVED 或 CANCELED。

maxResults

可选。每个请求返回的最大结果数。

nextToken

可选。用于检索下一组结果的令牌。

响应:

{ "executionSummaries": [ JobExecutionSummary ... ] }
executionSummaries

与指定的任务 ID 关联的 JobExecutionSummary 对象的列表。

CLI (9)

摘要:

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 format:

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

cli-input-json 字段:

名称

类型

描述

jobId

字符串

最大长度:64,最小长度:1

模式:[a-zA-Z0-9_-]+

您在创建此任务时向其分配的唯一标识符。

status

字符串

枚举:QUEUED | IN_PROGRESS | SUCCEEDED | FAILED | REJECTED | REMOVED | CANCELED

java 类:com.amazonaws.iot.laser.common.JobExecutionStatus

任务的状态。

maxResults

integer

java 类:java.lang.Integer

范围 - 最大值:250,最小值:1

每个请求返回的最大结果数。

nextToken

字符串

用于检索下一组结果的令牌。

输出:

{ "executionSummaries": [ { "thingArn": "string", "jobExecutionSummary": { "status": "string", "queuedAt": "timestamp", "startedAt": "timestamp", "lastUpdatedAt": "timestamp", "executionNumber": "long" } } ], "nextToken": "string" }

cli 输出字段:

名称

类型

描述

executionSummaries

列表

成员:JobExecutionSummaryForJob

java 类:java.util.List

任务执行摘要的列表。

JobExecutionSummaryForJob

JobExecutionSummaryForJob

thingArn

字符串

正在运行任务执行的事物的 ARN。

jobExecutionSummary

JobExecutionSummary

包含有关任务执行的信息的子集。

status

字符串

枚举:QUEUED | IN_PROGRESS | SUCCEEDED | FAILED | REJECTED | REMOVED | CANCELED

java 类:com.amazonaws.iot.laser.common.JobExecutionStatus

任务执行的状态。

queuedAt

timestamp

任务执行入队的时间,用从纪元开始的毫秒数表示。

startedAt

timestamp

任务执行开始的时间,用从纪元开始的毫秒数表示。

lastUpdatedAt

timestamp

上次更新任务执行的时间,用从纪元开始的毫秒数表示。

executionNumber

long

java 类:java.lang.Long

一个由从“0”到“9”的数字组成的字符串,用于标识此特定设备上的该特定任务执行。它可随后在返回或更新任务执行信息的命令中使用。

nextToken

字符串

下一组结果的令牌,没有更多结果时为 null

MQTT (9)

不可用。

ListJobExecutionsForThing

ListJobExecutionsForThing 命令HTTPS (10)CLI (10)MQTT (10)
ListJobExecutionsForThing 命令

获取事物的任务执行的列表。

HTTPS (10)

请求:

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

将列出其 JobExecutions 的事物的名称。

status

可用于搜索具有指定状态的任务的可选筛选条件:QUEUED、IN_PROGRESS、SUCCESS、FAILED、REJECTED、REMOVED 或 CANCELED。

maxResults

每个请求返回的最大结果数。

nextToken

下一组结果的令牌,没有更多结果时为 null

响应:

{ "executionSummaries": [ JobExecutionSummary ... ] }
executionSummaries

与指定事物关联的任务执行的 JobExecutionSummary 对象的列表。

CLI (10)

摘要:

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 format:

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

cli-input-json 字段:

名称

类型

描述

thingName

字符串

最大长度:128,最小长度:1

模式:[a-zA-Z0-9:_-]+

事物名称。

status

字符串

枚举:QUEUED | IN_PROGRESS | SUCCEEDED | FAILED | REJECTED | REMOVED | CANCELED

java 类:com.amazonaws.iot.laser.common.JobExecutionStatus

一个可选筛选条件,允许您搜索具有指定状态的任务。

maxResults

integer

java 类:java.lang.Integer

范围 - 最大值:250,最小值:1

每个请求返回的最大结果数。

nextToken

字符串

用于检索下一组结果的令牌。

输出:

{ "executionSummaries": [ { "jobId": "string", "jobExecutionSummary": { "status": "string", "queuedAt": "timestamp", "startedAt": "timestamp", "lastUpdatedAt": "timestamp", "executionNumber": "long" } } ], "nextToken": "string" }

cli 输出字段:

名称

类型

描述

executionSummaries

列表

成员:JobExecutionSummaryForThing

java 类:java.util.List

任务执行摘要的列表。

JobExecutionSummaryForThing

JobExecutionSummaryForThing

jobId

字符串

最大长度:64,最小长度:1

模式:[a-zA-Z0-9_-]+

您在创建此任务时向其分配的唯一标识符。

jobExecutionSummary

JobExecutionSummary

包含有关任务执行的信息的子集。

status

字符串

枚举:QUEUED | IN_PROGRESS | SUCCEEDED | FAILED | REJECTED | REMOVED | CANCELED

java 类:com.amazonaws.iot.laser.common.JobExecutionStatus

任务执行的状态。

queuedAt

timestamp

任务执行入队的时间,用从纪元开始的毫秒数表示。

startedAt

timestamp

任务执行开始的时间,用从纪元开始的毫秒数表示。

lastUpdatedAt

timestamp

上次更新任务执行的时间,用从纪元开始的毫秒数表示。

executionNumber

long

java 类:java.lang.Long

一个由从“0”到“9”的数字组成的字符串,用于标识此特定设备上的该特定任务执行。它可随后在返回或更新任务执行信息的命令中使用。

nextToken

字符串

下一组结果的令牌,没有更多结果时为 null

MQTT (10)

不可用。

ListJobs

ListJobs 命令HTTPS (11)CLI (11)MQTT (11)
ListJobs 命令

获取 AWS 账户中的任务的列表。

HTTPS (11)

请求:

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

可选。可用于搜索具有指定状态的任务的筛选条件:IN_PROGRESS、CANCELED 或 COMPLETED。

targetSelection

可选。可用于搜索具有指定 targetSelection 值的任务的筛选条件:CONTINUOUS 或 SNAPSHOT。

thingGroupName

可选。可用于搜索具有指定事物组名称作为目标的任务的筛选条件。

thingGroupId

可选。可用于搜索具有指定事物组 ID 作为目标的任务的筛选条件。

maxResults

可选。每个请求返回的最大结果数。

nextToken

可选。用于检索下一组结果的令牌。

响应:

{ "jobs": [ JobSummary ... ], }
jobs

JobSummary 对象的列表,每个对象对应于 AWS 账户中的一个匹配指定筛选条件的任务。

CLI (11)

摘要:

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 format:

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

cli-input-json 字段:

名称

类型

描述

status

字符串

枚举:IN_PROGRESS | CANCELED | COMPLETED

java 类:ccom.amazonaws.iot.laser.common.JobStatus

一个可选筛选条件,允许您搜索具有指定状态的任务。

targetSelection

字符串

枚举:CONTINUOUS | SNAPSHOT

java 类:com.amazonaws.iot.laser.TargetSelection

指定任务将继续运行 (CONTINUOUS),还是在指定作为目标的所有事物完成任务之后完成 (SNAPSHOT)。如果继续运行,则在检测到目标中出现更改时,任务也会在事物上运行。例如,当某个事物添加到目标组时会在该事物上运行任务,即使是组中原有的全部事物已经完成了任务。

maxResults

integer

java 类:java.lang.Integer

范围 - 最大值:250,最小值:1

每个请求返回的最大结果数。

nextToken

字符串

用于检索下一组结果的令牌。

thingGroupName

字符串

最大长度:128,最小长度:1

模式:[a-zA-Z0-9:_-]+

一个筛选条件,用于将返回的任务限制为指定组的任务。

thingGroupId

字符串

最大长度:128,最小长度:1

模式:[a-zA-Z0-9-]+

一个筛选条件,用于将返回的任务限制为指定组的任务。

输出:

{ "jobs": [ { "jobArn": "string", "jobId": "string", "thingGroupId": "string", "targetSelection": "string", "status": "string", "createdAt": "timestamp", "lastUpdatedAt": "timestamp", "completedAt": "timestamp" } ], "nextToken": "string" }

cli 输出字段:

名称

类型

描述

jobs

列表

成员:Job Summary

java 类:java.util.List

任务列表。

JobSummary

JobSummary

jobArn

字符串

任务 ARN。

jobId

字符串

最大长度:64,最小长度:1

模式:[a-zA-Z0-9_-]+

您在创建此任务时向其分配的唯一标识符。

thingGroupId

字符串

最大长度:128,最小长度:1

模式:[a-zA-Z0-9-]+

事物组的 ID。

targetSelection

字符串

枚举:CONTINUOUS | SNAPSHOT

java 类:com.amazonaws.iot.laser.TargetSelection

指定任务将继续运行 (CONTINUOUS),还是在指定作为目标的所有事物完成任务之后完成 (SNAPSHOT)。如果继续运行,则在检测到目标中出现更改时,任务也会在事物上运行。例如,当某个事物添加到目标组时会在该事物上运行任务,即使是组中原有的全部事物已经完成了任务。

status

字符串

枚举:IN_PROGRESS | CANCELED | COMPLETED

java 类:ccom.amazonaws.iot.laser.common.JobStatus

任务摘要状态。

createdAt

timestamp

创建任务的时间,用从纪元开始的毫秒数表示。

lastUpdatedAt

timestamp

上次更新任务的时间,用从纪元开始的毫秒数表示。

completedAt

timestamp

完成任务的时间,用从纪元开始的毫秒数表示。

nextToken

字符串

下一组结果的令牌,没有更多结果时为 null

MQTT (11)

不可用。

Jobs 设备 MQTT 和 HTTPS API

设备 MQTT 和 HTTPS 数据类型

可使用以下数据类型通过 MQTT 和 HTTPS 协议与 Jobs 进行通信。

JobExecution

JobExecution 数据类型语法 (7)描述 (7)
JobExecution 数据类型

包含有关任务执行的数据。

语法 (7)
{ "jobId" : "string", "thingName" : "string", "jobDocument" : "string", "status": "QUEUED|IN_PROGRESS|FAILED|SUCCESS|CANCELED|REJECTED|REMOVED", "statusDetails": { "string": "string" }, "queuedAt" : "timestamp", "startedAt" : "timestamp", "lastUpdatedAt" : "timestamp", "versionNumber" : "number", "executionNumber": "long" }
描述 (7)
jobId

您在创建此任务时向其分配的唯一标识符。

thingName

正在执行任务的事物的名称。

jobDocument

任务文档的内容。

status

任务执行的状态。可以为以下值之一:“QUEUED"、“IN_PROGRESS”、“FAILED”、“SUCCESS”、“CANCELED”、“REJECTED”或“REMOVED”。

statusDetails

描述任务执行状态的名称/值对的集合。

queuedAt

任务执行入队的时间,用从纪元开始的毫秒数表示。

startedAt

任务执行开始的时间,用从纪元开始的毫秒数表示。

lastUpdatedAt

上次更新任务执行的时间,用从纪元开始的毫秒数表示。

versionNumber

任务执行的版本。每次设备更新任务执行版本时,版本将递增。

executionNumber

标识特定设备上的特定任务执行的数字。它可随后在返回或更新任务执行信息的命令中使用。

JobExecutionState

JobExecutionState 数据类型语法 (8)描述 (8)
JobExecutionState 数据类型

包含有关任务执行的状态的数据。

语法 (8)
{ "status": "QUEUED|IN_PROGRESS|FAILED|SUCCESS|CANCELED|REJECTED|REMOVED", "statusDetails": { "string": "string" ... } "versionNumber": "number" }
描述 (8)
status

任务执行的状态。可以为以下值之一:“QUEUED"、“IN_PROGRESS”、“FAILED”、“SUCCESS”、“CANCELED”、“REJECTED”或“REMOVED”。

statusDetails

描述任务执行状态的名称/值对的集合。

versionNumber

任务执行的版本。每次设备更新任务执行版本时,版本将递增。

JobExecutionSummary

JobExecutionSummary 数据类型语法 (9)描述 (9)
JobExecutionSummary 数据类型

包含有关任务执行的信息的子集。

语法 (9)
{ "jobId": "string", "queuedAt": timestamp, "startedAt": timestamp, "lastUpdatedAt": timestamp, "versionNumber": "number", "executionNumber": "long" }
描述 (9)
jobId

您在创建此任务时向其分配的唯一标识符。

queuedAt

任务执行入队的时间,用从纪元开始的毫秒数表示。

startedAt

任务执行开始的时间,用从纪元开始的毫秒数表示。

lastUpdatedAt

上次更新任务执行的时间,用从纪元开始的毫秒数表示。

versionNumber

任务执行的版本。每当 AWS IoT Jobs 收到来自设备的更新时,任务执行版本都会递增。

executionNumber

标识特定设备上的特定任务执行的数字。

ErrorResponse

ErrorRepsonse 数据类型语法 (10)描述 (10)
ErrorRepsonse 数据类型

包含有关 Jobs 操作期间发生的错误的信息。

语法 (10)
{ "code": "ErrorCode", "message": "string", "clientToken": "string", "timestamp": timestamp, "executionState": JobExecutionState }
描述 (10)
code

可将 ErrorCode 设置为:

InvalidTopic

请求已发送至 Jobs 命名空间中未映射到任何 API 的主题。

InvalidJson

请求的内容无法解释为有效的 UTF-8 编码的 JSON。

InvalidRequest

请求的内容无效。例如,当 UpdateJobExecution 请求包含无效的状态详细信息时,将返回此代码。消息包含有关错误的详细信息。

InvalidStateTransition

更新尝试将任务执行更改为某个状态,但该状态由于任务执行的当前状态而无效 (例如,尝试将处于 SUCCESS 状态的请求更改为 IN_PROGRESS 状态)。在这种情况下,错误消息的正文还包含 executionState 字段。

ResourceNotFound

请求主题所指定的 JobExecution 不存在。

VersionMismatch

请求中指定的预期版本与 Jobs 中的任务执行版本不匹配。在这种情况下,错误消息的正文还包含 executionState 字段。

InternalError

处理请求时出现内部错误。

RequestThrottled

请求已被阻止。

TerminalStateReached

在处于最终状态的任务上执行描述任务的命令时发生。

message

错误消息字符串。

clientToken

用于将请求与其答复关联起来的任意字符串。

timestamp

用自纪元以来的毫秒数表示的时间。

executionState

一个 JobExecutionState 对象。仅在 code 字段具有 InvalidStateTransitionVersionMismatch 值时包含此字段。在这些情况下,这使得不必执行单独的 DescribeJobExecution 请求以获取当前任务执行状态数据。

设备命令

可通过 MQTT 和 HTTPS 协议使用以下命令。

GetPendingJobExecutions

GetPendingJobExecutions 命令MQTT (12)HTTPS (12)CLI (12)
GetPendingJobExecutions 命令

获取未处于最终状态的事物的所有任务列表。

MQTT (12)

要调用此 API,请在 $aws/things/thingName/jobs/get 上发布消息。

请求负载:

{ "clientToken": "string" }
clientToken

可选。用于将请求和响应关联起来的客户端令牌。在此处输入任意值,它将反映在响应中。

要接收响应,请订阅:

  • $aws/things/thingName/jobs/get/accepted ...和...

  • $aws/things/thingName/jobs/get/rejected ...或者...

  • $aws/things/thingName/jobs/get/# ...for both...

响应负载:

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

状态为 IN_PROGRESSJobExecutionSummary 对象的列表。

queuedJobs

状态为 QUEUEDJobExecutionSummary 对象的列表。

clientToken

用于将请求和响应关联起来的客户端令牌。

timestamp

发送消息的时间 (用从纪元开始的秒数表示)。

HTTPS (12)

请求:

GET /things/thingName/jobs
thingName

与设备关联的事物的名称。

响应:

{ "inProgressJobs" : [ JobExecutionSummary ... ], "queuedJobs" : [ JobExecutionSummary ... ] }
inProgressJobs

JobExecutionSummary 对象的列表。

queuedJobs

JobExecutionSummary 对象的列表。

CLI (12)

摘要:

aws iot-jobs-data get-pending-job-executions \ --thing-name <value> \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format:

{ "thingName": "string" }

cli-input-json 字段:

名称

类型

描述

thingName

字符串

最大长度:128,最小长度:1

模式:[a-zA-Z0-9:_-]+

正在执行任务的事物的名称。

输出:

{ "inProgressJobs": [ { "jobId": "string", "queuedAt": "long", "startedAt": "long", "lastUpdatedAt": "long", "versionNumber": "long", "executionNumber": "long" } ], "queuedJobs": [ { "jobId": "string", "queuedAt": "long", "startedAt": "long", "lastUpdatedAt": "long", "versionNumber": "long", "executionNumber": "long" } ] }

cli 输出字段:

名称

类型

描述

inProgressJobs

列表

成员:JobExecutionSummary

java 类:java.util.List

状态为 IN_PROGRESS 的 JobExecutionSummary 对象的列表。

JobExecutionSummary

JobExecutionSummary

jobId

字符串

最大长度:64,最小长度:1

模式:[a-zA-Z0-9_-]+

您在创建此任务时向其分配的唯一标识符。

queuedAt

long

任务执行入队的时间,用从纪元开始的毫秒数表示。

startedAt

long

java 类:java.lang.Long

任务执行开始的时间,用从纪元开始的毫秒数表示。

lastUpdatedAt

long

上次更新任务执行的时间,用从纪元开始的毫秒数表示。

versionNumber

long

任务执行的版本。每次 AWS IoT Jobs 从设备收到更新时,任务执行版本会递增。

executionNumber

long

java 类:java.lang.Long

标识特定设备上的特定任务执行的数字。

queuedJobs

列表

成员:JobExecutionSummary

java 类:java.util.List

状态为 QUEUED 的 JobExecutionSummary 对象的列表。

JobExecutionSummary

JobExecutionSummary

jobId

字符串

最大长度:64,最小长度:1

模式:[a-zA-Z0-9_-]+

您在创建此任务时向其分配的唯一标识符。

queuedAt

long

任务执行入队的时间,用从纪元开始的毫秒数表示。

startedAt

long

java 类:java.lang.Long

任务执行开始的时间,用从纪元开始的毫秒数表示。

lastUpdatedAt

long

上次更新任务执行的时间,用从纪元开始的毫秒数表示。

versionNumber

long

任务执行的版本。每次 AWS IoT Jobs 从设备收到更新时,任务执行版本会递增。

executionNumber

long

java 类:java.lang.Long

标识特定设备上的特定任务执行的数字。

StartNextPendingJobExecution

StartNextPendingJobExecution 命令MQTT (13)HTTPS (13)CLI (13)
StartNextPendingJobExecution 命令

获取并启动事物的下一个待处理 (状态 IN_PROGRESS 或 QUEUED) 任务执行。

  • 首先返回状态为 IN_PROGRESS 的所有任务执行。

  • 按任务执行的创建顺序返回这些执行。

  • 如果下一个待处理任务执行的状态为 QUEUED,则其状态将更改为 IN_PROGRESS,并且任务执行的状态详细信息将设定为指定内容。

  • 如果下一个待处理任务执行已处于 IN_PROGRESS 状态,则不会更改其状态。

  • 如果没有待处理的任务执行,则响应不包括 execution 字段。

MQTT (13)

要调用此 API,请在 $aws/things/thingName/jobs/start-next 上发布消息。

请求负载:

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

描述任务执行状态的名称/值对的集合。如果未指定,则 statusDetails 保持不变。

clientToken

用于将请求和响应关联起来的客户端令牌。在此处输入任意值,它将反映在响应中。

要接收响应,请订阅:

  • $aws/things/thingName/jobs/start-next/accepted ...和...

  • $aws/things/thingName/jobs/start-next/rejected ...或者...

  • $aws/things/thingName/jobs/start-next/# ...for both...

响应负载:

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

将消息发送到设备的时间 (用从纪元开始的秒数表示)。

clientToken

用于将请求和响应关联起来的客户端令牌。

HTTPS (13)

请求:

PUT /things/thingName/jobs/$next { "statusDetails": { "string": "string" ... } }
thingName

与设备关联的事物的名称。

statusDetails

描述任务执行状态的名称/值对的集合。如果未指定,则 statusDetails 保持不变。

响应:

{ "execution" : JobExecution }
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, }
CLI (13)

摘要:

aws iot-jobs-data start-next-pending-job-execution \ --thing-name <value> \ [--status-details <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format:

{ "thingName": "string", "statusDetails": { "string": "string" } }

cli-input-json 字段:

名称

类型

描述

thingName

字符串

最大长度:128,最小长度:1

模式:[a-zA-Z0-9:_-]+

与设备关联的事物的名称。

statusDetails

map

键:DetailsKey

值:DetailsValue

描述任务执行状态的名称/值对的集合。如果未指定,则 statusDetails 保持不变。

DetailsKey

字符串

最大长度:128,最小长度:1

模式:[a-zA-Z0-9:_-]+

DetailsValue

字符串

最大长度:1024,最小长度:1

模式:[^\\p{C}]*+

输出:

{ "execution": { "jobId": "string", "thingName": "string", "status": "string", "statusDetails": { "string": "string" }, "queuedAt": "long", "startedAt": "long", "lastUpdatedAt": "long", "versionNumber": "long", "executionNumber": "long", "jobDocument": "string" } }

cli 输出字段:

名称

类型

描述

execution

JobExecution

JobExecution 对象。

jobId

字符串

最大长度:64,最小长度:1

模式:[a-zA-Z0-9_-]+

您在创建此任务时向其分配的唯一标识符。

thingName

字符串

最大长度:128,最小长度:1

模式:[a-zA-Z0-9:_-]+

正在执行任务的事物的名称。

status

字符串

枚举:QUEUED | IN_PROGRESS | SUCCEEDED | FAILED | REJECTED | REMOVED | CANCELED

java 类:com.amazonaws.iot.laser.common.JobExecutionStatus

任务执行的状态。可以为以下值之一:“QUEUED"、“IN_PROGRESS”、“FAILED”、“SUCCESS”、“CANCELED”、“REJECTED”或“REMOVED”。

statusDetails

map

键:DetailsKey

值:DetailsValue

描述任务执行状态的名称/值对的集合。

DetailsKey

字符串

最大长度:128,最小长度:1

模式:[a-zA-Z0-9:_-]+

DetailsValue

字符串

最大长度:1024,最小长度:1

模式:[^\\p{C}]*+

queuedAt

long

任务执行入队的时间,用从纪元开始的毫秒数表示。

startedAt

long

java 类:java.lang.Long

任务执行开始的时间,用从纪元开始的毫秒数表示。

lastUpdatedAt

long

上次更新任务执行的时间,用从纪元开始的毫秒数表示。

versionNumber

long

任务执行的版本。每次设备更新任务执行版本时,版本将递增。

executionNumber

long

java 类:java.lang.Long

标识特定设备上的特定任务执行的数字。它可随后在返回或更新任务执行信息的命令中使用。

jobDocument

字符串

最大长度:32768

任务文档的内容。

DescribeJobExecution

DescribeJobExecution 命令MQTT (14)HTTPS (14)CLI (14)
DescribeJobExecution 命令

获取有关任务执行的详细信息。

您可以将 jobId 设置为 $next 以返回事物的下一个待处理 (状态 IN_PROGRESS 或 QUEUED) 任务执行。

MQTT (14)

要调用此 API,请在 $aws/things/thingName/jobs/jobId/get 上发布消息。

请求负载:

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

与设备关联的事物的名称。

jobId

创建此任务时向其分配的唯一标识符。

或使用 $next 返回事物的下一个待处理 (状态 IN_PROGRESS 或 QUEUED) 任务执行。在此情况下,首先返回状态为 IN_PROGRESS 的所有任务执行。按任务执行的创建顺序返回这些执行。

executionNumber

可选。标识特定设备上的特定任务执行的数字。如果未指定,则返回最新的任务执行。

includeJobDocument

可选。设置为 true 时,响应将包含任务文档。默认为 true

clientToken

用于将请求和响应关联起来的客户端令牌。在此处输入任意值,它将反映在响应中。

要接收响应,请订阅:

  • $aws/things/thingName/jobs/jobId/get/accepted ...和...

  • $aws/things/thingName/jobs/jobId/get/rejected ...或者...

  • $aws/things/thingName/jobs/jobId/get/# ...for both...

响应负载:

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

一个 JobExecution 对象。

timestamp

发送消息的时间 (用从纪元开始的秒数表示)。

clientToken

用于将请求和响应关联起来的客户端令牌。

HTTPS (14)

任务的执行状态必须为 QUEUEDIN_PROGRESS

请求:

GET /things/thingName/jobs/jobId?executionNumber=executionNumber&includeJobDocument=includeJobDocument
thingName

与设备关联的事物的名称。

jobId

创建此任务时向其分配的唯一标识符。

或使用 $next 返回事物的下一个待处理 (状态 IN_PROGRESS 或 QUEUED) 任务执行。在此情况下,首先返回状态为 IN_PROGRESS 的所有任务执行。按任务执行的创建顺序返回这些执行。

includeJobDocument

可选。设置为 true 时,响应将包含任务文档。默认为 false

executionNumber

可选。标识特定设备上的特定任务执行的数字。如果未指定,则返回最新的任务执行。

响应:

{ "execution" : JobExecution, }
execution

一个 JobExecution 对象。

CLI (14)

任务的执行状态必须为 QUEUEDIN_PROGRESS

摘要:

aws iot-jobs-data describe-job-execution \ --job-id <value> \ --thing-name <value> \ [--include-job-document | --no-include-job-document] \ [--execution-number <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format:

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

cli-input-json 字段:

名称

类型

描述

jobId

字符串

模式:[a-zA-Z0-9_-]+|^$next

在此任务创建时分配给它的唯一标识符,或者用于返回事物的下一个待处理 (状态 IN_PROGRESS 或 QUEUED) 任务执行的 $next。在此情况下,首先返回状态为 IN_PROGRESS 的所有任务执行。按任务执行的创建顺序返回这些执行。

thingName

字符串

最大长度:128,最小长度:1

模式:[a-zA-Z0-9:_-]+

与正在运行任务执行的设备关联的事物名称。

includeJobDocument

布尔值

java 类:java.lang.Boolean

可选。设置为 true 时,响应将包含任务文档。默认为 false。

executionNumber

long

java 类:java.lang.Long

可选。标识特定设备上的特定任务执行的数字。如果未指定,则返回最新的任务执行。

输出:

{ "execution": { "jobId": "string", "thingName": "string", "status": "string", "statusDetails": { "string": "string" }, "queuedAt": "long", "startedAt": "long", "lastUpdatedAt": "long", "versionNumber": "long", "executionNumber": "long", "jobDocument": "string" } }

cli 输出字段:

名称

类型

描述

execution

JobExecution

包含有关任务执行的数据。

jobId

字符串

最大长度:64,最小长度:1

模式:[a-zA-Z0-9_-]+

您在创建此任务时向其分配的唯一标识符。

thingName

字符串

最大长度:128,最小长度:1

模式:[a-zA-Z0-9:_-]+

正在执行任务的事物的名称。

status

字符串

枚举:QUEUED | IN_PROGRESS | SUCCEEDED | FAILED | REJECTED | REMOVED | CANCELED

java 类:com.amazonaws.iot.laser.common.JobExecutionStatus

任务执行的状态。可以为以下值之一:“QUEUED"、“IN_PROGRESS”、“FAILED”、“SUCCESS”、“CANCELED”、“REJECTED”或“REMOVED”。

statusDetails

map

键:DetailsKey

值:DetailsValue

描述任务执行状态的名称/值对的集合。

DetailsKey

字符串

最大长度:128,最小长度:1

模式:[a-zA-Z0-9:_-]+

DetailsValue

字符串

最大长度:1024,最小长度:1

模式:[^\\p{C}]*+

queuedAt

long

任务执行入队的时间,用从纪元开始的毫秒数表示。

startedAt

long

java 类:java.lang.Long

任务执行开始的时间,用从纪元开始的毫秒数表示。

lastUpdatedAt

long

上次更新任务执行的时间,用从纪元开始的毫秒数表示。

versionNumber

long

任务执行的版本。每次设备更新任务执行版本时,版本将递增。

executionNumber

long

java 类:java.lang.Long

标识特定设备上的特定任务执行的数字。它可随后在返回或更新任务执行信息的命令中使用。

jobDocument

字符串

最大长度:32768

任务文档的内容。

UpdateJobExecution

UpdateJobExecution 命令MQTT (15)HTTPS (15)CLI (15)
UpdateJobExecution 命令

更新任务执行的状态。

MQTT (15)

要调用此 API,请在 $aws/things/thingName/jobs/jobId/update 上发布消息。

请求负载:

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

任务执行的新状态 (IN_PROGRESS、FAILED、SUCCEEDED 或 REJECTED)。这必须在每次更新时指定。

statusDetails

描述任务执行状态的名称/值对的集合。如果未指定,则 statusDetails 保持不变。

expectedVersion

任务执行的预期当前版本。每次更新任务执行时,其版本将递增。如果存储在 Jobs 中的任务执行版本不匹配,则更新将被拒绝并出现 VersionMismatch 错误,并且将返回包含当前任务执行状态数据的 ErrorResponse。(这样就不必执行单独的 DescribeJobExecution 请求以获取任务执行状态数据。)

executionNumber

可选。标识特定设备上的特定任务执行的数字。如果未指定,则使用最新的任务执行。

includeJobExecutionState

可选。在包含此项并设置为 true 时,响应将包含 JobExecutionState 字段。默认为 false

includeJobDocument

可选。在包含此参数且设置为 true 时,响应将包含 JobDocument。默认为 false

clientToken

用于将请求和响应关联起来的客户端令牌。在此处输入任意值,它将反映在响应中。

要接收响应,请订阅:

  • $aws/things/thingName/jobs/jobId/update/accepted ...和...

  • $aws/things/thingName/jobs/jobId/update/rejected ...或者...

  • $aws/things/thingName/jobs/jobId/update/# ...for both...

响应负载:

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

一个 JobExecutionState 对象。

jobDocument

一个任务文档对象。

timestamp

发送消息的时间 (用从纪元开始的秒数表示)。

clientToken

用于将请求和响应关联起来的客户端令牌。

HTTPS (15)

请求:

POST /things/thingName/jobs/jobId { "status": "job-execution-state", "statusDetails": { "string": "string" ... }, "expectedVersion": "number", "includeJobExecutionState": "boolean", "includeJobDocument": "boolean", "executionNumber": "long" }
thingName

与设备关联的事物的名称。

jobId

创建此任务时向其分配的唯一标识符。

status

任务执行的新状态 (IN_PROGRESS、FAILED、SUCCEEDED 或 REJECTED)。这必须在每次更新时指定。

statusDetails

可选。描述任务执行状态的名称/值对的集合。如果未指定,则 statusDetails 保持不变。

expectedVersion

可选。任务执行的预期当前版本。每次更新任务执行时,其版本将递增。如果存储在 Jobs 中的任务执行版本不匹配,则更新将被拒绝并出现 VersionMismatch 错误,并且将返回包含当前任务执行状态数据的 ErrorResponse。(这样就不必执行单独的 DescribeJobExecution 请求以获取任务执行状态数据。)

includeJobExecutionState

可选。在包括此项并设置为 true 时,响应将包含 JobExecutionState 数据。默认为 false

includeJobDocument

可选。设置为 true 时,响应将包含任务文档。默认为 false

executionNumber

可选。标识特定设备上的特定任务执行的数字。

响应:

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

一个 JobExecutionState 对象。

jobDocument

任务文档的内容。

CLI (15)

摘要:

aws iot-jobs-data update-job-execution \ --job-id <value> \ --thing-name <value> \ --status <value> \ [--status-details <value>] \ [--expected-version <value>] \ [--include-job-execution-state | --no-include-job-execution-state] \ [--include-job-document | --no-include-job-document] \ [--execution-number <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json format:

{ "jobId": "string", "thingName": "string", "status": "string", "statusDetails": { "string": "string" }, "expectedVersion": "long", "includeJobExecutionState": "boolean", "includeJobDocument": "boolean", "executionNumber": "long" }

cli-input-json 字段:

名称

类型

描述

jobId

字符串

最大长度:64,最小长度:1

模式:[a-zA-Z0-9_-]+

创建此任务时向其分配的唯一标识符。

thingName

字符串

最大长度:128,最小长度:1

模式:[a-zA-Z0-9:_-]+

与设备关联的事物的名称。

status

字符串

枚举:QUEUED | IN_PROGRESS | SUCCEEDED | FAILED | REJECTED | REMOVED | CANCELED

java 类:com.amazonaws.iot.laser.common.JobExecutionStatus

任务执行的新状态 (IN_PROGRESS、FAILED、SUCCESS 或 REJECTED)。这必须在每次更新时指定。

statusDetails

map

键:DetailsKey

值:DetailsValue

可选。描述任务执行状态的名称/值对的集合。如果未指定,则 statusDetails 保持不变。

DetailsKey

字符串

最大长度:128,最小长度:1

模式:[a-zA-Z0-9:_-]+

DetailsValue

字符串

最大长度:1024,最小长度:1

模式:[^\\p{C}]*+

expectedVersion

long

java 类:java.lang.Long

可选。任务执行的预期当前版本。每次更新任务执行时,其版本将递增。如果存储在 Jobs 中的任务执行版本不匹配,则更新将被拒绝并出现 VersionMismatch 错误,并且将返回包含当前任务执行状态数据的 ErrorResponse。(这样就不再需要执行单独的 DescribeJobExecution 请求来获取任务执行状态数据。)

includeJobExecutionState

布尔值

java 类:java.lang.Boolean

可选。包括此项并设置为 true 时,响应将包含 JobExecutionState 数据。默认为 false。

includeJobDocument

布尔值

java 类:java.lang.Boolean

可选。设置为 true 时,响应将包含任务文档。默认为 false。

executionNumber

long

java 类:java.lang.Long

可选。标识特定设备上的特定任务执行的数字。

输出:

{ "executionState": { "status": "string", "statusDetails": { "string": "string" }, "versionNumber": "long" }, "jobDocument": "string" }

cli 输出字段:

名称

类型

描述

executionState

JobExecutionState

JobExecutionState 对象。

status

字符串

枚举:QUEUED | IN_PROGRESS | SUCCEEDED | FAILED | REJECTED | REMOVED | CANCELED

java 类:com.amazonaws.iot.laser.common.JobExecutionStatus

任务执行的状态。可以为以下值之一:“QUEUED"、“IN_PROGRESS”、“FAILED”、“SUCCESS”、“CANCELED”、“REJECTED”或“REMOVED”。

statusDetails

map

键:DetailsKey

值:DetailsValue

描述任务执行状态的名称/值对的集合。

DetailsKey

字符串

最大长度:128,最小长度:1

模式:[a-zA-Z0-9:_-]+

DetailsValue

字符串

最大长度:1024,最小长度:1

模式:[^\\p{C}]*+

versionNumber

long

任务执行的版本。每次设备更新任务执行版本时,版本将递增。

jobDocument

字符串

最大长度:32768

任务文档的内容。

JobExecutionsChanged

JobExecutionsChanged 消息MQTT (16)HTTPS (16)CLI (16)
JobExecutionsChanged 消息

在事物的待处理任务执行列表中添加或删除任务执行时发送。

MQTT (16)

主题: $aws/things/thingName/jobs/notify

消息负载:

{ "jobs" : { "JobExecutionState": [ JobExecutionSummary ... ] }, "timestamp": timestamp, }
HTTPS (16)

不可用。

CLI (16)

不可用。

NextJobExecutionChanged

NextJobExecutionChanged 消息MQTT (17)HTTPS (17)CLI (17)
NextJobExecutionChanged 消息

当存在对事物的待处理任务执行列表中的下一个任务执行的更改 (由 jobId 为 $nextDescribeJobExecution 定义) 时发送。当下一个任务的执行详细信息发送更改时不会发送此消息,而仅在将由 jobId 为 $nextDescribeJobExecution 返回的下一个任务发生更改时发送。考虑状态为 QUEUED 的任务执行 J1 和 J2。J1 是待处理任务执行列表中的下一个待处理任务执行。如果 J2 的状态更改为 IN_PROGRESS,而 J1 的状态保持不变,则将发送此通知,并且此通知包含 J2 的详细信息。

MQTT (17)

主题: $aws/things/thingName/jobs/notify-next

消息负载:

{ "execution" : JobExecutionData, "timestamp": timestamp, }
HTTPS (17)

不可用。

CLI (17)

不可用。