本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# AWS IoT 职位
使用 AWS IoT Jobs 定义一组远程操作，这些操作可以发送到一个或多个连接到的设备并在这些设备上运行 AWS IoT。例如，您可以定义一个任务，该任务指示一组设备下载并安装应用程序或固件更新、重启、轮换证书或执行远程故障排除操作。
## 访问 AWS IoT 作业
您可以使用控制台或 AWS IoT Core API 开始使用 AWS IoT Jobs。
**使用控制台**
登录 AWS 管理控制台，然后转到 AWS IoT 控制台。在导航窗格中，选择 **Manage**（管理），然后选择 **Jobs**（任务）。您可以从此部分创建和管理任务。如果要创建和管理任务模板，请在导航窗格中，选择 **Job templates**（任务模板）。有关更多信息，请参阅 [使用创建和管理作业 AWS 管理控制台](manage-job-console.md)。
**使用 API 或 CLI**
您可以使用 AWS IoT Core API 操作开始使用。有关更多信息，请参阅 [AWS IoT API 参考](https://docs.aws.amazon.com/iot/latest/apireference/)。 AWS SDK 支持构建 AWS IoT 作业所依据的 AWS IoT Core API。有关更多信息，请参阅[AWS SDKs 和工具包](https://aws.amazon.com/getting-started/tools-sdks/)。
您可以使用运行命令 AWS CLI 来创建和管理作业和作业模板。有关更多信息，请参阅 [AWS IoT CLI 参考](https://docs.aws.amazon.com/cli/latest/reference/iot/index.html)。
## AWS IoT 作业、区域和终端节点
AWS IoT Jobs 支持特定于您的控制平面和数据平面 API 端点 AWS 区域。数据平面 API 端点特定于您的 AWS 账户 和 AWS 区域。有关 AWS IoT 任务端点的更多信息，请参阅《*AWS 一般参考*》中的 [AWS IoT Device Management -作业数据端点](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html#iot_device_management_region_jobs)。
# 什么是远程操作？
**注意**
Over-the-air (OTA) 更新不适用于以下区域：
欧洲（西班牙）
亚太地区（马来西亚）
远程操作是指您可以在物理设备、虚拟设备或端点上执行的任何更新或操作，无需操作人员或技术人员亲自到场即可远程完成。远程操作是使用 over-the-air（OTA）更新执行的，因此您的设备不必实际存在。在中管理您的设备群 AWS 云 允许您在注册设备后对设备执行远程操作 AWS IoT Core。
AWS IoT Device Management Jobs 提供了一种可扩展的方法，用于在注册的设备上执行远程操作 AWS IoT Core。在中创建任务 AWS 云 并通过 MQTT 或 HTTP 协议通过 OTA 更新推送到所有目标设备。
AWS IoT Device Management 作业使您能够以安全、可扩展且更具成本效益的方式执行远程操作，例如恢复出厂设置、设备重启和软件 OTA 更新。
有关的更多信息 AWS IoT Core，请参阅[什么是 AWS IoT？](what-is-aws-iot.md)。
有关 AWS IoT Device Management Jobs 的更多信息，请参阅[什么是 AWS IoT 乔布斯？](jobs-what-is.md)。
## 使用 AWS IoT Device Management Jobs 进行远程操作的好处
使用 AWS IoT Device Management Jobs 执行远程操作可以简化设备群的管理。以下列表重点介绍了使用 AWS IoT Device Management Jobs 执行远程操作的一些主要好处：
+ **与其他 AWS 服务无缝集成**
+ AWS IoT Device Management Jobs 与以下增值 AWS 服务 和功能紧密结合：
+ **Amazon S3**：将您的远程操作说明存储在安全的 Amazon S3 存储桶中，您可以在该存储桶中控制这些内容的访问权限。使用 Amazon S3 存储桶提供了一种可扩展且耐用的存储解决方案，该解决方案与 AWS IoT 设备管理软件包目录本机集成，允许 AWS IoT Device Management 任务在更新说明中参考和替换。有关更多信息，请参阅[什么是 Amazon S3？](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html)。
+ **Amazon CloudWatch**：监控和记录每台设备任务执行的远程操作实施状态以及其他设备活动，以跟踪和分析任务中的 AWS IoT Device Management 整体作业绩效。有关更多信息，请参阅[什么是亚马逊 CloudWatch？](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html) 监控任务日志并捕获历史数据以进行问题排除。如何与任务配合使用。
+ **AWS IoT 设备影子服务**: 使用 AWS IoT Device Management Jobs 通过设备影子维护 AWS IoT 事物的数字化呈现，这样无论设备连接如何，应用程序和其他服务都可以访问设备的状态。有关更多信息，请参阅 [AWS IoT 设备影子服务](https://docs.aws.amazon.com/iot/latest/developerguide/iot-device-shadows.html)。
+ **安全最佳实践**
+ **权限控制**：使用 Amazon S3 控制对远程操作说明的访问权限，并确定哪些 IAM 用户可以使用 AWS IoT 策略和 IAM 用户角色将您的远程操作说明部署到您的设备群中。
+ 有关 AWS IoT 策略的更多信息，请参阅[创建 AWS IoT 策略](create-iot-resources.md#create-iot-policy)。
+ 有关 IAM 用户角色的更多信息，请参阅[的身份和访问管理 AWS IoT](security-iam.md)。
+ **可扩展性**
+ **目标任务部署**：使用创建任务时在任务文档中输入的特定设备分组条件，控制哪些设备通过目标任务部署从任务接收任务文档。通过为每台设备创建 AWS IoT 事物并将该信息存储在 AWS IoT 注册表中，您可以使用舰队索引进行有针对性的搜索。您可以根据实例集索引搜索结果创建自定义群组，来支持您的目标任务部署。有关更多信息，请参阅 [使用管理设备 AWS IoT](iot-thing-management.md)。使用任务来拍摄快照而不是连续任务。
+ **任务状态**：除了每台设备上任务文档的单独实施状态外，还将跟踪部署到设备实例集的任务文档的状态，以及设备实例集级别的整体任务状态。有关更多信息，请参阅 [任务和任务执行状态](iot-jobs-lifecycle.md)。
+ **新设备可扩展性**：通过连续任务将任务文档添加到使用实例集索引创建的现有自定义群组中，便可轻松将其部署到新设备。这将为您节省时间，让您不必将任务文档单独部署到每台新设备上。或者，您可以使用更具针对性的方法来拍摄快照，方法是一次性将任务文档部署到预先确定的一组设备上，然后任务就完成了。
+ **弹性**
+ **任务配置**：使用可选的任务配置（部署、调度、中止、超时和重试）来自定义您的任务和任务文档，以满足您的特定需求。有关更多信息，请参阅 [任务 配置](jobs-configurations.md)。
+ **经济高效**
+ 利用 AWS IoT Device Management Jobs 部署关键更新和执行例行维护任务，引入更有效的维护设备群的成本结构。维护设备群的 do-it-yourself（DIY）解决方案包括经常性的、可变的成本，例如托管和管理 DIY 解决方案所需的基础架构、开发、维护和扩展 DIY 解决方案的人力成本以及数据传输成本。利用 AWS IoT Device Management 任务的透明固定成本结构，除了便于向设备群发布任务文档和跟踪每台设备的任务执行状态所需的数据传输成本外，您还可以确切地知道设备每次执行任务的成本。有关更多信息，请参阅[AWS IoT Core 定价](https://docs.aws.amazon.com/iot/latest/developerguide/iot-price.html)。
# 什么是 AWS IoT 乔布斯？
使用 AWS IoT Jobs 定义一组远程操作，这些操作可以发送到一个或多个连接到的设备并在这些设备上运行 AWS IoT。
要创建任务，首先定义*任务文档*，其中包含描述设备必须远程执行的操作的说明列表。要执行这些操作，请指定*目标*列表，这些都是单独事物、[事物组](thing-groups.md)，或同时选择两者。任务文件和目标共同构成了*部署*。
每个部署都可以有额外的配置：
+ **Rollout**（推出）：此配置定义了每分钟有多少设备接收任务文档。
+ **中止**：如果一定数量的设备没有收到任务通知，则可使用此配置取消任务。这样可以避免向整个实例集发送错误的更新。
+ **Timeout**（超时）：如果在一定时间内没有从您的工作目标收到响应，任务可能会失败。您可以跟踪在这些设备上运行的任务。
+ **重试**：如果设备报告故障或作业超时，您可以使用任务 AWS IoT 自动将任务文档重新发送到设备。
+ **Scheduling**（计划）：此配置使您能够为未来的日期和时间安排任务。它还允许您创建定期维护时段，以便在预定义的低流量时段内更新设备。
AWS IoT 作业会发送一条消息，通知目标有任务可用。目标通过下载任务文档、*执行*其指定的操作并将其进度报告给来开始执行任务 AWS IoT。您可以通过运行作业提供的命令来跟踪特定目标或所有目标的 AWS IoT 任务进度。任务开始时，状态为*正在进行中*。然后，设备在显示此状态的同时报告增量更新，直到任务成功、失败或超时。
以下主题描述任务的一些关键概念以及任务和任务执行的生命周期。
**Topics**
+ [任务关键概念](key-concepts-jobs.md)
+ [任务和任务执行状态](iot-jobs-lifecycle.md)
# 任务关键概念
以下概念提供了有关 AWS IoT 作业以及如何创建和部署作业以在设备上运行远程操作的详细信息。
## 基本概念
以下是您在使用 AWS IoT Jobs 时必须了解的基本概念。
**任务**
任务是被发送到一台或多台连接到 AWS IoT的设备并在这些设备上运行的远程操作。例如，您可以定义一个任务，该任务指示一组设备下载并安装应用程序或运行固件更新、重启、轮换证书或执行远程故障排除操作。
**任务文档**
要创建任务，您必须先创建一个任务文档，该文档是要由设备执行的远程操作的描述。
任务文档是 UTF-8 编码的 JSON 文档，其中包含您的设备执行任务所需的信息。任务文档包含一个或多个文件，设备可以在 URLs 其中下载更新或其他数据。任务文档可存储在 Amazon S3 存储桶中，或者随用于创建任务的命令内联包含。
在 MQTT 响应中，`jobDocument` 字段是一个 JSON 对象。在 HTTP 响应中，它是 JSON 对象的字符串表示形式。
** 目标**
在创建任务时，您需要指定一系列目标，它们是应执行操作的设备。目标可以是事物和/或[事物组](thing-groups.md)。 AWS IoT 作业服务向每个目标发送一条消息，告知其有任务可用。
**部署**
通过提供任务文档并指定目标列表创建任务之后，系统会将任务文档部署到要为其执行更新的远程目标设备上。对于快照任务，任务会在部署到目标设备后完成。对于持续任务，任务会在设备添加到组时部署到该组设备。
**任务执行**
任务执行是目标设备上的任务的实例。目标通过下载任务文档来开始执行任务。然后，它执行文档中指定的操作，并将其进度报告给 AWS IoT。执行编号是特定目标上的任务执行的唯一标识符。 AWS IoT 作业服务提供命令来跟踪目标上作业的执行进度以及所有目标上的作业进度。
## 任务类型概念
以下概念可以帮助您更多地了解可以使用 Jobs 创建的不同类型的 AWS IoT 作业。
**快照任务**
默认情况下，任务将发送到您在创建该任务时指定的所有目标。在这些目标完成任务（或报告它们无法执行此操作）后，任务即完成。
**持续任务**
持续的任务将发送到您在创建该任务时指定的所有目标。它继续运行并发送到添加到目标组的任何新设备（事物）。例如，在将设备添加到组时，可使用持续任务加入或升级设备。您可以通过在创建任务时设置可选参数，来使任务成为持续任务。
当使用动态事物组确定目标物联网实例集时，我们建议您使用连续任务而不是快照任务。通过使用连续任务，加入组的设备即使在任务创建之后也会收到任务执行。
## 预签名 URLs
为了安全、有时间限制地访问未包含在任务文档中的数据，您可以使用预签名的 Amazon S3。 URLs将数据放置在 Amazon S3 存储桶中，并添加一个指向任务文档中的数据的占位符链接。当 AWS IoT Jobs 收到任务文档请求时，它会通过查找占位符链接来解析任务文档，然后用预签名的 Amazon S3 替换这些链接。 URLs
占位符链接采用以下格式：
```
${aws:iot:s3-presigned-url:https://s3.amazonaws.com/bucket/key}
```
其中*bucket*，是您的存储桶名称，*key*是您要关联的存储桶中的对象。
在北京和宁夏区域，只有资源所有者拥有 ICP（互联网内容提供商）许可证，预签名才 URLs 有效。有关更多信息，请参阅《*中国[服务入门》文档中的 Amazon 简单存储](https://docs.amazonaws.cn/en_us/aws/latest/userguide/s3.html) AWS 服务*。
## 任务配置概念
以下概念可以帮助您了解如何配置任务。
** 推出**
您可以指定向目标发送待处理任务执行通知的速度。这样，您就可以创建一个分段推出以更好地管理更新、重启和其它操作。您可以使用静态推出率或指数级推出率来创建部署配置。您可以使用静态推出速率来指定每分钟可通知的最大任务目标数。
有关设置推出速率的示例，以及有关配置任务推出的更多信息，请参阅 [任务推出、计划和中止配置](jobs-configurations-details.md#job-rollout-abort-scheduling)。
** 计划**
通过任务计划，您可以计划向目标组中的所有设备推出连续任务和快照任务的任务文档的时间。此外，您可以创建一个可选的维护时段，其中包含任务向目标组中的所有设备推出任务文档的特定日期和时间。维护时段是一种周期性实例，其频率为每天、每周、每月或在初始任务或任务模板创建期间选择的自定义日期和时间。只能将连续任务安排为在维护时段内执行推出。
任务计划是特定于您的任务的。无法安排单个任务执行。有关更多信息，请参阅 [任务推出、计划和中止配置](jobs-configurations-details.md#job-rollout-abort-scheduling)。
** 中止**
您可以创建一组条件在满足您指定的特定条件时中止推出。有关更多信息，请参阅 [任务推出、计划和中止配置](jobs-configurations-details.md#job-rollout-abort-scheduling)。
** 超时**
只要任务部署卡在 `IN_PROGRESS` 状态的时间超出预期，您就会收到任务超时通知。有两种类型的计时器：进行中计时器和步骤计时器。当任务为 `IN_PROGRESS` 时，您可以监控和跟踪任务部署的进度。
推出和中止配置特定于您的任务，而超时配置特定于任务部署。有关更多信息，请参阅 [任务执行超时和重试配置](jobs-configurations-details.md#job-timeout-retry)。
** 重试**
通过任务重试，可以在任务失败和/或超时时重试任务执行。您最多可以重试 10 次任务执行。您可以监控和跟踪重试的进度以及任务执行是否成功。
推出和中止配置特定于您的任务，而超时和重试配置特定于任务执行。有关更多信息，请参阅 [任务执行超时和重试配置](jobs-configurations-details.md#job-timeout-retry)。
# 任务和任务执行状态
以下各节描述了 AWS IoT 任务的生命周期和任务执行的生命周期。
## 任务状态
下图显示了 AWS IoT 作业的不同状态。
![\[该图显示了 AWS IoT 作业的不同状态。\]](http://docs.aws.amazon.com/zh_cn/iot/latest/developerguide/images/job-states-diagram.png)
您使用 J AWS IoT obs 创建的任务可能处于以下状态之一：
+
**SCHEDULED**
在使用 AWS IoT 控制台、[CreateJob](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html)API 或 API 创建初始任务或[CreateJobTemplate](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html)任务模板期间，您可以在 AWS IoT 控制台或 [CreateJob](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html)API 或 [CreateJobTemplate](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html)API 中选择可选`SchedulingConfig`的计划配置。当您启动包含特定 `startTime`、`endTime` 和 `endBehavior` 的计划任务时，任务状态将更新为 `SCHEDULED`。当任务达到您选择的 `startTime` 或下一个维护时段的 `startTime` 时（如果您在维护时段中选择了任务推出），状态将从 `SCHEDULED` 更新为 `IN_PROGRESS`，并开始将任务文档推出到目标组中的所有设备。
+
**进行中**
当您使用 AWS IoT 控制台或 [CreateJob](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html)API 创建任务时，任务状态会更新为`IN_PROGRESS`。在任务创建期间， AWS IoT Jobs 开始向目标组中的设备推出任务执行。在所有任务执行都推出后， AWS IoT Jobs 就会等待设备完成远程操作。
有关适用于进行中任务的并发和限制的信息，请参阅 [AWS IoT 职位限制](job-limits.md)。
**注意**
当 `IN_PROGRESS` 任务达到当前维护时段结束时，任务文档的推出将停止。该任务将更新为 `SCHEDULED`，直至下一个维护时段的 `startTime`。
+
**COMPLETED**
连续任务通过以下方式之一进行处理：
+ 对于*未*选择可选计划配置的连续任务，此任务始终处于进行中，并继续针对添加到目标组的任何新设备运行。它从不会达到 `COMPLETED` 状态。
+ 对于*选择*了可选计划配置的连续任务，以下表述是正确的：
+ 如果*提供了* `endTime`，则连续任务将在 `endTime` 已过且所有任务执行都达到最终状态时达到 `COMPLETED` 状态。
+ 如果在可选计划配置中*未提供* `endTime`，则连续任务将继续执行任务文档推出。
对于快照任务，当其所有任务执行都进入最终状态（如 `SUCCEEDED`、`FAILED`、`TIMED_OUT`、`REMOVED` 或 `CANCELED`）时，任务状态更改为 `COMPLETED`。
+
**CANCELED**
当您使用 AWS IoT 控制台、[CancelJob](https://docs.aws.amazon.com/iot/latest/apireference/API_CancelJob.html)API 或取消任务时[ 任务中止配置](jobs-configurations-details.md#job-abort-using)，任务状态将更改为`CANCELED`。在任务取消期间， AWS IoT 作业开始取消先前创建的任务执行。
有关适用于正在取消的任务的并发和限制的信息，请参阅 [AWS IoT 职位限制](job-limits.md)。
+
**DELETION\$1IN\$1PROGRESS**
当您使用 AWS IoT 控制台或 [DeleteJob](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJob.html)API 删除任务时，任务状态会更改为`DELETION_IN_PROGRESS`。在删除任务期间， AWS IoT 作业开始删除先前创建的任务执行。删除所有任务执行后，该任务将从您的 AWS 账户中消失。
## 任务执行状态
下表显示了 AWS IoT 任务执行的不同状态，以及状态更改是由设备启动的，还是由 AWS IoT 任务启动的。
**任务执行状态和源**
| 任务执行状态 | 由设备发起？ | 由 AWS IoT 乔布斯发起？ | 终端状态？ | 是否可以重试？ |
| --- | --- | --- | --- | --- |
| QUEUED | 否 | 是 | 否 | 不适用 |
| IN\$1PROGRESS | 是 | 否 | 否 | 不适用 |
| SUCCEEDED | 是 | 否 | 是 | 不适用 |
| FAILED | 是 | 否 | 是 | 是 |
| TIMED\$1OUT | 否 | 是 | 是 | 是 |
| REJECTED | 是 | 否 | 是 | 否 |
| REMOVED | 否 | 是 | 是 | 否 |
| CANCELED | 否 | 是 | 是 | 否 |
以下部分详细介绍了使用 AWS IoT 作业创建任务时推出的任务执行状态。
+
**QUEUED**
当 AWS IoT Jobs 为目标设备推出任务执行时，任务执行状态将设置为`QUEUED`。任务执行保留为 `QUEUED` 状态，直到：
+ 您的设备收到任务执行，调用任务 API 操作并将状态报告为 `IN_PROGRESS`。
+ 您取消任务或任务执行，或者当满足您指定的中止条件时，状态更改为 `CANCELED`。
+ 您的设备已从目标组中移除且状态更改为 `REMOVED`。
![\[此图像显示排队的任务执行如何将状态更改为 IN_PROGRESS 以及在设备不接受任务创建请求时如何拒绝任务。\]](http://docs.aws.amazon.com/zh_cn/iot/latest/developerguide/images/JE-queued-inprogress.png)
+
**进行中**
如果您的 IoT 设备订阅了预留[任务主题](reserved-topics.md#reserved-topics-job)`$notify`和`$notify-next`，并且您的设备调用了 `StartNextPendingJobExecution` API 或 API，状态为`IN_PROGRESS`，则 AWS IoT Jobs 会将任务执行状态设置为。`UpdateJobExecution` `IN_PROGRESS`
`UpdateJobExecution` API 可以多次调用，状态为 `IN_PROGRESS`。您可以使用 `statusDetails` 对象指定有关执行步骤的其他详细信息。
**注意**
如果您为每台设备创建多个任务，则 AWS IoT Jobs 和 MQTT 协议无法保证交付顺序。
+
**SUCCEEDED**
当您的设备成功完成远程操作时，设备必须调用状态为的 `UpdateJobExecution` API，`SUCCEEDED`以表示任务执行成功。 AWS IoT 然后，作业会更新任务执行状态并将其返回为`SUCCEEDED`。
![\[此图像显示正在进行的任务执行如何失败以及如何重试执行。\]](http://docs.aws.amazon.com/zh_cn/iot/latest/developerguide/images/JE-success-path.png)
+
**FAILED**
当您的设备无法完成远程操作时，设备必须调用状态为`UpdateJobExecution`的 API，`Failed`以表明任务执行失败。 AWS IoT 然后，作业会更新任务执行状态并将其返回为`Failed`。您可以使用[Job 执行重试配置](jobs-configurations-details.md#job-retry-configuration)重试设备的这一任务执行。
![\[此图像显示正在进行的任务执行如何失败以及如何重试执行。\]](http://docs.aws.amazon.com/zh_cn/iot/latest/developerguide/images/JE-inprogress-failed.png)
+
**超时**
当您的设备在状态为时未能完成任务步骤`IN_PROGRESS`，或者在正在进行的计时器的超时时间内未能完成远程操作时，J AWS IoT obs 会将任务执行状态设置为`TIMED_OUT`。您还有一个用于正在进行的任务的每个任务步骤的步骤计时器，并且仅适用于任务执行。正在进行的计时器持续时间是使用 [任务执行超时配置](jobs-configurations-details.md#job-timeout-configuration) 的 `inProgressTimeoutInMinutes` 属性指定的。您可以使用[Job 执行重试配置](jobs-configurations-details.md#job-retry-configuration)重试设备的这一任务执行。
![\[此图像显示正在进行的任务执行如何超时以及如何重试执行。\]](http://docs.aws.amazon.com/zh_cn/iot/latest/developerguide/images/JE-inprogress-timedout.png)
+
**REJECTED**
当您的设备收到无效或不兼容的请求时，设备必须调用状态为`UpdateJobExecution`的 API `REJECTED`。 AWS IoT 然后，作业会更新任务执行状态并将其返回为`REJECTED`。
+
**REMOVED**
当设备不再是任务执行的有效目标时，例如当它脱离动态事物组时， AWS IoT Jobs 将任务执行状态设置为 `REMOVED`。您可以将事物重新附加到目标组，然后重新启动设备的任务执行。
+
**CANCELED**
当您使用控制台或或 `CancelJobExecution` API 取消任务或取消任务执行时，或者当满足使用指定的中止条件时， AWS IoT 作业会取消该任务并将任务执行状态设置[ 任务中止配置](jobs-configurations-details.md#job-abort-using)为。`CancelJob` `CANCELED`
# 管理任务
使用任务通知设备软件或固件更新。您可以使用[AWS IoT 控制台](https://console.aws.amazon.com/iot/)、[任务管理和控制 API 操作](jobs-management-control-api.md#jobs-http-api)[AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/reference/iot/index.html)、或[AWS SDKs](https://aws.amazon.com/tools/#sdk)来创建和管理作业。
## 任务的代码签名
向设备发送代码时，为了让设备检测代码是否在传输过程中被修改，建议您使用 AWS CLI对代码文件进行签名。有关说明，请参阅[使用 AWS CLI创建和管理任务](manage-job-cli.md)。
有关更多信息，请参阅[代码签名的用途 AWS IoT？](https://docs.aws.amazon.com/signer/latest/developerguide/Welcome.html) 。
## 任务文档
在创建任务之前，您必须创建任务文档。如果您使用代码签名 AWS IoT，则必须将任务文档上传到受版本控制的 Amazon S3 存储桶。有关创建 Amazon S3 存储桶并将向其上载文件的信息，请参阅 *Amazon S3 入门指南*中的 [Amazon Simple Storage Service 入门](https://docs.aws.amazon.com/AmazonS3/latest/userguide/GetStartedWithS3.html)。
**提示**
有关作业文档示例，请参阅软件 AWS IoT 开发工具包中的 [jobs-agent.js](https://www.npmjs.com/package/aws-iot-device-sdk#jobs-agentjs) 示例 JavaScript。
## 预签名 URLs
您的任务文档可以包含指向您的代码文件（或其它文件）的预签名 Amazon S3 URL。预签名 Amazon S3 URLs 仅在有限的时间内有效，并且是在设备请求任务文档时生成的。因为在您创建任务文档时尚未创建预签名 URL，所以在您的任务文档中使用占位符 URL。占位符 URL 类似如下所示：
`${aws:iot:s3-presigned-url-v2:https://s3.region.amazonaws.com//}`
其中：
+ *bucket*是包含代码文件的 Amazon S3 存储桶。
+ *code file*是代码文件的 Amazon S3 密钥。
当设备请求任务文档时， AWS IoT 会生成预签名 URL，并将占位符 URL 替换为预签名 URL。然后将您的任务文档发送到设备。
**IAM 角色，用于授予从 S3 下载文件的权限**
当您创建使用预签名 Amazon S3 的任务时 URLs，必须提供一个 IAM 角色。该角色必须授予从存储数据或更新的 Amazon S3 桶下载文件的权限。该角色还必须向 AWS IoT 授予代入角色的权限。
您可以为预签名 URL 指定可选的超时。有关更多信息，请参阅 [CreateJob](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html)。
**授予 AWS IoT Jobs 代入你的角色的权限**
1. 转到 [IAM 控制台的角色中心](https://console.aws.amazon.com/iamv2/home#/roles)，然后选择您的角色。
1. 在**信任关系**选项卡上，选择 **Edit Trust Relationship** （编辑信任关系），用以下 JSON 替换当前策略文档。选择**更新信任策略**。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": [
"iot.amazonaws.com"
]
},
"Action": "sts:AssumeRole"
}
]
}
```
1. 为防止出现混淆代理人问题，请在策略中添加全局条件键 [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourcearn](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourcearn) 和 [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceaccount](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceaccount)。
**重要**
您的 `aws:SourceArn` 必须符合此格式：`arn:aws:iot:region:account-id:*`。请确保它*region*与您的 AWS IoT 地区相*account-id*匹配并且与您的客户账户 ID 相匹配。有关更多信息，请参阅[防止跨服务混淆代理](cross-service-confused-deputy-prevention.md)。
```
{
"Effect": "Allow",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service":
"iot.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "123456789012"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:iot:*:123456789012:job/*"
}
}
}
]
}
```
1. 如果您的任务使用的任务文档是一个 Amazon S3 对象，请选择**权限**，然后使用以下 JSON。这将添加一个策略，以授予从您的 Amazon S3 桶下载文件的权限：
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::your_S3_bucket/*"
}
]
}
```
## 用于文件上传的预签名 URL
如果您的设备在任务部署期间需要将文件上传到 Amazon S3 存储桶，则可以在任务文档中包含以下预签名 URL 占位符：
```
${aws:iot:s3-presigned-url-upload:https://s3.region.amazonaws.com//}
```
在任务文档中的文件上传占位符 URL 中，您最多可以使用 `${thingName}`、`${jobId}` 和 `${executionNumber}` 中的两个作为 `key` 属性中的保留关键字。创建任务执行时，将解析并替换代表 `key` 属性中保留关键字的本地占位符。使用包含特定于每台设备的保留关键字的本地占位符，可确保从设备上传的每个文件都特定于该设备，并且不会被从同一任务部署的另一台目标设备上传的类似文件所覆盖。有关对任务部署期间用于上传文件的预签名 URL 占位符中的本地占位符进行问题排除的信息，请参阅 [一般错误消息疑难解答](software-package-catalog-troubleshooting.md#spc-general-troubleshooting)。
**注意**
Amazon S3 存储桶名称不能包含代表已上传文件的保留关键字的本地占位符。本地占位符必须位于 `key` 属性中。
当设备收到预签名 URL 占位符时，该预签名 URL 占位符将在您的任务文档中转换为 Amazon S3 预签名上传 URL。您的设备将使用该 URL 将文件上传到目标 Amazon S3 存储桶。
**注意**
如果上述占位符 URL 中未提供 Amazon S3 存储桶和密钥，则 AWS IoT Jobs 将最多使用 `${thingName}`、`${jobId}` 和 `${executionNumber}` 中的两个自动为每台设备生成一个密钥。
## 使用 Amazon S3 版本控制的预签名 URL
保护存储在 Amazon S3 存储桶中的文件的完整性，对于确保使用该文件将任务安全部署到您的设备实例集至关重要。使用 Amazon S3 版本控制，您可以为存储在 Amazon S3 存储桶中的文件的每个变体添加版本标识符，以便跟踪文件的每个版本。这可以让您深入了解使用 AWS IoT 任务将哪个版本的文件部署到您的设备群中。有关使用版本控制的 Amazon S3 存储桶的更多信息，请参阅[在 Amazon S3 存储桶中使用版本控制](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html)。
如果文件存储在 Amazon S3 中，并且任务文档包含预签名 URL 占位符，则 AWS IoT 任务将使用 Amazon S3 存储桶、存储桶密钥和存储在 Amazon S3 存储桶中的文件版本在任务文档中生成预签名 URL。在任务文档中生成的这个预签名 URL 将取代任务文档中最初的预签名 URL 占位符。如果您更新存储在 Amazon S3 存储桶中的文件，则将创建该文件的新版本及后续 `versionId`，以表明所做的更新，并支持在未来的任务部署中定位到该特定文件。
请参阅以下示例，了解使用任务文档中预先签名的 Amazon S3 的查看之前和之 URLs `versionId`中：
**Amazon S3 预签名 URL 占位符（在任务部署之前）**
```
//Virtual-hosted style URL
${aws:iot:s3-presigned-url-v2:https://bucket-name.s3.region-code.amazonaws.com/key-name%3FversionId%3Dversion-id}
//Path-style URL
${aws:iot:s3-presigned-url-v2:https://s3.region-code.amazonaws.com/bucket-name/key-name%3FversionId%3Dversion-id}
```
**Amazon S3 预签名 URL（在任务部署期间）**
```
//Virtual-hosted style URL
${aws:iot:s3-presigned-url-v2:https://sample-bucket-name.s3.us-west-2.amazonaws.com/sample-code-file.png%3FversionId%3Dversion1}
//Path-style
${aws:iot:s3-presigned-url-v2:https://s3.us-west-2.amazonaws.com/sample-bucket-name/sample-code-file.png%3FversionId%3Dversion1}
```
[有关 Amazon S3 虚拟托管和路径式对象的更多信息 URLs，请参阅[Virtual-hosted-style 请求和路径式请求](https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.html#virtual-hosted-style-access)。](https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.html#path-style-access)
**注意**
如果要将 `versionId` 附加到 Amazon S3 预签名 URL，则它必须符合支持 AWS SDK for Java 2.x的 URL 编码。有关更多信息，请参阅[解析 Amazon S3 URIs 从版本 1 到版本 2 的更改](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration-s3-uri-parser.html#migration-3-uri-parser-api-changes)。
**Amazon S3 预签名 URL 占位符版本差异**
以下列表概述了 Amazon S3 预签名 URL 占位符 `${aws:iot:s3-presigned-url-v1`（版本 1）和 `${aws:iot:s3-presigned-url-v2`（版本 2）之间的差异：
+ Amazon S3 预签名 URL 占位符 `${aws:iot:s3-presigned-url-v1` 不支持 `version-id`。
+ Amazon S3 预签名 URL 占位符 `${aws:iot:s3-presigned-url-v1` 接收未编码的 Amazon S3 URL。Amazon S3 预签名 URL 占位符 `${aws:iot:s3-presigned-url-v2` 要求 Amazon S3 URL 经过编码以符合 Amazon S3 SDK 标准。
**Topics**
+ [任务的代码签名](#create-manage-jobs-code-signing)
+ [任务文档](#create-manage-jobs-job-doc)
+ [预签名 URLs](#create-manage-jobs-presigned-URLs)
+ [用于文件上传的预签名 URL](#create-manage-jobs-presigned-URLs-upload)
+ [使用 Amazon S3 版本控制的预签名 URL](#create-manage-jobs-presigned-URLs-versioning)
+ [使用创建和管理作业 AWS 管理控制台](manage-job-console.md)
+ [使用创建和管理作业 AWS CLI](manage-job-cli.md)
# 使用创建和管理作业 AWS 管理控制台
本节介绍如何通过 AWS IoT 控制台创建和管理作业。创建任务后，您可以在详细信息页面上查看任务的相关信息，并管理任务。
**注意**
如果要对 AWS IoT 作业执行代码签名，请使用 AWS CLI。有关更多信息，请参阅[使用 AWS CLI创建和管理任务](manage-job-cli.md)。
**Topics**
+ [使用创建管理作业 AWS 管理控制台](#create-job-console)
+ [使用查看和管理作业 AWS 管理控制台](#view-manage-job-console)
## 使用创建管理作业 AWS 管理控制台
要创建作业，请登录 AWS IoT 控制台，然后转到 “**远程操作**” 部分的 “[作业” 中心](https://console.aws.amazon.com/iot/home#/jobhub)。然后，执行下列步骤。
1. 在**任务**对话框的**任务**页面上，选择**创建任务**。
1. 根据您使用的设备，您可以创建自定义任务、FreeRTOS OTA 更新任务或任务。 AWS IoT Greengrass 在此示例中，选择 **Create a custom job**（创建自定义任务）。选择**下一步**。
1. 在 **Job properties**（任务属性）对话框的 **Custom job properties**（自定义任务属性）页面上，为以下字段输入您的信息：
+ **Name**（名称）：输入唯一的字母数字任务名称。
+ **Description - optional**（描述 - 可选）：输入有关您的任务的可选描述。
+ **Tags - optional**（标签 - 可选）：
**注意**
我们建议您不要在职位 IDs 和描述中使用个人身份信息。
选择**下一步**。
1. 在**任务目标**对话框的**文件配置**页面上，选择要运行此任务的**事物**或**事物组**。
在 **Job document**（任务文档）对话框中，选择以下选项之一：
+ **From file**（源文件）：您之前上传到 Amazon S3 存储桶的 JSON 任务文件
+ **代码签名**
在位于 Amazon S3 URL 的任务文档中，需要 `${aws:iot:code-sign-signature:s3://region.bucket/code-file@code-file-version-id}` 作为占位符，直到使用您的**代码签名配置文件**将其替换为已签名的代码文件路径。新的签名代码文件最初将出现在 Amazon S3 源桶的 `SignedImages` 文件夹中。将创建一个包含 `Codesigned_` 前缀的新任务文档，其签名代码文件路径将替换代码签名占位符，并放入您的 Amazon S3 URL 中以创建新任务。
+ **预签名资源 URLs**
在**预签名角色**下拉列表中，选择您在[预 URLs](https://docs.aws.amazon.com/iot/latest/developerguide/create-manage-jobs.html#create-manage-jobs-presigned-URLs)签名中创建的 IAM 角色。 URLs 对于从 Amazon S3 下载对象的设备来说，使用`${aws:iot:s3-presigned-url:`对位于 Amazon S3 中的对象进行预签名是一种最佳安全实践。
如果要使用预签名作为代码签 URLs 名占位符，请使用以下示例模板：
```
${aws:iot:s3-presigned-url:${aws:iot:code-sign-signature:}
```
+ **From template**（源模板）：包含任务文档和任务配置的任务模板。作业模板可以是您创建的自定义作业模板或 AWS 托管模板。
如果您要创建任务来执行常用的远程操作（例如重启设备），则可以使用 AWS 托管模板。这些模板已经进行了预调配以供使用。有关更多信息，请参阅[创建自定义任务模板](job-templates-console.md#job-templates-console-create)和[从托管模板创建自定义任务模板](job-template-manage-console-create.md#job-template-manage-create-template)。
1. 在 **Job configuration**（任务配置）对话框的 **Job configuration**（任务配置）页面上，选择以下任务类型之一：
+ **快照任务**：快照任务在目标设备和组上完成运行后即完成。
+ **连续任务**：连续任务适用于事物组，并会在以后添加到指定目标组的任何设备上运行。
1. 在 **Additional configurations - optional**（其他配置 - 可选）对话框中，查看以下可选任务配置并做出相应的选择：
+ **推出配置**
+ **计划配置**
+ **任务执行超时配置**
+ **任务执行重试配置 - 新增**
+ **中止配置**
有关任务配置的更多信息，请参阅以下部分：
+ [任务推出、计划和中止配置](jobs-configurations-details.md#job-rollout-abort-scheduling)
+ [任务执行超时和重试配置](jobs-configurations-details.md#job-timeout-retry)
查看您的所有任务选择，然后选择 **Submit**（提交）以创建任务。
## 使用查看和管理作业 AWS 管理控制台
在您创建任务后，控制台会生成一个 JSON 签名并将其放在您的任务文档中。您可以使用 [AWS IoT 控制台](https://console.aws.amazon.com/iot/)查看状态、取消或删除任务。
如果您选择自己创建的任务，则可以找到：
+ 一般任务详细信息，例如任务名称、描述、类型、创建时间、上次更新时间以及预计开始时间。
+ 您指定的任何任务配置及其状态。
+ 任务文档。
+ 您指定的任务执行和任何可选标签。
要管理任务，请转到[控制台的任务中心](https://console.aws.amazon.com/iot/home#/jobhub)，然后选择是编辑、删除还是取消任务。
# 使用创建和管理作业 AWS CLI
本部分介绍如何创建和管理任务。
## 创建任务
要创建作 AWS IoT 业，请使用**CreateJob**命令。任务将进行排队以便在您指定的目标（事物或事物组）上执行。要创建 AWS IoT 任务，您需要一份可以包含在请求正文中或作为 Amazon S3 文档链接的任务文档。如果任务包括使用预签名 Amazon S3 下载文件 URLs，则您需要一个 IAM 角色 Amazon 资源名称 (ARN)，该角色有权下载文件并向任务服务授予代入 AWS IoT 该角色的权限。
有关使用 API 命令或输入日期和时间时语法的更多信息 AWS CLI，请参阅[时间戳](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-parameters-types.html#parameter-type-timestamp)。
### 使用任务进行代码签名
如果您使用代码签名 AWS IoT，则必须启动代码签名作业，并将输出包含在作业文档中。这将替换任务文档中的代码签名占位符，在使用您的**代码签名配置文件**将其替换为已签名的代码文件路径之前，该占位符是必需的。代码签名占位符将如下所示：
```
${aws:iot:code-sign-signature:s3://region.bucket/code-file@code-file-version-id}
```
使用[start-signing-job](https://docs.aws.amazon.com/signer/latest/developerguide/api-startsigningjob.html)命令创建代码签名作业。 `start-signing-job`返回作业 ID。要获取存储签名的 Amazon S3 位置，使用 **describe-signing-job** 命令。然后，您可以从 Amazon S3 中下载签名。有关代码签名任务的更多信息，请参阅 [AWS IoT的代码签名](https://docs.aws.amazon.com/signer/latest/developerguide/Welcome.html)。
您的任务文档必须包含代码文件的预签名 URL 占位符和使用 **start-signing-job** 命令放置在 Amazon S3 桶中的 JSON 签名输出：
```
{
"presign": "${aws:iot:s3-presigned-url:https://s3.region.amazonaws.com/bucket/image}",
}
```
### 使用任务文档创建任务
以下命令显示如何使用存储在 Amazon S3 存储桶 (*job-document.json*) 中的任务文档 (*jobBucket*) 和有权从 Amazon S3 下载文件的角色 (*S3DownloadRole*) 创建任务。
```
aws iot create-job \
--job-id 010 \
--targets arn:aws:iot:us-east-1:123456789012:thing/thingOne \
--document-source https://s3.amazonaws.com/amzn-s3-demo-bucket/job-document.json \
--timeout-config inProgressTimeoutInMinutes=100 \
--job-executions-rollout-config "{ \"exponentialRate\": { \"baseRatePerMinute\": 50, \"incrementFactor\": 2, \"rateIncreaseCriteria\": { \"numberOfNotifiedThings\": 1000, \"numberOfSucceededThings\": 1000}}, \"maximumPerMinute\": 1000}" \
--abort-config "{ \"criteriaList\": [ { \"action\": \"CANCEL\", \"failureType\": \"FAILED\", \"minNumberOfExecutedThings\": 100, \"thresholdPercentage\": 20}, { \"action\": \"CANCEL\", \"failureType\": \"TIMED_OUT\", \"minNumberOfExecutedThings\": 200, \"thresholdPercentage\": 50}]}" \
--presigned-url-config "{\"roleArn\":\"arn:aws:iam::123456789012:role/S3DownloadRole\", \"expiresInSec\":3600}"
```
作业正在运行*thingOne*。
可选的 `timeout-config` 参数指定每个设备完成其任务执行所具有的时间。计时器在任务执行状态设置为 `IN_PROGRESS` 时启动。如果任务执行状态未在时间到期之前设置为其它最终状态，则会设置为 `TIMED_OUT`。
进行中计时器无法更新，将应用到该任务的全部任务执行。每当任务执行保持`IN_PROGRESS`状态的时间超过此时间间隔时，它就会失败并切换到终端`TIMED_OUT`状态。 AWS IoT 还会发布 MQTT 通知。
有关创建任务推出和中止相关配置的更多信息，请参阅[任务推出和中止配置](job-rollout-abort.html)。
**注意**
在您创建任务时，系统会检索指定为 Amazon S3 文件的任务文档。如果在创建任务文档后，您更改用作任务文档源的 Amazon S3 文件的内容，则发送到任务目标的内容不会更改。
## 更新任务
要更新任务，使用 **UpdateJob** 命令。您可以更新任务的 `description`、`presignedUrlConfig`、`jobExecutionsRolloutConfig`、`abortConfig` 和 `timeoutConfig` 字段。
```
aws iot update-job \
--job-id 010 \
--description "updated description" \
--timeout-config inProgressTimeoutInMinutes=100 \
--job-executions-rollout-config "{ \"exponentialRate\": { \"baseRatePerMinute\": 50, \"incrementFactor\": 2, \"rateIncreaseCriteria\": { \"numberOfNotifiedThings\": 1000, \"numberOfSucceededThings\": 1000}, \"maximumPerMinute\": 1000}}" \
--abort-config "{ \"criteriaList\": [ { \"action\": \"CANCEL\", \"failureType\": \"FAILED\", \"minNumberOfExecutedThings\": 100, \"thresholdPercentage\": 20}, { \"action\": \"CANCEL\", \"failureType\": \"TIMED_OUT\", \"minNumberOfExecutedThings\": 200, \"thresholdPercentage\": 50}]}" \
--presigned-url-config "{\"roleArn\":\"arn:aws:iam::123456789012:role/S3DownloadRole\", \"expiresInSec\":3600}"
```
有关更多信息，请参阅[任务推出和中止配置](job-rollout-abort.html)。
## 取消任务
要取消任务，请使用 **CancelJob** 命令。取消任务将停止 AWS IoT 为该作业推出任何新的任务执行。它还会取消任何处于`QUEUED`状态的任务执行。 AWS IoT 由于设备已完成作业，因此所有任务执行保持终端状态不变。如果任务执行的状态为 `IN_PROGRESS`，它也将保持不变，除非您使用可选的 `--force` 参数。
以下命令说明如何取消 ID 为 010 的任务。
```
aws iot cancel-job --job-id 010
```
该命令将显示以下输出：
```
{
"jobArn": "string",
"jobId": "string",
"description": "string"
}
```
当您取消任务时，将取消处于 `QUEUED` 状态的任务执行。如果您指定了可选的 `--force` 参数，将取消处于 `IN_PROGRESS` 状态的任务执行。不会取消处于最终状态的任务执行。
**警告**
取消处于 `IN_PROGRESS` 状态的任务（通过设置 `--force` 参数）将取消正在进行的任何任务执行，并且会导致运行该任务的设备无法更新任务执行状态。请谨慎使用，并且 确保执行已取消的任务的每个设备能够恢复到有效状态。
已取消的任务或其中一个任务执行的状态最终是一致的。 AWS IoT 停止尽快将该任务的新`QUEUED`任务执行和任务执行调度到设备。将任务执行的状态更改为 `CANCELED` 可能需要一些时间，具体取决于设备数和其它因素。
如果任务因满足 `AbortConfig` 对象定义的条件而被取消，服务会为 `comment` 和 `reasonCode` 字段添加自动填充的值。当任务取消由用户驱动时，您可以为 `reasonCode` 创建自己的值。
## 取消任务执行
要取消设备上的任务执行，请使用 **CancelJobExecution** 命令。它将取消处于 `QUEUED` 状态的任务执行。如果要取消正在进行的任务执行，您必须使用 `--force` 参数。
以下命令说明如何取消在 `myThing` 上运行的任务 010 的任务执行。
```
aws iot cancel-job-execution --job-id 010 --thing-name myThing
```
该命令不显示任何输出。
将取消处于 `QUEUED` 状态的任务执行。如果您指定了可选的 `--force` 参数，则将取消处于 `IN_PROGRESS` 状态的任务执行。无法取消处于最终状态的任务执行。
**警告**
取消处于 `IN_PROGRESS` 状态的任务执行后，设备无法更新任务执行状态。请谨慎使用，并且 确保 设备能够恢复到有效状态。
如果任务执行处于最终状态，或者任务执行处于 `IN_PROGRESS` 状态而 `--force` 参数未设置为 `true`，则此命令将导致 `InvalidStateTransitionException`。
已取消任务执行的状态最终是一致的。将任务执行的状态更改为 `CANCELED` 可能需要一些时间，具体取决于各种因素。
## 删除任务
要删除任务及其任务执行，使用 **DeleteJob** 命令。默认情况下，您只能删除处于最终状态（`SUCCEEDED` 或 `CANCELED`）的任务。否则，会出现异常。但是，仅当 `force` 参数设置为 `true` 时，才能删除处于 `IN_PROGRESS` 状态的任务。
要删除任务，运行以下命令：
```
aws iot delete-job --job-id 010 --force|--no-force
```
该命令不显示任何输出。
**警告**
删除处于 `IN_PROGRESS` 状态的任务后，部署该任务的设备将无法访问任务信息或更新任务执行状态。请谨慎使用，并且确保部署已删除的任务的每个设备能够恢复到有效状态。
删除任务可能需要一些时间，具体取决于为该任务创建的任务执行的数量以及其它因素。在删除任务过程中，任务的状态将显示为 `DELETION_IN_PROGRESS`。如果您尝试删除或取消其状态已为 `DELETION_IN_PROGRESS` 的任务，将导致错误。
只能有 10 个任务的状态可以同时为 `DELETION_IN_PROGRESS`。否则，会出现 `LimitExceededException`。
## 获取任务文档
要检索任务的任务文档，使用 **GetJobDocument** 命令。任务文档是对设备将执行的远程操作的描述。
要获取任务文档，运行以下命令：
```
aws iot get-job-document --job-id 010
```
该命令返回指定任务的任务文档：
```
{
"document": "{\n\t\"operation\":\"install\",\n\t\"url\":\"http://amazon.com/firmWareUpate-01\",\n\t\"data\":\"${aws:iot:s3-presigned-url:https://s3.amazonaws.com/amzn-s3-demo-bucket/datafile}\"\n}"
}
```
**注意**
当您使用此命令检索任务文档时，占位符 URLs不会被预签名的 Amazon S3 所取代。 URLs当设备调用 [GetPendingJobExecutions](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_GetPendingJobExecutions.html)API 操作时，占位符将替换 URLs 为任务文档 URLs 中预签名的 Amazon S3。
## 列出任务
要获取您中所有任务的列表 AWS 账户，请使用**ListJobs**命令。任务数据和任务执行数据将在 [有限的时间](https://docs.aws.amazon.com//general/latest/gr/iot_device_management.html#job-limits)内保留。运行以下命令列出您的中的所有作业 AWS 账户：
```
aws iot list-jobs
```
该命令将返回您账户中按任务状态排序的所有任务：
```
{
"jobs": [
{
"status": "IN_PROGRESS",
"lastUpdatedAt": 1486687079.743,
"jobArn": "arn:aws:iot:us-east-1:123456789012:job/013",
"createdAt": 1486687079.743,
"targetSelection": "SNAPSHOT",
"jobId": "013"
},
{
"status": "SUCCEEDED",
"lastUpdatedAt": 1486685868.444,
"jobArn": "arn:aws:iot:us-east-1:123456789012:job/012",
"createdAt": 1486685868.444,
"completedAt": 148668789.690,
"targetSelection": "SNAPSHOT",
"jobId": "012"
},
{
"status": "CANCELED",
"lastUpdatedAt": 1486678850.575,
"jobArn": "arn:aws:iot:us-east-1:123456789012:job/011",
"createdAt": 1486678850.575,
"targetSelection": "SNAPSHOT",
"jobId": "011"
}
]
}
```
## 描述任务
要获取任务的状态，运行 **DescribeJob** 命令。以下命令说明如何描述任务：
```
$ aws iot describe-job --job-id 010
```
该命令返回指定任务的状态。例如：
```
{
"documentSource": "https://s3.amazonaws.com/amzn-s3-demo-bucket/job-document.json",
"job": {
"status": "IN_PROGRESS",
"jobArn": "arn:aws:iot:us-east-1:123456789012:job/010",
"targets": [
"arn:aws:iot:us-east-1:123456789012:thing/myThing"
],
"jobProcessDetails": {
"numberOfCanceledThings": 0,
"numberOfFailedThings": 0,
"numberOfInProgressThings": 0,
"numberOfQueuedThings": 0,
"numberOfRejectedThings": 0,
"numberOfRemovedThings": 0,
"numberOfSucceededThings": 0,
"numberOfTimedOutThings": 0,
"processingTargets": [
arn:aws:iot:us-east-1:123456789012:thing/thingOne,
arn:aws:iot:us-east-1:123456789012:thinggroup/thinggroupOne,
arn:aws:iot:us-east-1:123456789012:thing/thingTwo,
arn:aws:iot:us-east-1:123456789012:thinggroup/thinggroupTwo
]
},
"presignedUrlConfig": {
"expiresInSec": 60,
"roleArn": "arn:aws:iam::123456789012:role/S3DownloadRole"
},
"jobId": "010",
"lastUpdatedAt": 1486593195.006,
"createdAt": 1486593195.006,
"targetSelection": "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": number
}
}
}
```
## 列出任务的执行
在特定设备上运行的任务由任务执行对象表示。运行 **ListJobExecutionsForJob** 命令来列出任务的所有任务执行。以下命令说明如何列出任务的执行：
```
aws iot list-job-executions-for-job --job-id 010
```
该命令将返回任务执行的列表：
```
{
"executionSummaries": [
{
"thingArn": "arn:aws:iot:us-east-1:123456789012:thing/thingOne",
"jobExecutionSummary": {
"status": "QUEUED",
"lastUpdatedAt": 1486593196.378,
"queuedAt": 1486593196.378,
"executionNumber": 1234567890
}
},
{
"thingArn": "arn:aws:iot:us-east-1:123456789012:thing/thingTwo",
"jobExecutionSummary": {
"status": "IN_PROGRESS",
"lastUpdatedAt": 1486593345.659,
"queuedAt": 1486593196.378,
"startedAt": 1486593345.659,
"executionNumber": 4567890123
}
}
]
}
```
## 列出事物的任务执行
运行 **ListJobExecutionsForThing** 命令来列出在事物上运行的所有任务执行。以下命令说明如何列出事物的任务执行：
```
aws iot list-job-executions-for-thing --thing-name thingOne
```
该命令将返回正在指定事物上运行的或在指定事物上运行过的任务执行的列表：
```
{
"executionSummaries": [
{
"jobExecutionSummary": {
"status": "QUEUED",
"lastUpdatedAt": 1486687082.071,
"queuedAt": 1486687082.071,
"executionNumber": 9876543210
},
"jobId": "013"
},
{
"jobExecutionSummary": {
"status": "IN_PROGRESS",
"startAt": 1486685870.729,
"lastUpdatedAt": 1486685870.729,
"queuedAt": 1486685870.729,
"executionNumber": 1357924680
},
"jobId": "012"
},
{
"jobExecutionSummary": {
"status": "SUCCEEDED",
"startAt": 1486678853.415,
"lastUpdatedAt": 1486678853.415,
"queuedAt": 1486678853.415,
"executionNumber": 4357680912
},
"jobId": "011"
},
{
"jobExecutionSummary": {
"status": "CANCELED",
"startAt": 1486593196.378,
"lastUpdatedAt": 1486593196.378,
"queuedAt": 1486593196.378,
"executionNumber": 2143174250
},
"jobId": "010"
}
]
}
```
## 描述任务执行
运行 **DescribeJobExecution** 命令来获取任务执行的状态。您必须指定任务 ID 和事物名称（也可以选择指定执行编号）来标识任务执行。以下命令说明如何描述任务执行：
```
aws iot describe-job-execution --job-id 017 --thing-name thingOne
```
该命令将返回 [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecution.html)。例如：
```
{
"execution": {
"jobId": "017",
"executionNumber": 4516820379,
"thingArn": "arn:aws:iot:us-east-1:123456789012:thing/thingOne",
"versionNumber": 123,
"createdAt": 1489084805.285,
"lastUpdatedAt": 1489086279.937,
"startedAt": 1489086279.937,
"status": "IN_PROGRESS",
"approximateSecondsBeforeTimedOut": 100,
"statusDetails": {
"status": "IN_PROGRESS",
"detailsMap": {
"percentComplete": "10"
}
}
}
}
```
## 删除任务执行
运行 **DeleteJobExecution** 命令来删除任务执行。您必须指定任务 ID、事物名称和执行编号来标识任务执行。以下命令说明如何删除任务执行：
```
aws iot delete-job-execution --job-id 017 --thing-name thingOne --execution-number 1234567890 --force|--no-force
```
该命令不显示任何输出。
默认情况下，任务执行的状态必须为 `QUEUED` 或处于最终状态（`SUCCEEDED`、`FAILED`、`REJECTED`、`TIMED_OUT`、`REMOVED` 或 `CANCELED`）。否则将出错。要删除状态为 `IN_PROGRESS` 的任务执行，您可以将 `force` 参数设置为 `true`。
**警告**
删除状态为 `IN_PROGRESS` 的任务执行后，执行该任务的设备将无法访问任务信息或更新任务执行状态。请谨慎使用，并且 确保 设备能够恢复到有效状态。
# 作业模板
使用任务模板预置可以部署到多组目标设备的任务。要将频繁执行的远程操作部署到设备（如重启或安装应用程序），可以使用模板来定义标准配置。要执行诸如部署安全补丁和错误修复等操作，您可以从现有任务中创建模板。
创建任务模板时，请指定以下附加配置和资源。
+ 任务属性
+ 任务文件和目标
+ 推出、计划和取消标准
+ 超时和重试标准
## 自定义和 AWS 托管模板
根据您要执行的远程操作，您可以创建自定义作业模板或使用 AWS 托管模板。使用自定义作业模板提供您自己的自定义任务文档，并创建可重复使用的作业以部署到您的设备。 AWS 托管模板是作业为常用操作提供的 AWS IoT 作业模板。这些模板具有用于某些远程操作的预定义任务文档，因此您无需创建自己的任务文档。托管式模板可帮助您创建可重复使用的任务，以便更快地启动设备。
**Topics**
+ [自定义和 AWS 托管模板](#job-templates-types)
+ [使用 AWS 托管模板部署常见的远程操作](job-templates-managed.md)
+ [创建自定义任务模板](job-templates-create.md)
# 使用 AWS 托管模板部署常见的远程操作
AWS 托管模板是由提供的作业模板 AWS。这些任务模板用于频繁执行的远程操作，例如重启、下载文件或在设备上安装应用程序。这些模板具有用于每个远程操作的预定义任务文档，因此您无需创建自己的任务文档。
您可以从一组预定义的配置中进行选择，并使用这些模板创建任务，而无需编写任何其他代码 使用托管模板，您可以查看部署到机群的任务文档。您可以使用这些模板创建任务，然后创建可以重复用于远程操作的自定义任务模板。
## 托管模板包含哪些内容？
每个 AWS 托管模板都包含：
+ 在任务文档中运行命令的环境。
+ 指定操作名称及其参数的任务文档。例如，如果您使用**下载文件**模板，操作名称是*下载文件*，参数可以是：
+ 要下载到设备的文件的 URL。这可以是互联网资源，也可以是公共或预签名 Amazon Simple Storage Service (Amazon S3) URL。
+ 设备上用于存储下载文件的本地文件路径。
有任务文档及其参数的更多信息，请参阅 [托管模板远程操作和任务文档](#job-template-manage-actions)。
## 先决条件
要使设备运行托管模板任务文档指定的远程操作，您必须：
+ **在设备上安装特定软件**
使用您自己的设备软件和作业处理程序或 AWS IoT 设备客户端。根据您的业务案例，您也可以同时运行它们，以使它们执行不同的功能。
+ **使用您自己的设备软件和任务处理程序**
您可以使用 AWS IoT Device SDK 及其支持远程操作的处理程序库为设备编写自己的代码。要部署和运行任务，请验证设备代理库已正确安装并正在这些设备上运行。
您也可以选择使用自己的支持远程操作的处理程序。有关更多信息，请参阅 AWS IoT 设备客户端 GitHub存储库中的[示例作业处理程序](https://github.com/awslabs/aws-iot-device-client/tree/main/sample-job-handlers)。
+ **使用 AWS IoT 设备客户端**
或者，您可以在设备上安装和运行 AWS IoT 设备客户端，因为它默认支持直接从控制台使用所有托管模板。
Device Client 是用 C\$1\$1 编写的开源软件，您可以在基于 Linux 的嵌入式 IoT 设备上编译和安装。Device Client 有*基本客户端*和离散的*客户端特征*。基础客户端 AWS IoT 通过 MQTT 协议建立连接，并且可以连接不同的客户端功能。
要在设备上执行远程操作，请使用 Device Client 的*客户端任务特征*。此特征包含一个用于接收任务文档的解析器以及实现任务文档中指定的远程操作的任务处理程序。有关Device Client 及其特征的更多信息，请参阅 [AWS IoT Device Client。](https://github.com/awslabs/aws-iot-device-client#readme)
在设备上运行时，Device Client 会收到任务文档，并具有用于在文档中运行命令的特定于平台的实现。有关设置 Device Client 和使用任务特征的详细信息，请参阅 [AWS IoT 教程](https://docs.aws.amazon.com/iot/latest/developerguide/iot-tutorials.html)。
+ **使用支持的环境**
对于每个托管模板，您将找到有关可用于运行远程操作的环境信息。我们建议您将模板与模板中指定的受支持的 Linux 环境结合使用。使用 AWS IoT 设备客户端运行托管模板远程操作，因为它支持常见的微处理器和 Linux 环境，例如 Debian 和 Ubuntu。
## 托管模板远程操作和任务文档
以下部分列出了 AWS IoT 任务的不同 AWS 托管模板，并描述了可以在设备上执行的远程操作。以下章节提供有关任务文档的信息以及每个远程操作的任务文档参数的描述。设备端软件使用模板名称和参数来执行远程操作。
AWS 托管模板接受您在使用模板创建作业时为其指定值的输入参数。所有托管式模板都有以下两个共同的可选输入参数：`runAsUser` 和 `pathToHandler`。除了 `AWS-Reboot` 模板时，模板需要额外的输入参数，在使用模板创建任务时必须为这些参数指定值。这些所需的输入参数因您所选的模板而异。例如，如果您选择 `AWS-Download-File` 模板，则必须指定要安装的软件包列表以及从中下载文件的 URL。
使用 AWS IoT 控制台或 AWS Command Line Interface (AWS CLI) 创建使用托管模板的作业时，请为输入参数指定一个值。使用 CLI 时，可以使用 `document-parameters` 对象提供这些值。有关更多信息，请参阅[文档参数](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html#iot-CreateJob-request-documentParameters)。
**注意**
仅当从 AWS 托管式模板创建任务时，才使用 `document-parameters`。此参数不能与自定义任务模板一起使用，也不能从中创建作业。
下面显示了常见可选输入参数的说明。您将在下一节中看到每个托管式模板所需的其它输入参数的说明。
`runAsUser`
此参数指定是否以其他用户身份运行任务处理程序。如果在任务创建过程中未指定，任务处理程序将以与 Device Client 相同的用户身份运行。当您以其他用户身份运行任务处理程序时，请指定不超过 256 个字符的字符串值。
`pathToHandler`
设备上运行的任务处理程序的路径。如果在创建任务时未指定它，Device Client 将使用当前工作目录。
下面显示了不同的远程操作、其任务文档以及它们接受的参数。所有这些模板都支持在设备上运行远程操作的 Linux 环境。
### AWS- 下载- 文件
**模板名称**
`AWS–Download–File`
**模板描述**
提供的 AWS 用于下载文件的托管模板。
**输入参数**
此模板具有以下必需参数。您还可以指定可选参数 `runAsUser` 和 `pathToHandler`
`downloadUrl`
从中下载文件的 URL。这可以是互联网资源、Amazon S3 中可公开访问的对象，也可以是 Amazon S3 中只能由设备使用预签名 URL 访问的对象。有关使用预签名 URLs和授予权限的更多信息，请参阅[预签名 URLs](create-manage-jobs.md#create-manage-jobs-presigned-URLs)。
`filePath`
本地文件路径，显示设备中存储下载文件的位置。
**设备的行为**
设备从指定位置下载文件，验证下载完成并将其存储在本地。
**任务文档**
下面显示了任务文档及其最新版本。模板显示了任务处理程序和 shell 脚本的路径，`download-file.sh`，必须运行任务处理程序才能下载文件。它还显示了必需参数 `downloadUrl` 和 `filePath`。
```
{
"version": "1.0",
"steps": [
{
"action": {
"name": "Download-File",
"type": "runHandler",
"input": {
"handler": "download-file.sh",
"args": [
"${aws:iot:parameter:downloadUrl}",
"${aws:iot:parameter:filePath}"
],
"path": "${aws:iot:parameter:pathToHandler}"
},
"runAsUser": "${aws:iot:parameter:runAsUser}"
}
}
]
}
```
### AWS–安装 - 应用程序。
**模板名称**
`AWS–Install–Application`
**模板描述**
提供的 AWS 用于安装一个或多个应用程序的托管模板。
**输入参数**
此模板具有以下必需参数，`packages`。您还可以指定可选参数 `runAsUser` 和 `pathToHandler`
`packages`
要安装的一个或多个应用程序列表，以空格分隔。
**设备的行为**
设备将按照任务文档中的指定安装应用程序。
**任务文档**
下面显示了任务文档及其最新版本。模板显示了任务处理程序和 shell 脚本的路径，`install-packages.sh`，必须运行任务处理程序才能下载文件。它还显示必需参数 `packages`。
```
{
"version": "1.0",
"steps": [
{
"action": {
"name": "Install-Application",
"type": "runHandler",
"input": {
"handler": "install-packages.sh",
"args": [
"${aws:iot:parameter:packages}"
],
"path": "${aws:iot:parameter:pathToHandler}"
},
"runAsUser": "${aws:iot:parameter:runAsUser}"
}
}
]
}
```
### AWS- 重启
**模板名称**
`AWS–Reboot`
**模板描述**
提供的 AWS 用于重启设备的托管模板。
**输入参数**
此模板没有必需参数。但是，您可以指定可选参数 `runAsUser` 和 `pathToHandler`。
**设备的行为**
设备已成功重新启动。
**任务文档**
下面显示了任务文档及其最新版本。模板显示了任务处理程序和 shell 脚本的路径，`reboot.sh`，必须运行任务处理程序才能重新启动设备。
```
{
"version": "1.0",
"steps": [
{
"action": {
"name": "Reboot",
"type": "runHandler",
"input": {
"handler": "reboot.sh",
"path": "${aws:iot:parameter:pathToHandler}"
},
"runAsUser": "${aws:iot:parameter:runAsUser}"
}
}
]
}
```
### AWS–删除–应用程序
**模板名称**
`AWS–Remove–Application`
**模板描述**
提供的托管模板， AWS 用于卸载一个或多个应用程序。
**输入参数**
此模板具有以下必需参数，`packages`。您还可以指定可选参数 `runAsUser` 和 `pathToHandler`
`packages`
要卸载的一个或多个应用程序列表，以空格分隔。
**设备的行为**
设备将按照任务文档中的指定卸载应用程序。
**任务文档**
下面显示了任务文档及其最新版本。模板显示了任务处理程序和 shell 脚本的路径，`remove-packages.sh`，必须运行任务处理程序才能下载文件。它还显示必需参数 `packages`。
```
{
"version": "1.0",
"steps": [
{
"action": {
"name": "Remove-Application",
"type": "runHandler",
"input": {
"handler": "remove-packages.sh",
"args": [
"${aws:iot:parameter:packages}"
],
"path": "${aws:iot:parameter:pathToHandler}"
},
"runAsUser": "${aws:iot:parameter:runAsUser}"
}
}
]
}
```
### AWS— 重新启动 — 应用
**模板名称**
`AWS–Restart–Application`
**模板描述**
提供的托管模板， AWS 用于停止和重启一项或多项服务。
**输入参数**
此模板具有以下必需参数，`services`。您还可以指定可选参数 `runAsUser` 和 `pathToHandler`
**Services**
将重新启动的一个或多个应用程序列表，以空格分隔。
**设备的行为**
指定的应用程序停止然后在设备上重新启动。
**任务文档**
下面显示了任务文档及其最新版本。模板显示了任务处理程序和 shell 脚本的路径，`restart-services.sh`，必须运行任务处理程序才能重新启动系统服务。它还显示必需参数 `services`。
```
{
"version": "1.0",
"steps": [
{
"action": {
"name": "Restart-Application",
"type": "runHandler",
"input": {
"handler": "restart-services.sh",
"args": [
"${aws:iot:parameter:services}"
],
"path": "${aws:iot:parameter:pathToHandler}"
},
"runAsUser": "${aws:iot:parameter:runAsUser}"
}
}
]
}
```
### AWS–开始–复制
**模板名称**
`AWS-Start-Application`
**模板描述**
为启动一项或多 AWS 项服务而提供的托管模板。
**输入参数**
此模板具有以下必需参数，`services`。您还可以指定可选参数 `runAsUser` 和 `pathToHandler`
`services`
将启动的一个或多个应用程序列表，以空格分隔。
**设备的行为**
指定的应用程序开始在设备上运行。
**任务文档**
下面显示了任务文档及其最新版本。模板显示了任务处理程序和 shell 脚本的路径，`start-services.sh`，必须运行任务处理程序才能启动系统服务。它还显示必需参数 `services`。
```
{
"version": "1.0",
"steps": [
{
"action": {
"name": "Start-Application",
"type": "runHandler",
"input": {
"handler": "start-services.sh",
"args": [
"${aws:iot:parameter:services}"
],
"path": "${aws:iot:parameter:pathToHandler}"
},
"runAsUser": "${aws:iot:parameter:runAsUser}"
}
}
]
}
```
### AWS–停止–应用程序
**模板名称**
`AWS–Stop–Application`
**模板描述**
提供的托管模板， AWS 用于停止一项或多项服务。
**输入参数**
此模板具有以下必需参数，`services`。您还可以指定可选参数 `runAsUser` 和 `pathToHandler`
`services`
将停止的一个或多个应用程序列表，以空格分隔。
**设备的行为**
指定的应用程序停止在设备上运行。
**任务文档**
下面显示了任务文档及其最新版本。模板显示了任务处理程序和 shell 脚本的路径，`stop-services.sh`，必须运行任务处理程序才能停止系统服务。它还显示必需参数 `services`。
```
{
"version": "1.0",
"steps": [
{
"action": {
"name": "Stop-Application",
"type": "runHandler",
"input": {
"handler": "stop-services.sh",
"args": [
"${aws:iot:parameter:services}"
],
"path": "${aws:iot:parameter:pathToHandler}"
},
"runAsUser": "${aws:iot:parameter:runAsUser}"
}
}
]
}
```
### AWS–Run–Command
**模板名称**
`AWS–Run–Command`
**模板描述**
由提供的 AWS 用于运行 shell 命令的托管模板。
**输入参数**
此模板具有以下必需参数，`command`。您还可以指定可选参数 `runAsUser`。
`command`
以逗号分隔的命令字符串。必须对命令本身中包含的任何逗号进行转义。
**设备的行为**
设备按照任务文档中的指定运行 shell 命令。
**任务文档**
下面显示了任务文档及其最新版本。此模板显示任务命令的路径，以及您提供的且设备将运行的命令。
```
{
"version": "1.0",
"steps": [
{
"action": {
"name": "Run-Command",
"type": "runCommand",
"input": {
"command": "${aws:iot:parameter:command}"
},
"runAsUser": "${aws:iot:parameter:runAsUser}"
}
}
]
}
```
**Topics**
+ [托管模板包含哪些内容？](#job-template-managed-contains)
+ [先决条件](#job-template-managed-prereq)
+ [托管模板远程操作和任务文档](#job-template-manage-actions)
+ [使用 AWS 托管模板创建作业 AWS 管理控制台](job-template-manage-console-create.md)
+ [使用 AWS 托管模板创建作业 AWS CLI](job-template-manage-cli-create.md)
# 使用 AWS 托管模板创建作业 AWS 管理控制台
使用获取 AWS 管理控制台 有关 AWS 托管模板的信息，并使用这些模板创建作业。然后，您可以将创建的任务保存为自己的自定义模板。
## 获取有关托管模板的详细信息
您可以从 AWS IoT 控制台获取有关可供使用的不同托管模板的信息。
1. 要查看可用的托管模板，请前往[AWS IoT 控制台的 Job Templates 中心](https://console.aws.amazon.com/iot/home#/jobtemplatehub)，然后选择**托管模板**选项卡。
1. 要查看详细信息，请选择托管式模板。
详细信息页面包括以下信息：
+ 托管模板的名称、描述和 Amazon Resource Name (ARN)。
+ 可以执行远程操作的环境，例如 Linux。
+ JSON 任务文档，用于指定任务处理程序的路径以及要在设备上运行的命令。例如，下面显示了一个示例任务文档 **AWS-Reboot** 模板。模板显示了任务处理程序和 shell 脚本的路径，`reboot.sh`，必须运行任务处理程序才能重新启动设备。
```
{
"version": "1.0",
"steps": [
{
"action": {
"name": "Reboot",
"type": "runHandler",
"input": {
"handler": "reboot.sh",
"path": "${aws:iot:parameter:pathToHandler}"
},
"runAsUser": "${aws:iot:parameter:runAsUser}"
}
}
]
}
```
有关任务文档及其各种远程操作参数的详细信息，请参阅 [托管模板远程操作和任务文档](job-templates-managed.md#job-template-manage-actions)。
+ 任务文档的最新版本。
## 使用托管模板创建任务
您可以使用 AWS 管理控制台选择用于创建作业的 AWS 托管模板。本节向您演示了应如何进行操作。
您也可以启动任务创建工作流程，然后选择要在创建作业时使用的 AWS 托管模板。有关工作流的更多信息，请参阅 [使用创建和管理作业 AWS 管理控制台](manage-job-console.md)。
1.
**选择您的 AWS 托管模板**
前往[AWS IoT 控制台的 Job 模板中心](https://console.aws.amazon.com/iot/home#/jobtemplatehub)，选择**托管模板**选项卡，然后选择您的模板。
1.
**使用托管模板创建任务**
1. 在模板详细信息页面上，选择 **Create job**(创建任务)。
控制台切换到添加模板配置的工作流的**创建任务**的**自定义任务属性**的步骤。
1. 输入唯一的字母数字任务名称以及可选的描述和标签，然后选择**下一步**。
1. 选择要在此任务中运行的事物或事物组作为任务目标。
1. 在 **Job document**（任务文档）部分中，您的模板随其配置设置和输入参数一起显示。输入所选模板的输入参数的值。例如，如果您选择了 **AWS-Download-File** 模板：
+ 对于 **downloadUrl**，输入要下载的文件的 URL，例如：`https://example.com/index.html`。
+ 对于 **filePath**，输入设备上存储下载文件的路径，例如：`path/to/file`。
还可以选择输入 `runAsUser` 和 `pathToHandler` 参数的值。有关每个模板的输入参数的更多信息，请参阅[托管模板远程操作和任务文档](job-templates-managed.md#job-template-manage-actions)。
1. 在 **Job configuration**（作业配置）页面上，将作业类型选择为连续或快照作业。快照任务在目标设备和组上完成运行后即算完成任务。连续任务适用于事物组，并会添加到指定目标组的任何设备上运行。
1. 继续为您的任务添加任何其他配置，然后查看并创建任务。有关其他配置的更多信息，请参阅：
+ [任务推出、计划和中止配置](jobs-configurations-details.md#job-rollout-abort-scheduling)
+ [任务执行超时和重试配置](jobs-configurations-details.md#job-timeout-retry)
## 从托管模板创建自定义任务模板
您可以使用 AWS 托管模板和自定义作业作为起点来创建自己的自定义作业模板。要创建自定义作业模板，请先使用您的 AWS 托管模板创建作业，如上一节所述。
然后，您可以将自定义任务另存为模板，创建自己的自定义任务模板。要另存为模板：
1. 前往[AWS IoT 控制台的 Job 中心](https://console.aws.amazon.com/iot/home#/jobhub)并选择包含您的托管模板的作业。
1. 选择**另存为任务模板**，然后创建自定义任务模板。有关创建自定义模板的更多信息，请参阅 [从现有任务创建任务模板](job-templates-console.md#job-templates-console-create-exist-job)。
# 使用 AWS 托管模板创建作业 AWS CLI
使用获取 AWS CLI 有关 AWS 托管模板的信息，并使用这些模板创建作业。然后，您可以将任务另存为模板，并创建自己的自定义模板。
## 列出托管模板
该[https://docs.aws.amazon.com/cli/latest/reference/iot/list-managed-job-templates.html](https://docs.aws.amazon.com/cli/latest/reference/iot/list-managed-job-templates.html) AWS CLI 命令列出了您的所有作业模板 AWS 账户。
```
aws iot list-managed-job-templates
```
默认情况下，运行此命令会显示所有可用的 AWS 托管模板及其详细信息。
```
{
"managedJobTemplates": [
{
"templateArn": "arn:aws:iot:region::jobtemplate/AWS-Reboot:1.0",
"templateName": "AWS-Reboot",
"description": "A managed job template for rebooting the device.",
"environments": [
"LINUX"
],
"templateVersion": "1.0"
},
{
"templateArn": "arn:aws:iot:region::jobtemplate/AWS-Remove-Application:1.0",
"templateName": "AWS-Remove-Application",
"description": "A managed job template for uninstalling one or more applications.",
"environments": [
"LINUX"
],
"templateVersion": "1.0"
},
{
"templateArn": "arn:aws:iot:region::jobtemplate/AWS-Stop-Application:1.0",
"templateName": "AWS-Stop-Application",
"description": "A managed job template for stopping one or more system services.",
"environments": [
"LINUX"
],
"templateVersion": "1.0"
},
...
{
"templateArn": "arn:aws:iot:us-east-1::jobtemplate/AWS-Restart-Application:1.0",
"templateName": "AWS-Restart-Application",
"description": "A managed job template for restarting one or more system services.",
"environments": [
"LINUX"
],
"templateVersion": "1.0"
}
]
}
```
有关更多信息，请参阅 [ListManagedJobTemplates](https://docs.aws.amazon.com/iot/latest/apireference/API_ListManagedJobTemplates.html)。
## 获取有关托管式模板的详细信息
该[https://docs.aws.amazon.com/cli/latest/reference/iot/describe-managed-job-template.html](https://docs.aws.amazon.com/cli/latest/reference/iot/describe-managed-job-template.html) AWS CLI 命令获取有关指定作业模板的详细信息。指定任务模板名称和可选的模板版本。如果未指定模板版本，则返回预定义的默认版本。以下示例显示运行命令以获取有关 `AWS-Download-File` 模板的详细信息。
```
aws iot describe-managed-job-template \
--template-name AWS-Download-File
```
该命令显示模板详细信息和 ARN、其任务文档以及 `documentParameters` 参数，此参数是模板输入参数的键/值对的列表。有关不同模板和输入参数的信息，请参阅[托管模板远程操作和任务文档](job-templates-managed.md#job-template-manage-actions)。
**注意**
使用此 API 时返回的`documentParameters`对象只能在通过 AWS 托管模板创建任务时使用。此对象不得用于自定义任务模板。有关演示如何使用此参数的示例，请参阅[使用托管模板创建任务](#job-template-manage-cli-create-job)。
```
{
"templateName": "AWS-Download-File",
"templateArn": "arn:aws:iot:region::jobtemplate/AWS-Download-File:1.0",
"description": "A managed job template for downloading a file.",
"templateVersion": "1.0",
"environments": [
"LINUX"
],
"documentParameters": [
{
"key": "downloadUrl",
"description": "URL of file to download.",
"regex": "(.*?)",
"example": "http://www.example.com/index.html",
"optional": false
},
{
"key": "filePath",
"description": "Path on the device where downloaded file is written.",
"regex": "(.*?)",
"example": "/path/to/file",
"optional": false
},
{
"key": "runAsUser",
"description": "Execute handler as another user. If not specified, then handler is executed as the same user as device client.",
"regex": "(.){0,256}",
"example": "user1",
"optional": true
},
{
"key": "pathToHandler",
"description": "Path to handler on the device. If not specified, then device client will use the current working directory.",
"regex": "(.){0,4096}",
"example": "/path/to/handler/script",
"optional": true
}
],
"document": "{\"version\":\"1.0\",\"steps\":[{\"action\":{\"name\":\"Download-File\",\"type\":\"runHandler\",\"input\":{\"handler\":\"download-file.sh\",\"args\":[\"${aws:iot:parameter:downloadUrl}\",\"${aws:iot:parameter:filePath}\"],\"path\":\"${aws:iot:parameter:pathToHandler}\"},\"runAsUser\":\"${aws:iot:parameter:runAsUser}\"}}]}"
}
```
有关更多信息，请参阅 [DescribeManagedJobTemplate](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeManagedJobTemplate.html)。
## 使用托管模板创建任务
该[https://docs.aws.amazon.com/cli/latest/reference/iot/create-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/create-job.html) AWS CLI 命令可用于根据作业模板创建作业。它的目标是名为 `thingOne` 的设备，并将指定托管模板的 Amazon Resource Name (ARN)，用作该任务的基础。您可以覆盖高级配置（如超时和取消配置），方法是传递 `create-job` 命令的关联参数。
该示例显示如何创建使用 `AWS-Download-File` 模板的任务。它还展示了如何使用 `document-parameters` 参数指定模板的输入参数。
**注意**
仅在 AWS 托管模板中使用该`document-parameters`对象。此对象不得与自定义任务模板一起使用。
```
aws iot create-job \
--targets arn:aws:iot:region:account-id:thing/thingOne \
--job-id "new-managed-template-job" \
--job-template-arn arn:aws:iot:region::jobtemplate/AWS-Download-File:1.0 \
--document-parameters downloadUrl=https://example.com/index.html,filePath=path/to/file
```
其中：
+ *region*是 AWS 区域。
+ *account-id*是唯一的 AWS 账户 数字。
+ `thingOne` 是任务指向的 IoT 事物的名称。
+ *AWS-Download-File:1.0*是托管模板的名称。
+ `https://example.com/index.html` 是从中下载文件的 URL。
+ `https://pathto/file/index` 是设备上用于存储下载文件的路径。
运行以下命令创建模板的任务：`AWS-Download-File`。
```
{
"jobArn": "arn:aws:iot:region:account-id:job/new-managed-template-job",
"jobId": "new-managed-template-job",
"description": "A managed job template for downloading a file."
}
```
## 从托管模板创建自定义任务模板
1. 使用上一节中介绍的托管模板创建任务。
1. 使用您创建的任务的 ARN 创建自定义任务模板。有关更多信息，请参阅 [从现有任务创建任务模板](job-templates-cli.md#job-templates-cli-create-from-job)。
# 创建自定义任务模板
您可以使用 AWS CLI 和 AWS IoT 控制台创建作业模板。您还可以使用用于 AWS IoT 设备管理 Web 应用程序的 Fleet Hub AWS CLI、 AWS IoT 控制台和舰队中心，根据任务模板创建作业。有关在 Fleet Hub 应用程序中使用作业模板的更多信息，请参阅在 F [leet Hub 中使用任务模板进行 AWS IoT 设备管理](https://docs.aws.amazon.com/iot/latest/fleethubuserguide/aws-iot-monitor-technician-job-templates.html)。
**注意**
作业文档中的替换模式总数应小于或等于 10。
**Topics**
+ [使用创建自定义作业模板 AWS 管理控制台](job-templates-console.md)
+ [使用创建自定义作业模板 AWS CLI](job-templates-cli.md)
# 使用创建自定义作业模板 AWS 管理控制台
本主题介绍如何使用 AWS IoT 控制台创建、删除和查看有关作业模板的详细信息。
## 创建自定义任务模板
您可以创建一个原始 自定义任务模板或从现有任务创建任务模板。您也可以根据使用 AWS 托管模板创建的现有作业创建自定义作业模板。有关更多信息，请参阅 [从托管模板创建自定义任务模板](job-template-manage-console-create.md#job-template-manage-create-template)。
### 创建原始任务模板
1.
**开始创建您的任务模板**
1. 前往[AWS IoT 控制台的 Job 模板中心，](https://console.aws.amazon.com/iot/home#/jobtemplatehub)然后选择**自定义模板**选项卡。
1. 选择 **Create job template**（创建任务模板）。
**注意**
您还可以从 **Fleet Hub** 下的 **Related services**（相关服务）页面导航到 **Job templates**（任务模板）页面。
1.
**指定任务模板属性**
在**创建任务模板**页面中，输入任务名称的字母数字标识符和字母数字描述，提供有关该模板的其他详细信息。
**注意**
我们不建议在职位 IDs 或描述中使用个人身份信息。
1.
**提供任务文档**
提供 JSON 任务文件，该文件存储在 S3 存储桶中或作为任务中指定的内联任务文档。当您使用此模板创建任务时，此任务文件将成为任务文档。
如果任务文件存储在 S3 存储桶中，请输入 S3 URL 或选择**浏览 S3**，然后导航到您的工作文档并选择它。
**注意**
您可以选择当前区域中的 S3 存储桶。
1. 继续为您的任务添加任何其他配置，然后查看并创建任务。有关其他可选配置的信息，请参阅以下链接：
+ [任务推出、计划和中止配置](jobs-configurations-details.md#job-rollout-abort-scheduling)
+ [任务执行超时和重试配置](jobs-configurations-details.md#job-timeout-retry)
### 从现有任务创建任务模板
1.
**选择您的任务**
1. 前往[AWS IoT 控制台的 Job Hub](https://console.aws.amazon.com/iot/home#/jobhub)，选择要用作作业模板基础的作业。
1. 选择**另存为任务模板**。
**注意**
您可以选择不同的任务文档或编辑原始任务中的高级配置，然后选择 **Create job template**（创建任务模板）。您的新任务模板将显示在 **Job template**（任务模板）页面。
1.
**指定任务模板属性**
在**创建任务模板**页面中，输入任务名称的字母数字标识符和字母数字描述，提供有关该模板的其他详细信息。
**注意**
任务文档是您在创建模板时指定的任务文件。如果是在任务中指定任务文档的，而不是 S3 位置，可以在此任务的详细信息页面中看到任务文档。
1. 继续为您的任务添加任何其他配置，然后查看并创建任务。有关其他配置的更多信息，请参阅：
+ [任务推出、计划和中止配置](jobs-configurations-details.md#job-rollout-abort-scheduling)
+ [任务执行超时和重试配置](jobs-configurations-details.md#job-timeout-retry)
## 从自定义任务模板创建任务。
您可以通过转到任务模板的详细信息页面，从自定义任务模板创建任务，如本主题中所述。您还可以创建任务，或者通过选择运行任务创建工作流程时要使用的任务模板来创建任务。有关更多信息，请参阅 [使用创建和管理作业 AWS 管理控制台](manage-job-console.md)。
本主题介绍如何从自定义任务模板的详细信息页面创建任务。您也可以使用 AWS 托管模板创建作业。有关更多信息，请参阅 [使用托管模板创建任务](job-template-manage-console-create.md#job-template-manage-create-job)。
1.
**选择自定义任务模板**
前往[AWS IoT 控制台的 Job Tem](https://console.aws.amazon.com/iot/home#/jobtemplatehub) plates 中心，选择**自定义模板**选项卡，然后选择您的模板。
1.
**使用自定义模板创建任务**
要创建任务：
1. 在模板详细信息页面上，选择 **Create job**(创建任务)。
控制台切换到添加模板配置的工作流的**创建任务**的**自定义任务属性**的步骤。
1. 输入唯一的字母数字任务名称以及可选的描述和标签，然后选择**下一步**。
1. 选择要在此任务中运行的事物或事物组作为任务目标。
在**任务文档**部分中，您的模板随其配置设置一起显示。如果要使用不同的任务文档，请选择 **Browse**（浏览），然后选择不同的存储桶和文档。选择**下一步**。
1. 在 **Job configuration**（作业配置）页面上，将作业类型选择为连续或快照作业。快照任务在目标设备和组上完成运行后即算完成任务。连续任务适用于事物组，并会添加到指定目标组的任何设备上运行。
1. 继续为您的任务添加任何其他配置，然后查看并创建任务。有关其他配置的更多信息，请参阅：
+ [任务推出、计划和中止配置](jobs-configurations-details.md#job-rollout-abort-scheduling)
+ [任务执行超时和重试配置](jobs-configurations-details.md#job-timeout-retry)
**注意**
当根据任务模板创建的任务更新该任务模板提供的现有参数时，这些更新的参数将覆盖该任务模板为该任务提供的现有参数。
您还可以使用 Fleet Hub Web 应用程序从任务模板创建任务。有关在 Fleet Hub 中创建任务的信息，[请参阅在 Fleet Hub 中使用任务模板进行 AWS IoT 设备管理](https://docs.aws.amazon.com/iot/latest/fleethubuserguide/aws-iot-monitor-technician-job-templates.html)。
## 删除任务模板
要删除作业模板，请先进入[AWS IoT 控制台的 Job Templates 中心](https://console.aws.amazon.com/iot/home#/jobtemplatehub)，然后选择**自定义模板**选项卡。然后，选择要删除的任务模板，然后选择**下一步**。
**注意**
删除是永久性的，任务模板不再显示在**自定义模板**选项卡。
# 使用创建自定义作业模板 AWS CLI
本主题介绍如何使用 AWS CLI创建、删除任务模板以及检索有关详细信息。
## 从头开始创建任务模板
以下 AWS CLI 命令显示如何使用存储在 S3 存储桶中的任务文档 (*job-document.json*) 和有权从 Amazon S3 下载文件的角色 (*S3DownloadRole*) 创建任务。
```
aws iot create-job-template \
--job-template-id 010 \
--description "My custom job template for updating the device firmware"
--document-source https://s3.amazonaws.com/amzn-s3-demo-bucket/job-document.json \
--timeout-config inProgressTimeoutInMinutes=100 \
--job-executions-rollout-config "{ \"exponentialRate\": { \"baseRatePerMinute\": 50, \"incrementFactor\": 2, \"rateIncreaseCriteria\": { \"numberOfNotifiedThings\": 1000, \"numberOfSucceededThings\": 1000}}, \"maximumPerMinute\": 1000}" \
--abort-config "{ \"criteriaList\": [ { \"action\": \"CANCEL\", \"failureType\": \"FAILED\", \"minNumberOfExecutedThings\": 100, \"thresholdPercentage\": 20}, { \"action\": \"CANCEL\", \"failureType\": \"TIMED_OUT\", \"minNumberOfExecutedThings\": 200, \"thresholdPercentage\": 50}]}" \
--presigned-url-config "{\"roleArn\":\"arn:aws:iam::123456789012:role/S3DownloadRole\", \"expiresInSec\":3600}"
```
可选的 `timeout-config` 参数指定每个设备完成任务运行所具有的时间。计时器在任务执行状态设置为 `IN_PROGRESS` 时启动。如果任务执行状态未在时间到期之前设置为其它最终状态，则会设置为 `TIMED_OUT`。
进行中的计时器无法更新，将应用到该任务的所有任务启动。每当任务启动保持`IN_PROGRESS`状态的时间超过此时间间隔时，任务启动就会失败并切换到终端`TIMED_OUT`状态。 AWS IoT 还会发布 MQTT 通知。
有关创建任务推出和中止相关配置的更多信息，请参阅[任务推出和中止配置](job-rollout-abort-scheduling.html)。
**注意**
在您创建任务时，系统会检索指定为 Amazon S3 文件的任务文档。如果在创建任务后更改任务文档源 Amazon S3文件的内容，发送到任务目标的内容不会更改。
## 从现有任务创建任务模板
以下 AWS CLI 命令通过指定现有任务的 Amazon 资源名称 (ARN) 来创建任务模板。新任务模板将使用任务中指定的所有配置。或者，您可以使用任何可选参数更改现有任务中的任何配置。
```
aws iot create-job-template \
--job-arn arn:aws:iot:region:123456789012:job/job-name \
--timeout-config inProgressTimeoutInMinutes=100
```
## 获取有关任务模板的详细信息
以下 AWS CLI 命令获取有关指定作业模板的详细信息。
```
aws iot describe-job-template \
--job-template-id template-id
```
该命令将显示以下输出。
```
{
"abortConfig": {
"criteriaList": [
{
"action": "string",
"failureType": "string",
"minNumberOfExecutedThings": number,
"thresholdPercentage": number
}
]
},
"createdAt": number,
"description": "string",
"document": "string",
"documentSource": "string",
"jobExecutionsRolloutConfig": {
"exponentialRate": {
"baseRatePerMinute": number,
"incrementFactor": number,
"rateIncreaseCriteria": {
"numberOfNotifiedThings": number,
"numberOfSucceededThings": number
}
},
"maximumPerMinute": number
},
"jobTemplateArn": "string",
"jobTemplateId": "string",
"presignedUrlConfig": {
"expiresInSec": number,
"roleArn": "string"
},
"timeoutConfig": {
"inProgressTimeoutInMinutes": number
}
}
```
## 列出任务模板
以下 AWS CLI 命令列出了您的所有作业模板 AWS 账户。
```
aws iot list-job-templates
```
该命令将显示以下输出。
```
{
"jobTemplates": [
{
"createdAt": number,
"description": "string",
"jobTemplateArn": "string",
"jobTemplateId": "string"
}
],
"nextToken": "string"
}
```
要检索其它结果页面，使用 `nextToken` 字段的值。
## 删除任务模板
以下 AWS CLI 命令删除指定的作业模板。
```
aws iot delete-job-template \
--job-template-id template-id
```
该命令不显示任何输出。
## 从自定义任务模板创建任务。
以下 AWS CLI 命令根据自定义作业模板创建作业。它的目标是名为 `thingOne` 的设备，并将指定任务模板的 Amazon Resource Name (ARN)，用作该任务的基础。您可以覆盖高级配置（如超时和取消配置），方法是传递 `create-job` 命令的关联参数。
**警告**
仅当从 AWS 托管式模板创建任务时，`document-parameters` 对象才能与 `create-job` 命令一起使用。此对象不得与自定义任务模板一起使用。有关演示如何使用此参数创建任务的示例，请参阅[使用托管模板创建任务](job-template-manage-cli-create.md#job-template-manage-cli-create-job)。
```
aws iot create-job \
--targets arn:aws:iot:region:123456789012:thing/thingOne \
--job-template-arn arn:aws:iot:region:123456789012:jobtemplate/template-id
```
# 任务 配置
对于部署到指定目标的每个任务，您可以拥有以下附加配置。
+ **推出**：定义了每分钟有多少台设备接收任务文档。
+ **计划**：除了使用定期维护时段外，还可针对将来的日期和时间计划任务。
+ **中止**：如果部分设备未收到任务通知或设备报告其任务执行失败，则取消任务。
+ **Timeout**（超时）：如果任务目标在其任务执行开始后的一段时间内没有响应，则任务可能会失败。
+ **重试**：如果设备在尝试完成任务执行时报告失败或任务执行超时，则重试任务执行。
通过使用这些配置，您可以监控任务执行状态，避免向整个实例集发送错误的更新。
**Topics**
+ [任务配置的工作原理](jobs-configurations-details.md)
+ [指定其他配置](jobs-configurations-specify.md)
# 任务配置的工作原理
您可以在部署任务时使用推出和中止配置，在执行任务时使用超时和重试配置。以下各部分显示了有关这些配置如何工作的更多信息。
**Topics**
+ [任务推出、计划和中止配置](#job-rollout-abort-scheduling)
+ [任务执行超时和重试配置](#job-timeout-retry)
## 任务推出、计划和中止配置
您可以使用任务推出、计划和中止配置来定义接收任务文档的设备数量、计划任务推出，并确定取消任务的条件。
### 任务推出配置
您可以指定向目标发送待处理任务执行通知的速度。您可以创建分段推出来管理更新、重启和其它操作。若要指定目标的通知方式，请使用任务推出速率。
#### 任务推出速率
您可以使用恒定推出速率或指数推出速率来创建推出配置。您可以使用恒定推出速率来指定每分钟可通知的最大任务目标数。
AWS IoT 当满足各种标准和阈值时，可以使用指数级部署率来部署工作。如果失败任务数与指定的一组条件相匹配，则您可以取消任务推出。在创建任务时，使用 [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionsRolloutConfig.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionsRolloutConfig.html) 对象设置任务推出速率条件。在创建任务时，使用 [https://docs.aws.amazon.com/iot/latest/apireference/API_AbortConfig.html](https://docs.aws.amazon.com/iot/latest/apireference/API_AbortConfig.html) 对象设置任务中止条件。
下面的示例显示推出速率的工作原理。例如，基本速率为每分钟 50 次、增量因子为 2、通知和成功设备数量各为 1000 的任务推出，其工作方式如下：该任务将以每分钟 50 次任务执行的速率开始，并以该速率继续工作，直到 1000 个事物收到任务执行通知，或发生了 1000 次成功的任务执行。
下表说明了推出将如何通过前四个增量继续。
| | | | | |
| --- |--- |--- |--- |--- |
| 每分钟的推出速率 | 50 | 100 | 200 | 400 |
| 满足速率提高的通知设备数或成功的任务执行 | 1000 | 2000 | 3000 | 4,000 |
**注意**
如果您的最大并发任务限制为 500 个 (`isConcurrent = True`)，则所有活动任务的状态将保持为 `IN-PROGRESS`，并且在并发任务数达到 499 个 (`isConcurrent = False)`) 之前，不会推出任何新任务执行。此规则适用于快照任务和连续任务。
如果 `isConcurrent = True`，表示该任务当前正在向目标组中的所有设备推出任务执行。如果 `isConcurrent = False`，则表示该任务已完成向目标组中的所有设备推出全部任务执行。如果您选择了任务中止配置，则当目标组中的所有设备都达到最终状态或目标组的阈值百分比时，任务将更新其状态。`isConcurrent = True` 和 `isConcurrent = False` 的任务级别状态都为 `IN_PROGRESS`。
有关活动和并发任务限制的更多信息，请参阅 [活动和并发任务限制](job-limits.md#job-limits-active-concurrent)。
#### 使用动态事物组的连续任务的任务推出速率
当你使用连续任务在队列上部署远程操作时，J AWS IoT obs 会为目标事物组中的设备推出任务执行。对于添加到动态事务组中的新设备，这些任务执行会继续推出到这些设备，甚至在创建任务之后也是如此。
推出配置只能控制在创建任务之前添加到组中的设备的推出速率。创建任务后，对于任何新设备，一旦设备加入目标组，就会立即近乎实时地创建任务执行。
### 任务计划配置
您可以使用预先确定的开始时间、结束时间和结束行为，最多提前一年安排连续任务或快照任务，以确定在到达结束时间后每个任务执行将发生的情况。此外，您可以创建一个可选的定期维护时段，该时段具有灵活的频率、开始时间和持续时间，以供连续任务将任务文档推出到目标组中的所有设备。
#### 任务计划配置
**开始时间**
计划任务的开始时间是该任务开始向目标组中的所有设备推出任务文档的未来日期和时间。计划任务的开始时间适用于连续任务和快照任务。在最初创建计划任务时，该任务保持 `SCHEDULED` 状态。到达您选择的 `startTime` 后，任务将更新为 `IN_PROGRESS` 并开始推出任务文档。`startTime` 必须小于或等于自您创建计划任务的初始日期和时间起一年。
有关使用 API 命令或`startTime`时的语法的更多信息 AWS CLI，请参阅[时间戳](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-parameters-types.html#parameter-type-timestamp)。
对于具有可选计划配置的任务，且该任务在定期维护时段内在采用夏令时（DST）的位置发生，从 DST 切换到标准时间和从标准时间切换到 DST 时，时间将变动一小时。
**注意**
中显示的时区 AWS 管理控制台 是您当前的系统时区。但是，这些时区将在系统中转换为 UTC。
**结束时间**
计划任务的结束时间是该任务停止向目标组中的任何剩余设备推出任务文档的未来日期和时间。计划任务的结束时间适用于连续任务和快照任务。在计划任务达到所选的 `endTime` 并且所有任务执行都达到最终状态后，它会将其状态从 `IN_PROGRESS` 更新为 `COMPLETED`。`endTime` 必须小于或等于自您创建计划任务的初始日期和时间起两年。介于 `startTime` 和 `endTime` 之间的最短持续时间为 30 分钟。将重试任务执行，直到任务达到 `endTime`，然后 `endBehavior` 将决定如何继续。
有关使用 API 命令或`endTime`时的语法的更多信息 AWS CLI，请参阅[时间戳](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-parameters-types.html#parameter-type-timestamp)。
对于具有可选计划配置的任务，且该任务在定期维护时段内在采用夏令时（DST）的位置发生，从 DST 切换到标准时间和从标准时间切换到 DST 时，时间将变动一小时。
**注意**
中显示的时区 AWS 管理控制台 是您当前的系统时区。但是，这些时区将在系统中转换为 UTC。
**结束行为**
计划任务的结束行为决定了当任务达到所选的 `endTime` 时，任务执行和所有未完成的任务执行会发生什么情况。
以下列出了创建任务或任务模板时可以选择的结束行为：
+ `STOP_ROLLOUT`
+ `STOP_ROLLOUT` 会停止向任务的目标组中的所有剩余设备推出任务文档。此外，所有 `QUEUED` 和 `IN_PROGRESS` 任务执行都将继续，直到达到最终状态。除非选择 `CANCEL` 或 `FORCE_CANCEL`，否则这是默认结束行为。
+ `CANCEL`
+ `CANCEL` 会停止向任务的目标组中的所有剩余设备推出任务文档。此外，所有 `QUEUED` 任务执行都将被取消，而所有 `IN_PROGRESS` 任务执行都将继续，直到达到终止状态。
+ `FORCE_CANCEL`
+ `FORCE_CANCEL` 会停止向任务的目标组中的所有剩余设备推出任务文档。此外，所有 `QUEUED` 和 `IN_PROGRESS` 任务执行都将被取消。
**注意**
必须选择 `endtime` 才能选择 `endbehavior`
**最长持续时间**
无论 `startTime` 和 `endTime` 如何，计划任务的最长持续时间都必须小于或等于两年。
下表列出了计划任务的常见持续时间场景：
| **计划任务示例编号** | **startTime** | **endTime** | **最长持续时间** |
| --- | --- | --- | --- |
| 1 | 在初始任务创建后立即。 | 在初始任务创建后一年。 | 一年 |
| 2 | 在初始任务创建后一个月。 | 在初始任务创建后 13 个月。 | 一年 |
| 3 | 在初始任务创建后一年。 | 在初始任务创建后两年。 | 一年 |
| 4 | 在初始任务创建后立即。 | 在初始任务创建后两年。 | 两年 |
#### 定期维护时段
维护时段是 AWS 管理控制台 和中的调度配置`SchedulingConfig`中的`CreateJob`可选配置`CreateJobTemplate` APIs。您可以设置定期维护时段，其中包含预先确定的开始时间、持续时间和维护时段发生的频率（每天、每周或每月）。维护时段仅适用于连续任务。定期维护时段的最长持续时间为 23 小时 50 分钟。
下图显示了具有可选维护时段的各种计划任务场景的任务状态：
![\[显示发生某些事件后一个连续任务生命周期的示意图，状态从 SCHEDULED、IN_PROGRESS、CANCELLED 到 DELETION_IN_PROGRESS 不断转换。\]](http://docs.aws.amazon.com/zh_cn/iot/latest/developerguide/images/job-states-diagram-scheduled-maintenance-window.png)
有关任务状态的更多信息，请参阅 [任务和任务执行状态](iot-jobs-lifecycle.md)。
**注意**
如果任务在维护时段内达到 `endTime`，它将从 `IN_PROGRESS` 更新为 `COMPLETED`。此外，任何剩余的任务执行都将遵循任务的 `endBehavior`。
**Cron 表达式**
对于在维护时段内以自定义频率推出任务文档的计划任务，使用 cron 表达式输入自定义频率。Cron 表达式有六个必填字段，字段之间以空格分隔。
**语法**
```
cron(fields)
```
| **字段** | **值** | **通配符** |
| --- | --- | --- |
| Minutes | 0-59 | , - \$1 / |
| Hours | 0-23 | , - \$1 / |
| D ay-of-month | 1-31 | , - \$1 ? / L W |
| Month | 1-12 或 JAN-DEC | , - \$1 / |
| D ay-of-week | 1-7 或 SUN-SAT | , - \$1 ? L \$1 |
| Year | 1970-2199 | , - \$1 / |
**通配符**
+ **,**（逗号）通配符包含其他值。在“月份”字段中，JAN、FEB 和 MAR 将包含 January、February 和 March。
+ **-**（破折号）通配符用于指定范围。在“日”字段中，1-15 将包含指定月份的 1 - 15 日。
+ **\$1**（星号）通配符包含该字段中的所有值。在“小时”字段中，**\$1** 将包含每个小时。不能在 Day-of-month和 Day-of-week字段中同时使用 **\$1**。如果您在一个中使用它，则必须在另一个中使用 **?** 。
+ **/**（正斜杠）通配符用于指定增量。在“分钟”字段中，您可以输入 1/10 以指定从一个小时的第一分钟开始的每个第十分钟（例如，第 11 分钟、第 21 分钟和第 31 分钟，依此类推）。
+ **?**（问号）通配符用于指定一个或另一个。在 Day-of-month字段中，你可以输入 **7**，如果你不在乎 7 号是一周中的哪一天，你可以输入**？** 在 Day-of-week野外。
+ ** 或 ** 字段中的 Day-of-monthL Day-of-week 通配符用于指定月或周的最后一天。
+ 该 Day-of-month字段中的**W**通配符指定工作日。在该 Day-of-month字段中，**3W**指定最接近该月第三天的工作日。
+ Day-of-week字段中的 **\$1** 通配符指定一个月内一周中指定某一天的特定实例。例如，3\$12 指该月的第二个星期二：3 指的是星期二，因为它是每周的第三天，2 是指该月内该类型的第二天。
**注意**
如果使用 '\$1' 字符，则只能在 day-of-week字段中定义一个表达式。例如，`"3#1,6#3"` 是无效的，因为它被解释为两个表达式。
**限制**
+ 您无法在同一 cron 表达式中为 Day-of-month 和 Day-of-week 字段同时指定值。如果您在其中一个字段中指定了值（或一个 \$1），则必须在另一个字段中使用 **?**。
**示例**
在为定期维护时段的 `startTime` 使用 cron 表达式时，请参阅以下示例 cron 字符串。
| **分钟** | **小时** | **日期** | **月份** | **星期几** | **年** | **意义** |
| --- | --- | --- | --- | --- | --- | --- |
| 0 | 10 | \$1 | \$1 | ? | \$1 | 每天上午的 10:00（UTC）运行 |
| 15 | 12 | \$1 | \$1 | ? | \$1 | 每天在下午 12:15（UTC）运行 |
| 0 | 18 | ? | \$1 | MON-FRI | \$1 | 每星期一到星期五的下午 6:00（UTC）运行 |
| 0 | 8 | 1 | \$1 | ? | \$1 | 每月第 1 天上午 8:00（UTC）运行 |
#### 定期维护时段持续时间结束逻辑
当维护时段期间的任务推出达到当前维护时段事件持续时间结束时，将发生以下操作：
+ 任务将停止所有向目标组中的任何剩余设备推出任务文档的过程。它将在下一个维护时段的 `startTime` 继续运行。
+ 所有状态为 `QUEUED` 的任务执行都将保持 `QUEUED` 状态，直到下一个维护时段事件的 `startTime` 为止。在下一个时段中，当设备准备好开始执行在任务文档中指定的操作时，任务可以切换到 `IN_PROGRESS`。
+ 所有状态为 `IN_PROGRESS` 的任务执行都将继续执行在任务文档中指定的操作，直到它们达到最终状态。`JobExecutionsRetryConfig` 中指定的任何重试都将在下一个维护时段的 `startTime` 进行。
### 任务中止配置
使用此配置可创建条件，以便设备的阈值百分比符合该条件时取消任务。例如，在以下情况，您可以使用此配置取消任务：
+ 当一定比例的设备未收到任务执行通知时，例如当您的设备不兼容 Over-The-Air (OTA) 更新时。在这种情况下，设备可以报告 `REJECTED` 状态。
+ 设备的阈值百分比报告其任务执行失败时，例如设备尝试从 Amazon S3 URL 下载任务文档时发生连接中断。在这种情况下，设备必须进行编程，才能向 AWS IoT报告 `FAILURE` 状态。
+ 任务执行开始后，由于任务执行超时达到设备的某个阈值百分比而报告 `TIMED_OUT` 状态时。
+ 出现多次重试失败时。添加重试配置时，每次重试都可能让您的 AWS 账户产生额外费用。在这种情况下，取消任务可以取消排队的任务执行，避免重试这些执行。有关重试配置以及其与中止配置搭配使用的更多信息，请参阅 [任务执行超时和重试配置](#job-timeout-retry)。
您可以使用 AWS IoT 控制台或 Jobs API 设置 AWS IoT 任务中止条件。
## 任务执行超时和重试配置
当任务执行的时间超过设置的持续时间时，系统使用任务执行超时配置向您发送 [任务通知](jobs-comm-notifications.md)。如果任务失败或超时，系统会使用任务执行重试配置来重试执行。
### 任务执行超时配置
只要任务执行卡在 `IN_PROGRESS` 状态的时间超出预期，系统便会使用任务执行超时配置通知您。任务处于 `IN_PROGRESS` 状态时，您可以监控任务执行的进度。
#### 任务超时计时器
有两种类型的计时器：进行中计时器和步骤计时器。
**进行中计时器**
创建任务或任务模板时，您可以为进行中计时器指定介于 1 分钟到 7 天之间的值。在任务执行开始之前，您可以更新此计时器的值。计时器启动后便无法更新，且计时器值应用于任务的所有任务执行。每当任务执行保持`IN_PROGRESS`状态的时间超过此时间间隔时，任务执行就会失败并切换到终端`TIMED_OUT`状态。 AWS IoT 还会发布 MQTT 通知。
**步骤计时器**
您还可以设置仅适用于要更新的任务执行的步骤计时器。这种计时器不会对进行中计时器产生影响。您每次更新任务执行时，都可以为此步骤计时器设置新值。为事物启动下一个待处理任务执行时，您还可以创建新的步骤计时器。如果任务执行保持在 `IN_PROGRESS` 状态的时间长度超过了此步骤计时器间隔，它将失败，并切换为最终 `TIMED_OUT` 状态。
**注意**
您可以使用 AWS IoT 控制台或 AWS IoT Jobs API 设置进行中的计时器。若要指定步骤计时器，请使用 API。
#### 任务超时计时器工作原理
下图说明了进行中超时计时器与步骤超时计时器在 20 分钟超时期限内相互作用的方式。
![\[显示 20 分钟进行中计时器的时间线，嵌套步进计时器分别为 7、5 和 8 分钟。\]](http://docs.aws.amazon.com/zh_cn/iot/latest/developerguide/images/timeout-diagram.png)
下面介绍了不同步骤：
1.
**12:00**
此时会创建一个新任务，还会在创建任务时启动 20 分钟的进行中计时器。进行中计时器开始运行，任务执行切换到 `IN_PROGRESS` 状态。
1.
**12:05 PM**
此时会创建一个值为 7 分钟的新步骤计时器。任务执行现在会在 12:12 PM 超时。
1.
**12:10 PM**
此时会创建一个值为 5 分钟的新步骤计时器。创建新步骤计时器后，系统会丢弃旧步骤计时器，任务执行现在会在 12:15 PM 超时。
1.
**12:13 PM**
此时会创建一个值为 9 分钟的新步骤计时器。系统会丢弃旧步骤计时器，任务执行现在会在 12:20 PM 超时，因为进行中计时器会在 12:20 PM 超时。步骤计时器不能超过进行中计时器的绝对界限。
### Job 执行重试配置
您可以在满足某组条件时使用重试配置来重试任务执行。如果任务超时或设备报告失败，就可以尝试重试。如果要因超时错误重试执行，则必须启用超时配置。
**如何使用重试配置**
使用以下步骤重试配置：
1. 确定是否对 `FAILED`、`TIMED_OUT` 或这两种失败条件使用重试配置。对于`TIMED_OUT`状态，在报告状态后， AWS IoT Jobs 会自动重试设备执行任务。
1. 对于 `FAILED` 状态，请检查是否可以重试任务执行失败。如果可以重试，请对设备进行编程，以便向 AWS IoT报告 `FAILURE` 状态。以下部分介绍了有关可重试和不可重试失败的更多信息。
1. 使用前述的信息指定每种失败类型的重试次数。最多可以为单台设备的两种失败类型组合指定 10 次重试。当执行成功或达到指定的尝试次数时，重试尝试会自动停止。
1. 添加中止配置，以便在重复出现重试失败时取消任务，以避免大量重试产生额外费用。
**注意**
当任务达到定期维护时段事件结束时，所有 `IN_PROGRESS` 任务执行都将继续执行在任务文档中确定的操作，直到它们达到最终状态。如果任务执行在维护时段之外达到最终状态 `FAILED` 或 `TIMED_OUT`，则当尝试次数未耗尽时，将在下一个时段中尝试进行重试。在下一个维护时段事件的 `startTime`，将创建一个新的任务执行并进入 `QUEUED` 状态，直到设备准备好开始为止。
**重试和中止配置**
每次重试都会向您收取额外费用。 AWS 账户为避免重复出现的重试失败产生额外费用，我们建议添加中止配置。有关定价的更多信息，请参阅 [AWS IoT Device Management 定价](https://aws.amazon.com/iot-device-management/pricing/)。
当设备的高阈值百分比超时或报告失败时，您就可能遇到多次重试失败。在这种情况下，您可以使用中止配置取消任务，避免任何排队的任务执行或更多重试尝试。
**注意**
符合取消任务执行的中止条件仅会取消 `QUEUED` 任务执行。系统不会尝试设备的任何排队重试。不过，当前具有 `IN_PROGRESS` 状态的任务执行不会遭到取消。
在重试失败的任务执行之前，我们还建议您检查任务执行失败是否可以重试，如下面的部分所述。
**`FAILED` 失败类型重试**
若要重试 `FAILED` 失败类型，就必须对设备进行编程，以便向 `FAILURE` 报告失败任务执行 AWS IoT状态。使用重试 `FAILED` 任务执行的条件来设置重试配置，并指定要执行的重试次数。当 AWS IoT Jobs 检测到`FAILURE`状态时，它将自动尝试重试设备执行作业。任务执行成功或达到最大重试次数，重试才会停止。
您可以跟踪每次重试以及在这些设备上运行的任务。通过跟踪执行状态，您可以在达到指定的重试次数后，使用设备报告失败以及发起另一次重试。
**可重试和不可重试失败**
任务执行失败可以是可重试或不可重试的失败。每次重试都会让您的 AWS 账户产生费用。为避免因多次重试而产生额外费用，请先检查任务执行失败是否可以重试。可重试失败示例包括设备尝试从 Amazon S3 URL 下载任务文档时发生的连接错误。如果任务执行失败是可重试的，可对设备进行编程，以便在出现任务执行失败时报告 `FAILURE` 状态。然后，将重试配置设置为重试 `FAILED` 执行。
如果执行不可重试，为避免重试以及可能让您的账户产生额外费用，我们建议您对设备进行编程以向 AWS IoT报告 `REJECTED` 状态。不可重试失败的示例包括：设备与接收任务更新不兼容，或执行任务时遇到内存错误。在这些情况下， AWS IoT Jobs 不会重试任务执行，因为它只有在检测到`FAILED`或`TIMED_OUT`状态时才会重试任务执行。
在确定任务执行失败可重试后，如果重试仍然失败，请考虑检查设备日志。
**注意**
当具有可选计划配置的任务达到其 `endTime` 时，所选的 `endBehavior` 将停止向目标组中的所有剩余设备推出任务文档，并指示如何继续剩余的任务执行。如果通过重试配置选择了这些尝试，则会重试这些尝试。
**`TIMEOUT` 失败类型重试**
如果您在创建任务时启用超时，则 AWS IoT 当状态从`IN_PROGRESS`变为时，任务将尝试重试设备执行任务。`TIMED_OUT`如果进行中计时器超时，或者您指定的步骤计时器处于 `IN_PROGRESS` 中然后超时，此状态可能会发生更改。任务执行成功或达到此失败类型的最大重试次数后，重试才会停止。
**持续任务和事物组成员资格更新**
对于任务状态为 `IN_PROGRESS` 的连续任务，当事物的组成员资格更新时，重试次数将重置为零。例如，假设您指定了五次重试，并且已经执行了三次重试。如果现已从事物组中删除事物，然后该事物重新加入该组（例如动态事物组），则重试次数将重置为零。您现在可以对事物组执行五次重试，而非剩余的两次重试。此外，从事物组中删除事物将取消其他重试次数。
# 指定其他配置
您可以在创建任务或任务模板时指定其他配置。下文介绍了何时可以指定这些配置。
+ 创建自定义任务模板时。从模板创建任务时，系统会保存您指定的其他配置设置。
+ 使用任务文件创建自定义任务时。任务文件可以是在 S3 存储桶中上传的 JSON 文件。
+ 使用自定义任务模板创建自定义任务时。如果模板已经指定了这些设置，则可以重复使用，也可以通过指定新的配置设置将其覆盖。
+ 使用 AWS 托管模板创建自定义作业时。
**Topics**
+ [使用指定作业配置 AWS 管理控制台](job-configurations-console.md)
+ [使用作业 API 指定 AWS IoT 任务配置](job-configurations-api.md)
# 使用指定作业配置 AWS 管理控制台
您可以使用 AWS IoT 控制台为任务添加不同的配置。创建任务后，您可以在任务详细信息页面上查看任务配置的状态详细信息。有关不同配置及其工作方式的更多信息，请参阅 [任务配置的工作原理](jobs-configurations-details.md)。
创建任务或任务模板时添加任务配置。
**创建自定义任务模板时**
创建自定义任务模板时指定推出配置
1. 转到[AWS IoT 控制台的作业模板中心，](https://console.aws.amazon.com/iot/home#/jobtemplatehub)然后选择**创建作业模板**。
1. 指定任务模板属性、提供任务文档、展开要添加的配置，然后指定配置参数。
**创建自定义任务**
创建自定义任务时指定推出配置
1. 前往[AWS IoT 控制台的 Job 中心](https://console.aws.amazon.com/iot/home#/jobhub)并选择 C **reate job**。
1. 请选择 **Create a custom job**（创建自定义任务），指定任务属性、目标，然后指定任务文档使用任务文件还是模板。您可以使用自定义模板或 AWS 托管模板。
1. 请选择任务配置，展开 **Rollout configuration**（推出部署），再在其中指定使用 **Constant rate**（恒定速率）或 **Exponential rate**（指数速率）。然后，指定配置参数。
下一部分介绍可以为每个配置指定的参数。
## 推出配置
您可以指定使用恒定推出速率还是指数速率。
+
**设置恒定推出速率**
要为任务执行设置固定速率，请选择**固定速率**，然后为速率上限指定**每分钟最大值**。此值为可选值，范围从 1 到 1000。如果不设置该值，则会使用 1000 作为默认值。
+
**设置指数推出速率**
若要设置指数速率，请选择 **Exponential rate**（指数速率），然后指定这些参数：
+
**每分钟的基本速率**
指**通知的设备数**或**成功的设备数量**阈值满足**速率提高标准**之前，执行任务的速率。
+
**增量因子**
指 **Number of notified devices**（通知设备数）或 **Number of succeeded devices**（成功设备数）阈值满足 **Rate increase criteria**（速率增加条件）之后，推出速率增加的指数因子。
+
**速率增加条件**
**Number of notified devices**（通知设备数）或 **Number of succeeded devices**（成功设备数）的阈值。
## 中止配置
请选择**添加新配置**，然后为每个配置指定以下参数：
+
**失败类型**
指定启动任务中止的失败类型。其中包括 **FAILED**（失败）、**REJECTED**（已被拒绝）、**TIMED\$1OUT**（超时）或 **ALL**（全部）。
+
**增量因子**
指定在满足任务中止条件之前必须完成的任务执行数量。
+
**阈值百分比**
指定启动任务中止的已执行事物的总数。
## 计划配置
每项任务可以在初始创建时立即启动，计划在以后的日期和时间启动，也可以在定期维护时段进行。
请选择**添加新配置**，然后为每个配置指定以下参数：
+
**任务开始**
指定任务开始的日期和时间。
+
**定期维护时段**
定期维护时段定义了任务可以将任务文档部署到任务中的目标设备的具体日期和时间。维护时段可以按每天、每周、每月重复，也可以按自定义日期和时间重复。
+
**任务结束**
指定任务结束的日期和时间。
+
**任务结束行为**
为所有未完成的任务执行选择任务结束时的结束行为。
**注意**
当具有可选计划配置和所选结束时间的任务达到结束时间时，该任务将停止向目标组中的所有剩余设备进行推出。它还利用所选的结束行为，来决定如何继续剩余的任务执行以及根据重试配置进行重试。
## 超时配置
默认无超时，任务运行会遭到取消或删除。要使用超时，请选择**启用超时**，然后指定 1 分钟到 7 天之间的超时值。
## 重试配置
**注意**
创建任务后，便无法更新重试次数。您只能删除所有失败类型的重试配置。创建任务时，请考虑为配置采用适当的重试次数。为避免因潜在的重试失败产生额外成本，请添加中止配置。
请选择 **Add new configuration**（添加新配置），然后为每个配置指定以下参数：
+
**失败类型**
指定应触发任务执行重试的失败类型。其中包括 **Failed**（失败）、**Timeout**（超时）和 **All**（全部）。
+
**重试次数**
请为所选择的 **Failure type**（失败类型）指定重试次数。最多可以为两种失败类型组合指定 10 次重试。
# 使用作业 API 指定 AWS IoT 任务配置
您可以使用[CreateJob](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html)或 [CreateJobTemplate](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html)API 来指定不同的任务配置。以下各节介绍如何添加这些配置。添加配置后，您可以使用[JobExecutionSummary](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummary.html)和[JobExecutionSummaryForJob](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummaryForJob.html)来查看其状态。
有关不同配置及其工作方式的更多信息，请参阅 [任务配置的工作原理](jobs-configurations-details.md)。
## 推出配置
您可以为推出配置指定恒定推出速率或指数推出速率。
+
**设置恒定推出速率**
若要设置恒定推出速率，请使用 [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionsRolloutConfig.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionsRolloutConfig.html) 对象将 `maximumPerMinute` 参数添加到 `CreateJob` 请求。该参数会指定任务执行的速率上限。此值为可选值，范围从 1 到 1000。如果不设置该值，则会使用 1000 作为默认值。
```
"jobExecutionsRolloutConfig": {
"maximumPerMinute": 1000
}
```
+
**设置指数推出速率**
若要设置任务可变推出速率，请使用 [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionsRolloutConfig.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionsRolloutConfig.html) 对象。您可以在运行 `ExponentialRolloutRate` API 操作时配置 `CreateJob` 属性。以下示例使用 `exponentialRate` 参数设置指数推出速率。有关这些参数的更多信息，请参阅[https://docs.aws.amazon.com/iot/latest/apireference/API_ExponentialRolloutRate.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ExponentialRolloutRate.html)。
```
{
...
"jobExecutionsRolloutConfig": {
"exponentialRate": {
"baseRatePerMinute": 50,
"incrementFactor": 2,
"rateIncreaseCriteria": {
"numberOfNotifiedThings": 1000,
"numberOfSucceededThings": 1000
},
"maximumPerMinute": 1000
}
}
...
}
```
其中，参数：
**baseRatePer分钟**
指定达到 `numberOfNotifiedThings` 或 `numberOfSucceededThings` 阈值之前任务的执行速率。
**incrementFactor**
指定达到 `numberOfNotifiedThings` 或 `numberOfSucceededThings` 阈值之后推出速率增加的指数因子。
**rateIncreaseCriteria**
指定 `numberOfNotifiedThings` 或 `numberOfSucceededThings` 阈值。
## 中止配置
要使用 API 添加此配置，请在运行 [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html) 或 [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html) API 操作时指定 [https://docs.aws.amazon.com/iot/latest/apireference/API_AbortConfig.html](https://docs.aws.amazon.com/iot/latest/apireference/API_AbortConfig.html) 参数。以下示例介绍了任务推出的中止配置，该任务经历了如 `CreateJob` API 操作指定的多次失败执行。
**注意**
删除任务执行会影响已完成执行总数的计算值。当任务中止时，服务会创建自动的 `comment` 和 `reasonCode` 以将用户驱动的取消与任务中止取消区分开来。
```
"abortConfig": {
"criteriaList": [
{
"action": "CANCEL",
"failureType": "FAILED",
"minNumberOfExecutedThings": 100,
"thresholdPercentage": 20
},
{
"action": "CANCEL",
"failureType": "TIMED_OUT",
"minNumberOfExecutedThings": 200,
"thresholdPercentage": 50
}
]
}
```
其中，参数：
**action**
指定满足中止条件时要采取的操作。此参数是必需的，并且 `CANCEL` 是唯一的有效值。
**failureType**
指定哪种失败类型应启动任务中止。有效值为 `FAILED`、`REJECTED`、`TIMED_OUT` 和 `ALL`。
**minNumberOfExecutedThings**
指定在满足任务中止条件之前必须完成的任务执行数量。在此示例中， AWS IoT 直到至少 100 个设备已完成任务执行时才检查是否应执行任务中止。
**thresholdPercentage**
指定可启动任务中止的已执行任务的事物总数。在此示例中，如果达到阈值百分比，则按顺序 AWS IoT 检查并启动任务中止。如果完成 100 次执行后至少有 20% 的完整执行失败，则会取消任务推出。如果不符合此标准， AWS IoT 则检查是否有至少 50% 的已完成执行在 200 次执行完成后超时。如果是这样，则会取消任务推出。
## 计划配置
要使用此 API 添加此配置，请在运行 [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html) 或 [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html) API 操作时指定可选的 [https://docs.aws.amazon.com/iot/latest/apireference/API_SchedulingConfig.html](https://docs.aws.amazon.com/iot/latest/apireference/API_SchedulingConfig.html)。
```
"SchedulingConfig": {
"endBehavior": string
"endTime": string
"maintenanceWindows": string
"startTime": string
}
```
其中，参数：
**startTime**
指定任务开始的日期和时间。
**endTime**
指定任务结束的日期和时间。
**maintenanceWindows**
指定是否为计划任务选择了可选维护时段，以便将任务文档推出到目标组中的所有设备。的字符串格式`maintenanceWindow`YYYY/MM/DD为日期，hh: mm 表示时间。
**endBehavior**
指定计划任务到达 `endTime` 时的任务行为。
**注意**
作业`SchedulingConfig`的可选内容可在[https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJob.html)和[https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobTemplate.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobTemplate.html) APIs中查看。
## 超时配置
要使用 API 添加此配置，请在运行 [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html) 或 [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html) API 操作时指定 [https://docs.aws.amazon.com/iot/latest/apireference/API_TimeoutConfig.html](https://docs.aws.amazon.com/iot/latest/apireference/API_TimeoutConfig.html) 参数。
使用超时配置
1. 要在创建作业或作业模板时设置正在进行的计时器，请为可选[TimeoutConfig](https://docs.aws.amazon.com//iot/latest/apireference/API_TimeoutConfig.html)对象的`inProgressTimeoutInMinutes`属性设置一个值。
```
"timeoutConfig": {
"inProgressTimeoutInMinutes": number
}
```
1. 要为任务执行指定步数计时器，请为调用`stepTimeoutInMinutes`时设置一个值[UpdateJobExecution](https://docs.aws.amazon.com//iot/latest/apireference/API_iot-jobs-data_UpdateJobExecution.html)。步骤计时器仅应用于您更新的任务执行。您每次更新任务执行时，可以为此计时器设置新值。
**注意**
`UpdateJobExecution` 可以通过创建新的值为 -1 的步骤计时器来丢弃已经创建的步骤计时器。
```
{
...
"statusDetails": {
"string" : "string"
},
"stepTimeoutInMinutes": number
}
```
1. 要创建新的步数计时器，您也可以调用 [StartNextPendingJobExecution](https://docs.aws.amazon.com//iot/latest/apireference/API_iot-jobs-data_StartNextPendingJobExecution.html)API 操作。
## 重试配置
**注意**
创建任务时，请考虑为配置采用适当的重试次数。为避免因潜在的重试失败产生额外成本，请添加中止配置。创建任务后，便无法更新重试次数。您只能使用 [UpdateJob](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateJob.html)API 操作将重试次数设置为 0。
要使用 API 添加此配置，请在运行 [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html) 或 [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html) API 操作时指定 [https://docs.aws.amazon.com/iot/latest/apireference/API_jobExecutionsRetryConfig.html](https://docs.aws.amazon.com/iot/latest/apireference/API_jobExecutionsRetryConfig.html) 参数。
```
{
...
"jobExecutionsRetryConfig": {
"criteriaList": [
{
"failureType": "string",
"numberOfRetries": number
}
]
}
...
}
```
其中 **criteriaList** 是指定条件列表的数组，用于确定任务的每种失败类型允许的重试次数。
# 设备和任务
设备可以使用 MQTT、HTTP 签名版本 4 或 HTTP TLS 与AWS IoT任务通信。要确定您的设备与 AWS IoT Jobs 通信时要使用的终端节点，请运行**DescribeEndpoint**命令。例如，如果您运行此命令：
```
aws iot describe-endpoint --endpoint-type iot:Data-ATS
```
您会获得与以下内容相似的结果：
```
{
"endpointAddress": "a1b2c3d4e5f6g7-ats.iot.us-west-2.amazonaws.com"
}
```
## 使用 MQTT 协议
设备可以使用 MQTT 协议与AWS IoT任务通信。设备订阅 MQTT 主题是为了收到有关新任务的通知并接收来自AWS IoT任务服务的响应。设备在 MQTT 主题上发布以查询或更新任务启动的状态。每台设备都有自己的一般 MQTT 主题。有关发布和订阅 MQTT 主题的更多信息，请参阅 [设备通信协议](protocols.md)。
通过这种通信方式，您的设备使用其设备专用证书和私钥向 Jobs 进行AWS IoT身份验证。
您的设备可以订阅以下主题。`thing-name` 是与设备关联的事物名称。
+
**`$aws/things/thing-name/jobs/notify`**
订阅此主题，以便在待处理任务启动列表中添加或删除任务启动时接收通知。
+
**`$aws/things/thing-name/jobs/notify-next`**
订阅此主题，以在下一个待处理任务执行发生更改时通知您。
+
**`$aws/things/thing-name/jobs/request-name/accepted`**
AWS IoT作业服务发布有关 MQTT 主题的成功和失败消息。通过将 `accepted` 或 `rejected` 追加到用于发出请求的主题来构成该主题。这里，`request-name`是请求的名称，例如`Get`，主题可以是：`$aws/things/myThing/jobs/get`。 AWS IoT然后，Jobs 会发布有关该`$aws/things/myThing/jobs/get/accepted`主题的成功消息。
+
**`$aws/things/thing-name/jobs/request-name/rejected`**
此处，`request-name` 是请求的名称，例如 `Get`。如果请求失败，AWS IoTJobs 将发布有关该`$aws/things/myThing/jobs/get/rejected`主题的失败消息。
您还可以使用以下 HTTPS API 操作：
+ 通过调用 [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_UpdateJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_UpdateJobExecution.html) API 来更新任务执行的状态。
+ 通过调用 [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html) API 来查询任务执行的状态。
+ 通过调用 [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_GetPendingJobExecutions.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_GetPendingJobExecutions.html) API 来检索待处理任务执行的列表。
+ 通过使用 `jobId` 作为 `$next` 调用 [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html) API 来检索下一个待定任务执行。
+ 通过调用 [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_StartNextPendingJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_StartNextPendingJobExecution.html) API 来获取和开启下一个待处理任务执行。
## 使用 HTTP Signature 版本 4
设备可以在端口 443 上使用 HTTP 签名版本 4 与 AWS IoT Job 通信。这是AWSSDKs 和 CLI 使用的方法。有关这些工具的更多信息，请参阅[AWS CLI命令参考： iot-jobs-data](https://docs.aws.amazon.com/cli/latest/reference/iot-jobs-data/index.html)或[AWSSDKs 和工具](https://aws.amazon.com/tools/#sdk)，并参考您的首选语言 IotJobsDataPlane 部分。
通过这种通信方式，您的设备使用 IAM 凭证通过 AWS IoT Jobs 进行身份验证。
可以使用此方法执行以下命令：
+ **DescribeJobExecution**
`aws iot-jobs-data describe-job-execution ...`
+ **GetPendingJobExecutions**
`aws iot-jobs-data get-pending-job-executions ...`
+ **StartNextPendingJobExecution**
`aws iot-jobs-data start-next-pending-job-execution ...`
+ **UpdateJobExecution**
`aws iot-jobs-data update-job-execution ...`
## 使用 HTTP TLS
设备可以使用支持该协议的第三方软件客户端，在端口 8443 上使用 HTTP TLS 与 AWS IoT Jobs 通信。
利用此方法，您的设备可使用基于 X.509 证书的身份验证（例如，其特定于设备的证书和私有密钥）。
可以使用此方法执行以下命令：
+ **DescribeJobExecution**
+ **GetPendingJobExecutions**
+ **StartNextPendingJobExecution**
+ **UpdateJobExecution**
## 对设备进行编程以使用任务
本部分中的示例使用 MQTT 来演示设备如何使用 AWS IoT Jobs 服务。或者，您也可以使用相应的 API 或 CLI 命令。对于这些示例，我们假定名为 `MyThing` 的设备订阅以下 MQTT 主题：
+ `$aws/things/MyThing/jobs/notify` – 、 或 `$aws/things/MyThing/jobs/notify-next`
+ `$aws/things/MyThing/jobs/get/accepted`
+ `$aws/things/MyThing/jobs/get/rejected`
+ `$aws/things/MyThing/jobs/jobId/get/accepted`
+ `$aws/things/MyThing/jobs/jobId/get/rejected`
如果您使用代码签名AWS IoT，则您的设备代码必须验证代码文件的签名。该签名在任务文档中的 `codesign` 属性内。有关验证代码文件签名的更多信息，请参阅[设备代理示例](https://github.com/aws/aws-iot-device-sdk-js#jobsAgent)。
**Topics**
+ [对设备进行编程以使用任务](#programming-devices)
+ [设备工作流程](jobs-workflow-device-online.md)
+ [任务流](jobs-workflow-jobs-online.md)
+ [任务通知](jobs-comm-notifications.md)
# 设备工作流程
设备可以使用以下任一方式处理它运行的任务。
+
**获取下一个任务**
1. 当设备首次联机时，它应订阅设备的 `notify-next` 主题。
1. 使用 jobId `$next` 调用 [DescribeJobExecution](jobs-mqtt-api.md#mqtt-describejobexecution) MQTT API 以获取下一个任务、其任务文档和其他详细信息，包括保存在 `statusDetails` 中的任何状态。如果任务文档具有代码文件签名，则您必须验证签名，然后才能继续处理任务请求。
1. 调用 [UpdateJobExecution](jobs-mqtt-api.md#mqtt-updatejobexecution) MQTT API 以更新任务状态。或者，要在一个调用中将此步骤与上一步骤合并，设备可调用 [StartNextPendingJobExecution](jobs-mqtt-api.md#mqtt-startnextpendingjobexecution)。
1. （可选）您可在调用 [UpdateJobExecution](jobs-mqtt-api.md#mqtt-updatejobexecution) 或 [StartNextPendingJobExecution](jobs-mqtt-api.md#mqtt-startnextpendingjobexecution) 时为 `stepTimeoutInMinutes` 设置值来添加步骤计时器。
1. 使用 [UpdateJobExecution](jobs-mqtt-api.md#mqtt-updatejobexecution) MQTT API 执行任务文档所指定的操作以报告任务的进度。
1. 通过使用此 jobId 调用 [DescribeJobExecution](jobs-mqtt-api.md#mqtt-describejobexecution) MQTT API 来继续监控任务执行。如果删除了任务执行，[DescribeJobExecution](jobs-mqtt-api.md#mqtt-describejobexecution) 将返回 `ResourceNotFoundException`。
如果在设备运行任务时取消或删除了任务执行，则设备应能够恢复到有效状态。
1. 在任务完成后调用 [UpdateJobExecution](jobs-mqtt-api.md#mqtt-updatejobexecution) MQTT API 以更新任务状态并报告成功或失败。
1. 由于此任务的执行状态已更改为最终状态，因此，可用于执行的下一个任务（如果有）将发生更改。设备将收到下一个待处理任务执行已更改的通知。此时，设备将按照步骤 2 中所述继续操作。
如果设备保持联机状态，则将继续收到下一个待处理任务执行的通知。这包括它在完成任务或添加新的待处理任务执行时的任务执行数据。在发生此情况时，设备将按照步骤 2 中所述继续操作。
+
**从可用任务中选择**
1. 当设备首次联机时，它应订阅事物的 `notify` 主题。
1. 调用 [GetPendingJobExecutions](jobs-mqtt-api.md#mqtt-getpendingjobexecutions) MQTT API 以获取待处理任务执行的列表。
1. 如果列表中包含一个或多个任务执行，请选择一个任务执行。
1. 调用 [DescribeJobExecution](jobs-mqtt-api.md#mqtt-describejobexecution) MQTT API 以获取任务文档和其它详细信息，包括保存在 `statusDetails` 中的任何状态。
1. 调用 [UpdateJobExecution](jobs-mqtt-api.md#mqtt-updatejobexecution) MQTT API 以更新任务状态。如果在此命令中将 `includeJobDocument` 字段设置为 `true`，则设备可跳过上一个步骤并在此时检索任务文档。
1. （可选）您可在调用 [UpdateJobExecution](jobs-mqtt-api.md#mqtt-updatejobexecution) 时为 `stepTimeoutInMinutes` 设置值来添加步骤计时器。
1. 使用 [UpdateJobExecution](jobs-mqtt-api.md#mqtt-updatejobexecution) MQTT API 执行任务文档所指定的操作以报告任务的进度。
1. 通过使用此 jobId 调用 [DescribeJobExecution](jobs-mqtt-api.md#mqtt-describejobexecution) MQTT API 来继续监控任务执行。如果在设备运行任务时取消或删除了任务执行，则设备应能够恢复到有效状态。
1. 在任务完成后调用 [UpdateJobExecution](jobs-mqtt-api.md#mqtt-updatejobexecution) MQTT API 以更新任务状态并报告成功或失败。
如果设备保持联机状态，则在一个新的待处理任务执行变为可用时，它将收到所有待处理任务执行的通知。在发生此情况时，设备可按照步骤 2 中所述继续操作。
如果设备无法执行任务，它应调用 [UpdateJobExecution](jobs-mqtt-api.md#mqtt-updatejobexecution) MQTT API 来将任务状态更新为 `REJECTED`。
# 任务流
下面显示了任务工作流程中的不同步骤，从启动新任务到报告任务执行的完成状态。
## 开始新任务
创建新任务后，J AWS IoT obs 会为每台目标设备发布一条有关该`$aws/things/thing-name/jobs/notify`主题的消息。
消息包含以下信息：
```
{
"timestamp":1476214217017,
"jobs":{
"QUEUED":[{
"jobId":"0001",
"queuedAt":1476214216981,
"lastUpdatedAt":1476214216981,
"versionNumber" : 1
}]
}
}
```
在对任务执行进行排队时，设备将在 `'$aws/things/thingName/jobs/notify'` 主题上收到此消息。
**注意**
对于具有可选 `SchedulingConfig` 的任务，该任务将保持初始状态 `SCHEDULED`。当任务达到所选的 `startTime` 时，将发生以下情况：
任务状态将更新为 `IN_PROGRESS`。
任务将开始向目标组中的所有设备推出任务文档。
## 获取任务信息
要获取有关任务执行的更多信息，请调用 [DescribeJobExecution](jobs-mqtt-api.md#mqtt-describejobexecution) MQTT API 并将 `includeJobDocument` 字段设置为 `true`（默认值）。
如果请求成功，AWS IoT作业服务将发布一条有关该`$aws/things/MyThing/jobs/0023/get/accepted`主题的消息：
```
{
"clientToken" : "client-001",
"timestamp" : 1489097434407,
"execution" : {
"approximateSecondsBeforeTimedOut": number,
"jobId" : "023",
"status" : "QUEUED",
"queuedAt" : 1489097374841,
"lastUpdatedAt" : 1489097374841,
"versionNumber" : 1,
"jobDocument" : {
< contents of job document >
}
}
}
```
如果请求失败，AWS IoT作业服务将发布一条有关该`$aws/things/MyThing/jobs/0023/get/rejected`主题的消息。
设备现在已有任务文档，它可使用该文档执行任务的远程操作。如果任务文档包含一个 Amazon S3 预签名 URL，则设备可使用该 URL 下载任务的任何所需文件。
## 报告任务执行状态
当设备执行任务时，它可调用 [UpdateJobExecution](jobs-mqtt-api.md#mqtt-updatejobexecution) MQTT API 来更新任务执行的状态。
例如，设备可通过在 `IN_PROGRESS` 主题上发布以下消息来将任务执行状态更新为 `$aws/things/MyThing/jobs/0023/update`：
```
{
"status":"IN_PROGRESS",
"statusDetails": {
"progress":"50%"
},
"expectedVersion":"1",
"clientToken":"client001"
}
```
Jobs 通过将消息发布到 `$aws/things/MyThing/jobs/0023/update/accepted` 或 `$aws/things/MyThing/jobs/0023/update/rejected` 主题来进行响应：
```
{
"clientToken":"client001",
"timestamp":1476289222841
}
```
设备可通过调用 [StartNextPendingJobExecution](jobs-mqtt-api.md#mqtt-startnextpendingjobexecution) 来合并两个以前的请求。这将获取并开始下一个待处理任务执行，并允许设备更新任务执行状态。此请求还在有待处理任务执行时返回任务文档。
如果作业包含 [TimeoutConfig](https://docs.aws.amazon.com//iot/latest/apireference/API_TimeoutConfig.html)，则正在进行的计时器开始运行。您还可以通过设置调用时的值来为任务执行设置步进计`stepTimeoutInMinutes`时器[UpdateJobExecution](https://docs.aws.amazon.com//iot/latest/apireference/API_iot-jobs-data_UpdateJobExecution.html)。步骤计时器仅应用于您更新的任务执行。您每次更新任务执行时，可以为此计时器设置新值。您也可以在呼叫时创建计步器[StartNextPendingJobExecution](https://docs.aws.amazon.com//iot/latest/apireference/API_iot-jobs-data_StartNextPendingJobExecution.html)。如果任务执行保持在 `IN_PROGRESS` 状态的时间长度超过了此步骤计时器间隔，它将失败，并切换为最终 `TIMED_OUT` 状态。步骤计时器对您在创建任务时设置的进行中计时器没有任何影响。
`status` 字段可设置为 `IN_PROGRESS`、`SUCCEEDED` 或 `FAILED`。您无法更新已处于最终状态的任务执行的状态。
## 报告执行已完成
在设备执行完任务后，它将调用 [UpdateJobExecution](jobs-mqtt-api.md#mqtt-updatejobexecution) MQTT API。如果任务已成功，则将 `status` 设置为 `SUCCEEDED`，并在消息有效载荷的 `statusDetails` 中，将有关任务的其它信息作为名称-值对添加。任务执行完成时，进行中计时器和步骤计时器结束。
例如：
```
{
"status":"SUCCEEDED",
"statusDetails": {
"progress":"100%"
},
"expectedVersion":"2",
"clientToken":"client-001"
}
```
如果任务未成功，则将 `status` 设置为 `FAILED`，并在 `statusDetails` 中，添加有关出现的错误的信息：
```
{
"status":"FAILED",
"statusDetails": {
"errorCode":"101",
"errorMsg":"Unable to install update"
},
"expectedVersion":"2",
"clientToken":"client-001"
}
```
**注意**
`statusDetails` 属性可包含任意数量的名称-值对。
当 AWS IoT Jobs 服务收到此更新时，它会发布一条有关该`$aws/things/MyThing/jobs/notify`主题的消息，表示任务执行已完成：
```
{
"timestamp":1476290692776,
"jobs":{}
}
```
## 其它任务
如果设备有其它待处理的任务执行，这些任务执行将包含在发布到 `$aws/things/MyThing/jobs/notify` 的消息中。
例如：
```
{
"timestamp":1476290692776,
"jobs":{
"QUEUED":[{
"jobId":"0002",
"queuedAt":1476290646230,
"lastUpdatedAt":1476290646230
}],
"IN_PROGRESS":[{
"jobId":"0003",
"queuedAt":1476290646230,
"lastUpdatedAt":1476290646230
}]
}
}
```
# 任务通知
当任务处于待处理状态或列表中的第一个任务执行发生变化时，AWS IoT作业服务会向保留主题发布 MQTT 消息。设备可通过订阅这些主题来跟踪待处理任务。
## 任务通知类型。
任务通知将作为 JSON 有效载荷发布到 MQTT 主题。通知有两种：
**ListNotification**
`ListNotification` 包含一个列表，其中待处理的任务执行不超过 15 个。它们依次按照状态（`IN_PROGRESS` 任务执行在 `QUEUED` 任务执行之前）和排队的时间进行排序。
如果满足以下条件之一，则发布 `ListNotification`。
+ 新的任务执行已排队或更改为非最终状态（`IN_PROGRESS` 或 `QUEUED`）。
+ 旧的任务执行更改为最终状态（`FAILED`、`SUCCEEDED`、`CANCELED`、`TIMED_OUT`、`REJECTED` 或 `REMOVED`）。
有关使用和不使用调度配置时的限制的更多信息，请参阅 [任务执行限制](job-limits.md#job-execution-limits)。
**NextNotification**
+ `NextNotification` 包含有关队列中下一个任务执行的摘要信息。
每当列表中第一个任务执行更改时，则会发布 `NextNotification`。
+ 新的任务执行作为 `QUEUED` 添加到列表，并且在列表中排在第一位。
+ 不是列表中第一位的现有任务执行的状态从 `QUEUED` 更改为 `IN_PROGRESS`，然后成为列表中的第一个。（当列表中没有其它 `IN_PROGRESS` 任务执行时，或者当状态从 `QUEUED` 更改为 `IN_PROGRESS` 的任务执行排队的时间早于列表中其他所有 `IN_PROGRESS` 任务执行时，会出现这种情况。）
+ 列表第一的任务执行状态更改为最终状态，并且从列表中删除。
有关发布和订阅 MQTT 主题的更多信息，请参阅 [设备通信协议](protocols.md)。
**注意**
当您使用 HTTP Signature Version 4 或 HTTP TLS 与 Jobs 通信时，通知不可用。
## 任务待处理
在某事物的待处理任务执行列表中添加或从中删除任务或列表中的第一个任务执行发生变化时，AWS IoT作业服务会在 MQTT 主题上发布一条消息：
+ `$aws/things/thingName/jobs/notify`
+ `$aws/things/thingName/jobs/notify-next`
消息包含以下示例有效载荷：
`$aws/things/thingName/jobs/notify`:
```
{
"timestamp" : 10011,
"jobs" : {
"IN_PROGRESS" : [ {
"jobId" : "other-job",
"queuedAt" : 10003,
"lastUpdatedAt" : 10009,
"executionNumber" : 1,
"versionNumber" : 1
} ],
"QUEUED" : [ {
"jobId" : "this-job",
"queuedAt" : 10011,
"lastUpdatedAt" : 10011,
"executionNumber" : 1,
"versionNumber" : 0
} ]
}
}
```
如果名为 `this-job` 的任务执行源自某个选定了可选计划配置且任务文档推出计划在维护时段内进行的任务，则该任务只会在定期维护时段内出现。在维护时段之外，名为 `this-job` 的任务将从待处理的任务执行列表中排除，如以下示例所示。
```
{
"timestamp" : 10011,
"jobs" : {
"IN_PROGRESS" : [ {
"jobId" : "other-job",
"queuedAt" : 10003,
"lastUpdatedAt" : 10009,
"executionNumber" : 1,
"versionNumber" : 1
} ],
"QUEUED" : []
}
}
```
`$aws/things/thingName/jobs/notify-next`:
```
{
"timestamp" : 10011,
"execution" : {
"jobId" : "other-job",
"status" : "IN_PROGRESS",
"queuedAt" : 10009,
"lastUpdatedAt" : 10009,
"versionNumber" : 1,
"executionNumber" : 1,
"jobDocument" : {"c":"d"}
}
}
```
如果名为 `other-job` 的任务执行源自某个选定了可选计划配置且任务文档推出计划在维护时段内进行的任务，则该任务只会在定期维护时段内出现。在维护时段之外，名为 `other-job` 的任务不会列为下一个任务执行，如以下示例所示。
```
{} //No other pending jobs
```
```
{
"timestamp" : 10011,
"execution" : {
"jobId" : "this-job",
"queuedAt" : 10011,
"lastUpdatedAt" : 10011,
"executionNumber" : 1,
"versionNumber" : 0,
"jobDocument" : {"a":"b"}
}
} // "this-job" is pending next to "other-job"
```
可能的任务执行状态值为 `QUEUED`、`IN_PROGRESS`、`FAILED`、`SUCCEEDED`、`CANCELED`、`TIMED_OUT`、`REJECTED` 和 `REMOVED`。
以下一系列示例显示了在创建任务执行以及任务执行从一种状态更改为另一种状态时向每个主题发布的通知。
首先，创建了一个名为 `job1` 的任务。此通知发布到 `jobs/notify` 主题：
```
{
"timestamp": 1517016948,
"jobs": {
"QUEUED": [
{
"jobId": "job1",
"queuedAt": 1517016947,
"lastUpdatedAt": 1517016947,
"executionNumber": 1,
"versionNumber": 1
}
]
}
}
```
此通知发布到 `jobs/notify-next` 主题：
```
{
"timestamp": 1517016948,
"execution": {
"jobId": "job1",
"status": "QUEUED",
"queuedAt": 1517016947,
"lastUpdatedAt": 1517016947,
"versionNumber": 1,
"executionNumber": 1,
"jobDocument": {
"operation": "test"
}
}
}
```
当创建另一个任务 (`job2`) 时，此通知将发布到 `jobs/notify` 主题：
```
{
"timestamp": 1517017192,
"jobs": {
"QUEUED": [
{
"jobId": "job1",
"queuedAt": 1517016947,
"lastUpdatedAt": 1517016947,
"executionNumber": 1,
"versionNumber": 1
},
{
"jobId": "job2",
"queuedAt": 1517017191,
"lastUpdatedAt": 1517017191,
"executionNumber": 1,
"versionNumber": 1
}
]
}
}
```
通知未发布到 `jobs/notify-next` 主题，因为队列中的下一个任务 (`job1`) 尚未更改。当 `job1` 开始执行时，其状态更改为 `IN_PROGRESS`。没有发布任何通知，因为任务列表和队列中的下一个任务尚未更改。
当添加第三个任务 (`job3`) 时，此通知将发布到 `jobs/notify` 主题：
```
{
"timestamp": 1517017906,
"jobs": {
"IN_PROGRESS": [
{
"jobId": "job1",
"queuedAt": 1517016947,
"lastUpdatedAt": 1517017472,
"startedAt": 1517017472,
"executionNumber": 1,
"versionNumber": 2
}
],
"QUEUED": [
{
"jobId": "job2",
"queuedAt": 1517017191,
"lastUpdatedAt": 1517017191,
"executionNumber": 1,
"versionNumber": 1
},
{
"jobId": "job3",
"queuedAt": 1517017905,
"lastUpdatedAt": 1517017905,
"executionNumber": 1,
"versionNumber": 1
}
]
}
}
```
通知未发布到 `jobs/notify-next` 主题，因为队列中的下一个任务仍为 `job1`。
当 `job1` 完成后，其状态更改为 `SUCCEEDED`，此通知将发布到 `jobs/notify` 主题：
```
{
"timestamp": 1517186269,
"jobs": {
"QUEUED": [
{
"jobId": "job2",
"queuedAt": 1517017191,
"lastUpdatedAt": 1517017191,
"executionNumber": 1,
"versionNumber": 1
},
{
"jobId": "job3",
"queuedAt": 1517017905,
"lastUpdatedAt": 1517017905,
"executionNumber": 1,
"versionNumber": 1
}
]
}
}
```
此时，已从队列中删除 `job1`，要执行的下一个任务是 `job2`。此通知发布到 `jobs/notify-next` 主题：
```
{
"timestamp": 1517186269,
"execution": {
"jobId": "job2",
"status": "QUEUED",
"queuedAt": 1517017191,
"lastUpdatedAt": 1517017191,
"versionNumber": 1,
"executionNumber": 1,
"jobDocument": {
"operation": "test"
}
}
}
```
如果 `job3` 必须在 `job2` 之前开始执行（不推荐），`job3` 的状态可以更改为 `IN_PROGRESS`。更改后，`job2` 则不再是队列中的下一个任务，此通知将发布到 `jobs/notify-next` 主题：
```
{
"timestamp": 1517186779,
"execution": {
"jobId": "job3",
"status": "IN_PROGRESS",
"queuedAt": 1517017905,
"startedAt": 1517186779,
"lastUpdatedAt": 1517186779,
"versionNumber": 2,
"executionNumber": 1,
"jobDocument": {
"operation": "test"
}
}
}
```
没有向 `jobs/notify` 主题发布任何通知，因为没有添加或删除任何任务。
如果设备拒绝 `job2`，并且将其状态更新为 `REJECTED`，则此通知将发布到 `jobs/notify` 主题：
```
{
"timestamp": 1517189392,
"jobs": {
"IN_PROGRESS": [
{
"jobId": "job3",
"queuedAt": 1517017905,
"lastUpdatedAt": 1517186779,
"startedAt": 1517186779,
"executionNumber": 1,
"versionNumber": 2
}
]
}
}
```
如果 `job3`（仍在进行）被强制删除，则此通知将发布到 `jobs/notify` 主题：
```
{
"timestamp": 1517189551,
"jobs": {}
}
```
此时队列为空。此通知发布到 `jobs/notify-next` 主题：
```
{
"timestamp": 1517189551
}
```
# AWS IoT 作业 API 操作
AWS IoT 作业 API 可用于以下任一类别：
+ 诸如管理和控制任务等管理任务。这是*控制面板*。
+ 执行这些任务的设备。这是*数据面板*，允许您发送和接收数据。
任务的管理和控制操作将使用 HTTPS 协议 API。设备可以使用 MQTT 或 HTTPS 协议 API。控制面板 API 旨在用于在创建和跟踪任务时通常进行的少量调用。它通常会为一个请求打开一个连接，然后在收到响应后关闭此连接。数据面板 HTTPS 和 MQTT API 允许进行长时间轮询。这些 API 操作旨在用于可扩展至数百万台设备的大量流量。
每个 AWS IoT Jobs HTTPS API 都有相应的命令，允许你从 AWS Command Line Interface (AWS CLI) 调用 API。命令采用小写形式，并且在构成 API 名称的单词之间使用连字符。例如，您可以通过键入以下内容，在 CLI 上调用 `CreateJob` API：
```
aws iot create-job ...
```
如果在操作过程中发生错误，您会收到包含有关错误的信息的错误响应。
## ErrorResponse
包含有关 AWS IoT Jobs 服务操作期间发生的错误的信息。
以下示例显示此操作的语法：
```
{
"code": "ErrorCode",
"message": "string",
"clientToken": "string",
"timestamp": timestamp,
"executionState": JobExecutionState
}
```
以下是此 `ErrorResponse` 的描述：
`code`
ErrorCode 可以设置为：
InvalidTopic
该请求已发送到 AWS IoT Jobs 命名空间中未映射到任何 API 操作的主题。
InvalidJson
请求的内容无法解释为有效的 UTF-8 编码的 JSON。
InvalidRequest
请求的内容无效。例如，当 `UpdateJobExecution` 请求包含无效的状态详细信息时，将返回此代码。消息包含有关错误的详细信息。
InvalidStateTransition
由于任务执行的当前状态，更新已尝试将任务执行更改为无效的状态。例如，尝试将状态为 SUCCEEDED 的请求更改为状态 IN\$1PROGRESS。在这种情况下，错误消息的正文还包含 `executionState` 字段。
ResourceNotFound
请求主题所指定的 `JobExecution` 不存在。
VersionMismatch
请求中指定的预期版本与 AWS IoT 作业服务中任务执行的版本不匹配。在这种情况下，错误消息的正文还包含 `executionState` 字段。
InternalError
处理请求期间出现内部错误。
RequestThrottled
请求已被阻止。
TerminalStateReached
在处于最终状态的任务上执行描述任务的命令时发生。
`message`
错误消息字符串。
`clientToken`
用于将请求与其答复关联起来的任意字符串。
`timestamp`
用自纪元以来的秒数表示的时间。
`executionState`
一个 [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_JobExecutionState.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_JobExecutionState.html) 对象。仅在 `code` 字段具有 `InvalidStateTransition` 或 `VersionMismatch` 值时包含此字段。在这些情况下，这使得不必执行单独的 `DescribeJobExecution` 请求以获取当前任务执行状态数据。
**Topics**
+ [任务管理和控制 API 以及数据类型](jobs-management-control-api.md)
+ [任务设备 MQTT 和 HTTPS API 操作以及数据类型](jobs-mqtt-https-api.md)
# 任务管理和控制 API 以及数据类型
**Topics**
+ [任务管理和控制数据类型](#jobs-control-plane-data-types)
+ [任务管理和控制 API 操作](#jobs-http-api)
要确定 CLI 命令的*endpoint-url*参数，请运行此命令。
```
aws iot describe-endpoint --endpoint-type=iot:Jobs
```
此命令将返回以下输出。
```
{
"endpointAddress": "account-specific-prefix.jobs.iot.aws-region.amazonaws.com"
}
```
**注意**
Jobs 端点不支持 ALPN `x-amzn-http-ca`。
如果您使用的是双堆栈终端节点（IPv6 和 IPv6），请使用`iot:Data-ATS`终端节点。该`iot:Jobs`端点仅支持 IPv4。
## 任务管理和控制数据类型
管理和控制应用程序使用以下数据类型与 AWS IoT 作业通信。
### 任务
`Job` 对象包含有关任务的详细信息。以下示例显示该语法：
```
{
"jobArn": "string",
"jobId": "string",
"status": "IN_PROGRESS|CANCELED|SUCCEEDED",
"forceCanceled": boolean,
"targetSelection": "CONTINUOUS|SNAPSHOT",
"comment": "string",
"targets": ["string"],
"description": "string",
"createdAt": timestamp,
"lastUpdatedAt": timestamp,
"completedAt": timestamp,
"jobProcessDetails": {
"processingTargets": ["string"],
"numberOfCanceledThings": long,
"numberOfSucceededThings": long,
"numberOfFailedThings": long,
"numberOfRejectedThings": long,
"numberOfQueuedThings": long,
"numberOfInProgressThings": long,
"numberOfRemovedThings": long,
"numberOfTimedOutThings": long
},
"presignedUrlConfig": {
"expiresInSec": number,
"roleArn": "string"
},
"jobExecutionsRolloutConfig": {
"exponentialRate": {
"baseRatePerMinute": integer,
"incrementFactor": integer,
"rateIncreaseCriteria": {
"numberOfNotifiedThings": integer, // Set one or the other
"numberOfSucceededThings": integer // of these two values.
},
"maximumPerMinute": integer
}
},
"abortConfig": {
"criteriaList": [
{
"action": "string",
"failureType": "string",
"minNumberOfExecutedThings": integer,
"thresholdPercentage": integer
}
]
},
"SchedulingConfig": {
"startTime": string
"endTime": string
"timeZone": string
"endTimeBehavior": string
},
"timeoutConfig": {
"inProgressTimeoutInMinutes": long
}
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/iot/latest/apireference/API_Job.html](https://docs.aws.amazon.com/iot/latest/apireference/API_Job.html)或 [https://docs.aws.amazon.com/cli/latest/reference/iot/job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/job.html)。
### JobSummary
`JobSummary` 对象包含任务摘要。以下示例显示该语法：
```
{
"jobArn": "string",
"jobId": "string",
"status": "IN_PROGRESS|CANCELED|SUCCEEDED|SCHEDULED",
"targetSelection": "CONTINUOUS|SNAPSHOT",
"thingGroupId": "string",
"createdAt": timestamp,
"lastUpdatedAt": timestamp,
"completedAt": timestamp
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/iot/latest/apireference/API_JobSummary.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobSummary.html)或 [https://docs.aws.amazon.com/cli/latest/reference/iot/job-summary.html](https://docs.aws.amazon.com/cli/latest/reference/iot/job-summary.html)。
### JobExecution
`JobExecution` 对象表示设备上的任务执行。以下示例显示该语法：
**注意**
当您使用控制面板 API 操作时，`JobExecution` 数据类型不包含 `JobDocument` 字段。要获取此信息，您可以使用 [https://docs.aws.amazon.com/iot/latest/apireference/API_GetJobDocument.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetJobDocument.html) API 操作或 [https://docs.aws.amazon.com/cli/latest/reference/get-job-document.html](https://docs.aws.amazon.com/cli/latest/reference/get-job-document.html) CLI 命令。
```
{
"approximateSecondsBeforeTimedOut": 50,
"executionNumber": 1234567890,
"forceCanceled": true|false,
"jobId": "string",
"lastUpdatedAt": timestamp,
"queuedAt": timestamp,
"startedAt": timestamp,
"status": "QUEUED|IN_PROGRESS|FAILED|SUCCEEDED|CANCELED|TIMED_OUT|REJECTED|REMOVED",
"forceCanceled": boolean,
"statusDetails": {
"detailsMap": {
"string": "string" ...
},
"status": "string"
},
"thingArn": "string",
"versionNumber": 123
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecution.html)或 [https://docs.aws.amazon.com/cli/latest/reference/iot/job-execution.html](https://docs.aws.amazon.com/cli/latest/reference/iot/job-execution.html)。
### JobExecutionSummary
`JobExecutionSummary` 对象包含任务执行摘要信息。以下示例显示该语法：
```
{
"executionNumber": 1234567890,
"queuedAt": timestamp,
"lastUpdatedAt": timestamp,
"startedAt": timestamp,
"status": "QUEUED|IN_PROGRESS|FAILED|SUCCEEDED|CANCELED|TIMED_OUT|REJECTED|REMOVED"
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummary.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummary.html)或 [https://docs.aws.amazon.com/cli/latest/reference/iot/job-execution-summary.html](https://docs.aws.amazon.com/cli/latest/reference/iot/job-execution-summary.html)。
### JobExecutionSummaryForJob
`JobExecutionSummaryForJob` 对象包含有关特定任务的任务执行的信息摘要。以下示例显示该语法：
```
{
"executionSummaries": [
{
"thingArn": "arn:aws:iot:us-west-2:123456789012:thing/MyThing",
"jobExecutionSummary": {
"status": "IN_PROGRESS",
"lastUpdatedAt": 1549395301.389,
"queuedAt": 1541526002.609,
"executionNumber": 1
}
},
...
]
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummaryForJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummaryForJob.html)或 [https://docs.aws.amazon.com/cli/latest/reference/iot/job-execution-summary-for-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/job-execution-summary-for-job.html)。
### JobExecutionSummaryForThing
该`JobExecutionSummaryForThing`对象包含有关在特定事物上执行任务的信息摘要。 FThe 以下示例显示了语法：
```
{
"executionSummaries": [
{
"jobExecutionSummary": {
"status": "IN_PROGRESS",
"lastUpdatedAt": 1549395301.389,
"queuedAt": 1541526002.609,
"executionNumber": 1
},
"jobId": "MyThingJob"
},
...
]
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummaryForThing.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummaryForThing.html)或 [https://docs.aws.amazon.com/cli/latest/reference/iot/job-execution-summary-for-thing.html](https://docs.aws.amazon.com/cli/latest/reference/iot/job-execution-summary-for-thing.html)。
## 任务管理和控制 API 操作
使用以下 API 操作或 CLI 命令：
### AssociateTargetsWithJob
将组与持续任务关联。必须满足以下标准：
+ 必须已在 `targetSelection` 字段设置为 `CONTINUOUS` 的情况下创建任务。
+ 任务状态当前必须为 `IN_PROGRESS`。
+ 与任务关联的目标总数不能超过 100。
------
#### [ HTTPS request ]
```
POST /jobs/jobId/targets
{
"targets": [ "string" ],
"comment": "string"
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/iot/latest/apireference/API_AssociateTargetsWithJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_AssociateTargetsWithJob.html)。
------
#### [ CLI syntax ]
```
aws iot associate-targets-with-job \
--targets \
--job-id \
[--comment ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` 格式：
```
{
"targets": [
"string"
],
"jobId": "string",
"comment": "string"
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/cli/latest/reference/iot/associate-targets-with-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/associate-targets-with-job.html)。
------
### CancelJob
取消任务。
------
#### [ HTTPS request ]
```
PUT /jobs/jobId/cancel
{
"force": boolean,
"comment": "string",
"reasonCode": "string"
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/iot/latest/apireference/API_CancelJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CancelJob.html)。
------
#### [ CLI syntax ]
```
aws iot cancel-job \
--job-id \
[--force ] \
[--comment ] \
[--reasonCode ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` 格式：
```
{
"jobId": "string",
"force": boolean,
"comment": "string"
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/cli/latest/reference/iot/cancel-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/cancel-job.html)。
------
### CancelJobExecution
取消设备上的任务执行。
------
#### [ HTTPS request ]
```
PUT /things/thingName/jobs/jobId/cancel
{
"force": boolean,
"expectedVersion": "string",
"statusDetails": {
"string": "string"
...
}
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/iot/latest/apireference/API_CancelJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CancelJobExecution.html)。
------
#### [ CLI syntax ]
```
aws iot cancel-job-execution \
--job-id \
--thing-name \
[--force | --no-force] \
[--expected-version ] \
[--status-details ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` 格式：
```
{
"jobId": "string",
"thingName": "string",
"force": boolean,
"expectedVersion": long,
"statusDetails": {
"string": "string"
}
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/cli/latest/reference/iot/cancel-job-execution.html](https://docs.aws.amazon.com/cli/latest/reference/iot/cancel-job-execution.html)。
------
### CreateJob
创建任务。您可以提供任务文档，作为指向 Amazon S3 桶（`documentSource` 参数）中或请求正文（`document` 参数）中的文件的链接。
通过将可选的 `targetSelection` 参数设置为 `CONTINUOUS`（默认为 `SNAPSHOT`），可使任务成为*连续*任务。连续任务可用于在将设备添加到组时登记或升级设备，因为它将继续运行并在新添加的事物上启动。即使在创建任务时组中的事物已完成任务，也可能发生这种情况。
作业可以有一个可选的 [TimeoutConfig](https://docs.aws.amazon.com//iot/latest/apireference/API_TimeoutConfig.html)，用于设置正在进行的计时器的值。进行中计时器无法更新，应用到该任务的全部执行。
对 `CreateJob` API 的参数执行以下验证：
+ `targets`参数必须是有效事物或事物组的列表 ARNs。所有事物和事物组都必须位于您的中 AWS 账户。
+ `documentSource` 参数必须是指向任务文档的有效 Amazon S3 URL。亚马逊 URLs S3 的格式为:`https://s3.amazonaws.com/bucketName/objectName`.
+ 存储在由 `documentSource` 参数指定的 URL 中的文档必须是 UTF-8 编码的 JSON 文档。
+ 由于 MQTT 消息大小限制（128 KB）和加密的原因，任务文档的大小限制为 32 KB。
+ 在您的中`jobId`必须是唯一的 AWS 账户。
------
#### [ HTTPS request ]
```
PUT /jobs/jobId
{
"targets": [ "string" ],
"document": "string",
"documentSource": "string",
"description": "string",
"jobTemplateArn": "string",
"presignedUrlConfigData": {
"roleArn": "string",
"expiresInSec": "integer"
},
"targetSelection": "CONTINUOUS|SNAPSHOT",
"jobExecutionsRolloutConfig": {
"exponentialRate": {
"baseRatePerMinute": integer,
"incrementFactor": integer,
"rateIncreaseCriteria": {
"numberOfNotifiedThings": integer, // Set one or the other
"numberOfSucceededThings": integer // of these two values.
},
"maximumPerMinute": integer
}
},
"abortConfig": {
"criteriaList": [
{
"action": "string",
"failureType": "string",
"minNumberOfExecutedThings": integer,
"thresholdPercentage": integer
}
]
},
"SchedulingConfig": {
"startTime": string
"endTime": string
"timeZone": string
"endTimeBehavior": string
}
"timeoutConfig": {
"inProgressTimeoutInMinutes": long
}
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html)。
------
#### [ CLI syntax ]
```
aws iot create-job \
--job-id \
--targets \
[--document-source ] \
[--document ] \
[--description ] \
[--job-template-arn ] \
[--presigned-url-config ] \
[--target-selection ] \
[--job-executions-rollout-config ] \
[--abort-config ] \
[--timeout-config ] \
[--document-parameters ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` 格式：
```
{
"jobId": "string",
"targets": [ "string" ],
"documentSource": "string",
"document": "string",
"description": "string",
"jobTemplateArn": "string",
"presignedUrlConfig": {
"roleArn": "string",
"expiresInSec": long
},
"targetSelection": "string",
"jobExecutionsRolloutConfig": {
"exponentialRate": {
"baseRatePerMinute": integer,
"incrementFactor": integer,
"rateIncreaseCriteria": {
"numberOfNotifiedThings": integer, // Set one or the other
"numberOfSucceededThings": integer // of these two values.
},
"maximumPerMinute": integer
}
},
"abortConfig": {
"criteriaList": [
{
"action": "string",
"failureType": "string",
"minNumberOfExecutedThings": integer,
"thresholdPercentage": integer
}
]
},
"timeoutConfig": {
"inProgressTimeoutInMinutes": long
},
"documentParameters": {
"string": "string"
}
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/cli/latest/reference/iot/create-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/create-job.html)。
------
### DeleteJob
删除任务及其相关的任务执行。
删除任务可能需要一些时间，具体取决于为该任务创建的任务执行的数量以及其它各种因素。正在删除任务时，任务的状态显示为“DELETION\$1IN\$1PROGRESS”。尝试删除或取消已处于“DELETION\$1IN\$1PROGRESS”状态的任务将导致错误。
------
#### [ HTTPS request ]
```
DELETE /jobs/jobId?force=force
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJob.html)。
------
#### [ CLI syntax ]
```
aws iot delete-job \
--job-id \
[--force | --no-force] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` 格式：
```
{
"jobId": "string",
"force": boolean
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/cli/latest/reference/iot/delete-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/delete-job.html)。
------
### DeleteJobExecution
删除任务执行。
------
#### [ HTTPS request ]
```
DELETE /things/thingName/jobs/jobId/executionNumber/executionNumber?force=force
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJobExecution.html)。
------
#### [ CLI syntax ]
```
aws iot delete-job-execution \
--job-id \
--thing-name \
--execution-number \
[--force | --no-force] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` 格式：
```
{
"jobId": "string",
"thingName": "string",
"executionNumber": long,
"force": boolean
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/cli/latest/reference/iot/delete-job-execution.html](https://docs.aws.amazon.com/cli/latest/reference/iot/delete-job-execution.html)。
------
### DescribeJob
获取任务执行的详细信息。
------
#### [ HTTPS request ]
```
GET /jobs/jobId
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJob.html)。
------
#### [ CLI syntax ]
```
aws iot describe-job \
--job-id \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` 格式：
```
{
"jobId": "string"
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/cli/latest/reference/iot/describe-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/describe-job.html)。
------
### DescribeJobExecution
获取任务执行的详细信息。任务的执行状态必须为 `SUCCEEDED` 或 `FAILED`。
------
#### [ HTTPS request ]
```
GET /things/thingName/jobs/jobId?executionNumber=executionNumber
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html)。
------
#### [ CLI syntax ]
```
aws iot describe-job-execution \
--job-id \
--thing-name \
[--execution-number ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` 格式：
```
{
"jobId": "string",
"thingName": "string",
"executionNumber": long
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/cli/latest/reference/iot/describe-job-execution.html](https://docs.aws.amazon.com/cli/latest/reference/iot/describe-job-execution.html)。
------
### GetJobDocument
获取任务的任务文档。
**注意**
在返回的文档 URLs 中，占位符不会替换为预签名的 Amazon S3 URLs。仅当 AWS IoT 任务服务通过 MQTT 收到请求时，才会生成预签名 URLs 。
------
#### [ HTTPS request ]
```
GET /jobs/jobId/job-document
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/iot/latest/apireference/API_GetJobDocument.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetJobDocument.html)。
------
#### [ CLI syntax ]
```
aws iot get-job-document \
--job-id \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` 格式：
```
{
"jobId": "string"
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/cli/latest/reference/iot/get-job-document.html](https://docs.aws.amazon.com/cli/latest/reference/iot/get-job-document.html)。
------
### ListJobExecutionsForJob
获取任务的任务执行的列表。
------
#### [ HTTPS request ]
```
GET /jobs/jobId/things?status=status&maxResults=maxResults&nextToken=nextToken
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobExecutionsForJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobExecutionsForJob.html)。
------
#### [ CLI syntax ]
```
aws iot list-job-executions-for-job \
--job-id \
[--status ] \
[--max-results ] \
[--next-token ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` 格式：
```
{
"jobId": "string",
"status": "string",
"maxResults": "integer",
"nextToken": "string"
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/cli/latest/reference/iot/list-job-executions-for-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/list-job-executions-for-job.html)。
------
### ListJobExecutionsForThing
获取事物的任务执行的列表。
------
#### [ HTTPS request ]
```
GET /things/thingName/jobs?status=status&maxResults=maxResults&nextToken=nextToken
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobExecutionsForThing.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobExecutionsForThing.html)。
------
#### [ CLI syntax ]
```
aws iot list-job-executions-for-thing \
--thing-name \
[--status ] \
[--max-results ] \
[--next-token ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` 格式：
```
{
"thingName": "string",
"status": "string",
"maxResults": "integer",
"nextToken": "string"
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/cli/latest/reference/iot/list-job-executions-for-thing.html](https://docs.aws.amazon.com/cli/latest/reference/iot/list-job-executions-for-thing.html)。
------
### ListJobs
获取您的职位列表 AWS 账户。
------
#### [ HTTPS request ]
```
GET /jobs?status=status&targetSelection=targetSelection&thingGroupName=thingGroupName&thingGroupId=thingGroupId&maxResults=maxResults&nextToken=nextToken
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobs.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobs.html)。
------
#### [ CLI syntax ]
```
aws iot list-jobs \
[--status ] \
[--target-selection ] \
[--max-results ] \
[--next-token ] \
[--thing-group-name ] \
[--thing-group-id ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` 格式：
```
{
"status": "string",
"targetSelection": "string",
"maxResults": "integer",
"nextToken": "string",
"thingGroupName": "string",
"thingGroupId": "string"
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/cli/latest/reference/iot/list-jobs.html](https://docs.aws.amazon.com/cli/latest/reference/iot/list-jobs.html)。
------
### UpdateJob
更新指定任务的受支持字段。`timeoutConfig` 的更新值仅对新的正在进行的启动生效。目前，正在进行的启动将继续使用之前的超时配置启动。
------
#### [ HTTPS request ]
```
PATCH /jobs/jobId
{
"description": "string",
"presignedUrlConfig": {
"expiresInSec": number,
"roleArn": "string"
},
"jobExecutionsRolloutConfig": {
"exponentialRate": {
"baseRatePerMinute": number,
"incrementFactor": number,
"rateIncreaseCriteria": {
"numberOfNotifiedThings": number,
"numberOfSucceededThings": number
},
"maximumPerMinute": number
},
"abortConfig": {
"criteriaList": [
{
"action": "string",
"failureType": "string",
"minNumberOfExecutedThings": number,
"thresholdPercentage": number
}
]
},
"timeoutConfig": {
"inProgressTimeoutInMinutes": number
}
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateJob.html)。
------
#### [ CLI syntax ]
```
aws iot update-job \
--job-id \
[--description ] \
[--presigned-url-config ] \
[--job-executions-rollout-config ] \
[--abort-config ] \
[--timeout-config ] \
[--cli-input-json ] \
[--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
}
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/cli/latest/reference/iot/update-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/update-job.html)。
------
# 任务设备 MQTT 和 HTTPS API 操作以及数据类型
可通过 MQTT 和 HTTPS 协议使用以下命令。在数据面板上对执行任务的设备使用这些 API 操作。
## 任务设备 MQTT 和 HTTPS 数据类型
以下数据类型用于通过 MQTT 和 HTTPS 协议与 AWS IoT 作业服务通信。
### JobExecution
`JobExecution` 对象表示设备上的任务执行。以下示例显示该语法：
**注意**
当您使用 MQTT 和 HTTP 数据面板 API 操作时，`JobExecution` 数据类型包含 `JobDocument` 字段。您的设备可以使用此信息从任务执行中检索任务文档。
```
{
"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
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_JobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_JobExecution.html)或 [https://docs.aws.amazon.com/cli/latest/reference/iot-data/job-execution.html](https://docs.aws.amazon.com/cli/latest/reference/iot-data/job-execution.html)。
### JobExecutionState
`JobExecutionState` 包含有关任务执行的状态的信息。以下示例显示该语法：
```
{
"status": "QUEUED|IN_PROGRESS|FAILED|SUCCEEDED|CANCELED|TIMED_OUT|REJECTED|REMOVED",
"statusDetails": {
"string": "string"
...
}
"versionNumber": "number"
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_JobExecutionState.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_JobExecutionState.html)或 [https://docs.aws.amazon.com/cli/latest/reference/iot-data/job-execution-state.html](https://docs.aws.amazon.com/cli/latest/reference/iot-data/job-execution-state.html)。
### JobExecutionSummary
包含有关任务执行的信息的子集。以下示例显示该语法：
```
{
"jobId": "string",
"queuedAt": timestamp,
"startedAt": timestamp,
"lastUpdatedAt": timestamp,
"versionNumber": "number",
"executionNumber": long
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_JobExecutionSummary.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_JobExecutionSummary.html)或 [https://docs.aws.amazon.com/cli/latest/reference/iot-data/job-execution-summary.html](https://docs.aws.amazon.com/cli/latest/reference/iot-data/job-execution-summary.html)。
**Topics**
+ [任务设备 MQTT 和 HTTPS 数据类型](#jobs-data-plane-data-types)
+ [任务设备 MQTT API 操作](jobs-mqtt-api.md)
+ [任务设备 HTTP API](jobs-http-device-api.md)
# 任务设备 MQTT API 操作
可以通过将 MQTT 消息发布到[用于 Jobs 命令的保留主题](reserved-topics.md#reserved-topics-job)来发出任务设备命令。
您的设备端客户端必须订阅这些命令的响应消息主题。如果您使用 AWS IoT 设备客户端，您的设备将自动订阅响应主题。这意味着消息代理将向发布命令消息的客户端发布响应消息主题，无论您的客户端是否订阅了该响应消息主题。这些响应消息不会通过消息代理，也无法由其它客户端或规则订阅。
订阅实例集监控解决方案的任务和 `jobExecution` 事件主题时，首先启用[任务和任务执行事件](iot-events.md)以接收云端的任何事件。Job 进度消息，这些消息通过消息代理处理并且可以由 AWS IoT 规则使用，将发布为 [任务事件](events-jobs.md)。由于消息代理会发布响应消息，即使没有明确订阅响应消息也是如此，因此必须配置您的客户端以接收和标识其接收的消息。*thingName*在客户端对消息采取行动之前，您的客户端还必须确认传入消息主题中的是否适用于客户端的事物名称。
**注意**
为响应 MQTT Jobs API 命令消息而 AWS IoT 发送的消息将从您的账户中扣款，无论您是否明确订阅了这些消息。
下面显示了 MQTT API 操作及其请求和响应语法。所有 MQTT API 操作都具有以下参数：
clientToken
用于将请求和响应关联起来的可选客户端令牌。在此处输入任意值，它将反映在响应中。
`timestamp`
发送消息的时间（用从纪元开始的秒数表示）。
## GetPendingJobExecutions
针对指定的事物，获取未处于最终状态的所有任务的列表。
要调用此 API，请在 `$aws/things/thingName/jobs/get` 上发布消息。
请求负载：
```
{ "clientToken": "string" }
```
消息代理将发布 `$aws/things/thingName/jobs/get/accepted` 和 `$aws/things/thingName/jobs/get/rejected`，即使您没有指定订阅它们。但是，为了让您的客户端接收消息，客户端必须侦听这些消息。有关更多信息，请参阅[关于 Job API 消息的说明](#jobs-mqtt-note)。
响应负载：
```
{
"inProgressJobs" : [ JobExecutionSummary ... ],
"queuedJobs" : [ JobExecutionSummary ... ],
"timestamp" : 1489096425069,
"clientToken" : "client-001"
}
```
其中，`inProgressJobs` 和 `queuedJobs` 返回状态为 `IN_PROGRESS` 或 `QUEUED` 的 [JobExecutionSummary](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-summary) 对象的列表。
## StartNextPendingJobExecution
获取并启动事物的下一个待处理任务执行（状态为 `IN_PROGRESS` 或 `QUEUED`）。
+ 首先返回状态为 `IN_PROGRESS` 的所有任务执行。
+ 按任务执行的排队顺序返回这些任务执行。在任务的目标组中添加或移除某个事物时，请确认任何新的任务执行与现有任务执行相比的推出顺序。
+ 如果下一个待处理任务执行的状态为 `QUEUED`，则其状态将更改为 `IN_PROGRESS`，并且任务执行的状态详细信息将设定为指定内容。
+ 如果下一个待处理任务执行已处于 `IN_PROGRESS` 状态，则不会更改其状态详细信息。
+ 如果没有待处理的任务执行，则响应不包括 `execution` 字段。
+ （可选）您可以通过为 `stepTimeoutInMinutes` 属性设置值来创建步骤计时器。如果您没有通过运行 `UpdateJobExecution` 更新此属性的值，任务执行将在步骤计时器到期时超时。
要调用此 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` 字段）可能指定的任务执行超时。
此参数的有效值范围为 1 到 10080（1 分钟到 7 天）。值为 -1 也是有效的，它将取消当前的步进计时器（由之前的使用创建 UpdateJobExecutionRequest）。
消息代理将发布 `$aws/things/thingName/jobs/start-next/accepted` 和 `$aws/things/thingName/jobs/start-next/rejected`，即使您没有指定订阅它们。但是，为了让您的客户端接收消息，客户端必须侦听这些消息。有关更多信息，请参阅[关于 Job API 消息的说明](#jobs-mqtt-note)。
响应负载：
```
{
"execution" : JobExecutionData,
"timestamp" : timestamp,
"clientToken" : "string"
}
```
其中，`execution` 是 [JobExecution](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-data) 对象。例如：
```
{
"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,
}
```
## DescribeJobExecution
获取有关任务执行的详细信息。
您可以将 `jobId` 设置为 `$next` 以返回事物的下一个待处理任务执行（状态为 `IN_PROGRESS` 或 `QUEUED`）。
要调用此 API，请在 `$aws/things/thingName/jobs/jobId/get` 上发布消息。
请求负载：
```
{
"jobId" : "022",
"thingName" : "MyThing",
"executionNumber": long,
"includeJobDocument": boolean,
"clientToken": "string"
}
```
`thingName`
与设备关联的事物的名称。
`jobId`
创建此任务时向其分配的唯一标识符。
或使用 `$next` 返回事物的下一个待处理任务执行（状态为 `IN_PROGRESS` 或 `QUEUED`）。在此情况下，首先返回状态为 `IN_PROGRESS` 的所有任务执行。按任务执行的创建顺序返回这些执行。
`executionNumber`
（可选）标识设备上的任务执行的数字。如果未指定，则返回最新的任务执行。
`includeJobDocument`
（可选）除非设置为 `false`，否则响应将包含任务文档。默认值为 `true`。
消息代理将发布 `$aws/things/thingName/jobs/jobId/get/accepted` 和 `$aws/things/thingName/jobs/jobId/get/rejected`，即使您没有指定订阅它们。但是，为了让您的客户端接收消息，客户端必须侦听这些消息。有关更多信息，请参阅[关于 Job API 消息的说明](#jobs-mqtt-note)。
响应负载：
```
{
"execution" : JobExecutionData,
"timestamp": "timestamp",
"clientToken": "string"
}
```
其中，`execution` 是 [JobExecution](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-data) 对象。
## UpdateJobExecution
更新任务执行的状态。（可选）您可以通过为 `stepTimeoutInMinutes` 属性设置值创建步骤计时器。如果您没有通过再次运行 `UpdateJobExecution` 更新此属性的值，任务执行将在步骤计时器到期时超时。
要调用此 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 作业服务中的任务执行版本不匹配，则更新会因`VersionMismatch`错误而被拒绝。还会返回包含当前任务执行状态数据的 [ErrorResponse](jobs-api.md#jobs-mqtt-error-response)。（这样就不必执行单独的 `DescribeJobExecution` 请求以获取任务执行状态数据。）
`executionNumber`
（可选）标识设备上的任务执行的数字。如果未指定，则使用最新的任务执行。
`includeJobExecutionState`
（可选）在包含此参数且设置为 `true` 时，响应将包含 `JobExecutionState` 字段。默认值为 `false`。
`includeJobDocument`
（可选）在包含此参数且设置为 `true` 时，响应将包含 `JobDocument`。默认值为 `false`。
`stepTimeoutInMinutes`
指定此设备完成该任务执行所具有的时间。如果在该计时器到期之前或在重置计时器之前，任务执行状态未设置为最终状态，则任务执行状态设置为 `TIMED_OUT`。设置或重置此超时不会影响在创建任务时可能已指定的任务执行超时。
消息代理将发布 `$aws/things/thingName/jobs/jobId/update/accepted` 和 `$aws/things/thingName/jobs/jobId/update/rejected`，即使您没有指定订阅它们。但是，为了让您的客户端接收消息，客户端必须侦听这些消息。有关更多信息，请参阅[关于 Job API 消息的说明](#jobs-mqtt-note)。
响应负载：
```
{
"executionState": JobExecutionState,
"jobDocument": "string",
"timestamp": timestamp,
"clientToken": "string"
}
```
`executionState`
一个 [JobExecutionState](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-state) 对象。
`jobDocument`
一个[任务文档](key-concepts-jobs.md)对象。
在 MQTT 响应中，`jobDocument` 字段是一个 JSON 对象。在 HTTP 响应中，它是 JSON 对象的字符串表示形式。
`timestamp`
发送消息的时间（用从纪元 开始的秒数表示）。
`clientToken`
用于将请求和响应关联起来的客户端令牌。
使用 MQTT 协议时，您还可以执行以下更新：
## JobExecutionsChanged
在事物的待处理任务执行列表中添加或删除任务执行时发送。
使用 主题：
`$aws/things/thingName/jobs/notify`
消息负载：
```
{
"jobs" : {
"JobExecutionState": [ [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummary.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummary.html) ... ]
},
"timestamp": timestamp
}
```
## NextJobExecutionChanged
当存在对事物的待处理任务执行列表中的下一个任务执行的更改（使用 `jobId` `$next` 为 [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html) 定义）时发送。当下一个任务的执行详细信息发生更改时不会发送此消息，而仅在将由 `DescribeJobExecution`（`jobId` 为 `$next`）返回的下一个任务发生更改时发送。考虑状态为 `QUEUED` 的任务执行 J1 和 J2。J1 是待处理任务执行列表中的下一个待处理任务执行。如果 J2 的状态更改为 `IN_PROGRESS`，而 J1 的状态保持不变，则将发送此通知，并且此通知包含 J2 的详细信息。
使用 主题：
`$aws/things/thingName/jobs/notify-next`
消息负载：
```
{
"execution" : [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecution.html),
"timestamp": timestamp,
}
```
# 任务设备 HTTP API
设备可以在端口 443 上使用 HTTP 签名版本 4 与 AWS IoT Job 通信。这是 AWS SDKs 和 CLI 使用的方法。有关这些工具的更多信息，请参阅[AWS CLI 命令参考：iot-jobs-data](https://docs.aws.amazon.com/cli/latest/reference/iot-jobs-data/index.html)或[AWS SDKs 和工具](https://aws.amazon.com/tools/#sdk)。
以下命令可用于执行任务的设备。有关将 API 操作与 MQTT 协议结合使用的信息，请参阅 [任务设备 MQTT API 操作](jobs-mqtt-api.md)。
## GetPendingJobExecutions
针对指定的事物，获取未处于最终状态的所有任务的列表。
------
#### [ HTTPS request ]
```
GET /things/thingName/jobs
```
响应：
```
{
"inProgressJobs" : [ JobExecutionSummary ... ],
"queuedJobs" : [ JobExecutionSummary ... ]
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_GetPendingJobExecutions.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_GetPendingJobExecutions.html)。
------
#### [ CLI syntax ]
```
aws iot-jobs-data get-pending-job-executions \
--thing-name \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` 格式：
```
{
"thingName": "string"
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/cli/latest/reference/iot-jobs-data/get-pending-job-executions.html](https://docs.aws.amazon.com/cli/latest/reference/iot-jobs-data/get-pending-job-executions.html)。
------
## StartNextPendingJobExecution
获取并启动事物的下一个待处理任务执行（状态为 `IN_PROGRESS` 或 `QUEUED`）。
+ 首先返回状态为 `IN_PROGRESS` 的所有任务执行。
+ 按任务执行的创建顺序返回这些执行。
+ 如果下一个待处理任务执行的状态为 `QUEUED`，则其状态将更改为 `IN_PROGRESS`，并且任务执行的状态详细信息将设定为指定内容。
+ 如果下一个待处理任务执行已处于 `IN_PROGRESS` 状态，其状态详细信息不会发生变化。
+ 如果没有待处理的任务执行，则响应不包括 `execution` 字段。
+ （可选）您可以通过为 `stepTimeoutInMinutes` 属性设置值来创建步骤计时器。如果您没有通过运行 `UpdateJobExecution` 更新此属性的值，任务执行将在步骤计时器到期时超时。
------
#### [ HTTPS request ]
以下示例显示请求语法：
```
PUT /things/thingName/jobs/$next
{
"statusDetails": {
"string": "string"
...
},
"stepTimeoutInMinutes": long
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_StartNextPendingJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_StartNextPendingJobExecution.html)。
------
#### [ CLI syntax ]
**摘要：**
```
aws iot-jobs-data start-next-pending-job-execution \
--thing-name \
{--step-timeout-in-minutes ] \
[--status-details ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` 格式：
```
{
"thingName": "string",
"statusDetails": {
"string": "string"
},
"stepTimeoutInMinutes": long
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/cli/latest/reference/iot-jobs-data/start-next-pending-job-execution.html](https://docs.aws.amazon.com/cli/latest/reference/iot-jobs-data/start-next-pending-job-execution.html)。
------
## DescribeJobExecution
获取有关任务执行的详细信息。
您可以将 `jobId` 设置为 `$next` 以返回事物的下一个待处理任务执行。任务的执行状态必须为 `QUEUED` 或 `IN_PROGRESS`。
------
#### [ HTTPS request ]
请求:
```
GET /things/thingName/jobs/jobId?executionNumber=executionNumber&includeJobDocument=includeJobDocument
```
响应:
```
{
"execution" : JobExecution,
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html)。
------
#### [ CLI syntax ]
**摘要：**
```
aws iot-jobs-data describe-job-execution \
--job-id \
--thing-name \
[--include-job-document | --no-include-job-document] \
[--execution-number ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` 格式：
```
{
"jobId": "string",
"thingName": "string",
"includeJobDocument": boolean,
"executionNumber": long
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/cli/latest/reference/iot-data/describe-job-execution.html](https://docs.aws.amazon.com/cli/latest/reference/iot-data/describe-job-execution.html)。
------
## UpdateJobExecution
更新任务执行的状态。（可选）您可以通过为 `stepTimeoutInMinutes` 属性设置值来创建步骤计时器。如果您没有通过再次运行 `UpdateJobExecution` 更新此属性的值，任务执行将在步骤计时器到期时超时。
------
#### [ HTTPS request ]
请求:
```
POST /things/thingName/jobs/jobId
{
"status": "job-execution-state",
"statusDetails": {
"string": "string"
...
},
"expectedVersion": "number",
"includeJobExecutionState": boolean,
"includeJobDocument": boolean,
"stepTimeoutInMinutes": long,
"executionNumber": long
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_UpdateJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_UpdateJobExecution.html)。
------
#### [ CLI syntax ]
**摘要：**
```
aws iot-jobs-data update-job-execution \
--job-id \
--thing-name \
--status \
[--status-details ] \
[--expected-version ] \
[--include-job-execution-state | --no-include-job-execution-state] \
[--include-job-document | --no-include-job-document] \
[--execution-number ] \
[--cli-input-json ] \
[--step-timeout-in-minutes ] \
[--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
}
```
有关更多信息，请参阅 [https://docs.aws.amazon.com/cli/latest/reference/iot-data/update-job-execution.html](https://docs.aws.amazon.com/cli/latest/reference/iot-data/update-job-execution.html)。
------
# 使用 AWS IoT Jobs 保护用户和设备
要授权用户在其设备上使用 AWS IoT Jobs，您必须使用 IAM 策略向他们授予权限。然后，必须使用 AWS IoT Core 策略对设备进行授权 AWS IoT，才能安全连接、接收任务执行并更新执行状态。
## AWS IoT 任务必需的策略类型
下表显示了进行授权所必须使用的不同类型的策略。有关要使用的所需策略的更多信息，请参阅 [Authorization](iot-authorization.md)。
**所需策略类型**
| 使用案例 | 协议 | 身份验证 | 控制 plane/data 平面 | 身份类型 | 所需策略类型 |
| --- | --- | --- | --- | --- | --- |
| 授权管理员、运营商或云服务安全地使用 Jobs | HTTPS | AWS 签名版本 4 身份验证（端口 443） | 控制面板和数据面板 | Amazon Cognito Identity 、IAM 或联合身份用户 | IAM 策略 |
| 授权您的物联网设备安全地使用 Jobs | MQTT/HTTPS | TCP 或 TLS 双向身份验证（端口 8883 或 443 ） | 数据面板 | X.509 证书 | AWS IoT Core 政策 |
要授权可在控制平面和数据平面上执行的 AWS IoT 任务操作，您必须使用 IAM 策略。身份必须已向 AWS IoT 进行身份验证才能执行这些操作，必须为 [Amazon Cognito Identity](cognito-identities.md) 或 [IAM 用户、组和角色](iam-users-groups-roles.md)。有关身份验证的更多信息，请参阅 [身份验证](authentication.md)。
现在，必须使用 AWS IoT Core 策略在数据平面上对设备进行授权，才能安全地连接到设备网关。设备网关使设备能够安全地与之通信 AWS IoT、接收任务执行并更新任务执行状态。通过使用安全的 [MQTT](mqtt.md) 或 [HTTPS 发布](http.md) 通信协议保护设备通信。这些协议使用[X.509 客户端证书](x509-client-certs.md)提供的协议 AWS IoT 对设备连接进行身份验证。
以下内容显示了您如何授权您的用户、云服务和设备使用 AWS IoT Jobs。有关控制面板和数据面板 API 操作的更多信息，请参阅 [AWS IoT 作业 API 操作](jobs-api.md)。
**Topics**
+ [AWS IoT 任务必需的策略类型](#jobs-required-policy)
+ [授权用户和云服务使用 AWS IoT 作业](iam-policy-users-jobs.md)
+ [授权您的设备在数据平面上安全地使用 AWS IoT 作业](iot-data-plane-jobs.md)
# 授权用户和云服务使用 AWS IoT 作业
要向用户和云服务授权，您必须同时在控制面板和数据面板上使用 IAM 策略。这些策略必须与 HTTPS 协议一起使用，并且必须使用 AWS 签名版本 4 身份验证（端口 443）对用户进行身份验证。
**注意**
AWS IoT Core 不得在控制平面上使用策略。只有 IAM 策略用于向用户或云服务授权。有关使用所需策略类型的更多信息，请参阅 [AWS IoT 任务必需的策略类型](iot-jobs-security.md#jobs-required-policy)。
IAM 策略是包含策略声明的 JSON 文档。策略语句使用*效果*、*操作* 和*资源* 元素以指定资源、允许或拒绝的操作以及允许或拒绝操作的条件。有关更多信息，请参阅*《IAM 用户指南》*中的 [IAM JSON 策略元素参考](https://docs.aws.amazon.com/service-authorization/latest/reference/reference_policies_elements.html)。
**警告**
我们建议您不要使用通配符权限，例如`"Action": ["iot:*"]`在 IAM 策略或 AWS IoT Core 策略中使用通配符权限。使用通配符权限不是推荐的安全最佳实践。有关更多信息，请参阅 [AWS IoT 策略过于宽容](https://docs.aws.amazon.com/iot-device-defender/latest/devguide/audit-chk-iot-policy-permissive.html)。
## 控制面板上的 IAM 策略
在控制面板上，IAM 策略对操作使用 `iot:` 前缀，以便授权执行相应的任务 API 操作。例如，`iot:CreateJob` 策略操作授予用户使用 [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html) API 的权限。
### 策略操作
下表显示了 IAM 策略操作和使用 API 操作的权限的列表。有关资源类型的信息，请参阅[由定义的资源类型 AWS IoT](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsiot.html#awsiot-job)。有关 AWS IoT 操作的更多信息，请参阅[由定义的操作 AWS IoT](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsiot.html)。
**控制面板上的 IAM 策略操作**
| 策略操作 | API 操作 | 资源类型 | 说明 |
| --- | --- | --- | --- |
| iot:AssociateTargetsWithJob | [https://docs.aws.amazon.com/iot/latest/apireference/API_AssociateTargetsWithJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_AssociateTargetsWithJob.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot/latest/developerguide/iam-policy-users-jobs.html) | 表示将组与连续任务关联的权限。每次请求关联目标时，都会检查 iot:AssociateTargetsWithJob 权限。 |
| iot:CancelJob | [https://docs.aws.amazon.com/iot/latest/apireference/API_CancelJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CancelJob.html) | 作业 | 表示取消任务的权限。每次请求取消任务时，都会检查 iot:CancelJob 权限。 |
| iot:CancelJobExecution | [https://docs.aws.amazon.com/iot/latest/apireference/API_CancelJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CancelJobExecution.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot/latest/developerguide/iam-policy-users-jobs.html) | 表示取消任务执行的权限。每次请求取消任务执行时，都会检查 iot: CancelJobExecution 权限。 |
| iot:CreateJob | [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot/latest/developerguide/iam-policy-users-jobs.html) | 表示创建任务的权限。每次请求创建任务时，都会检查 iot: CreateJob 权限。 |
| iot:CreateJobTemplate | [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot/latest/developerguide/iam-policy-users-jobs.html) | 表示创建任务模板的权限。每次请求创建任务模板时，都会检查 iot: CreateJobTemplate 权限。 |
| iot:DeleteJob | [https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJob.html) | 作业 | 表示删除任务的权限。每次请求删除任务时，都会检查 iot: DeleteJob 权限。 |
| iot:DeleteJobTemplate | [https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJobTemplate.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJobTemplate.html) | jobtemplate | 表示删除任务模板的权限。每次请求删除任务模板时，都会检查 iot: CreateJobTemplate 权限。 |
| iot:DeleteJobExecution | [https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJobExecution.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot/latest/developerguide/iam-policy-users-jobs.html) | 表示删除任务执行的权限。每次请求删除任务执行时，都会检查 iot: DeleteJobExecution 权限。 |
| iot:DescribeJob | [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJob.html) | 作业 | 表示描述任务的权限。每次请求描述任务时，都会检查 iot: DescribeJob 权限。 |
| iot:DescribeJobExecution | [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot/latest/developerguide/iam-policy-users-jobs.html) | 表示描述任务执行的权限。每次请求描述任务执行时，都会检查 iot: DescribeJobExecution 权限。 |
| iot:DescribeJobTemplate | [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobTemplate.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobTemplate.html) | jobtemplate | 表示描述任务模板的权限。每次请求描述任务模板时，都会检查 iot: DescribeJobTemplate 权限。 |
| iot:DescribeManagedJobTemplate | [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeManagedJobTemplate.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeManagedJobTemplate.html) | jobtemplate | 表示描述托管式任务模板的权限。每次请求描述托管式任务模板时，都会检查 iot: DescribeManagedJobTemplate 权限。 |
| iot:GetJobDocument | [https://docs.aws.amazon.com/iot/latest/apireference/API_GetJobDocument.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetJobDocument.html) | 作业 | 表示获取任务的任务文档的权限。每次请求获取任务文档时，都会检查 iot:GetJobDocument 权限。 |
| iot:ListJobExecutionsForJob | [https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobExecutionsForJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobExecutionsForJob.html) | 作业 | 表示列出任务的任务执行的权限。每次请求列出任务的任务执行时，都会检查 iot:ListJobExecutionsForJob 权限。 |
| iot:ListJobExecutionsForThing | [https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobExecutionsForThing.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobExecutionsForThing.html) | thing | 表示列出任务的任务执行的权限。每次请求列出事物的任务执行时，都会检查 iot:ListJobExecutionsForThing 权限。 |
| iot:ListJobs | [https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobs.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobs.html) | none | 表示列出任务的权限。每次请求列出任务时，都会检查 iot:ListJobs 权限。 |
| iot:ListJobTemplates | [https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobTemplates.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobTemplates.html) | none | 表示列出任务模板的权限。每次请求列出任务模板时，都会检查 iot:ListJobTemplates 权限。 |
| iot:ListManagedJobTemplates | [https://docs.aws.amazon.com/iot/latest/apireference/API_ListManagedJobTemplates.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListManagedJobTemplates.html) | none | 表示列出托管式任务模板的权限。每次请求列出托管式任务模板时，都会检查 iot:ListManagedJobTemplates 权限。 |
| iot:UpdateJob | [https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateJob.html) | 作业 | 表示更新任务的权限。每次请求更新任务时，都会检查 iot:UpdateJob 权限。 |
| iot:TagResource | [https://docs.aws.amazon.com/iot/latest/apireference/API_TagResource.html](https://docs.aws.amazon.com/iot/latest/apireference/API_TagResource.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot/latest/developerguide/iam-policy-users-jobs.html) | 授予标记特定资源的权限。 |
| iot:UntagResource | [https://docs.aws.amazon.com/iot/latest/apireference/API_UntagResource.html](https://docs.aws.amazon.com/iot/latest/apireference/API_UntagResource.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot/latest/developerguide/iam-policy-users-jobs.html) | 授予取消标记特定资源的权限。 |
### 基本 IAM 策略示例
下面的示例显示了 IAM 策略，该策略授予用户对物联网事物和事物组执行以下操作的权限。
在此示例中：
+ *region*和你的 AWS 区域，比如`us-east-1`。
+ *account-id*用你的 AWS 账户 电话号码，比如`57EXAMPLE833`。
+ *thing-group-name*上面写上你要定位工作的物联网事物组的名称，例如`FirmwareUpdateGroup`。
+ *thing-name*写上你瞄准工作的物联网事物的名称，例如`MyIoTThing`。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"iot:CreateJobTemplate",
"iot:CreateJob"
],
"Effect": "Allow",
"Resource": "arn:aws:iot:us-east-1:123456789012:thinggroup/thing-group-name"
},
{
"Action": [
"iot:DescribeJob",
"iot:CancelJob",
"iot:DeleteJob"
],
"Effect": "Allow",
"Resource": "arn:aws:iot:us-east-1:123456789012:job/*"
},
{
"Action": [
"iot:DescribeJobExecution",
"iot:CancelJobExecution",
"iot:DeleteJobExecution"
],
"Effect": "Allow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing-123",
"arn:aws:iot:us-east-1:123456789012:job/*"
]
}
]
}
```
### 适用于基于 IP 的授权的 IAM 策略示例
您可以限制*主体* 从特定 IP 地址对控制面板端点进行 API 调用。要指定可以允许的 IP 地址，请在 IAM policy 的条件元素中使用 [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceip](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceip) 全局条件键。
使用此条件密钥还可以拒绝其他 AWS 服务人代表您进行这些 API 调用，例如 AWS CloudFormation。要允许访问这些服务，请使用带有 aws: 密钥的[https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-viaawsservice](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-viaawsservice)全局条件SourceIp 密钥。这可以确保源 IP 地址访问限制仅适用于由主体直接发出的请求。有关更多信息，请参阅 [AWS： AWS 根据源 IP 拒绝访问](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_examples_aws_deny-ip.html)。
以下示例说明如何仅允许能够对控制面板端点进行 API 调用的特定 IP 地址。`aws:ViaAWSService` 键设置为 `true`，这允许其它服务代表您进行 API 调用。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:CreateJobTemplate",
"iot:CreateJob"
],
"Resource": [
"*"
],
"Condition": {
"IpAddress": {
"aws:SourceIp": "123.45.167.89"
},
"Bool": {
"aws:ViaAWSService": "false"
}
}
}]
}
```
## 数据面板上的 IAM 策略
数据面板上的 IAM 策略使用 `iotjobsdata:` 前缀以授权用户可以执行的任务 API 操作。在数据面板上，可以通过使用 `iotjobsdata:DescribeJobExecution` 策略操作授予用户使用 [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html) API 的权限。
**警告**
当设备的目标指向 AWS IoT Jobs 时，不建议在数据面板上使用 IAM 策略。我们建议您在控制面板上使用 IAM 策略，供用户创建和管理任务。在数据面板上，要授权设备检索任务执行和更新执行状态，请使用 [AWS IoT Core HTTPS 协议的策略](iot-data-plane-jobs.md#iot-jobs-data-http)。
### 基本 IAM 策略示例
必须授权的 API 操作通常由您键入 CLI 命令来执行。下面显示了用户执行 `DescribeJobExecution` 操作的示例。
在此示例中：
+ *region*和你的 AWS 区域，比如`us-east-1`。
+ *account-id*用你的 AWS 账户 电话号码，比如`57EXAMPLE833`。
+ *thing-name*写上你瞄准工作的物联网事物的名称，例如`myRegisteredThing`。
+ `job-id` 是使用 API 确定的目标任务的唯一标识符。
```
aws iot-jobs-data describe-job-execution \
--endpoint-url "https://account-id.jobs.iot.region.amazonaws.com" \
--job-id jobID --thing-name thing-name
```
下面显示了授权执行此操作的示例 IAM 策略：
****
```
{
"Version":"2012-10-17",
"Statement": {
"Action": [
"iotjobsdata:DescribeJobExecution"
],
"Effect": "Allow",
"Resource": "arn:aws:iot:us-east-1:123456789012:thing/thing-123"
}
}
```
### 适用于基于 IP 的授权的 IAM 策略示例
您可以限制*主体* 从特定 IP 地址对数据面板端点进行 API 调用。要指定可以允许的 IP 地址，请在 IAM policy 的条件元素中使用 [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceip](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceip) 全局条件键。
使用此条件密钥还可以拒绝其他 AWS 服务人代表您进行这些 API 调用，例如 AWS CloudFormation。要允许访问这些服务，请将 [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-viaawsservice](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-viaawsservice) 全局条件键与 `aws:SourceIp` 条件键一起使用。这可确保 IP 地址访问限制仅适用于主体直接发出的请求。有关更多信息，请参阅 [AWS： AWS 根据源 IP 拒绝访问](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_examples_aws_deny-ip.html)。
以下示例说明如何仅允许能够对数据面板端点进行 API 调用的特定 IP 地址。
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"iotjobsdata:*"
],
"Resource": [
"*"
],
"Condition": {
"IpAddress": {
"aws:SourceIp": "123.45.167.89"
},
"Bool": {
"aws:ViaAWSService": "false"
}
}
}]
}
```
以下示例说明如何限制特定 IP 地址或地址范围，使其无法对数据面板端点进行 API 调用。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": [
"iotjobsdata:*"
],
"Condition": {
"IpAddress": {
"aws:SourceIp": [
"123.45.167.89",
"192.0.2.0/24",
"203.0.113.0/24"
]
}
},
"Resource": [
"*"
]
}
]
}
```
### 控制面板和数据面板的 IAM 策略示例
如果您同时在控制面板和数据面板上执行 API 操作，则控制面板策略操作必须使用 `iot:` 前缀，而数据面板策略操作必须使用 `iotjobsdata:` 前缀。
例如，`DescribeJobExecution` API 可以同时用于控制面板和数据面板中。在控制平面上，[DescribeJobExecution](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html)API 用于描述任务执行。在数据层面上，[ DescribeJobExecution](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html)API 用于获取任务执行的详细信息。
以下 IAM 策略授予用户同时在控制面板和数据面板上使用 `DescribeJobExecution` API 的权限。
在此示例中：
+ *region*和你的 AWS 区域，比如`us-east-1`。
+ *account-id*用你的 AWS 账户 电话号码，比如`57EXAMPLE833`。
+ *thing-name*写上你瞄准工作的物联网事物的名称，例如`MyIoTThing`。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"iotjobsdata:DescribeJobExecution"
],
"Effect": "Allow",
"Resource": "arn:aws:iot:us-east-1:123456789012:thing/thing-123"
},
{
"Action": [
"iot:DescribeJobExecution",
"iot:CancelJobExecution",
"iot:DeleteJobExecution"
],
"Effect": "Allow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing-123",
"arn:aws:iot:us-east-1:123456789012:job/*"
]
}
]
}
```
## 授权对 IoT 资源进行标记
为了更好地控制您可以创建、修改或使用的任务和任务模板，可以将标签附加到任务或任务模板。还可以通过将标签放在账单组中并向其附加标签，帮助您辨别所有权并分配和分摊成本。
当用户想要标记他们使用或创建的任务或任务模板时 AWS CLI，您的 IAM 策略必须向该用户授予对其进行标记的权限。 AWS 管理控制台 要授予权限，IAM 策略必须使用 `iot:TagResource` 操作。
**注意**
如果您的 IAM 策略不包含 `iot:TagResource` 操作，则任何带有标签的 [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html) 或 [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html) 都将返回 `AccessDeniedException` 错误。
当您想要为使用或创建的任务或任务模板添加标签时，您的 IAM 策略必须授予对它们进行标记的权限。 AWS 管理控制台 AWS CLI要授予权限，IAM 策略必须使用 `iot:TagResource` 操作。
有关标记实例的一般信息，请参阅[为资源添加 AWS IoT 标签](tagging-iot.md)。
### IAM 策略示例
请参阅以下授予标记权限的 IAM 策略示例：
*示例 1*
某位用户运行以下命令来创建任务并将其标记到特定环境。
在此示例中：
+ *region*和你的 AWS 区域，比如`us-east-1`。
+ *account-id*用你的 AWS 账户 电话号码，比如`57EXAMPLE833`。
+ *thing-name*写上你瞄准工作的物联网事物的名称，例如`MyIoTThing`。
```
aws iot create-job
--job-id test_job
--targets "arn:aws:iot:region:account-id:thing/thingOne"
--document-source "https://s3.amazonaws.com/amzn-s3-demo-bucket/job-document.json"
--description "test job description"
--tags Key=environment,Value=beta
```
对于本示例，您必须使用以下 IAM 策略：
****
```
{
"Version":"2012-10-17",
"Statement": {
"Action": [
"iot:CreateJob",
"iot:CreateJobTemplate",
"iot:TagResource"
],
"Effect": "Allow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:job/*",
"arn:aws:iot:us-east-1:123456789012:jobtemplate/*"
]
}
}
```
# 授权您的设备在数据平面上安全地使用 AWS IoT 作业
要授权您的设备在数据层面上安全地与 AWS IoT 任务交互，您必须使用 AWS IoT Core 策略。 AWS IoT Core 作业策略是包含政策声明的 JSON 文档。这些策略还使用*效果*、*操作* 和*资源* 元素，并遵循与 IAM 策略类似的约定。有关这些元素的更多信息，请参阅*《IAM 用户指南》*中的 [IAM JSON 策略元素参考](https://docs.aws.amazon.com/service-authorization/latest/reference/reference_policies_elements.html)。
这些策略可以与 MQTT 和 HTTPS 协议一起使用，并且必须使用 TCP 或 TLS 双向身份验证来对设备进行身份验证。下面展示了如何在不同的通信协议中使用这些策略。
**警告**
我们建议您不要使用通配符权限，例如`"Action": ["iot:*"]`在 IAM 策略或 AWS IoT Core 策略中使用通配符权限。使用通配符权限不是推荐的安全最佳实践。有关更多信息，请参阅 [AWS IoT 策略过于宽容](https://docs.aws.amazon.com/iot-device-defender/latest/devguide/audit-chk-iot-policy-permissive.html)。
## AWS IoT Core 适用于 MQTT 协议的策略
AWS IoT Core MQTT 协议策略授予您使用作业设备 MQTT API 操作的权限。MQTT API 操作用于处理为任务命令保留的 MQTT 主题。有关这些 API 操作的更多信息，请参阅 [任务设备 MQTT API 操作](jobs-mqtt-api.md)。
MQTT 策略使用策略操作（如 `iot:Connect`、`iot:Publish`、`iot:Subscribe` 和 `iot:Receieve`）来处理任务主题。这些策略允许您连接到消息代理，订阅任务 MQTT 主题，以及在设备和云之间发送和接收 MQTT 消息。有关这些操作的更多信息，请参阅 [AWS IoT Core 政策行动](iot-policy-actions.md)。
有关 AWS IoT 作业主题的信息，请参阅[任务主题](reserved-topics.md#reserved-topics-job)。
### 基本 MQTT 策略示例
下面的示例显示如何使用 `iot:Publish` 和 `iot:Subscribe` 发布和订阅任务和任务执行。
在此示例中：
+ *region*和你的 AWS 区域，比如`us-east-1`。
+ *account-id*用你的 AWS 账户 电话号码，比如`57EXAMPLE833`。
+ *thing-name*写上你瞄准工作的物联网事物的名称，例如`MyIoTThing`。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Publish",
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/events/job/*",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/events/jobExecution/*",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thing-123/jobs/*"
]
}
]
}
```
## AWS IoT Core HTTPS 协议的策略
AWS IoT Core 数据层面的策略还可以使用带有 TLS 身份验证机制的 HTTPS 协议来授权您的设备。在数据面板上，策略使用 `iotjobsdata:` 前缀以授权您的设备可以执行的任务 API 操作。例如，`iotjobsdata:DescribeJobExecution` 策略操作授予用户使用 [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html) API 的权限。
**注意**
数据面板策略操作必须使用 `iotjobsdata:` 前缀。在控制面板上，操作必须使用 `iot:` 前缀。有关使用控制面板和数据面板策略操作时的 IAM 策略示例，请参阅 [控制面板和数据面板的 IAM 策略示例](iam-policy-users-jobs.md#iam-data-plane-example2)。
### 策略操作
下表显示了授权设备使用 API 操作的 AWS IoT Core 策略操作和权限列表。有关可以在数据面板执行的 API 操作的列表，请参阅 [任务设备 HTTP API](jobs-http-device-api.md)。
**注意**
这些任务执行策略操作仅适用于 HTTP TLS 端点。如果您使用 MQTT 端点，则必须之前定义的 MQTT 策略操作。
**AWS IoT Core 数据层面的策略操作**
| 策略操作 | API 操作 | 资源类型 | 说明 |
| --- | --- | --- | --- |
| iotjobsdata:DescribeJobExecution | [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot/latest/developerguide/iot-data-plane-jobs.html) | 表示检索任务执行的权限。每次请求检索任务执行时，都会检查 iotjobsdata:DescribeJobExecution 权限。 |
| iotjobsdata:GetPendingJobExecutions | [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_GetPendingJobExecutions.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_GetPendingJobExecutions.html) | thing | 表示一个权限，用于为事物检索未处于最终状态的任务的列表。每次请求检索该列表时，都会检查 iotjobsdata:GetPendingJobExecutions 权限。 |
| iotjobsdata:StartNextPendingJobExecution | [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_GetPendingJobExecutions.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_GetPendingJobExecutions.html) | thing | 表示一个权限，用于为事物获取和启动下一个待处理任务执行。即，将状态为 QUEUED 的任务执行更新为状态 IN\$1PROGRESS。每次请求启动下一个待处理任务执行，都会检查 iotjobsdata:StartNextPendingJobExecution 权限。 |
| iotjobsdata:UpdateJobExecution | [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_UpdateJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_UpdateJobExecution.html) | thing | 表示更新任务执行的权限。每次请求更新任务执行的状态时，都会检查 iotjobsdata:UpdateJobExecution 权限。 |
### 基本策略示例
以下是一个策略示例，该 AWS IoT Core 策略授予对任何资源在数据平面 API 操作上执行操作的权限。您可以将策略范围限定为特定资源，例如物联网事物。在您的示例中：
+ *region*和你的，比 AWS 区域 如`us-east-1`。
+ *account-id*用你的 AWS 账户 电话号码，比如`57EXAMPLE833`。
+ *thing-name*用物联网的名字命名，比如`MyIoTthing`。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"iotjobsdata:GetPendingJobExecutions",
"iotjobsdata:StartNextPendingJobExecution",
"iotjobsdata:DescribeJobExecution",
"iotjobsdata:UpdateJobExecution"
],
"Effect": "Allow",
"Resource": "arn:aws:iot:us-east-1:123456789012:thing/thing-123"
}
]
}
```
必须使用这些策略的一个示例情形是：IoT 设备使用 AWS IoT Core 策略来访问其中一个 API 操作，例如下面的 `DescribeJobExecution` API 示例：
```
GET /things/thingName/jobs/jobId?executionNumber=executionNumber&includeJobDocument=includeJobDocument&namespaceId=namespaceId HTTP/1.1
```
# AWS IoT 职位限制
AWS IoT 作业的服务配额或限制与您的服务资源或操作的最大数量相对应 AWS 账户。
**Topics**
+ [任务执行限制](#job-execution-limits)
+ [活动和并发任务限制](#job-limits-active-concurrent)
## 任务执行限制
本节提供有关 AWS IoT Device Management的任务执行限制的信息。
**注意**
这些限制不属于您可以在 [AWS IoT Device Management 服务配额文档](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html#iot_device_management_quotas)中找到的服务配额的一部分。
要获取有关待执行任务数量的信息，您可以使用 `GetPendingJobExecutions` API，也可以订阅 MQTT 为 AWS IoT 任务保留的主题并接收[任务通知类型。](jobs-comm-notifications.md#jobs-comm-notifications-types)。
您账户中待处理的任务执行数量可能会有所不同，具体取决于您是否启用了调度配置并使用重复维护窗口。
**最大待处理任务执行数**
| API/通知名称 | 说明 | 无计划配置 | 有计划配置 |
| --- | --- | --- | --- |
| ListNotification | 当旧的任务执行进入终端状态，或者新的任务执行排队或更改为非终端状态时，会发布 ListNotification。它最多可以显示 15 个处于 QUEUED 或 IN\$1PROGRESS 状态的待处理任务执行。 | 10 | 15（在维护窗口期间，ListNotification 中仅显示最多 5 个任务执行）。 |
| GetPendingJobExecutions | 当您调用 `GetPendingJobExecutions` API 时，它会返回尚未启动且可以在 API 调用后启动的任务执行列表。API 最多可以返回 10 个待处理的任务执行。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot/latest/developerguide/job-limits.html) | 10 | 15 |
## 活动和并发任务限制
本节将帮助您了解有关活动和并发任务以及适用于这些任务的限制的更多信息。
**活动任务和活动任务限制**
当您使用 AWS IoT 控制台或 `CreateJob` API 创建任务时，任务状态会更改为`IN_PROGRESS`。所有正在进行的任务都是*活动任务* 并计入活动任务限制。这包括正在推出新任务执行的任务，或者正在等待设备完成任务执行的任务。此限制同时适用于连续任务和快照任务。
**并发任务和任务并发限制**
正在推出新任务执行或取消先前创建的任务执行的正在进行的作业均为*并发作业*，计入作业并发限制。 AWS IoT 任务可以以每分钟 1000 台设备的速度快速推出和取消任务执行。每个任务都是 `concurrent`，并且仅在短时间内计入任务并发限制。在推出或取消任务执行之后，该任务将不再为并发的，而不计入任务并发限制。在等待设备完成任务执行的同时，您可以使用任务并发创建大量任务。
**注意**
如果计划在维护时段内执行的具有可选计划配置和任务文档推出的任务达到选定的 `startTime`，并且您处于最大任务并发限制，则该计划任务将移至 `CANCELED` 状态。
要确定作业是否为并发任务，可以在 AWS IoT 控制台中使用作业的`IsConcurrent`属性，也可以使用`DescribeJob`或 `ListJob` API。此限制同时适用于连续任务和快照任务。
要查看您的活动任务和任务并发限制以及其他 AWS IoT 任务配额 AWS 账户 并请求提高限制，请参阅中的[AWS IoT 设备管理终端节点和配额](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html#job-limits)。 AWS 一般参考
下图显示了任务并发如何适用于正在进行的任务和正在取消的任务。
![\[该图显示了 AWS IoT 作业的不同状态。\]](http://docs.aws.amazon.com/zh_cn/iot/latest/developerguide/images/job-states-concurrency.png)
**注意**
带有可选 `SchedulingConfig` 的新任务将保持初始状态 `SCHEDULED`，并在达到选定 `startTime` 时更新为 `IN_PROGRESS`。在带有可选 `SchedulingConfig` 的新任务达到选定的 `startTime`，并更新为 `IN_PROGRESS` 后，它将计入活动任务限制和任务并发限制。状态为 `SCHEDULED` 的任务将计入活动任务限制，但不会计入任务并发限制。
下表显示了适用于活跃和并发任务以及任务状态的并发和非并发阶段的限制。
**活动和并发任务限制**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot/latest/developerguide/job-limits.html)
**注意**
定期维护时段的最长持续时间为 23 小时 50 分钟。