명령 생성 및 관리 - AWS IoT Core
명령 리소스 생성명령에 대한 정보 검색에서 명령 나열 AWS 계정명령 리소스 업데이트명령 리소스의 사용 중지 또는 복원명령 리소스 삭제

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

명령 생성 및 관리

AWS IoT Device Management 명령을 사용하여 재사용 가능한 원격 작업을 구성하거나 디바이스에 즉시 지침을 보냅니다. AWS IoT 콘솔에서 또는를 사용하여 명령을 생성하고 관리합니다 AWS CLI.

명령 리소스 생성

명령을 생성할 때 다음 정보를 제공합니다.

  • 일반 정보

    대상 디바이스에서 명령을 실행할 때 고유한 명령 ID를 제공하여 명령을 식별합니다. 선택적으로 관리를 위한 표시 이름, 설명 및 태그를 지정합니다.

  • 페이로드

    정적 명령의 경우 디바이스 작업을 정의하는 페이로드를 제공합니다. 올바른 디바이스 해석을 위해 페이로드 형식 유형을 지정합니다.

    동적 명령은 페이로드 템플릿 속성을 참조하세요.

  • 페이로드 템플릿

    동적 명령의 경우 자리 표시자 및 파라미터가 포함된 payloadTemplate을 제공합니다. 선택적으로 defaultValue 및 조건을 제공합니다. AWS IoT Device Management 명령은 런타임 시 자리 표시자를 대체합니다. 누락된 파라미터는 defaultValue를 사용합니다. 모든 값은 정의된 조건을 충족해야 합니다.

    다음과 같은 대/소문자를 구분하는 자리 표시자 유형이 지원됩니다.

    • ${aws:iot:commandexecution::parameter:parameter1} - 이름이 인 파라미터 값의 자리 표시자입니다parameter1.

    • ${aws:iot:commandexecution::executionTimeoutSec} - 런타임에 제공된 명령 실행 제한 시간 파라미터의 자리 표시자입니다.

명령 예약 주제는 페이로드 형식 유형에 따라 형식을 사용합니다.

  • application/json 또는 application/cbor 콘텐츠 유형의 경우 다음 요청 주제를 사용합니다.

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

  • 다른 콘텐츠 유형 또는 지정되지 않은 형식의 경우이 요청 주제를 사용합니다. 페이로드 형식이 MQTT 메시지 헤더에 나타납니다.

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

명령 응답 주제는 페이로드 유형에 관계없이 json 또는 cbor 형식을 사용합니다. <PayloadFormat>은 json 또는 여야 합니다cbor.

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

다음 섹션에서는 콘솔에서 페이로드 형식 고려 사항 및 명령 생성에 대해 설명합니다.

정적 명령 페이로드 형식

페이로드는 최대 32KB의 모든 형식을 지원합니다. 안전하고 올바른 디바이스 해석을 위해 페이로드 형식 유형을 지정합니다.

형식을 사용하여 페이로드 type/subtype 형식 유형을 지정합니다(예: application/json 또는 application/cbor). 기본값: application/octet-stream. 지원되는 형식은 일반 MIME 유형을 참조하세요.

동적 명령 페이로드 형식

payloadTemplate은 자리 표시자가 하나 이상 최대 32KB인 유효한 JSON이어야 합니다.

AwsJsonSubstitution 프리프로세서의 경우 AWS IoT Device Management 명령은 프리프로세서 구성을 기반으로 JSON 또는 CBOR 형식으로 알림을 보냅니다.

명령을 생성하는 방법(콘솔)

콘솔에서 명령을 생성하려면 Command Hub로 이동하여 다음 단계를 따릅니다.

  1. 명령 생성을 선택합니다.

  2. 고유한 명령 ID를 지정합니다.

  3. (선택 사항) 표시 이름, 설명 및 태그를 지정합니다.

  4. 디바이스 작업이 포함된 페이로드 파일을 업로드합니다. 올바른 디바이스 해석을 위해 페이로드 형식 유형을 지정합니다.

  5. (선택 사항) 자리 표시자가 있는 JSON 페이로드 템플릿의 경우 편집을 위해 인라인 테이블에 파라미터가 미리 채워집니다.

  6. (선택 사항) 파라미터 값 유형(필수), 기본값 및 조건을 구성합니다.

  7. 명령 생성을 선택합니다.

CreateCommand API 또는 create-command CLI 명령을 사용하여 명령을 생성합니다.

명령 페이로드

정적 페이로드 또는 페이로드 템플릿을 제공합니다. 정적 페이로드는 base64로 인코딩됩니다. 페이로드 템플릿의 경우 최종 페이로드는 파라미터 값을 사용하여 런타임에를 생성합니다. 디바이스는 페이로드를 처리하고 지정된 작업을 수행합니다. 올바른 디바이스 수신을 위해 페이로드 콘텐츠 유형을 지정합니다.

참고

명령 생성 후에는 페이로드를 수정할 수 없습니다. 새 명령을 생성하여 페이로드를 수정합니다.

샘플 IAM 정책

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

대체 예시:

  • region 대신 AWS 리전(예: us-east-1)로 대체합니다.

  • account-id 대신 AWS 계정 번호(예: 123456789012)로 대체합니다.

  • command-id와 같이 AWS IoT 명령 ID의 고유 식별자가 있는 LockDoor. 둘 이상의 명령을 전송하려면 IAM 정책의 리소스 섹션에서 이러한 명령을 지정할 수 있습니다.

{
    "Version":"2012-10-17",		 	 	 
    "Statement": {
        "Action": "iot:CreateCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id"
    }
}

정적 명령 생성 예제

다음 예제에서는 정적 명령을 생성하는 방법을 보여줍니다. 애플리케이션에 따라 다음을 대체합니다.

  • <command-id>를 명령의 고유 식별자로 대체합니다. 예를 들어 집의 문을 잠그려면를 지정할 수 있습니다LockDoor. UUID를 사용할 것을 권장합니다. 영숫자, "-" 및 "_"를 사용할 수도 있습니다.

  • (선택 사항) <display-name>와 <description>는 Lock the doors of my home와 같이 기억하기 쉬운 이름과 명령에 대한 의미 있는 설명을 제공하는 데 사용할 수 있는 선택적 필드입니다.

  • namespace는 명령의 네임스페이스를 지정하는 데 사용할 수 있습니다. 반드시 AWS-IoT이어야 합니다. 에서이 기능을 사용하는 방법에 대한 자세한 내용은 원격 명령을 AWS IoT FleetWise참조하세요.

  • payload에는 명령을 실행할 때 사용하려는 페이로드에 대한 정보와 콘텐츠 유형이 포함되어 있습니다.

aws iot create-command \ 
    --command-id <command-id> \
    --display-name <display-name> \
    --description <description> \ 
    --namespace AWS-IoT \ 
    --payload '{"content":"eyAibWVzc2FnZSI6ICJIZWxsbyBJb1QiIH0=","contentType":"application/json"}'

이 명령을 실행하면 명령의 ID 및 ARN(Amazon 리소스 이름)이 포함된 응답이 생성됩니다. 예를 들어, 생성 중에 LockDoor 명령을 지정한 경우 다음은 명령 실행의 샘플 출력을 보여줍니다.

{
    "commandId": "LockDoor",
    "commandArn": "arn:aws:iot:us-east-1:123456789012:command/LockDoor"
}

동적 명령 생성 예제

다음 예제에서는 동적 명령을 생성하는 방법을 보여줍니다. 애플리케이션에 따라 다음을 대체합니다.

  • <command-id>를 명령의 고유 식별자로 대체합니다. 예를 들어 조명 전원 상태를 설정하려면를 지정할 수 있습니다Light_Power_Status. UUID를 사용할 것을 권장합니다. 영숫자, "-" 및 "_"를 사용할 수도 있습니다.

  • (선택 사항) <display-name>와 <description>는 Turn a light ON or OFF와 같이 기억하기 쉬운 이름과 명령에 대한 의미 있는 설명을 제공하는 데 사용할 수 있는 선택적 필드입니다.

  • namespace는 명령의 네임스페이스를 지정하는 데 사용할 수 있습니다. 반드시 AWS-IoT이어야 합니다. 에서이 기능을 사용하는 방법에 대한 자세한 내용은 원격 명령을 AWS IoT FleetWise참조하세요.

  • payloadTemplate 에는 placehodler가 있는 JSON 형식의 플레이오드 템플릿이 포함되어 있습니다.

  • preprocessor 에는 payloadTemplate 처리 방법을 결정하는 프리프로세서에 대한 구성이 포함되어 있습니다.

  • mandatoryParameter 에는 payloadTemplate의 자리 표시자, 유형, 기본값 및 조건에 해당하는 파라미터가 포함되어 있습니다.

aws iot create-command \
    --command-id Light_Power_Status \
    --description "Turn a light ON or OFF" \
    --namespace AWS-IoT \
    --payload-template '{"powerStatus":"${aws:iot:commandexecution::parameter:powerStatus}"}' \
    --preprocessor awsJsonSubstitution={outputFormat=JSON} \
    --mandatory-parameters "name=powerStatus, defaultValue={S=OFF}, valueConditions=[{comparisonOperator=IN_SET, operand={strings=['ON','OFF']}}]"

이 명령을 실행하면 명령의 ID 및 ARN(Amazon 리소스 이름)이 포함된 응답이 생성됩니다. 예를 들어, 생성 중에 Light_Power_Status 명령을 지정한 경우 다음은 명령 실행의 샘플 출력을 보여줍니다.

{
    "commandId": "Light_Power_Status",
    "commandArn": "arn:aws:iot:us-east-1:123456789012:command/Light_Power_Status"
}

명령에 대한 정보 검색

명령을 생성한 후 AWS IoT 콘솔에서 또는 AWS CLI를 사용하여 해당 명령에 대한 정보를 검색할 수 있습니다. 다음 정보를 획득할 수 있습니다.

  • 명령 ID, Amazon 리소스 이름(ARN), 명령에 지정한 표시 이름 및 설명

  • 대상 디바이스에서 명령을 실행할 수 있는지 또는 명령이 사용 중지되거나 삭제되었는지 여부를 나타내는 명령 상태

  • 제공한 페이로드 또는 payloadTemplate입니다.

  • 제공한 프리프로세서입니다.

  • 제공한 mandatoryParameters입니다.

  • 명령이 생성되고 마지막으로 업데이트된 시간

콘솔에서 명령을 검색하려면 콘솔의 Command Hub로 이동한 AWS IoT 다음 생성한 명령을 선택하여 세부 정보를 확인합니다.

명령 세부 정보 외에도 대상 디바이스에서 명령 실행에 대한 정보를 제공하는 명령 기록을 볼 수 있습니다. 디바이스에서 이 명령을 실행한 후 이 탭에서 실행에 대한 정보를 확인할 수 있습니다.

GetCommand HTTP 컨트롤 플레인 API 작업 또는 get-command AWS CLI 명령을 사용하여 명령 리소스에 대한 정보를 검색합니다. CreateCommand API 요청 또는 create-command CLI를 사용하여 명령을 이미 생성했어야 합니다.

샘플 IAM 정책

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

대체 예시:

  • region 대신 AWS 리전(예: us-east-1)로 대체합니다.

  • account-id 대신 AWS 계정 번호(예: 123456789023)로 대체합니다.

  • command-id LockDoor 또는와 같은 고유한 명령 식별자가 있는 AWS IoT Light_Power_Status. 둘 이상의 명령을 검색하려면 IAM 정책의 리소스 섹션에서 이러한 명령을 지정할 수 있습니다.

{
    "Version":"2012-10-17",		 	 	 
    "Statement": {
        "Action": "iot:GetCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id"
    }
}

명령 검색 예제(AWS CLI)

다음 예제에서는를 사용하여 명령에 대한 정보를 검색하는 방법을 보여줍니다get-command AWS CLI. 애플리케이션에 따라 <command-id>를 정보를 검색할 명령의 식별자로 바꿉니다. create-command CLI의 응답에서 이 정보를 획득할 수 있습니다.

aws iot get-command --command-id <command-id>

이 명령을 실행하면 응답이 생성되며, 이 응답에는 명령, 페이로드, 및 응답이 생성되고 마지막으로 업데이트된 시간에 대한 정보가 포함됩니다. 또한 명령이 사용되지 않는지 또는 삭제 중인지 여부를 나타내는 정보도 제공합니다.

예를 들어, 다음 코드는 샘플 응답입니다.

{
    "commandId": "LockDoor",
    "commandArn": "arn:aws:iot:<region>:<account>:command/LockDoor",
    "namespace": "AWS-IoT",
    "payload":{
        "content": "eyAibWVzc2FnZSI6ICJIZWxsbyBJb1QiIH0=",
        "contentType": "application/json"
    },
    "createdAt": "2024-03-23T00:50:10.095000-07:00",
    "lastUpdatedAt": "2024-03-23T00:50:10.095000-07:00",
    "deprecated": false,
    "pendingDeletion": false
}

에서 명령 나열 AWS 계정

명령을 생성한 후 계정에서 생성한 명령을 볼 수 있습니다. 목록에서 다음에 대한 정보를 확인할 수 있습니다.

  • 명령 ID 및 명령에 지정한 표시 이름

  • 명령의 Amazon 리소스 이름(ARN)

  • 대상 디바이스에서 명령을 실행할 수 있는지 또는 명령이 사용 중지되었는지 여부를 나타내는 명령 상태

    참고

    계정에서 삭제 중인 명령은 목록에 표시되지 않습니다. 명령이 삭제 보류 중인 경우에도 명령 ID를 사용하여 이러한 명령의 세부 정보를 볼 수 있습니다.

  • 명령이 생성되고 마지막으로 업데이트된 시간

AWS IoT 콘솔에서 Command Hub로 이동하여 생성한 명령 목록과 세부 정보를 찾을 수 있습니다.

생성한 명령을 나열하려면 ListCommands API 작업 또는 list-commands CLI를 사용합니다.

샘플 IAM 정책

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

대체 예시:

  • region 대신 AWS 리전(예: us-east-1)로 대체합니다.

  • account-id 대신 AWS 계정 번호(예: 123456789012)로 대체합니다.

{
    "Version":"2012-10-17",		 	 	 
    "Statement": {
        "Action": "iot:ListCommands",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:us-east-1:123456789012:command/*"
    }
}

계정의 명령 나열 예제

다음 명령은 계정의 명령을 나열하는 방법을 보여줍니다.

aws iot list-commands --namespace "AWS-IoT"

이 명령을 실행하면 생성한 명령 목록, 명령이 생성된 시간 및 마지막으로 업데이트된 시간이 포함된 응답이 생성됩니다. 여기서는 또한 명령이 사용되지 않는지 또는 대상 디바이스에서 명령을 실행할 수 있는지 여부를 나타내는 명령 상태 정보를 제공합니다. 다양한 상태 및 상태 이유에 대한 자세한 내용은 명령 실행 상태 섹션을 참조하세요.

명령 리소스 업데이트

명령을 생성한 후 명령의 표시 이름과 설명을 업데이트할 수 있습니다.

참고

명령의 페이로드는 업데이트할 수 없습니다. 이 정보를 업데이트하거나 수정된 페이로드를 사용하려면, 새 명령을 생성해야 합니다.

콘솔에서 명령을 업데이트하려면 콘솔의 Command Hub로 이동하여 다음 단계를 AWS IoT 수행합니다.

  1. 기존 명령 리소스를 업데이트하려면 업데이트할 명령을 선택한 다음 작업에서 편집을 선택합니다.

  2. 사용하려는 표시 이름 및 설명과 이름-값 페어를 명령의 태그로 지정합니다.

  3. 편집을 선택하여 명령을 새 설정과 함께 저장합니다.

UpdateCommand 컨트롤 플레인 API 작업 또는 update-command AWS CLI 를 사용하여 명령 리소스를 업데이트합니다. 이 API를 사용하여 다음을 수행할 수 있습니다.

  • 생성한 명령의 표시 이름과 설명을 편집합니다.

  • 명령 리소스를 사용 하지 않거나, 이미 사용 중지된 명령을 복원합니다.

샘플 IAM 정책

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

대체 예시:

  • region 대신 AWS 리전(예: us-east-1)로 대체합니다.

  • account-id 대신 AWS 계정 번호(예: 123456789012)로 대체합니다.

  • command-id 대신 AWS IoT 고유 명령 식별자(예: LockDoor)로 대체합니다. 둘 이상의 명령을 검색하려면 IAM 정책의 리소스 섹션에서 이러한 명령을 지정할 수 있습니다.

{
    "Version":"2012-10-17",		 	 	 
    "Statement": {
        "Action": "iot:UpdateCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id"
    }
}

명령에 대한 정보 업데이트 예제(AWS CLI)

다음 예제에서는 명령을 사용하여 update-command AWS CLI 명령에 대한 정보를 업데이트하는 방법을 보여줍니다. 이 API를 사용하여 명령 리소스를 사용 중지하거나 복원하는 방법에 대한 자세한 내용은 명령 리소스 업데이트(CLI) 섹션을 참조하세요.

이 예제에서는 명령의 표시 이름과 설명을 업데이트하는 방법을 보여줍니다. 애플리케이션에 따라 <command-id>를 정보를 검색할 명령의 식별자로 바꿉니다.

aws iot update-command \ 
    --command-id <command-id>    
    --displayname <display-name> \
    --description <description>

이 명령을 실행하면 명령에 대해 업데이트된 정보와 마지막으로 업데이트된 시간이 포함하여 응답이 생성됩니다. 다음 코드는 AC를 끄는 명령의 표시 이름 및 설명을 업데이트하기 위한 샘플 요청 및 응답을 보여줍니다.

aws iot update-command \ 
    --command-id <LockDoor> \ 
    --displayname <Secondary lock door> \
    --description <Locks doors to my home>

이 명령을 실행하면 다음 응답이 생성됩니다.

{
    "commandId": "LockDoor",
    "commandArn": "arn:aws:iot:us-east-1:123456789012:command/LockDoor",
    "displayName": "Secondary lock door",
    "description": "Locks doors to my home",
    "lastUpdatedAt": "2024-05-09T23:15:53.899000-07:00"
}

명령 리소스의 사용 중지 또는 복원

명령을 생성한 후, 더 이상 명령을 계속 사용하지 않으려면 사용되지 않음 상태로 표시할 수 있습니다. 명령을 사용 중지하면 대기 중인 모든 명령 실행이 터미널 상태에 도달할 때까지 대상 디바이스에서 계속 실행됩니다. 명령이 사용 중지되면, 대상 디바이스로 새 명령 실행을 보내는 등 해당 명령을 사용하기 위해서는 명령을 복원해야 합니다.

참고

사용 중지된 명령은 편집하거나 새 실행을 실행할 수 없습니다. 디바이스에서 새 명령을 실행하려면, 명령 상태가 사용 가능으로 변경되도록 디바이스를 복원해야 합니다.

명령 사용 중단 및 복원과 이에 대한 고려 사항에 대한 자세한 내용은 명령 리소스 사용 중지 섹션을 참조하세요.

명령 리소스 삭제

명령을 더 이상 사용하지 않을 경우, 계정에서 영구적으로 제거할 수 있습니다. 삭제 작업이 성공한 경우:

  • 명령이 최대 제한 시간인 12시간보다 긴 기간 동안 사용되지 않았던 경우, 해당 명령이 즉시 삭제됩니다.

  • 명령이 사용되지 않는 상태거나 최대 제한 시간보다 짧은 기간 동안 사용되지 않았던 경우, 해당 명령은 pending deletion 상태가 됩니다. 최대 제한 시간인 12시간이 지나면 계정에서 해당 명령이 자동으로 제거됩니다.

참고

보류 중인 명령 실행이 있더라도 명령이 삭제될 수 있습니다. 명령은 삭제 보류 중 상태가 되고 계정에서 자동으로 제거됩니다.

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

  1. 삭제할 명령을 선택한 다음, 작업에서 삭제를 선택합니다.

  2. 명령을 정말로 삭제할 것인지 다시 한 번 묻는 메시지가 나오면 확인 후 삭제를 선택합니다.

명령은 삭제 대상으로 표시되고 12시간 후에 계정에서 영구적으로 제거됩니다.

DeleteCommand HTTP 컨트롤 플레인 API 작업 또는 delete-command AWS CLI 명령을 사용하여 명령 리소스를 삭제합니다. 삭제 작업이 성공하면 HTTP statusCode가 204 또는 202로 표시되고 최대 제한 시간인 12시간이 지나면 계정에서 명령이 자동으로 삭제됩니다. 204 상태의 경우 명령이 삭제되었음을 나타냅니다.

샘플 IAM 정책

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

대체 예시:

  • region 대신 AWS 리전(예: us-east-1)로 대체합니다.

  • account-id 대신 AWS 계정 번호(예: 123456789012)로 대체합니다.

  • command-id 대신 AWS IoT 고유 명령 식별자(예: LockDoor)로 대체합니다. 둘 이상의 명령을 검색하려면 IAM 정책의 리소스 섹션에서 이러한 명령을 지정할 수 있습니다.

{
    "Version":"2012-10-17",		 	 	 
    "Statement": {
        "Action": "iot:DeleteCommand",
        "Effect": "Allow",
        "Resource": "arn:aws:iot:us-east-1:123456789012:command/command-id"
    }
}

명령 삭제 예제(AWS CLI)

다음 예제에서는 명령을 사용하여 delete-command AWS CLI 명령을 삭제하는 방법을 보여줍니다. 애플리케이션에 따라 <command-id>를 삭제하려는 명령의 식별자로 바꿉니다.

aws iot delete-command --command-id <command-id>

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