本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 使用创建和管理作业 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` 的任务执行后，执行该任务的设备将无法访问任务信息或更新任务执行状态。请谨慎使用，并且 确保 设备能够恢复到有效状态。