任务管理和控制 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 对象表示设备上的任务执行。下面显示语法：


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