스트림 데이터를 가져오는 DescribeStream 데 사용합니다.스트림 파일에서 데이터 블록 가져오기 AWS IoT MQTT 기반 파일 전송으로 인한 오류 처리

디바이스에서 AWS IoT MQTT 기반 파일 전송 사용

데이터 전송 프로세스를 시작하려면 디바이스가 최소한 스트림 ID를 포함하는 초기 데이터 세트를 수신해야 합니다. 작업을(를) 사용하여 작업 문서에 초기 데이터 세트를 포함하여 디바이스에 대한 데이터 전송 작업을 예약할 수 있습니다. 장치가 초기 데이터 세트를 수신하면 AWS IoT MQTT 기반 파일 전달과의 상호 작용을 시작해야 합니다. AWS IoT MQTT 기반 파일 전송으로 데이터를 교환하려면 기기는 다음을 수행해야 합니다.

MQTT 프로토콜을 사용하여 MQTT 기반 파일 전송 주제을(를) 구독합니다.
요청을 전송한 다음 MQTT 메시지를 사용하여 응답을 받을 때까지 기다립니다.

선택적으로 초기 데이터 세트에 스트림 파일 ID와 스트림 버전을 포함할 수 있습니다. ID를 얻기 위해 디바이스에서 DescribeStream 요청을 할 필요가 없기 때문에 스트림 파일 ID를 디바이스에 전송하면 디바이스의 펌웨어/소프트웨어 프로그래밍을 단순화할 수 있습니다. 디바이스는 스트림이 예기치 않게 업데이트된 경우 일관성 검사를 시행하기 위해 GetStream 요청에서 스트림 버전을 지정할 수 있습니다.

스트림 데이터를 가져오는 DescribeStream 데 사용합니다.

AWS IoT MQTT 기반 파일 전송은 스트림 데이터를 기기로 전송하는 DescribeStream API를 제공합니다. 이 API에서 반환되는 스트림 데이터에는 스트림 ID, 스트림 버전, 스트림 설명 및 스트림 파일 목록이 포함되며 각 스트림 파일 목록에는 파일 ID와 파일 크기(바이트)가 있습니다. 이 정보를 사용하여 디바이스는 임의의 파일을 선택하여 데이터 전송 프로세스를 시작할 수 있습니다.

참고

디바이스가 초기 데이터 세트에서 필요한 모든 스트림 파일 ID를 수신하는 경우 DescribeStream API를 사용할 필요가 없습니다.

DescribeStream 요청을 하려면 다음 단계를 따르세요.

“수락된” 주제 필터 $aws/things/ThingName/streams/StreamId/description/json을 구독합니다.
“거부된” 주제 필터 $aws/things/ThingName/streams/StreamId/rejected/json을 구독합니다.
메시지를 $aws/things/ThingName/streams/StreamId/describe/json에 전송해 DescribeStream 요청을 게시합니다.
요청이 수락된 경우 디바이스가 “수락된” 주제 필터에 대한 DescribeStream 응답을 수신합니다.
요청이 거부된 경우 디바이스는 “거부된” 주제 필터에 대한 오류 응답을 수신합니다.

참고

표시된 주제 및 주제 필터에서 json을 cbor로 바꾸면 디바이스가 JSON보다 더 간결한 CBOR 형식의 메시지를 수신합니다.

DescribeStream 요청

JSON 형식의 일반적인 DescribeStream 요청은 다음 예제와 같습니다.


{
    "c": "ec944cfb-1e3c-49ac-97de-9dc4aaad0039"
}

(선택 사항) “c“은 클라이언트 토큰 필드입니다.

클라이언트 토큰은 64바이트보다 길면 안 됩니다. 클라이언트 토큰이 64바이트보다 길면 오류 응답과 InvalidRequest 오류 메시지가 발생합니다.

DescribeStream 응답

JSON 형식의 DescribeStream 응답은 다음 예제와 유사합니다.


{
    "c": "ec944cfb-1e3c-49ac-97de-9dc4aaad0039",
    "s": 1,
    "d": "This is the description of stream ABC.",
    "r": [
        {
            "f": 0,
            "z": 131072
        },
        {
            "f": 1,
            "z": 51200
        }
    ]
}

“c“은(는) 클라이언트 토큰 필드입니다. DescribeStream 요청에 제공된 경우에 반환됩니다. 클라이언트 토큰을 사용하여 응답을 요청과 연결합니다.
“s“은(는) 정수로된 스트림 버전입니다. 이 버전을 사용하여 GetStream 요청에 대한 일관성 검사를 수행할 수 있습니다.
“r“에는 스트림의 파일 목록이 포함되어 있습니다.
- “f“은(는) 정수로 된 스트림 파일 ID입니다.
- “z“은(는) 스트림 파일 크기(바이트 수)입니다.
"d"에는 스트림에 대한 설명이 포함되어 있습니다.

스트림 파일에서 데이터 블록 가져오기

GetStream API를 사용하면 디바이스가 작은 데이터 블록에서 스트림 파일을 수신할 수 있으므로 대규모 블록 크기를 처리하는 데 제약이 있는 디바이스에서 사용할 수 있습니다. 전체 데이터 파일을 수신하려면 디바이스에서 모든 데이터 블록이 수신되고 처리될 때까지 여러 요청 및 응답을 전송하거나 수신해야 할 수 있습니다.

GetStream 요청

GetStream 요청을 하려면 다음 단계를 따르세요.

“수락된” 주제 필터 $aws/things/ThingName/streams/StreamId/data/json을 구독합니다.
“거부된” 주제 필터 $aws/things/ThingName/streams/StreamId/rejected/json을 구독합니다.
주제 $aws/things/ThingName/streams/StreamId/get/json에 GetStream 요청을 게시합니다.
요청이 수락되면 디바이스에 하나 이상의 “수락된” 주제 필터에 대한 GetStream 응답을 수신합니다. 각 응답 메시지에는 단일 블록에 대한 기본 정보와 데이터 페이로드가 포함됩니다.
3 및 4단계를 반복하여 모든 데이터 블록을 수신합니다. 요청된 데이터 양이 128KB보다 큰 경우 이러한 단계를 반복해야 합니다. 여러 GetStream 요청을 통해 요청된 모든 데이터를 수신하도록 디바이스를 프로그래밍해야 합니다.
요청이 거부되면 디바이스에서 “거부된” 주제 필터에 대한 오류 응답을 수신하게 됩니다.

참고

표시된 주제 및 주제 필터에서 “json”을 “cbor”로 바꾸면 디바이스에서 JSON보다 더 컴팩트한 CBOR 형식으로 메시지를 수신합니다.
AWS IoT MQTT 기반 파일 전송은 블록 크기를 128KB로 제한합니다. 128KB를 초과하는 블록에 대한 요청을 하면 요청이 실패합니다.
총 크기가 128KB보다 큰 여러 블록에 대해 요청할 수 있습니다(예: 총 160KB의 데이터에 대해 각각 32KB의 5개 블록을 요청하는 경우). 이 경우 요청은 실패하지 않지만 요청된 모든 데이터를 수신하려면 단말기에서 여러 번 요청해야 합니다. 이 서비스는 디바이스가 추가 요청을 할 때 추가 블록을 전송합니다. 이전 응답을 올바르게 받고 처리한 후에만 새 요청을 계속하는 것이 좋습니다.
요청된 데이터의 전체 크기에 관계없이, 블록이 수신되지 않거나 올바르게 수신되지 않을 때 재시도를 시작하도록 디바이스를 프로그래밍해야 합니다.

JSON 형식의 일반적인 GetStream 요청은 다음 예제와 같습니다.


{
    "c": "1bb8aaa1-5c18-4d21-80c2-0b44fee10380",
    "s": 1,
    "f": 0,
    "l": 4096,
    "o": 2,
    "n": 100,
    "b": "..."
}

[선택 사항] ”c“은(는) 클라이언트 토큰 필드입니다.

클라이언트 토큰은 64바이트보다 길면 안 됩니다. 클라이언트 토큰이 64바이트보다 길면 오류 응답과 InvalidRequest 오류 메시지가 발생합니다.
[선택 사항] ”s“은(는) 스트림 버전 필드(정수)입니다.

MQTT 기반 파일 전송은 요청된 버전 및 클라우드의 최신 스트림 버전을 기반으로 일관성 검사를 적용합니다. 스트림 버전이 디바이스에서 전송된 경우 GetStream 요청이 클라우드의 최신 스트림 버전과 일치하지 않는 경우 서비스에서 오류 응답과 VersionMismatch 오류 메시지를 전송합니다. 일반적으로 디바이스는 초기 데이터 세트 또는 DescribeStream에 대한 응답에서 예상되는 (최신) 스트림 버전을 수신합니다.
“f“은(는) 스트림 파일 ID(0~255 사이의 정수)입니다.

AWS CLI 또는 SDK를 사용하여 스트림을 만들거나 업데이트할 때는 스트림 파일 ID가 필요합니다. 디바이스가 존재하지 않는 ID를 가진 스트림 파일을 요청하면 서비스에서 오류 응답과 ResourceNotFound 오류 메시지를 전송합니다.
“l“은(는) 바이트 단위의 데이터 블록 크기(256~131,072 사이의 정수)입니다.

비트맵 필드를 사용하여 GetStream 응답에서 반환될 스트림 파일 부분을 지정하는 방법에 대한 지침은 요청을 위한 비트맵 작성 GetStream 을(를) 참조하세요. 디바이스가 범위를 벗어나는 블록 크기를 지정하는 경우 서비스는 오류 응답과 BlockSizeOutOfBounds 오류 메시지를 전송합니다.
[선택 사항] ”o“은(는) 스트림 파일에 있는 블록의 오프셋(0~98,304 사이의 정수)입니다.

비트맵 필드를 사용하여 GetStream 응답에서 반환될 스트림 파일 부분을 지정하는 방법에 대한 지침은 요청을 위한 비트맵 작성 GetStream 을(를) 참조하세요. 최대 값 98,304는 24MB 스트림 파일 크기 제한과 최소 블록 크기의 256바이트를 기준으로 합니다. 지정하지 않은 경우 기본값은 0입니다.
[선택 사항] ”n“은(는) 요청된 블록 수(0~98,304 사이의 정수)입니다.

“n” 필드는 (1) 요청된 블록 수 또는 (2) 비트맵 필드(“b”)가 사용되는 경우 비트맵 요청에 의해 반환될 블록 수에 대한 제한을 지정합니다. 이 두 번째 사용은 선택 사항입니다. 정의되지 않은 경우 기본값은 131072/입니다. DataBlockSize
[선택 사항] ”b“은(는) 요청되는 블록을 나타내는 비트맵입니다.

비트맵을 사용하면 디바이스에서 비연속 블록을 요청할 수 있으므로 오류 발생 후 재시도를 보다 편리하게 처리할 수 있습니다. 비트맵 필드를 사용하여 GetStream 응답에서 반환될 스트림 파일 부분을 지정하는 방법에 대한 지침은 요청을 위한 비트맵 작성 GetStream 을(를) 참조하세요. 이 필드의 경우 비트맵을, 16진수 표기법으로 비트맵의 값을 나타내는 문자열로 변환합니다. 비트맵은 12,288바이트 미만이어야 합니다.

중요

"n" 또는 "b"를 지정해야 합니다. 둘 다 지정하지 않으면 파일 크기가 131,072바이트(128KB) 미만인 경우 GetStream 요청이 유효하지 않을 수 있습니다.

GetStream 응답

JSON 형식의 GetStream 응답은 요청된 각 데이터 블록에 대해 이 예제와 같습니다.


{
    "c": "1bb8aaa1-5c18-4d21-80c2-0b44fee10380",
    "f": 0,
    "l": 4096,
    "i": 2,
    "p": "..."
}

“c“은(는) 클라이언트 토큰 필드입니다. GetStream 요청에 제공된 경우에 반환됩니다. 클라이언트 토큰을 사용하여 응답을 요청과 연결합니다.
“f“은(는) 현재 데이터 블록 페이로드가 속한 스트림 파일의 ID입니다.
“l“은(는) 데이터 블록 페이로드의 크기(바이트)입니다.
“i“은(는) 페이로드에 포함된 데이터 블록의 ID입니다. 데이터 블록은 0부터 시작해서 번호가 매겨집니다.
“p“에는 데이터 블록 페이로드가 포함됩니다. 이 필드는 Base64 인코딩으로 데이터 블록의 값을 나타내는 문자열입니다.

요청을 위한 비트맵 작성 GetStream

GetStream 요청에서 비트맵 필드(b)를 사용하여 스트림 파일에서 비연속 블록을 가져올 수 있습니다. 이렇게 하면 RAM 용량이 제한된 디바이스에서 네트워크 전송 문제를 처리할 수 있습니다. 디바이스는 수신되지 않았거나 올바르게 수신되지 않은 블록만 요청할 수 있습니다. 비트맵은 반환될 스트림 파일의 블록을 결정합니다. 비트맵에서 1로 설정된 각 비트에 대해 스트림 파일의 해당 블록이 반환됩니다.

다음은 GetStream 요청에서 비트맵 및 해당 지원 필드를 지정하는 방법의 예입니다. 예를 들어, 256바이트(블록 크기)의 청크로 스트림 파일을 수신하려고 합니다. 256바이트의 각 블록은 0에서 시작하여 파일에서 위치를 지정하는 숫자를 갖는 것으로 생각합니다. 따라서 블록 0이 파일의 256바이트의 첫 번째 블록이고 블록 1이 두 번째 블록이 되는 방식입니다. 파일에서 블록 20, 21, 24 및 43을 요청하려고 합니다.

블록 오프셋

첫 번째 블록이 숫자 20이기 때문에 오프셋(o 필드)을 20으로 지정하여 비트맵의 공간을 절약할 수 있습니다.

블록 수

디바이스가 제한된 메모리 리소스로 처리할 수 있는 것보다 많은 블록을 수신하지 않도록 하려면 MQTT 기반 파일 전송에서 전송한 각 메시지에 반환해야 하는 최대 블록 수를 지정할 수 있습니다. 비트맵 자체가 이 블록 수보다 작게 지정하거나 MQTT 기반 파일 전송에서 전송한 응답 메시지의 총 크기가 GetStream 요청당 128KB의 서비스 제한보다 크게 되는 경우 이 값은 무시됩니다.

블록 비트맵

비트맵 자체는 16진법으로 표현된 부호 없는 바이트 배열이며 GetStream 요청에 숫자의 문자열 표현으로 포함됩니다. 그러나 이 문자열을 구성하기 위해 비트맵을 긴 비트 시퀀스(이진수)로 생각해봅시다. 이 시퀀스의 비트가 1로 설정되면 스트림 파일의 해당 블록이 디바이스로 다시 전송됩니다. 예를 들어 블록 20, 21, 24 및 43을 받기를 원하므로 비트 20, 21, 24 및 43을 비트맵에 설정해야 합니다. 블록 오프셋을 사용하여 공간을 절약할 수 있으므로 각 블록 번호에서 오프셋을 뺀 후 다음 예제와 같이 0, 1, 4 및 23비트를 설정하려고 합니다.


 1 1 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1

한 번에 1바이트(8비트)를 취하면 일반적으로 "0b00010011", "0b00000000" 및 "0b10000000"으로 작성됩니다. 0비트는 첫 번째 바이트의 끝에 이진 표현으로 표시되고 마지막 바이트의 시작 부분에 23비트가 표시됩니다. 규칙을 알지 못하면 혼란스러울 수 있습니다. 첫 번째 바이트는 비트 7-0(순서대로), 두 번째 바이트는 15-8비트를 포함하고, 세 번째 바이트는 23-16비트 등을 포함합니다. 16진수 표기법에서는 "0x130080"으로 변환됩니다.

작은 정보

표준 바이너리를 16진수 표기법으로 변환할 수 있습니다. 한 번에 네 개의 2진수를 가져와서 16진수로 변환하세요. 예를 들어 “0001"은 “1"이 되고 “0011"은 “3"이 됩니다.

요청에서 문자열을 생성하기 위한 비트맵 분석을 차단합니다. GetStream

이 모든 것이 포함된 GetStream 요청의 JSON 형식은 다음과 같습니다.


{
    "c" : "1",       
    "s" : 1,         
    "l" : 256,       
    "f" : 1,         
    "o" : 20,        
    "n" : 32,       
    "b" : "130080"
}

“c“은(는) 클라이언트 토큰 필드입니다.
's'는 예상 스트림 버전입니다.
“l“은(는) 데이터 블록 페이로드의 크기(바이트)입니다.
'f'는 소스 파일 인덱스의 ID입니다.
'o'는 블록 오프셋입니다.
'n'은 블록 수입니다.
'b'는 오프셋에서 시작하는 누락된 blockId 비트맵입니다. 이 값은 base64로 인코딩해야 합니다.

AWS IoT MQTT 기반 파일 전송으로 인한 오류 처리

DescribeStream 및 GetStream API 모두에 대해 디바이스로 전송되는 오류 응답에는 클라이언트 토큰, 오류 코드 및 오류 메시지가 포함됩니다. 일반적인 오류 응답은 다음 예제와 비슷합니다.


{
    "o": "BlockSizeOutOfBounds", 
    "m": "The block size is out of bounds", 
    "c": "1bb8aaa1-5c18-4d21-80c2-0b44fee10380" 
}

"o"은(는) 오류가 발생한 이유를 나타내는 오류 코드입니다. 자세한 내용은 이 단원의 뒷부분에 나오는 오류 코드를 참조하세요.
“m“은(는) 오류에 대한 세부 정보가 포함된 오류 메시지입니다.
“c“은(는) 클라이언트 토큰 필드입니다. DescribeStream 요청에 제공된 경우에 반환될 수 있습니다. 클라이언트 토큰을 사용하여 응답을 요청과 연결할 수 있습니다.

클라이언트 토큰 필드가 항상 오류 응답에 포함되는 것은 아닙니다. 요청에 주어진 클라이언트 토큰이 유효하지 않거나 형식이 잘못된 경우 오류 응답으로 반환되지 않습니다.

참고

이전 버전과의 호환성을 위해 오류 응답의 필드는 약어가 아닌 형식일 수 있습니다. 예를 들어 오류 코드는 “code” 또는 “o” 필드에 의해 지정될 수 있으며 클라이언트 토큰 필드는 “clientToken” 또는 “c” 필드에 의해 지정될 수 있습니다. 위에 표시된 약어 양식을 사용하는 것이 좋습니다.

InvalidTopic: 스트림 메시지의 MQTT 주제가 유효하지 않습니다.
InvalidJson: 스트림 요청이 유효한 JSON 문서가 아닙니다.
InvalidCbor: 스트림 요청이 유효한 CBOR 문서가 아닙니다.
InvalidRequest: 요청은 일반적으로 잘못된 형식으로 식별됩니다. 자세한 내용은 오류 메시지를 참조하세요.
권한이 없음: 요청에는 Amazon S3와 같은 스토리지 미디어의 스트림 데이터 파일에 액세스할 수 있는 권한이 없습니다. 자세한 내용은 오류 메시지를 참조하세요.
BlockSizeOutOfBounds: 블록 크기가 범위를 벗어났습니다. AWS IoT Core Service Quotas의 “MQTT 기반 파일 전송” 섹션을 참조하세요.
OffsetOutOfBounds: 오프셋이 범위를 벗어났습니다. AWS IoT Core Service Quotas의 “MQTT 기반 파일 전송” 섹션을 참조하세요.
BlockCountLimitExceeded: 요청 블록 수가 범위를 벗어났습니다. AWS IoT Core Service Quotas의 “MQTT 기반 파일 전송” 섹션을 참조하세요.
BlockBitmapLimitExceeded: 요청 비트맵의 크기가 범위를 벗어났습니다. AWS IoT Core Service Quotas의 “MQTT 기반 파일 전송” 섹션을 참조하세요.
ResourceNotFound: 요청된 스트림, 파일, 파일 버전 또는 블록을 찾을 수 없습니다. 자세한 내용은 오류 메시지를 참조하세요.
VersionMismatch: 요청의 스트림 버전이 MQTT 기반 파일 전송 기능의 스트림 버전과 일치하지 않습니다. 이는 스트림 버전이 디바이스에서 처음 수신된 이후 스트림 데이터가 수정되었음을 나타냅니다.
E. TagMismatch: 스트림의 S3 ETag가 최신 S3 객체 버전의 ETag와 일치하지 않습니다.
InternalError: MQTT 기반 파일 전송에서 내부 오류가 발생했습니다.

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

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

문서 규칙

클라우드에서의 스트림 관리 AWS

FreeRTOS OTA의 예제 사용 사례