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

使用 AWS IoT Jobs API

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

  • 用于管理和控制作业的 API。

  • 由执行这些作业的设备使用的 API。

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

注意

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

aws iot create-job ...

作业管理和控制 API

作业管理和控制数据类型

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

作业

Job Data TypeSyntax (1)Description (1)
Job Data Type

Job 对象包含有关作业的详细信息。

Syntax (1)
{ "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 } }
Description (1)
jobArn

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

jobId

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

status

作业的状态,为 IN_PROGRESSCANCELEDSUCCEEDED 之一。

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 事物数。

numberOfTimedOutThings

作业执行状态为 TIMED_OUT 的事物数。

presignedUrlConfig

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

expiresInSec

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

roleArn

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

jobExecutionRolloutConfig

可选。允许您创建作业的分段推出。

maximumPerMinute

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

exponentialRate

允许您创建作业推出的指数速率。

baseRatePerMinute

在作业推出开始时,每分钟接收待处理作业通知的事物的最小数量。此参数允许您定义推出的初始速率。

incrementFactor

用于提高作业推出速率的指数因子。

rateIncreaseCriteria

启动作业推出速率提高的条件。您可以指定 numberOfNotifiedThingsnumberOfSucceededThing,但不能同时指定两者。

numberOfNotifiedThings

启动推出速率提高的被通知事物的数量阈值。

numberOfSucceededThings

启动推出速率提高的成功事物的数量阈值。

abortConfig

可选。用于中止作业的中止条件的详细信息。

criteriaList

定义中止作业的规则的中止条件列表。

action

启动作业中止的中止操作的类型。

failureType

定义启动作业中止的规则的作业执行失败的类型。

minNumberOfExecutedThings

评估中止规则之前已执行事物的最小数量。

thresholdPercentage

以启动作业中止的执行事物总数的百分比形式表示的阈值。

timeoutConfig

可选。指定每个设备完成其作业执行所具有的时间。计时器在作业执行状态设置为 IN_PROGRESS 时启动。如果作业执行状态未在时间到期之前设置为其他最终状态,它会设置为 TIMED_OUT

注意

作业超时功能目前在 AWS GovCloud(美国)区域中不可用。

inProgressTimeoutInMinutes

指定此设备完成该作业执行所具有的时间,以分钟为单位。只要作业的执行状态指定为 IN_PROGRESS 并且填充了此字段,计时器将启动或重新启动。如果在计时器到期之前,或者在发送另一个填充了此字段的作业执行状态更新之前,作业执行状态未设置为最终状态,状态将设置为 TIMED_OUT

JobSummary

JobSummary Data TypeSyntax (2)Description (2)
JobSummary Data Type

JobSummary 对象包含作业摘要。

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

一个标识作业的 ARN。

jobId

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

status

作业状态。可以为以下值之一:IN_PROGRESSCANCELEDSUCCEEDED

targetSelection

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

thingGroupId

事物组的 ID。

createdAt

创建作业的时间的 UNIX 时间戳。

lastUpdatedAt

上次更新作业的时间的 UNIX 时间戳。

completedAt

完成作业的时间的 UNIX 时间戳。

JobExecution

JobExection Data TypeSyntax (3)Description (3)
JobExection Data Type

JobExecution 对象表示设备上的作业执行。

Syntax (3)
{ "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 }
Description (3)
approximateSecondsBeforeTimedOut

作业执行状态更改为 TIMED_OUT 之前估计剩余的秒数。超时间隔可以为 1 分钟到 7 天(1 到 10080 分钟)之间的任意长度。实际作业执行超时可能晚于估计的持续时间最多 60 秒。

jobId

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

executionNumber

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

thingArn

AWS IoT 事物 ARN。

queuedAt

作业执行入队的时间,用从纪元开始的秒数表示。

lastUpdatedAt

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

startedAt

作业执行开始的时间,用从纪元开始的秒数表示。

status

作业执行的状态。可以为以下值之一:QUEUEDIN_PROGRESSFAILEDSUCCEEDEDCANCELEDTIMED_OUTREJECTEDREMOVED

statusDetails

描述作业执行状态的名称-值对的集合。

JobExecutionSummary

JobExecutionSummary Data TypeSyntax (4)Description (4)
JobExecutionSummary Data Type

JobExecutionSummary 对象包含作业执行摘要信息:

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

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

queuedAt

作业执行入队的时间,用从纪元开始的秒数表示。

lastUpdatedAt

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

startAt

作业执行开始的时间,用从纪元开始的秒数表示。

status

作业执行的状态:QUEUEDIN_PROGRESSFAILEDSUCCEEDEDCANCELEDTIMED_OUTREJECTEDREMOVED

JobExecutionSummaryForJob

JobExecutionSummaryForJob Data TypeSyntax (5)Description (5)
JobExecutionSummaryForJob Data Type

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

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

AWS IoT 事物 ARN。

jobExecutionSummary

一个 JobExecutionSummary 对象。

JobExecutionSummaryForThing

JobExecutionSummaryForThing Data TypeSyntax (6)Description (6)
JobExecutionSummaryForThing Data Type

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

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

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

jobExecutionSummary

一个 JobExecutionSummary 对象。

作业管理和控制 HTTPS 命令

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

AssociateTargetsWithJob

AssociateTargetsWithJob CommandHTTPS (1)CLI (1)MQTT (1)
AssociateTargetsWithJob Command

将组与持续作业关联。有关更多信息,请参阅 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 格式:

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

cli-input-json 字段:

名称

类型

描述

targets

list

成员:TargetArn

定义作业目标的事物组 ARN 的列表。

TargetArn

string

jobId

string

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

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

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

comment

string

最大长度:2028

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

一个可选的字符串,描述将作业与目标关联的原因。

输出:

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

CLI 输出字段:

名称

类型

描述

jobArn

string

标识作业的 ARN。

jobId

string

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

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

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

description

string

最大长度:2028

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

作业的简短文本描述。

MQTT (1)

不可用。

CancelJob

CancelJob CommandHTTPS (2)CLI (2)MQTT (2)
CancelJob Command

取消作业。

HTTPS (2)

请求:

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

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

force

[可选] 如果为 true,则将取消状态为 IN_PROGRESSQUEUED 的作业执行。否则,将仅取消状态为 QUEUED 的作业执行。默认为 false

警告

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

comment

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

reasonCode

[可选] 一个原因代码字符串,说明取消作业的原因。如果作业因满足 abortConfig 定义的条件而被取消,则会自动填充此字段。

响应:

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

作业 ARN。

jobId

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

description

作业的简短文本描述。

CLI (2)

摘要:

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

cli-input-json 字段:

名称

类型

描述

jobId

string

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

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

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

force

boolean

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

警告

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

comment

string

最大长度:2028

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

一个可选的字符串,用于描述为什么取消作业。

reasonCode

string

最大长度:128

模式:[\p{Upper}\p{Digit}_]+

一个可选的字符串,用于说明为什么取消作业。如果作业因满足 abortConfig 定义的条件而被取消,则会自动填充此字段。

输出:

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

CLI 输出字段:

名称

类型

描述

jobArn

string

作业 ARN。

jobId

string

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

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

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

description

string

最大长度:2028

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

作业的简短文本描述。

MQTT (2)

不可用。

CancelJobExecution

CancelJobExecution CommandHTTPS (3)CLI (3)MQTT (3)
CancelJobExecution Command

取消设备上的作业执行。

HTTPS (3)

请求:

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

将取消其作业执行的事物的名称。

jobId

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

force

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

警告

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

expectedVersion

可选。作业执行的预期当前版本。每次更新作业执行时,其版本将递增。如果存储在 AWS IoT 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 格式:

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

cli-input-json 字段:

名称

类型

描述

jobId

string

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

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

要取消的作业。

thingName

string

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

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

将取消其作业执行的事物的名称。

force

boolean

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

警告

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

expectedVersion

long

java 类:java.lang.Long

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

statusDetails

映射

键:DetailsKey

值:DetailsValue

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

DetailsKey

string

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

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

DetailsValue

string

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

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

输出:

MQTT (3)

不可用。

CreateJob

CreateJob CommandHTTPS (4)CLI (4)MQTT (4)
CreateJob Command

创建作业。您可以将作业文档作为 Amazon S3 存储桶(documentSource 参数)中或请求正文(document 参数)中的文档链接提供。

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

作业可以具有可选的 TimeoutConfig,这会设置进行中计时器的值。进行中计时器无法更新,应用到该作业的全部执行。

注意

作业超时功能目前在 AWS GovCloud(美国)区域中不可用。

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

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

targets

定义作业目标的事物或事物组 ARN 的列表。

document

可选。作业文档。

documentSource

可选。指向作业文档的 Amazon S3 链接。

description

可选。作业的简短文本描述。

presignedUrlConfigData

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

roleArn

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

expiresInSec

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

targetSelection

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

jobExecutionRolloutConfig

可选。允许您创建作业的分段推出。

maximumPerMinute

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

exponentialRate

允许您创建作业推出的指数速率。

baseRatePerMinute

在作业推出开始时,每分钟接收待处理作业通知的事物的最小数量。此参数允许您定义推出的初始速率。

incrementFactor

用于提高作业推出速率的指数因子。

rateIncreaseCriteria

启动作业推出速率提高的条件。设置 numberOfNotifiedThingsnumberOfSucceededThings 的值,但不能同时设置这两者。

numberOfNotifiedThings

启动推出速率提高的被通知事物的数量阈值。

numberOfSucceededThings

启动推出速率提高的成功事物的数量阈值。

abortConfig

可选。用于中止作业的中止条件的详细信息。

criteriaList

定义中止作业的规则的中止条件列表。

action

启动作业中止的中止操作的类型。

failureType

定义启动作业中止的规则的作业执行失败的类型。

minNumberOfExecutedThings

评估中止规则之前已执行事物的最小数量。

thresholdPercentage

以启动作业中止的执行事物总数的百分比形式表示的阈值。

timeoutConfig

可选。指定每个设备完成其作业执行所具有的时间。计时器在作业执行状态设置为 IN_PROGRESS 时启动。如果作业执行状态未在时间到期之前设置为其他最终状态,它会设置为 TIMED_OUT

注意

作业超时功能目前在 AWS GovCloud(美国)区域中不可用。

inProgressTimeoutInMinutes

指定此设备完成该作业执行所具有的时间,以分钟为单位。只要作业的执行状态指定为 IN_PROGRESS 并且填充了此字段,计时器将启动或重新启动。如果在计时器到期之前,或者在发送另一个填充了此字段的作业执行状态更新之前,作业执行状态未设置为最终状态,状态将设置为 TIMED_OUT

响应:

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

cli-input-json 字段:

名称

类型

描述

jobId

string

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

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

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

targets

list

成员:TargetArn

作业应发送到的事物和事物组的列表。

TargetArn

string

documentSource

string

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

指向作业文档的 S3 链接。

文档

string

最大长度:32768

作业文档。

description

string

最大长度:2028

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

作业的简短文本描述。

presignedUrlConfig

PresignedUrlConfig

预签名 S3 URL 的配置信息。

roleArn

string

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

IAM 角色的 ARN,该角色授予从存储作业数据或更新的 Amazon S3 存储桶下载文件的权限。该角色还必须向 AWS IoT 授予下载文件的权限。

expiresInSec

long

java 类:java.lang.Long

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

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

targetSelection

string

枚举:CONTINUOUS | SNAPSHOT

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

jobExecutionsRolloutConfig

JobExecutionsRolloutConfig

允许您创建作业的分段推出。

maximumPerMinute

integer

java 类:java.lang.Integer

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

每分钟接收待处理作业通知的事物的最大数量。此参数允许您创建分段推出。

exponentialRate

ExponentialRolloutRate

作业推出的增速。此参数允许您定义作业推出的指数速率。

baseRatePerMinute

java 类:java.lang.Integer

在作业推出开始时,每分钟接收待处理作业通知的事物的最小数量。此参数允许您定义推出的初始速率。

incrementFactor

java 类:java.lang.Double

用于提高作业推出速率的指数因子。

rateIncreaseCriteria

RateIncreaseCriteria

允许您定义启动作业推出速率提高的条件。设置 numberOfNotifiedThingsnumberOfSucceededThings 的值,但不能同时设置这两者。

numberOfNotifiedThings

java 类:java.lang.Double

启动推出速率提高的被通知事物的数量阈值。

numberOfSucceededThings

java 类:java.lang.Double

启动推出速率提高的成功事物的数量阈值。

abortConfig

AbortConfig

允许您创建中止作业的条件。

criteriaList

AbortCriteria

定义中止作业的规则的中止条件列表。

action

java 类:java.lang.String (CANCEL)

启动作业中止的中止操作的类型。

failureType

java 类:java.lang.String (FAILED | REJECTED | TIMED_OUT | ALL)

定义启动作业中止的规则的作业执行失败的类型。

minNumberOfExecutedThings

java 类:java.lang.Integer)

评估中止规则之前已执行事物的最小数量。

thresholdPercentage

java 类:java.lang.Double)

以启动作业中止的执行事物总数的百分比形式表示的阈值。

AWS IoT 最多支持小数点后两位(例如,支持 10.9 和 10.99,但不支持 10.999)。

timeoutConfig

TimeoutConfig

指定每个设备完成其作业执行所具有的时间。计时器在作业执行状态设置为 IN_PROGRESS 时启动。如果作业执行状态未在时间到期之前设置为其他最终状态,它会设置为 TIMED_OUT

注意

作业超时功能目前在 AWS GovCloud(美国)区域中不可用。

inProgressTimeoutInMinutes

long

指定此设备完成该作业执行所具有的时间,以分钟为单位。只要作业的执行状态指定为 IN_PROGRESS 并且填充了此字段,计时器将启动或重新启动。如果在计时器到期之前,或者在发送另一个填充了此字段的作业执行状态更新之前,作业执行状态未设置为最终状态,状态将设置为 TIMED_OUT

documentParameters

映射

键:ParameterKey

值:ParameterValue

作业文档的参数。

ParameterKey

string

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

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

ParameterValue

string

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

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

输出:

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

CLI 输出字段:

名称

类型

描述

jobArn

string

作业 ARN。

jobId

string

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

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

您分配给此作业的唯一标识符。

description

string

最大长度:2028

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

作业描述。

MQTT (4)

不可用。

DeleteJob

DeleteJob CommandHTTPS (5)CLI (5)MQTT (5)
DeleteJob Command

删除作业及其相关的作业执行。

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

HTTPS (5)

请求语法:

DELETE /jobs/jobId?force=force

URI 请求参数:

名称

类型

请求?

描述

jobId

JobId

要删除的作业的 ID。

force

ForceFlag

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

注意

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

错误:

InvalidRequestException

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

HTTP 响应代码:400

InvalidStateTransitionException

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

HTTP 响应代码:409

ResourceNotFoundException

指定的资源不存在。

HTTP 响应代码:404

ThrottlingException

速率超过限制。

HTTP 响应代码:429

ServiceUnavailableException

服务暂时不可用。

HTTP 响应代码:503

CLI (5)

摘要:

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

cli-input-json 格式:

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

cli-input-json 字段:

名称

类型

描述

jobId

string

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

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

要删除的作业的 ID。

force

boolean

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

注意

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

输出:

MQTT (5)

不可用。

DeleteJobExecution

DeleteJobExecution CommandHTTPS (6)CLI (6)MQTT (6)
DeleteJobExecution Command

删除作业执行。

HTTPS (6)

请求语法:

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、TIMED_OUT、REJECTED、REMOVED 或 CANCELED)的作业执行,否则会出现异常。默认为 false。

注意

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

错误:

InvalidRequestException

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

HTTP 响应代码:400

InvalidStateTransitionException

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

HTTP 响应代码:409

ResourceNotFoundException

指定的资源不存在。

HTTP 响应代码:404

ThrottlingException

速率超过限制。

HTTP 响应代码:429

ServiceUnavailableException

服务暂时不可用。

HTTP 响应代码:503

CLI (6)

摘要:

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 }

cli-input-json 字段:

名称

类型

描述

jobId

string

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

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

将删除其执行的作业的 ID。

thingName

string

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

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

将删除其作业执行的事物的名称。

executionNumber

long

java 类:java.lang.Long

要删除的作业执行的 ID。

force

boolean

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

注意

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

输出:

MQTT (6)

不可用。

DescribeJob

DescribeJob CommandHTTPS (7)CLI (7)MQTT (7)
DescribeJob Command

获取指定作业的详细信息。

HTTPS (7)

请求:

GET /jobs/jobId
jobId

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

响应:

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

指向作业文档的 Amazon S3 链接。

job

一个 作业 对象。

CLI (7)

摘要:

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

cli-input-json 格式:

{ "jobId": "string" }

cli-input-json 字段:

名称

类型

描述

jobId

string

最大长度: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": { "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 } ] }, "createdAt": "timestamp", "lastUpdatedAt": "timestamp", "completedAt": "timestamp", "jobProcessDetails": { "processingTargets": [ "string" ], "numberOfCanceledThings": "integer", "numberOfSucceededThings": "integer", "numberOfFailedThings": "integer", "numberOfRejectedThings": "integer", "numberOfQueuedThings": "integer", "numberOfInProgressThings": "integer", "numberOfRemovedThings": "integer", "numberOfTimedOutThings": "integer" }, "documentParameters": { "string": "string" }, "timeoutConfig": { "inProgressTimeoutInMinutes": number } } }

CLI 输出字段:

名称

类型

描述

documentSource

string

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

指向作业文档的 Amazon S3 链接。

作业

作业

该作业的相关信息。

jobArn

string

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

jobId

string

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

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

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

targetSelection

string

枚举:CONTINUOUS | SNAPSHOT

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

status

string

枚举:IN_PROGRESS | CANCELED | SUCCEEDED

作业的状态,为 IN_PROGRESSCANCELEDSUCCEEDED 之一。

forceCanceled

boolean

java 类:java.lang.Boolean

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

comment

string

最大长度:2028

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

如果作业已更新,介绍更新原因。

targets

list

成员:TargetArn

作业应发送到的 AWS IoT 事物和事物组的列表。

TargetArn

string

description

string

最大长度:2028

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

作业的简短文本描述。

presignedUrlConfig

PresignedUrlConfig

预签名 Amazon S3 URL 的配置。

roleArn

string

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

IAM 角色的 ARN,该角色授予从存储作业数据或更新的 Amazon S3 存储桶下载文件的权限。该角色还必须向 AWS IoT Jobs 服务授予下载文件的权限。

expiresInSec

long

java 类:java.lang.Long

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

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

jobExecutionsRolloutConfig

JobExecutionsRolloutConfig

允许您创建作业的分段推出。

maximumPerMinute

integer

java 类:java.lang.Integer

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

每分钟接收待处理作业通知的事物的最大数量。此参数允许您创建分段推出。

exponentialRate

ExponentialRolloutRate

作业推出的增速。此参数允许您定义作业推出的指数速率。

baseRatePerMinute

java 类:java.lang.Integer

在作业推出开始时,每分钟接收待处理作业通知的事物的最小数量。此参数允许您定义推出的初始速率。

incrementFactor

java 类:java.lang.Double

用于提高作业推出速率的指数因子。

rateIncreaseCriteria

RateIncreaseCriteria

允许您定义启动作业推出速率提高的条件。设置 numberOfNotifiedThingsnumberOfSucceededThings 的值,但不能同时设置这两者。

numberOfNotifiedThings

java 类:java.lang.Double

启动推出速率提高的被通知事物的数量阈值。

numberOfSucceededThings

java 类:java.lang.Double

启动推出速率提高的成功事物的数量阈值。

abortConfig

AbortConfig

允许您创建中止作业的条件。

criteriaList

AbortCriteria

定义中止作业的规则的中止条件列表。

action

java 类:java.lang.String (CANCEL)

启动作业中止的中止操作的类型。

failureType

java 类:java.lang.String (FAILED | REJECTED | TIMED_OUT | ALL)

定义启动作业中止的规则的作业执行失败的类型。

minNumberOfExecutedThings

java 类:java.lang.Integer)

评估中止规则之前已执行事物的最小数量。

thresholdPercentage

java 类:java.lang.Double)

以启动作业中止的执行事物总数的百分比形式表示的阈值。

AWS IoT 最多支持小数点后两位(例如,支持 10.9 和 10.99,但不支持 10.999)。

createdAt

timestamp

创建作业的时间,用从纪元开始的秒数表示。

lastUpdatedAt

timestamp

上次更新作业的时间,用从纪元开始的秒数表示。

completedAt

timestamp

完成作业的时间,用从纪元开始的秒数表示。

jobProcessDetails

JobProcessDetails

作业流程的详细信息。

processingTargets

list

成员:ProcessingTargetName

java 类:java.util.List

执行作业的设备。

ProcessingTargetName

string

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

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

numberOfTimedOutThings

integer

java 类:java.lang.Integer

作业执行状态为 TIMED_OUT 的事物数。

documentParameters

映射

键:ParameterKey

值:ParameterValue

为作业文档指定的参数。

ParameterKey

string

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

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

ParameterValue

string

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

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

timeoutConfig

TimeoutConfig

指定每个设备完成其作业执行所具有的时间。计时器在作业执行状态设置为 IN_PROGRESS 时启动。如果作业执行状态未在计时器到期之前设置为其他最终状态,它会设置为 TIMED_OUT

注意

作业超时功能目前在 AWS GovCloud(美国)区域中不可用。

inProgressTimeoutInMinutes

long

指定此设备完成该作业执行所具有的时间,以分钟为单位。超时间隔可以为 1 分钟到 7 天(1 到 10080 分钟)之间的任意长度。进行中计时器无法更新,将应用到该作业的全部作业执行。只要作业执行保持在 IN_PROGRESS 状态的时间长度超过了此间隔,作业执行将失败,并切换为最终 TIMED_OUT 状态。

MQTT (7)

不可用。

DescribeJobExecution

DescribeJobExecution CommandHTTPS (8)CLI (8)MQTT (8)
DescribeJobExecution Command

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

HTTPS (8)

请求:

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

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

thingName

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

executionNumber

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

响应:

{ "execution": { JobExecution } }
execution

一个 JobExecution 对象。

CLI (8)

摘要:

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 }

cli-input-json 字段:

名称

类型

描述

jobId

string

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

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

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

thingName

string

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

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

正在运行作业执行的事物的名称。

executionNumber

long

java 类:java.lang.Long

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

输出:

{ "execution": { "approximateSecondsBeforeTimedOut": "number" "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

作业执行的相关信息。

approximateSecondsBeforeTimedOut

long

作业执行状态更改为 TIMED_OUT 之前估计剩余的秒数。超时间隔可以为 1 分钟到 7 天(1 到 10080 分钟)之间的任意长度。实际作业执行超时可能晚于估计的持续时间最多 60 秒。如果作业执行进入了最终状态,则不包括此值。

jobId

string

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

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

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

status

string

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

作业执行的状态(IN_PROGRESS、QUEUED、FAILED、SUCCEEDED、TIMED_OUT、CANCELED 或 REJECTED)。

forceCanceled

boolean

java 类:java.lang.Boolean

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

statusDetails

JobExecutionStatusDetails

描述作业执行状态的名称-值对的集合。

detailsMap

映射

键:DetailsKey

值:DetailsValue

作业执行状态。

DetailsKey

string

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

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

DetailsValue

string

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

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

thingArn

string

正在运行作业执行的事物的 ARN。

queuedAt

timestamp

作业执行入队的时间,用从纪元开始的秒数表示。

startedAt

timestamp

作业执行开始的时间,用从纪元开始的秒数表示。

lastUpdatedAt

timestamp

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

executionNumber

long

java 类:java.lang.Long

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

versionNumber

long

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

MQTT (8)

不可用。

GetJobDocument

GetJobDocument CommandHTTPS (9)CLI (9)MQTT (9)
GetJobDocument Command

获取作业的作业文档。

注意

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

HTTPS (9)

请求:

GET /jobs/jobId/job-document
jobId

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

响应:

{ "document": "string" }
document

作业文档内容。

CLI (9)

摘要:

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

cli-input-json 格式:

{ "jobId": "string" }

cli-input-json 字段:

名称

类型

描述

jobId

string

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

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

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

输出:

{ "document": "string" }

CLI 输出字段:

名称

类型

描述

文档

string

最大长度:32768

作业文档内容。

MQTT (9)

不可用。

ListJobExecutionsForJob

ListExecutionsForJob CommandHTTPS (10)CLI (10)MQTT (10)
ListExecutionsForJob Command

获取作业的作业执行的列表。

HTTPS (10)

请求:

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

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

status

可选。可用于搜索具有指定状态的作业的筛选条件:QUEUED、IN_PROGRESS、SUCCEEDED、FAILED、TIMED_OUT、REJECTED、REMOVED 或 CANCELED。

maxResults

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

nextToken

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

响应:

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

与指定的作业 ID 关联的 JobExecutionSummary 对象的列表。

CLI (10)

摘要:

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

cli-input-json 字段:

名称

类型

描述

jobId

string

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

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

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

status

string

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

作业的状态。

maxResults

integer

java 类:java.lang.Integer

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

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

nextToken

string

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

输出:

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

CLI 输出字段:

名称

类型

描述

executionSummaries

list

成员:JobExecutionSummaryForJob

java 类:java.util.List

作业执行摘要的列表。

JobExecutionSummaryForJob

JobExecutionSummaryForJob

thingArn

string

正在运行作业执行的事物的 ARN。

jobExecutionSummary

JobExecutionSummary

包含有关作业执行的信息的子集。

status

string

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

作业执行的状态。

queuedAt

timestamp

作业执行入队的时间,用从纪元开始的秒数表示。

startedAt

timestamp

作业执行开始的时间,用从纪元开始的秒数表示。

lastUpdatedAt

timestamp

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

executionNumber

long

java 类:java.lang.Long

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

nextToken

string

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

MQTT (10)

不可用。

ListJobExecutionsForThing

ListJobExecutionsForThing CommandHTTPS (11)CLI (11)MQTT (11)
ListJobExecutionsForThing Command

获取事物的作业执行的列表。

HTTPS (11)

请求:

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

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

status

可用于搜索具有指定状态的作业的可选筛选条件:QUEUED、IN_PROGRESS、SUCCEEDED、FAILED、TIMED_OUT、REJECTED、REMOVED 或 CANCELED。

maxResults

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

nextToken

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

响应:

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

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

CLI (11)

摘要:

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

cli-input-json 字段:

名称

类型

描述

thingName

string

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

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

事物名称。

status

string

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

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

maxResults

integer

java 类:java.lang.Integer

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

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

nextToken

string

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

输出:

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

CLI 输出字段:

名称

类型

描述

executionSummaries

list

成员:JobExecutionSummaryForThing

java 类:java.util.List

作业执行摘要的列表。

JobExecutionSummaryForThing

JobExecutionSummaryForThing

jobId

string

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

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

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

jobExecutionSummary

JobExecutionSummary

包含有关作业执行的信息的子集。

status

string

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

作业执行的状态。

queuedAt

timestamp

作业执行入队的时间,用从纪元开始的秒数表示。

startedAt

timestamp

作业执行开始的时间,用从纪元开始的秒数表示。

lastUpdatedAt

timestamp

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

executionNumber

long

java 类:java.lang.Long

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

nextToken

string

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

MQTT (11)

不可用。

ListJobs

ListJobs CommandHTTPS (12)CLI (12)MQTT (12)
ListJobs Command

获取 AWS 账户中的作业的列表。

HTTPS (12)

请求:

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

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

targetSelection

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

thingGroupName

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

thingGroupId

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

maxResults

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

nextToken

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

响应:

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

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

CLI (12)

摘要:

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

cli-input-json 字段:

名称

类型

描述

status

string

枚举:IN_PROGRESS | CANCELED | SUCCEEDED

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

targetSelection

string

枚举:CONTINUOUS | SNAPSHOT

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

maxResults

integer

java 类:java.lang.Integer

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

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

nextToken

string

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

thingGroupName

string

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

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

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

thingGroupId

string

最大长度: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

list

成员:Job Summary

java 类:java.util.List

作业列表。

JobSummary

JobSummary

jobArn

string

作业 ARN。

jobId

string

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

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

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

thingGroupId

string

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

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

事物组的 ID。

targetSelection

string

枚举:CONTINUOUS | SNAPSHOT

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

status

string

枚举:IN_PROGRESS | CANCELED | SUCCEEDED

作业摘要状态。

createdAt

timestamp

创建作业的时间,用从纪元开始的秒数表示。

lastUpdatedAt

timestamp

上次更新作业的时间,用从纪元开始的秒数表示。

completedAt

timestamp

完成作业的时间,用从纪元开始的秒数表示。

nextToken

string

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

MQTT (12)

不可用。

UpdateJob

UpdateJob CommandHTTPS (13)CLI (13)MQTT (13)
UpdateJob Command

更新指定作业的受支持字段。timeoutConfig 的更新值仅对新的正在进行的执行有效。当前正在进行的执行继续使用旧超时配置执行。

HTTPS (13)

请求:

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 } }
jobId

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

description

可选。作业的简短文本描述。

presignedUrlConfigData

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

roleArn

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

expiresInSec

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

jobExecutionRolloutConfig

可选。允许您创建作业的分段推出。

maximumPerMinute

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

exponentialRate

允许您创建作业推出的指数速率。

baseRatePerMinute

在作业推出开始时,每分钟接收待处理作业通知的事物的最小数量。此参数允许您定义推出的初始速率。

incrementFactor

用于提高作业推出速率的指数因子。

rateIncreaseCriteria

启动作业推出速率提高的条件。设置 numberOfNotifiedThingsnumberOfSucceededThings 的值,但不能同时设置这两者。

numberOfNotifiedThings

启动推出速率提高的被通知事物的数量阈值。

numberOfSucceededThings

启动推出速率提高的成功事物的数量阈值。

abortConfig

可选。用于中止作业的中止条件的详细信息。

criteriaList

定义中止作业的规则的中止条件列表。

action

启动作业中止的中止操作的类型。

failureType

定义启动作业中止的规则的作业执行失败的类型。

minNumberOfExecutedThings

评估中止规则之前已执行事物的最小数量。

thresholdPercentage

以启动作业中止的执行事物总数的百分比形式表示的阈值。

timeoutConfig

可选。指定每个设备完成其作业执行所具有的时间。计时器在作业执行状态设置为 IN_PROGRESS 时启动。如果作业执行状态未在时间到期之前设置为其他最终状态,它会设置为 TIMED_OUT

inProgressTimeoutInMinutes

指定此设备完成该作业执行所具有的时间,以分钟为单位。只要作业的执行状态指定为 IN_PROGRESS 并且填充了此字段,计时器将启动或重新启动。如果在计时器到期之前,或者在发送另一个填充了此字段的作业执行状态更新之前,作业执行状态未设置为最终状态,状态将设置为 TIMED_OUT

响应:

HTTP/1.1 200

如果此操作成功,则该服务会发送回带有空 HTTP 正文的 HTTP 200 响应。

CLI (13)

摘要:

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

cli-input-json 字段:

名称

类型

描述

jobId

string

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

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

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

description

string

最大长度:2028

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

作业的简短文本描述。

presignedUrlConfig

PresignedUrlConfig

预签名 S3 URL 的配置信息。

roleArn

string

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

IAM 角色的 ARN,该角色授予从存储作业数据或更新的 S3 存储桶下载文件的权限。该角色还必须向 AWS IoT 授予下载文件的权限。

expiresInSec

long

java 类:java.lang.Long

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

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

jobExecutionsRolloutConfig

JobExecutionsRolloutConfig

允许您创建作业的分段推出。

maximumPerMinute

integer

java 类:java.lang.Integer

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

每分钟接收待处理作业通知的事物的最大数量。此参数允许您创建分段推出。

exponentialRate

ExponentialRolloutRate

作业推出的增速。此参数允许您定义作业推出的指数速率。

baseRatePerMinute

java 类:java.lang.Integer

在作业推出开始时,每分钟接收待处理作业通知的事物的最小数量。此参数允许您定义推出的初始速率。

incrementFactor

java 类:java.lang.Double

用于提高作业推出速率的指数因子。

rateIncreaseCriteria

RateIncreaseCriteria

允许您定义启动作业推出速率提高的条件。设置 numberOfNotifiedThingsnumberOfSucceededThings 的值,但不能同时设置这两者。

numberOfNotifiedThings

java 类:java.lang.Double

启动推出速率提高的被通知事物的数量阈值。

numberOfSucceededThings

java 类:java.lang.Double

启动推出速率提高的成功事物的数量阈值。

abortConfig

AbortConfig

允许您创建中止作业的条件。

criteriaList

AbortCriteria

定义中止作业的规则的中止条件列表。

action

java 类:java.lang.String (CANCEL)

启动作业中止的中止操作的类型。

failureType

java 类:java.lang.String (FAILED | REJECTED | TIMED_OUT | ALL)

定义启动作业中止的规则的作业执行失败的类型。

minNumberOfExecutedThings

java 类:java.lang.Integer)

评估中止规则之前已执行事物的最小数量。

thresholdPercentage

java 类:java.lang.Double)

以启动作业中止的执行事物总数的百分比形式表示的阈值。

AWS IoT 最多支持小数点后两位(例如,支持 10.9 和 10.99,但不支持 10.999)。

timeoutConfig

TimeoutConfig

指定每个设备完成其作业执行所具有的时间。计时器在作业执行状态设置为 IN_PROGRESS 时启动。如果作业执行状态未在时间到期之前设置为其他最终状态,它会设置为 TIMED_OUT

注意

作业超时功能目前在 AWS GovCloud(美国)区域中不可用。

inProgressTimeoutInMinutes

long

指定此设备完成该作业执行所具有的时间,以分钟为单位。只要作业的执行状态指定为 IN_PROGRESS 并且填充了此字段,计时器将启动或重新启动。如果在计时器到期之前,或者在发送另一个填充了此字段的作业执行状态更新之前,作业执行状态未设置为最终状态,状态将设置为 TIMED_OUT

documentParameters

映射

键:ParameterKey

值:ParameterValue

作业文档的参数。

ParameterKey

string

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

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

ParameterValue

string

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

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

输出:

HTTP/1.1 200

如果此操作成功,则该服务会发送回带有空 HTTP 正文的 HTTP 200 响应。

MQTT (13)

不可用。

Jobs 设备 MQTT 和 HTTPS API

设备 MQTT 和 HTTPS 数据类型

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

JobExecution

JobExecution Data TypeSyntax (7)Description (7)
JobExecution Data Type

包含有关作业执行的数据。

Syntax (7)
{ "jobId" : "string", "thingName" : "string", "jobDocument" : "string", "status": "QUEUED|IN_PROGRESS|FAILED|SUCCEEDED|CANCELED|TIMED_OUT|REJECTED|REMOVED", "statusDetails": { "string": "string" }, "queuedAt" : "timestamp", "startedAt" : "timestamp", "lastUpdatedAt" : "timestamp", "versionNumber" : "number", "executionNumber": long }
Description (7)
jobId

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

thingName

正在执行作业的事物的名称。

jobDocument

作业文档的内容。

status

作业执行的状态。可以为以下值之一:QUEUED、IN_PROGRESS、FAILED、SUCCEEDED、CANCELED、TIMED_OUT、REJECTED 或 REMOVED。

statusDetails

描述作业执行状态的名称-值对的集合。

queuedAt

作业执行入队的时间,用从纪元开始的秒数表示。

startedAt

作业执行开始的时间,用从纪元开始的秒数表示。

lastUpdatedAt

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

versionNumber

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

executionNumber

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

JobExecutionState

JobExecutionState Data TypeSyntax (8)Description (8)
JobExecutionState Data Type

包含有关作业执行的状态的数据。

Syntax (8)
{ "status": "QUEUED|IN_PROGRESS|FAILED|SUCCEEDED|CANCELED|TIMED_OUT|REJECTED|REMOVED", "statusDetails": { "string": "string" ... } "versionNumber": "number" }
Description (8)
status

作业执行的状态。可以为以下值之一:QUEUED、IN_PROGRESS、FAILED、SUCCEEDED、CANCELED、TIMED_OUT、REJECTED 或 REMOVED。

statusDetails

描述作业执行状态的名称-值对的集合。

versionNumber

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

JobExecutionSummary

JobExecutionSummary Data TypeSyntax (9)Description (9)
JobExecutionSummary Data Type

包含有关作业执行的信息的子集。

Syntax (9)
{ "jobId": "string", "queuedAt": timestamp, "startedAt": timestamp, "lastUpdatedAt": timestamp, "versionNumber": "number", "executionNumber": long }
Description (9)
jobId

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

queuedAt

作业执行入队的时间,用从纪元开始的秒数表示。

startedAt

作业执行开始的时间,用从纪元开始的秒数表示。

lastUpdatedAt

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

versionNumber

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

executionNumber

标识设备上的作业执行的数字。

ErrorResponse

ErrorResponse Data TypeSyntax (10)Description (10)
ErrorResponse Data Type

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

Syntax (10)
{ "code": "ErrorCode", "message": "string", "clientToken": "string", "timestamp": timestamp, "executionState": JobExecutionState }
Description (10)
code

可将 ErrorCode 设置为:

InvalidTopic

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

InvalidJson

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

InvalidRequest

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

InvalidStateTransition

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

ResourceNotFound

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

VersionMismatch

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

InternalError

处理请求期间出现内部错误。

RequestThrottled

请求已被阻止。

TerminalStateReached

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

message

错误消息字符串。

clientToken

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

timestamp

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

executionState

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

设备命令

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

GetPendingJobExecutions

GetPendingJobExecutions CommandMQTT (12)HTTPS (12)CLI (12)
GetPendingJobExecutions Command

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

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/#

响应负载:

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

状态为 JobExecutionSummaryIN_PROGRESS 对象的列表。

queuedJobs

状态为 JobExecutionSummaryQUEUED 对象的列表。

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 格式:

{ "thingName": "string" }

cli-input-json 字段:

名称

类型

描述

thingName

string

最大长度: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

list

成员:JobExecutionSummary

java 类:java.util.List

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

JobExecutionSummary

JobExecutionSummary

jobId

string

最大长度: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

list

成员:JobExecutionSummary

java 类:java.util.List

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

JobExecutionSummary

JobExecutionSummary

jobId

string

最大长度: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 CommandMQTT (13)HTTPS (13)CLI (13)
StartNextPendingJobExecution Command

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

  • 首先返回状态为 IN_PROGRESS 的所有作业执行。

  • 按作业执行的创建顺序返回这些执行。

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

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

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

  • (可选)您可以通过为 stepTimeoutInMinutes 属性设置值创建步骤计时器。如果您没有通过运行 UpdateJobExecution 更新此属性的值,作业执行将在步骤计时器到期时超时。

MQTT (13)

要调用此 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。设置此超时不会影响在创建作业时(CreateJob,使用 timeoutConfig 字段)可能指定的作业执行超时。

clientToken

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

要接收响应,请订阅:

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

  • $aws/things/thingName/jobs/start-next/rejected

  • 代表这两者的 $aws/things/thingName/jobs/start-next/#

响应负载:

{ "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" ... }, "stepTimeoutInMinutes": long }
thingName

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

statusDetails

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

stepTimeOutInMinutes

指定此设备完成该作业执行所具有的时间。如果作业执行状态未在此计时器过期或者重置计时器(通过调用 UpdateJobExecution,将状态设置为 IN_PROGRESS,并在字段 stepTimeoutInMinutes 中指定新超时值)之前设置为最终状态,则作业执行状态将设置为 TIMED_OUT。设置此超时不会影响在创建作业时(CreateJob,使用 timeoutConfig 字段)可能指定的作业执行超时。

响应:

{ "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> \ {--step-timeout-in-minutes <value>] \ [--status-details <value>] \ [--cli-input-json <value>] \ [--generate-cli-skeleton]

cli-input-json 格式:

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

cli-input-json 字段:

名称

类型

描述

thingName

string

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

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

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

statusDetails

映射

键:DetailsKey

值:DetailsValue

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

stepTimeOutInMinutes

long

指定此设备完成该作业执行所具有的时间。如果作业执行状态未在此计时器过期或者重置计时器(通过调用 UpdateJobExecution,将状态设置为 IN_PROGRESS,并在字段 stepTimeoutInMinutes 中指定新超时值)之前设置为最终状态,则作业执行状态将设置为 TIMED_OUT。设置此超时不会影响在创建作业时(CreateJob,使用 timeoutConfig 字段)可能指定的作业执行超时。

DetailsKey

string

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

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

DetailsValue

string

最大长度: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

string

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

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

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

thingName

string

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

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

正在执行作业的事物的名称。

status

string

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

作业执行的状态。可以为以下值之一:QUEUED、IN_PROGRESS、FAILED、SUCCEEDED、CANCELED、TIMED_OUT、REJECTED 或 REMOVED。

statusDetails

映射

键:DetailsKey

值:DetailsValue

描述作业执行状态的名称-值对的集合。

DetailsKey

string

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

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

DetailsValue

string

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

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

queuedAt

long

作业执行入队的时间,用从纪元开始的秒数表示。

startedAt

long

java 类:java.lang.Long

作业执行开始的时间,用从纪元开始的秒数表示。

lastUpdatedAt

long

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

versionNumber

long

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

executionNumber

long

java 类:java.lang.Long

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

jobDocument

string

最大长度:32768

作业文档的内容。

DescribeJobExecution

DescribeJobExecution CommandMQTT (14)HTTPS (14)CLI (14)
DescribeJobExecution Command

获取有关作业执行的详细信息。

您可以将 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

可选。除非设置为 false,否则响应将包含作业文档。默认为 true

clientToken

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

要接收响应,请订阅:

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

  • $aws/things/thingName/jobs/jobId/get/rejected

  • 代表这两者的 $aws/things/thingName/jobs/jobId/get/#

响应负载:

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

可选。除非设置为 false,否则响应将包含作业文档。默认为 true

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 格式:

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

cli-input-json 字段:

名称

类型

描述

jobId

string

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

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

thingName

string

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

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

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

includeJobDocument

boolean

java 类:java.lang.Boolean

可选。除非设置为 false,否则响应包含作业文档。默认值为 true。

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

string

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

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

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

thingName

string

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

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

正在执行作业的事物的名称。

status

string

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

作业执行的状态。可以为以下值之一:QUEUED、IN_PROGRESS、FAILED、SUCCEEDED、CANCELED、TIMED_OUT、REJECTED 或 REMOVED。

statusDetails

映射

键:DetailsKey

值:DetailsValue

描述作业执行状态的名称-值对的集合。

DetailsKey

string

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

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

DetailsValue

string

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

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

queuedAt

long

作业执行入队的时间,用从纪元开始的秒数表示。

startedAt

long

java 类:java.lang.Long

作业执行开始的时间,用从纪元开始的秒数表示。

lastUpdatedAt

long

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

versionNumber

long

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

executionNumber

long

java 类:java.lang.Long

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

jobDocument

string

最大长度:32768

作业文档的内容。

UpdateJobExecution

UpdateJobExecution CommandMQTT (15)HTTPS (15)CLI (15)
UpdateJobExecution Command

更新作业执行的状态。(可选)您可以通过为 stepTimeoutInMinutes 属性设置值创建步骤计时器。如果您没有通过再次运行 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, "stepTimeoutInMinutes": long, "clientToken": "string" }
status

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

statusDetails

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

expectedVersion

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

executionNumber

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

includeJobExecutionState

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

includeJobDocument

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

stepTimeoutInMinutes

指定此设备完成该作业执行所具有的时间。如果作业执行状态未在此计时器过期或者重置计时器(通过再次调用 UpdateJobExecution,将状态设置为 IN_PROGRESS,并在此字段中指定新超时值)之前设置为最终状态,则作业执行状态将设置为 TIMED_OUT。设置或重置此超时不会影响在创建作业时(使用 CreateJobtimeoutConfig)可能指定的作业执行超时。

clientToken

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

要接收响应,请订阅:

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

  • $aws/things/thingName/jobs/jobId/update/rejected

  • 代表这两者的 $aws/things/thingName/jobs/jobId/update/#

响应负载:

{ "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, "stepTimeoutInMinutes": long, "executionNumber": long }
thingName

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

jobId

创建此作业时向其分配的唯一标识符。

status

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

statusDetails

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

expectedVersion

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

includeJobExecutionState

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

includeJobDocument

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

stepTimeoutInMinutes

指定此设备完成该作业执行所具有的时间。如果作业执行状态未在此计时器过期或者重置计时器(通过再次调用 UpdateJobExecution,将状态设置为 IN_PROGRESS,并在此字段中指定新超时值)之前设置为最终状态,则作业执行状态将设置为 TIMED_OUT。设置或重置此超时不会影响在创建作业时(使用 CreateJobtimeoutConfig)可能指定的作业执行超时。

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>] \ [--step-timeout-in-minutes <value>] \ [--generate-cli-skeleton]

cli-input-json 格式:

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

cli-input-json 字段:

名称

类型

描述

jobId

string

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

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

创建此作业时向其分配的唯一标识符。

thingName

string

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

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

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

status

string

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

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

statusDetails

映射

键:DetailsKey

值:DetailsValue

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

DetailsKey

string

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

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

DetailsValue

string

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

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

stepTimeoutInMinutes

long

指定此设备完成该作业执行所具有的时间。如果作业执行状态未在此计时器过期或者重置计时器(通过再次调用 UpdateJobExecution,将状态设置为 IN_PROGRESS,并在此字段中指定新超时值)之前设置为最终状态,则作业执行状态将设置为 TIMED_OUT。设置或重置此超时不会影响在创建作业时(使用 CreateJobtimeoutConfig)可能指定的作业执行超时。

expectedVersion

long

java 类:java.lang.Long

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

includeJobExecutionState

boolean

java 类:java.lang.Boolean

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

includeJobDocument

boolean

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

string

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

作业执行的状态。可以为以下值之一:QUEUED、IN_PROGRESS、FAILED、SUCCEEDED、CANCELED、TIMED_OUT、REJECTED 或 REMOVED。

statusDetails

映射

键:DetailsKey

值:DetailsValue

描述作业执行状态的名称-值对的集合。

DetailsKey

string

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

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

DetailsValue

string

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

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

versionNumber

long

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

jobDocument

string

最大长度:32768

作业文档的内容。

JobExecutionsChanged

JobExecutionsChanged MessageMQTT (16)HTTPS (16)CLI (16)
JobExecutionsChanged Message

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

MQTT (16)

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

消息负载:

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

不可用。

CLI (16)

不可用。

NextJobExecutionChanged

NextJobExecutionChanged MessageMQTT (17)HTTPS (17)CLI (17)
NextJobExecutionChanged Message

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

MQTT (17)

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

消息负载:

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

不可用。

CLI (17)

不可用。