명령 실행 시작 및 모니터링

명령을 수신하고 실행할 대상 디바이스를 지정합니다. 등록된 디바이스에는 사물 이름을 사용하고 등록되지 않은 디바이스에는 클라이언트 ID를 사용합니다. 페이로드를 수신한 후 디바이스는 명령을 실행하고 지정된 작업을 수행합니다.

AWS IoT 사물

대상 디바이스는 AWS IoT 레지스트리에 등록된 사물일 수 있습니다. 사물은 디바이스 검색 및 관리를 간소화합니다.

Connect 디바이스 페이지에서 또는를 사용하여 디바이스를 사물로 등록합니다CreateThing. 를 사용하여 Thing Hub 또는에서 기존 사물을 찾습니다DescribeThing. 등록 세부 정보는 레지스트리로 사물 관리를 참조하세요.

클라이언트 ID입니다

등록되지 않은 디바이스의 경우 클라이언트 ID를 사용합니다.

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

클라이언트 ID는에 연결할 때 사용하는 MQTT 클라이언트 ID입니다 AWS IoT Core.는이 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 영구 세션 사용

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

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

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

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"
  ]
}

에 지원되는 조건 키 목록을 보려면 IAM 사용 설명서의에 대한 조건 키를 StartCommandExecution참조하세요. AWS IoT

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

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 명령 실행을 시작하는 방법을 보여줍니다.

대체 예시:

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

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

이 API 작업을 사용하기 전에 IAM 정책이 디바이스에 이러한 작업을 수행할 수 있는 권한을 부여해야 합니다. 다음은 디바이스에 작업을 수행할 권한을 부여하는 정책의 예입니다. UpdateCommandExecution MQTT 작업을 수행할 수 있는 사용자 권한을 허용하는 추가 샘플 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:us-east-1:123456789012:command/LockDoor",
    "targetArn": "arn:aws:iot:us-east-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를 사용하여 명령 실행이 계정에 더 이상 존재하지 않는지 확인할 수 있습니다.