View a markdown version of this page

부록: SelectObjectContent 응답 - Amazon Simple Storage Service
설명응답관련 리소스

부록: SelectObjectContent 응답

설명

Amazon S3 Select 작업은 간단한 구조화된 쿼리 언어(SQL) 문을 기반으로 Amazon S3 객체의 콘텐츠를 필터링합니다. 이 작업의 응답 크기를 알 수 없으므로, Amazon S3 Select는 응답을 일련의 메시지로 스트리밍하고 응답에 값이 chunked인 Transfer-Encoding 헤더를 포함합니다.

Amazon S3 Select에 대한 자세한 내용은 Amazon Simple Storage Service 사용 설명서의 객체에서 콘텐츠 선택을 참조하세요.

Amazon S3 Select와 함께 SQL을 사용하는 방법에 대한 자세한 내용은 Amazon Simple Storage Service 사용 설명서의 Amazon S3 Select 및 Amazon Glacier Select용 SQL 참조를 참조하세요.

응답

Amazon S3 Select 작업이 성공하면 200 OK 상태 코드가 반환됩니다.

응답 헤더

이 작업의 구현에서는 대부분의 응답에 공통되는 응답 헤더만 사용합니다. 자세한 내용은 공통 응답 헤더를 참조하세요.

응답 본문

Amazon S3 Select 응답 크기를 알 수 없으므로, Amazon S3는 응답을 일련의 메시지로 스트리밍하고 응답에 값이 chunked인 Transfer-Encoding 헤더를 포함합니다. 다음 예제는 최상위 수준의 응답 형식을 보여줍니다.

<Message 1>
<Message 2>
<Message 3>
......
<Message n>

각 메시지는 두 섹션(서문 및 데이터)으로 구성됩니다. 서문 섹션은 1) 메시지의 총 바이트 길이 및 2) 모든 헤더의 총 바이트 길이로 구성됩니다. 데이터 섹션은 1) 헤더 및 2) 페이로드로 구성됩니다.

각 섹션은 4바이트 빅 엔디안 정수 체크섬(CRC)으로 끝납니다. Amazon S3 Select는 CRC32(GZIP CRC32라고도 함)를 사용하여 두 CRC를 모두 계산합니다. CRC32에 대한 자세한 내용은 GZIP file format specification version 4.3을 참조하세요.

총 메시지 오버헤드(서문과 두 체크섬 포함)는 16바이트입니다.

참고

메시지 내의 모든 integer 값은 네트워크 바이트 순서 또는 빅 엔디안 순서입니다.

다음 다이어그램은 메시지와 헤더를 구성하는 구성 요소를 보여줍니다. 메시지별로 여러 개의 헤더가 있습니다.

총 바이트 길이, 헤더 바이트 길이, 서문 CRC, 헤더, 페이로드 및 메시지 CRC를 보여주는 예제 메시지 구조입니다.
참고

Amazon S3 Select의 경우 헤더 값 유형은 항상 7(type=String)입니다. 이 유형의 경우 헤더 값은 두 가지 구성 요소, 즉 2바이트 빅 엔디안 정수 길이와 해당 바이트 길이의 UTF-8 문자열로 이루어집니다. 다음 다이어그램은 Amazon S3 Select 헤더를 구성하는 구성 요소를 보여줍니다.

헤더 이름 바이트 길이, 헤더 이름 문자열, 헤더 값 유형, 값 바이트 길이 및 값 문자열을 보여주는 헤더 구조입니다.

페이로드 바이트 길이 계산(다음 두 계산은 동일):

  • payload_length = total_length - header_length - sizeOf(total_length) - sizeOf(header_length) - sizeOf(prelude_crc) - sizeOf(message_crc)

  • payload_length = total_length - header_length - 16

각 메시지는 다음 구성 요소를 포함합니다.

  • 서문: 항상 8바이트 고정 크기이며 두 필드가 각각 4바이트를 차지합니다.

    • 처음 4바이트: 총 바이트 길이: 전체 메시지의 빅 엔디안 정수 바이트 길이입니다(4바이트 총 길이 필드 자체를 포함).

    • 두 번째 4바이트: 헤더 바이트 길이: 메시지 헤더 부분의 빅 엔디안 정수 바이트 길이입니다(헤더 길이 필드 자체는 제외).

  • 서문 CRC: 메시지 서문 부분의 4바이트 빅 엔디안 정수 체크섬(CRC)입니다(CRC 자체는 제외). 서문에는 메시지 CRC(아래 참조)와 분리된 CRC가 있어서 비정상적인 버퍼링 동작을 일으키지 않으면서 손상된 바이트 길이 정보를 즉시 감지할 수 있습니다.

  • 헤더: 메시지 유형, 페이로드 형식 등 메시지에 대한 정보를 포함하는 메타데이터 세트입니다. 메시지에는 여러 헤더가 있을 수 있으므로 메시지의 이 부분은 메시지 유형에 따라 바이트 길이가 다를 수 있습니다. 헤더는 키-값 페어이며, 키와 값은 모두 UTF-8 문자열입니다. 헤더는 메시지의 헤더 부분에 순서에 상관없이 표시되며 특정 헤더 유형은 한 번만 표시될 수 있습니다.

    Amazon S3 Select의 경우 다음은 메시지 유형에 따른 헤더 이름 목록 및 유효한 값 세트입니다.

    • MessageType 헤더:

      • 헤더 이름 => ":message-type"

      • 유효한 헤더 값 => "error", "event"

    • EventType 헤더:

      • 헤더 이름 => ":event-type"

      • 유효한 헤더 값 => "Records", "Cont", "Progress", "Stats", "End"

    • ErrorCode 헤더:

    • ErrorMessage 헤더:

      • 헤더 이름 => ":error-message"

      • 유효한 헤더 값 => 요청 수준 오류를 진단하는 데 도움이 되도록 서비스에서 반환하는 오류 메시지입니다.

  • 페이로드: 무엇이든 가능합니다.

  • 메시지 CRC: 메시지 시작부터 체크섬 시작까지 4바이트 빅 엔디안 정수 체크섬(CRC), 즉 메시지 CRC 자체를 제외한 메시지의 모든 항목입니다.

각 헤더는 다음 구성 요소를 포함합니다. 메시지별로 여러 개의 헤더가 있을 수 있습니다.

  • 헤더 이름 바이트 길이: 헤더 이름의 바이트 길이입니다.

  • 헤더 이름: 헤더 유형을 나타내는 헤더 이름입니다. 유효한 값: ":message-type" ":event-type" ":error-code" ":error-message"

  • 헤더 값 유형: 헤더 값 유형을 나타내는 열거형입니다. Amazon S3 Select의 경우 항상 7입니다.

  • 값 문자열 바이트 길이: (Amazon S3 Select의 경우) 헤더 값 문자열의 바이트 길이입니다.

  • 헤더 값 문자열: (Amazon S3 Select의 경우) 헤더 문자열의 값입니다. 이 필드의 유효한 값은 헤더 유형에 따라 달라집니다. 각 헤더 유형 및 메시지 유형에 대한 유효한 값은 아래 섹션을 참조하세요.

Amazon S3 Select의 경우 응답은 다음 유형의 메시지일 수 있습니다.

  • 레코드 메시지: 단일 레코드, 부분 레코드 또는 여러 레코드를 포함할 수 있습니다. 결과의 크기에 따라 응답에 이러한 메시지가 하나 이상이 포함될 수 있습니다.

  • 연속 메시지: Amazon S3는 TCP 연결을 유지하기 위해 이 메시지를 주기적으로 전송합니다. 이러한 메시지는 응답에 무작위로 표시됩니다. 클라이언트는 메시지 유형을 감지하고 그에 따라 처리해야 합니다.

  • 진행 상황 메시지: Amazon S3는 요청 시 이 메시지를 주기적으로 전송합니다. 여기에는 시작되었지만 아직 완료되지 않은 쿼리의 진행 상황에 대한 정보가 포함되어 있습니다.

  • 통계 메시지: Amazon S3는 요청 종료 시 이 메시지를 전송합니다. 여기에는 쿼리에 대한 통계가 포함되어 있습니다.

  • 종료 메시지: 요청이 완료되었으며 더 이상 메시지가 전송되지 않음을 나타냅니다. 클라이언트가 End 메시지를 수신할 때까지는 요청이 완료되었다고 가정해서는 안 됩니다.

  • RequestLevelError 메시지: Amazon S3는 어떤 이유로든 요청이 실패한 경우 이 메시지를 전송합니다. 실패에 대한 오류 코드 및 오류 메시지가 포함되어 있습니다. Amazon S3는 RequestLevelError 메시지를 전송하는 경우 End 메시지를 전송하지 않습니다.

다음 섹션에서는 각 메시지 유형의 구조를 자세히 설명합니다.

이 프로토콜을 사용하는 샘플 코드 및 유닛 테스트는 GitHub 웹 사이트의 AWS C 이벤트 스트림을 참조하세요.

레코드 메시지

헤더 사양

레코드 메시지에는 다음과 같이 세 개의 헤더가 포함됩니다.

이 레코드 유형의 헤더를 포함하는 메시지 구조의 예입니다.
페이로드 사양

레코드 메시지 페이로드에는 단일 레코드, 부분 레코드 또는 여러 레코드가 포함될 수 있습니다.

연속 메시지

헤더 사양

연속 메시지에는 다음과 같이 두 개의 헤더가 포함됩니다.

이 레코드 유형의 헤더를 포함하는 메시지 구조의 예입니다.
페이로드 사양

연속 메시지에는 페이로드가 없습니다.

진행 상황 메시지

헤더 사양

진행 상황 메시지에는 다음과 같이 세 개의 헤더가 포함됩니다.

이 레코드 유형의 헤더를 포함하는 메시지 구조의 예입니다.
페이로드 사양

진행 상황 메시지 페이로드는 요청의 진행 상황에 대한 정보가 포함된 XML 문서입니다.

  • BytesScanned => 압축 해제 전에 처리된 바이트 수입니다(파일이 압축된 경우).

  • BytesProcessed => 압축 해제 후에 처리된 바이트 수입니다(파일이 압축된 경우).

  • BytesReturned => Amazon S3에서 반환한 레코드 페이로드 데이터의 현재 바이트 수입니다.

압축되지 않은 파일의 경우 BytesScanned와 BytesProcessed는 동일합니다.

예제:

<?xml version="1.0" encoding="UTF-8"?>
<Progress>
     <BytesScanned>512</BytesScanned>
     <BytesProcessed>1024</BytesProcessed>
     <BytesReturned>1024</BytesReturned>
</Progress>

통계 메시지

헤더 사양

통계 메시지에는 다음과 같이 세 개의 헤더가 포함됩니다.

이 레코드 유형의 헤더를 포함하는 메시지 구조의 예입니다.
페이로드 사양

통계 메시지 페이로드는 처리가 완료된 요청의 통계에 대한 정보가 포함된 XML 문서입니다.

  • BytesScanned => 압축 해제 전에 처리된 바이트 수입니다(파일이 압축된 경우).

  • BytesProcessed => 압축 해제 후에 처리된 바이트 수입니다(파일이 압축된 경우).

  • BytesReturned => Amazon S3에서 반환한 레코드 페이로드 데이터의 총 바이트 수입니다.

압축되지 않은 파일의 경우 BytesScanned와 BytesProcessed는 동일합니다.

예제:

<?xml version="1.0" encoding="UTF-8"?>
<Stats>
     <BytesScanned>512</BytesScanned>
     <BytesProcessed>1024</BytesProcessed>
     <BytesReturned>1024</BytesReturned>
</Stats>

종료 메시지

헤더 사양

종료 메시지에는 다음과 같이 두 개의 헤더가 포함됩니다.

이 레코드 유형의 헤더를 포함하는 메시지 구조의 예입니다.
페이로드 사양

종료 메시지에는 페이로드가 없습니다.

요청 수준 오류 메시지

헤더 사양

요청 수준 오류 메시지에는 다음과 같이 세 개의 헤더가 포함됩니다.

이 레코드 유형의 헤더를 포함하는 메시지 구조의 예입니다.

가능한 오류 코드 및 오류 메시지 목록은 SELECT 객체 콘텐츠 오류 코드 목록 섹션을 참조하세요.

페이로드 사양

요청 수준 오류 메시지에는 페이로드가 없습니다.

관련 리소스