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

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

任务管理和控制数据类型
任务管理和控制 API 操作

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


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

此命令将返回以下输出。



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

注意

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

任务管理和控制数据类型

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

Job 对象包含有关任务的详细信息。以下示例显示该语法：


{
    "jobArn": "string", 
    "jobId": "string", 
    "status": "IN_PROGRESS|CANCELED|SUCCEEDED", 
    "forceCanceled": boolean,
    "targetSelection": "CONTINUOUS|SNAPSHOT",
    "comment": "string",
    "targets": ["string"], 
    "description": "string",
    "createdAt": timestamp,
    "lastUpdatedAt": timestamp,
    "completedAt": timestamp,
    "jobProcessDetails": {
        "processingTargets": ["string"],
        "numberOfCanceledThings": long, 
        "numberOfSucceededThings": long, 
        "numberOfFailedThings": long,
        "numberOfRejectedThings": long, 
        "numberOfQueuedThings": long, 
        "numberOfInProgressThings": long, 
        "numberOfRemovedThings": long, 
        "numberOfTimedOutThings": long
    }, 
    "presignedUrlConfig": {
        "expiresInSec": number, 
        "roleArn": "string"
    }, 
    "jobExecutionsRolloutConfig": { 
        "exponentialRate": { 
           "baseRatePerMinute": integer,
           "incrementFactor": integer,
           "rateIncreaseCriteria": { 
              "numberOfNotifiedThings": integer, // Set one or the other
              "numberOfSucceededThings": integer // of these two values.
           },
           "maximumPerMinute": integer
      }
    },    
    "abortConfig": { 
       "criteriaList": [ 
          { 
             "action": "string",
             "failureType": "string",
             "minNumberOfExecutedThings": integer,
             "thresholdPercentage": integer
          }
       ]
    },
    "SchedulingConfig": { 
      "startTime": string
      "endTime": string
      "timeZone": string


      "endTimeBehavior": string

   },
    "timeoutConfig": {
        "inProgressTimeoutInMinutes": long
    }
}

有关更多信息，请参阅 Job 或 job。

JobSummary 对象包含任务摘要。以下示例显示该语法：


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

有关更多信息，请参阅 JobSummary 或 job-summary。

JobExecution 对象表示设备上的任务执行。以下示例显示该语法：

注意

当您使用控制面板 API 操作时，JobExecution 数据类型不包含 JobDocument 字段。要获取此信息，您可以使用 GetJobDocument API 操作或 get-job-document 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
}

有关更多信息，请参阅 JobExecution 或 job-execution。

JobExecutionSummary 对象包含任务执行摘要信息。以下示例显示该语法：


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

有关更多信息，请参阅 JobExecutionSummary 或 job-execution-summary。

JobExecutionSummaryForJob 对象包含有关特定任务的任务执行的信息摘要。以下示例显示该语法：


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

有关更多信息，请参阅 JobExecutionSummaryForJob 或 job-execution-summary-for-job。

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


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

有关更多信息，请参阅 JobExecutionSummaryForThing 或 job-execution-summary-for-thing。

任务管理和控制 API 操作

使用以下 API 操作或 CLI 命令：

将组与持续任务关联。必须满足以下标准：

必须已在 targetSelection 字段设置为 CONTINUOUS 的情况下创建任务。
任务状态当前必须为 IN_PROGRESS。
与任务关联的目标总数不能超过 100。

取消任务。

取消设备上的任务执行。

创建任务。您可以提供任务文档，作为指向 Amazon S3 桶（documentSource 参数）中或请求正文（document 参数）中的文件的链接。

通过将可选的 targetSelection 参数设置为 CONTINUOUS（默认为 SNAPSHOT），可使任务成为连续任务。连续任务可用于在将设备添加到组时登记或升级设备，因为它将继续运行并在新添加的事物上启动。即使在创建任务时组中的事物已完成任务，也可能发生这种情况。

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

对 CreateJob API 的参数执行以下验证：

targets 参数必须是有效事物或事物组 ARN 的列表。所有事物和事物组必须在您的Amazon Web Services 账户中。
documentSource 参数必须是指向任务文档的有效 Amazon S3 URL。Amazon S3 URL 的格式为：https://s3.amazonaws.com/bucketName/objectName。
存储在由 documentSource 参数指定的 URL 中的文档必须是 UTF-8 编码的 JSON 文档。
由于 MQTT 消息大小限制 (128 KB) 和加密的原因，任务文档的大小限制为 32 KB。
jobId 必须在您的Amazon Web Services 账户中是唯一的。

HTTPS request


PUT /jobs/jobId
 
{
"targets": [ "string" ],
"document": "string",
"documentSource": "string",
"description": "string",
"jobTemplateArn": "string",
"presignedUrlConfigData": {
    "roleArn": "string", 
    "expiresInSec": "integer" 
},
"targetSelection": "CONTINUOUS|SNAPSHOT",
"jobExecutionsRolloutConfig": { 
    "exponentialRate": { 
       "baseRatePerMinute": integer,
       "incrementFactor": integer,
       "rateIncreaseCriteria": { 
          "numberOfNotifiedThings": integer, // Set one or the other
          "numberOfSucceededThings": integer // of these two values.
       },
       "maximumPerMinute": integer
  }
},
"abortConfig": { 
   "criteriaList": [ 
      { 
         "action": "string",
         "failureType": "string",
         "minNumberOfExecutedThings": integer,
         "thresholdPercentage": integer
      }
   ]
},
"SchedulingConfig": { 
    "startTime": string
    "endTime": string
    "timeZone": string


    "endTimeBehavior": string

   }
"timeoutConfig": { 
  "inProgressTimeoutInMinutes": long
}
}

有关更多信息，请参阅CreateJob。

CLI syntax


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

cli-input-json 格式：


{
    "jobId": "string",
    "targets": [ "string" ],
    "documentSource": "string",
    "document": "string",
    "description": "string",
    "jobTemplateArn": "string",
    "presignedUrlConfig": {
        "roleArn": "string",
        "expiresInSec": long
     },
    "targetSelection": "string",
    "jobExecutionsRolloutConfig": { 
          "exponentialRate": { 
              "baseRatePerMinute": integer,
              "incrementFactor": integer,
              "rateIncreaseCriteria": { 
                 "numberOfNotifiedThings": integer, // Set one or the other
                 "numberOfSucceededThings": integer // of these two values.
              },
      "maximumPerMinute": integer
      }
    }, 
    "abortConfig": { 
    "criteriaList": [ 
        { 
           "action": "string",
           "failureType": "string",
           "minNumberOfExecutedThings": integer,
           "thresholdPercentage": integer
         }
      ]
    },
    "timeoutConfig": { 
          "inProgressTimeoutInMinutes": long
    },
    "documentParameters": {
    "string": "string"
    }
}

有关更多信息，请参阅create-job。

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

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

删除任务执行。

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

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

获取任务的任务文档。

注意

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

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

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

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

更新指定任务的受支持字段。timeoutConfig 的更新值仅对新的正在进行的启动生效。目前，正在进行的启动将继续使用之前的超时配置启动。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

Amazon IoT 任务 API 操作