명령 실행 시작 및 모니터링

명령을 실행하려면, 명령을 수신하고 지정된 지침을 수행할 대상 디바이스를 지정해야 합니다. 대상 디바이스는 AWS IoT 사물일 수도 있고, 디바이스가 AWS IoT 레지스트리에 등록되지 않은 경우에는 클라이언트 ID일 수도 있습니다. 명령 페이로드를 수신한 후 디바이스는 명령 실행을 시작하고 지정된 작업을 수행할 수 있습니다.

AWS IoT 사물

명령의 대상 디바이스는 AWS IoT 사물 레지스트리에 등록한 AWS IoT 사물일 수 있습니다. AWS IoT의 사물을 사용하면 디바이스를 더 쉽게 검색하고 관리할 수 있습니다.

디바이스 연결 페이지에서 또는 CreateThing API를 사용하여 디바이스를 AWS IoT에 연결할 때 디바이스를 사물로 등록할 수 있습니다. AWS IoT 콘솔의 Thing Hub 페이지에서 또는 DescribeThing API를 사용하여 명령을 실행할 기존 사물을 찾을 수 있습니다. 디바이스를 AWS IoT 사물로 등록하는 방법에 대한 자세한 내용은 레지스트리를 사용하여 사물 관리를 참조하세요.

클라이언트 ID

디바이스가 AWS IoT에 사물로 등록되지 않은 경우 클라이언트 ID를 대신 사용할 수 있습니다.

클라이언트 ID는 디바이스 또는 클라이언트에 할당하는 고유 식별자입니다. 클라이언트 ID는 MQTT 프로토콜에 정의되어 있으며 영숫자, 밑줄 또는 대시를 포함할 수 있습니다. AWS IoT에 연결하는 각 디바이스에 고유해야 합니다.

클라이언트 ID는 일반적으로 AWS IoT Core에 연결할 때 디바이스가 사용할 수 있는 MQTT 클라이언트 ID입니다. 이 ID는 AWS IoT에서 각 특정 디바이스를 식별하고 연결 및 구독을 관리하는 데 사용됩니다.

제한 시간은 디바이스가 명령 실행 결과를 제공할 수 있는 기간(초)이 만료되는 시간을 나타냅니다.

명령 실행을 생성하면 타이머가 시작됩니다. 디바이스가 오프라인 상태가 되거나 시간 초과 기한 내에 실행 결과를 보고하지 못한 경우, 명령 실행 시간이 초과되고 실행 상태는 TIMED_OUT으로 보고됩니다.

이 필드는 선택 사항이며, 값을 지정하지 않을 경우 기본값은 10초입니다. 또한 최대 12시간으로 제한 시간을 구성할 수 있습니다.

제한 시간 값 및 TIMED_OUT 명령 실행 상태

클라우드와 디바이스 모두에서 제한 시간 초과가 보고될 수 있습니다.

명령이 디바이스로 전송되면 타이머가 시작됩니다. 위에서 설명한 대로 지정된 제한 시간 내에 디바이스로부터 응답을 받지 못한 경우를 살펴봅니다. 이 경우, 클라우드는 명령 실행 상태를 TIMED_OUT으로 설정하고 이유 코드는 $NO_RESPONSE_FROM_DEVICE로 설정합니다.

이는 다음 경우 중 하나에서 발생할 수 있습니다.

이 경우에 실행 상태가 클라우드에서 TIMED_OUT으로 보고되면 명령 실행은 비터미널 상태입니다. 디바이스는 상태를 터미널 상태인 SUCCEEDED, FAILED 또는 REJECTED로 재정의하는 응답을 게시할 수 있습니다. 이제 명령 실행이 터미널 상태가 되고 추가 업데이트를 수락하지 않습니다.

또한 디바이스는 명령을 실행할 때 시간 초과가 발생했음을 보고하여 클라우드에서 시작된 TIMED_OUT 상태를 업데이트할 수 있습니다. 이 경우에 명령 실행 상태는 TIMED_OUT으로 유지되지만 statusReason 객체가 디바이스에서 보고한 정보를 기반으로 업데이트됩니다. 이제 명령 실행이 터미널 상태가 되고 추가 업데이트를 수락하지 않습니다.

MQTT 영구 세션 사용

MQTT 영구 세션에서 AWS IoT Device Management 명령 기능을 사용하도록 구성할 수 있습니다. 이 기능은 디바이스가 오프라인 상태가 되고 디바이스가 제한 시간 전에 다시 온라인 상태가 될 때 명령을 계속 수신하고 지정된 지침을 수행하는지 확인하려는 경우에 특히 유용합니다.

기본적으로 MQTT 영구 세션 만료는 60분으로 설정됩니다. 명령 실행 제한 시간이 이 기간보다 긴 값으로 구성된 경우, 메시지 브로커가 60분보다 더 오래 실행하는 명령 실행을 거부하여 명령이 실패할 수 있습니다. 지속 시간이 60분을 초과하는 명령을 실행하려면 영구 세션 만료 시간을 늘리도록 요청할 수 있습니다.

콘솔에서 명령 실행을 시작하려면 AWS IoT 콘솔의 Command Hub 페이지로 이동하여 다음 단계를 수행합니다.

StartCommandExecution HTTP 데이터 플레인 API 작업을 사용하여 명령 실행을 시작합니다. API 요청 및 응답은 명령 실행 ID와 상관관계를 가집니다. 디바이스가 명령 실행을 완료한 후, 명령 응답 주제에 메시지를 게시하여 상태 및 실행 결과를 클라우드에 보고할 수 있습니다. 사용자 지정 응답 코드의 경우, 소유한 애플리케이션 코드는 응답 메시지를 처리하고 결과를 AWS IoT에 게시할 수 있습니다.

디바이스가 명령 요청 주제를 구독한 경우에 StartCommandExecution API는 페이로드 메시지를 주제에 게시합니다. 페이로드는 원하는 형식을 사용할 수 있습니다. 자세한 내용은 명령 페이로드 섹션을 참조하세요.

$aws/commands/<devices>/<DeviceID>/executions/+/request/<PayloadFormat>

페이로드 형식이 JSON 또는 CBOR이 아닌 경우, 다음은 명령 요청 주제의 형식을 보여줍니다.

$aws/commands/<devices>/<DeviceID>/executions/+/request

샘플 IAM 정책

이 API 작업을 사용하기 전에 IAM 정책이 디바이스에서 이 작업을 수행할 수 있는 권한을 부여하는지 확인합니다. 다음은 사용자가 StartCommandExecution 작업을 수행할 수 있도록 허용하는 IAM 정책 예시입니다.

대체 예시:

{
  "Effect": "Allow",
  "Action": [
      "iot:StartCommandExecution"
  ],
  "Resource": [
      "arn:aws:iot:region:account-id:command/command-id",
      "arn:aws:iot:region:account-id:devices/device-id"
  ]
}

계정별 데이터 플레인 엔드포인트 획득

API 명령을 실행하기 전에 엔드포인트에 대한 계정별 엔드포인트 URL을 얻어야 합니다. 듀얼 스택 엔드포인트(IPv4 및 IPv6)를 사용하는 경우 iot:Data-ATS를 사용합니다. iot:Jobs 엔드포인트는 IPv4 전용입니다. 예를 들면 다음 명령을 실행하는 경우

aws iot describe-endpoint --endpoint-type iot:Data-ATS

아래 샘플 응답과 같이 계정별 엔드포인트 URL을 반환합니다.

{
    "endpointAddress": "<account-specific-prefix>-ats.iot.<region>.api.com"
}

명령 실행 시작 예제(AWS CLI)

다음 예제에서는 start-command-execution AWS CLI 명령을 사용하여 명령 실행을 시작하는 방법을 보여줍니다.

대체 예시:

aws iot-jobs-data start-command-execution \ 
    --command-arn <command-arn>  \
    --target-arn <target-arn> \  
    --endpoint <endpoint-url> \ 
    --execution-timeout-seconds 900

이 명령을 실행하면 명령 실행 ID가 반환됩니다. 이 ID를 사용하여 명령 실행 상태, 세부 정보 및 명령 실행 기록을 쿼리할 수 있습니다.

{
    "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542"
}

이 API 작업을 사용하기 전에 IAM 정책이 디바이스에 이러한 작업을 수행할 수 있는 권한을 부여해야 합니다. 다음은 디바이스에 작업을 수행할 권한을 부여하는 정책의 예입니다. 사용자 권한이 UpdateCommandExecution 작업을 수행하도록 허용하는 추가 샘플 IAM 정책은 연결 및 게시 정책 예제 섹션을 참조하세요.

대체 예시:

MQTT 클라이언트 ID에 대한 샘플 IAM 정책

다음 코드는 MQTT 클라이언트 ID를 사용할 때의 샘플 디바이스 정책을 보여줍니다.

IoT 사물에 대한 샘플 IAM 정책

다음 코드는 AWS IoT 사물을 사용할 때의 샘플 디바이스 정책을 보여줍니다.

요청 주제에서 명령 실행이 수신되면 디바이스는 명령을 처리합니다. 그런 다음 UpdateCommandExecution API를 사용하여 명령 실행의 상태 및 결과를 다음 응답 주제로 업데이트합니다.

$aws/commands/<devices>/<DeviceID>/executions/<ExecutionId>/response/<PayloadFormat>

이 예제에서 <DeviceID>는 대상 디바이스의 고유 식별자이고, <execution-id>는 대상 디바이스에서 명령 실행의 식별자입니다. <PayloadFormat>은 JSON 또는 CBOR일 수 있습니다.

$aws/commands/clients/<ClientID>/executions/<ExecutionId>/response/<PayloadFormat>

디바이스의 실행 상태 업데이트 보고

디바이스는 API를 사용하여 명령 실행에 다음과 같은 상태 업데이트를 보고할 수 있습니다. 이러한 상태에 대한 자세한 내용은 명령 실행 상태 섹션을 참조하세요.

TIMED_OUT 상태에 대한 자세한 내용은 제한 시간 값 및 TIMED_OUT 명령 실행 상태 섹션을 참조하세요.

UpdateCommandExecution API 사용 시 고려 사항

다음은 UpdateCommandExecution API를 사용할 때 고려해야 할 몇 가지 중요한 사항입니다.

UpdateCommandExecution API 예제

다음 코드는 자동차 배터리 백분율을 예로 들어서 디바이스가 UpdateCommandExecution API를 사용하여 실행 상태를 보고하고, statusReason 필드를 사용하여 상태에 대한 추가 정보를 제공하고, 결과 필드를 사용하여 실행 결과에 대한 정보를 제공하는 방법을 보여줍니다.

{
  "status": "IN_PROGRESS",
  "statusReason": {
    "reasonCode": "200",
    "reasonDescription": "Execution_in_progress"
  },
  "result": {
        "car_battery": {
            "s": "car battery at 50 percent"
        }
    }
}

다음 방법 중 하나를 사용하여 콘솔에서 명령 실행을 검색할 수 있습니다.

GetCommandExecution AWS IoT Core 컨트롤 플레인 HTTP API 작업을 사용하여 명령 실행에 대한 정보를 검색합니다. StartCommandExecution API 작업을 사용하여 이 명령을 이미 실행했어야 합니다.

샘플 IAM 정책

이 API 작업을 사용하기 전에 IAM 정책이 디바이스에서 이 작업을 수행할 수 있는 권한을 부여하는지 확인합니다. 다음은 사용자가 GetCommandExecution 작업을 수행할 수 있도록 허용하는 IAM 정책 예시입니다.

대체 예시:

{
  "Effect": "Allow",
  "Action": [
      "iot:GetCommandExecution"
  ],
  "Resource": [
      "arn:aws:iot:region:account-id:command/command-id",
      "arn:aws:iot:region:account-id:devices/device-id"
  ]
}

명령 실행 검색 예제

다음 예제에서는 start-command-execution AWS CLI 명령을 사용하여 실행된 명령에 대한 정보를 검색하는 방법을 보여줍니다. 다음 예제에서는 조향 모드를 끄기 위해 실행된 명령에 대한 정보를 검색하는 방법을 보여줍니다.

대체 예시:

aws iot get-command-execution  
    --execution-id <execution-id> \ 
    --target-arn <target-arn> \
    --include-result

이 명령을 실행하면, 명령 실행의 ARN, 실행 상태, 실행이 시작된 시간 및 완료된 시간에 대한 정보를 포함한 응답이 생성됩니다. 또한, 상태에 대한 추가 정보가 포함된 statusReason 객체를 제공합니다. 다양한 상태 및 상태 이유에 대한 자세한 내용은 명령 실행 상태 섹션을 참조하세요.

다음 코드는 API 요청의 샘플 응답을 보여줍니다.

{
    "executionId": "07e4b780-7eca-4ffd-b772-b76358da5542",
    "commandArn": "arn:aws:iot:ap-south-1:123456789012:command/LockDoor",
    "targetArn": "arn:aws:iot:ap-south-1:123456789012:thing/myRegisteredThing",
    "status": "SUCCEEDED",
    "statusReason": {
        "reasonCode": "DEVICE_SUCCESSFULLY_EXECUTED",
        "reasonDescription": "SUCCESS"
    },
    "result": {
        "sn": { "s": "ABC-001" },
        "digital": { "b": true }        
    },
    "createdAt": "2024-03-23T00:50:10.095000-07:00",
    "completedAt": "2024-03-23T00:50:10.095000-07:00"    
}

다음 방법 중 하나를 사용하여 콘솔에서 모든 명령 실행을 볼 수 있습니다.

ListCommandExecutions AWS IoT Core 컨트롤 플레인 HTTP API 작업을 사용하여 계정의 모든 명령 실행을 나열합니다.

샘플 IAM 정책

이 API 작업을 사용하기 전에 IAM 정책이 디바이스에서 이 작업을 수행할 수 있는 권한을 부여하는지 확인합니다. 다음은 사용자가 ListCommandExecutions 작업을 수행할 수 있도록 허용하는 IAM 정책 예시입니다.

대체 예시:

{
  "Effect": "Allow",
  "Action": "iot:ListCommandExecutions",
  "Resource": *
}

명령 실행 나열 예제

다음 예제에서는 AWS 계정에서 명령 실행을 나열하는 방법을 보여줍니다.

명령을 실행할 때 목록을 필터링할 때, targetArn을 사용하여 특정 디바이스에 대해 생성된 명령 실행만 표시할지 또는 commandArn을 사용하여 지정된 특정 명령에 대한 실행만 표시할지 지정해야 합니다.

대체 예시:

aws iot list-command-executions \ 
--target-arn <target-arn> \ 
--started-time-filter '{after=<after>}' \
--sort-order "ASCENDING"

이 명령을 실행하면 생성한 명령 실행 목록, 실행이 시작된 시간 및 완료된 시간이 포함된 응답이 생성됩니다. 또한, 상태 정보, 그리고 상태에 대한 추가 정보가 포함된 statusReason 객체도 제공합니다.

{
    "commandExecutions": [
        {
            "commandArn": "arn:aws:iot:us-east-1:123456789012:command/TestMe002",
            "executionId": "b2b654ca-1a71-427f-9669-e74ae9d92d24",
            "targetArn": "arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f",
            "status": "TIMED_OUT",
            "createdAt": "2024-11-24T14:39:25.791000-08:00",
            "startedAt": "2024-11-24T14:39:25.791000-08:00"
        },
        {
            "commandArn": "arn:aws:iot:us-east-1:123456789012:command/TestMe002",
            "executionId": "34bf015f-ef0f-4453-acd0-9cca2d42a48f",
            "targetArn": "arn:aws:iot:us-east-1:123456789012:thing/b8e4157c98f332cffb37627f",
            "status": "IN_PROGRESS",
            "createdAt": "2024-11-24T14:05:36.021000-08:00",
            "startedAt": "2024-11-24T14:05:36.021000-08:00"
        }
    ]
}

다양한 상태 및 상태 이유에 대한 자세한 내용은 명령 실행 상태 섹션을 참조하세요.

이 API 작업을 사용하기 전에 IAM 정책이 디바이스에 이러한 작업을 수행할 수 있는 권한을 부여해야 합니다. 다음은 디바이스에 작업을 수행할 권한을 부여하는 정책의 예입니다.

대체 예시:

{
  "Effect": "Allow",
  "Action": [
      "iot:DeleteCommandExecution"
  ],
  "Resource": [
      "arn:aws:iot:region:account-id:command/command-id",
      "arn:aws:iot:region:account-id:devices/device-id"
  ]
}

다음 예제에서는 delete-command AWS CLI 명령을 사용하여 명령을 삭제하는 방법을 보여줍니다. 애플리케이션에 따라 <execution-id>를 삭제하려는 명령 실행의 식별자로 대체하고 <target-arn>를 대상 디바이스의 ARN으로 바꿉니다.

aws iot delete-command-execution \ 
--execution-id <execution-id> \ 
--target-arn <target-arn>

API 요청이 성공하면 명령 실행은 상태 코드 200을 생성합니다. GetCommandExecution API를 사용하여 명령 실행이 계정에 더 이상 존재하지 않는지 확인할 수 있습니다.