작업 관리 및 제어 API 및 데이터 형식

다음은 작업 관리 및 제어에서 CLI 및 HTTPS 프로토콜을 통해 사용할 수 있는 명령입니다.

작업 관리 및 제어 데이터 형식
작업 관리 및 제어 API 작업

CLI 명령에 대한 endpoint-url 파라미터를 확인하려면 이 명령을 실행합니다.


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

이 명령은 다음 출력을 반환합니다.



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

참고

작업 엔드포인트는 ALPN z-amzn-http-ca를 지원하지 않습니다.

작업 관리 및 제어 데이터 형식

관리 및 제어 애플리케이션에서는 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
    }
}

자세한 내용은 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의 목록이어야 합니다. 모든 사물 및 사물 그룹은 AWS 계정에 속해야 합니다.
documentSource 인수는 작업 문서에 대해 유효한 Amazon S3 URL이어야 합니다. Amazon S3 URL의 형식은 https://s3.amazonaws.com/bucketName/objectName과 같습니다.
documentSource 인수에서 지정하는 URL에 저장된 문서는 UTF-8 인코딩 JSON 문서이어야 합니다.
작업 문서의 크기는 MQTT 메시지 크기(128KB) 및 암호화에 대한 제한으로 인해 32KB를 넘을 수 없습니다.
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
}
}

자세한 내용은 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로 바뀌지 않습니다. 미리 서명된 URL은 AWS IoT 작업 서비스가 MQTT를 통해 요청을 수신하는 경우에 한해 작성됩니다.

임의 작업에 대한 작업 실행 목록을 가져옵니다.

사물의 작업 실행 목록을 가져옵니다.

AWS 계정의 작업 목록을 가져옵니다.

지정된 작업의 지원되는 필드를 업데이트합니다. timeoutConfig에 대해 업데이트된 값은 새로 진행 중인 시작 작업에만 적용됩니다. 현재 진행 중인 시작은 이전의 제한 시간 구성으로 계속 실행됩니다.

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

AWS IoT Jobs API 작업

작업 디바이스 MQTT API 및 HTTPS API 작업 및 데이터 형식