View a markdown version of this page

GetObject(SOAP API) - Amazon Simple Storage Service
요소반환된 요소액세스 통제SOAP 청크 다운로드 및 재개 가능 다운로드

GetObject(SOAP API)

참고

Amazon S3용 SOAP API는 신규 고객에게 제공되지 않으며 2025년 8월 31일에 서비스 종료(EOL)됩니다. REST API 또는 AWS SDK를 사용하는 것이 좋습니다.

GetObject 작업은 객체의 현재 버전을 반환합니다. 삭제 마커가 현재 버전인 객체에 대해 GetObject를 시도하면 S3가 404 오류를 반환합니다. 이 SOAP API를 사용하여 객체의 지정된 버전을 검색할 수 없습니다. 이를 위해서는 REST API를 사용합니다. 자세한 내용은 버전 관리를 참조하십시오. 추가 옵션을 선택하려면 GetObjectExtended(SOAP API) 작업을 사용합니다.

참고

값이 "soap"인 객체 키 이름은 가상 호스팅 스타일 요청에 지원되지 않습니다. "soap"이 사용되는 객체 키 이름 값의 경우 경로 스타일 URL을 대신 사용해야 합니다.

예

이 예제에서는 'quotes' 버킷에서 'Nelson' 객체를 가져옵니다.

Sample Request

<GetObject xmlns="https://doc.s3.amazonaws.com/2006-03-01">
  <Bucket>quotes</Bucket>
  <Key>Nelson</Key>
  <GetMetadata>true</GetMetadata>
  <GetData>true</GetData>
  <InlineData>true</InlineData>
  <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
  <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
  <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</GetObject>

Sample Response

<GetObjectResponse xmlns="https://s3.amazonaws.com/doc/2006-03-01">
  <GetObjectResponse>
    <Status>
      <Code>200</Code>
      <Description>OK</Description>
    </Status>
    <Metadata>
      <Name>Content-Type</Name>
      <Value>text/plain</Value>
    </Metadata>
    <Metadata>
      <Name>family</Name>
      <Value>Muntz</Value>
    </Metadata>
    <Data>aGEtaGE=</Data>
    <LastModified>2006-01-01T12:00:00.000Z</LastModified>
    <ETag>&quot;828ef3fdfa96f00ad9f27c383fc9ac7f&quot;</ETag>
  </GetObjectResponse>
</GetObjectResponse>

요소

  • Bucket: 객체를 검색할 버킷입니다.

  • Key: 객체를 식별하는 키입니다.

  • GetMetadata: true인 경우 메타데이터가 객체와 함께 반환됩니다.

  • GetData: true인 경우 객체 데이터가 반환됩니다.

  • InlineData: true인 경우 데이터가 응답의 SOAP 본문의 일부로 Base64로 인코딩된 상태로 반환됩니다. false인 경우 데이터가 SOAP 첨부 파일로 반환됩니다. InlineData 옵션은 대형 객체에 사용하기에 적합하지 않습니다. 시스템은 이 작업을 1MB 이하의 데이터에 사용하도록 제한합니다. InlineData 플래그가 설정된 GetObject 요청은 결과 데이터 파라미터의 인코딩 후 크기가 1MB를 초과하게 될 경우 InlineDataTooLargeError 상태 코드와 함께 실패합니다. 대형 객체를 다운로드하려면 InlineData 플래그를 설정하지 않고 GetObject를 직접적으로 호출하거나 대신 REST API를 사용하는 것이 좋습니다.

반환된 요소

  • Metadata: 객체와 함께 저장된 이름-값 쌍 메타데이터입니다.

  • Data: 요청에서 InlineData가 true인 경우 여기에는 Base64로 인코딩된 객체 데이터가 포함됩니다.

  • LastModified: 객체가 Amazon S3에 저장된 시간입니다.

  • ETag: 객체의 엔터티 태그입니다. 조건부 가져오기를 수행하는 데 사용할 수 있는 객체의 해시입니다. ETag는 객체의 콘텐츠에 대한 변경 사항만 반영하고 메타데이터에 대한 변경을 반영하지 않습니다.

액세스 통제

객체에 대한 READ 액세스 권한이 부여된 경우에만 객체를 읽을 수 있습니다.

SOAP 청크 다운로드 및 재개 가능 다운로드

GET 유연성을 제공하기 위해 Amazon S3는 청크 다운로드와 재개 가능한 다운로드를 지원합니다.

다음 중에서 선택합니다.

  • 대형 객체 다운로드의 경우 객체를 작은 청크로 분할해야 할 수 있습니다. 자세한 내용은 범위 GET 섹션을 참조하세요.

  • GET 작업이 실패하는 경우 전체 파일 대신 나머지 파일을 다운로드하도록 애플리케이션을 설계할 수 있습니다. 자세한 내용은 REST GET 오류 복구 섹션을 참조하세요.

범위 GET

일부 클라이언트의 경우 대용량 다운로드를 더 작은 다운로드로 분할할 수 있습니다. GET을 더 작은 단위로 분할하려면 범위를 사용합니다.

GET을 더 작은 단위로 분할하려면 먼저 크기를 결정해야 합니다. 예를 들어 다음 요청은 bigfile 객체의 크기를 가져옵니다.

<ListBucket xmlns="https://doc.s3.amazonaws.com/2006-03-01">
  <Bucket>bigbucket</Bucket>
  <Prefix>bigfile</Prefix>
  <MaxKeys>1</MaxKeys>
  <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
  <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
  <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</ListBucket>

Amazon S3는 다음 응답을 반환합니다.

<ListBucketResult xmlns="https://s3.amazonaws.com/doc/2006-03-01">
  <Name>quotes</Name>
  <Prefix>N</Prefix>
  <MaxKeys>1</MaxKeys>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>bigfile</Key>
    <LastModified>2006-01-01T12:00:00.000Z</LastModified>
    <ETag>&quot;828ef3fdfa96f00ad9f27c383fc9ac7f&quot;</ETag>
    <Size>2023276</Size>
    <StorageClass>STANDARD</StorageClass>
    <Owner>
      <ID>bcaf1ffd86f41161ca5fb16fd081034f</ID>
      <DisplayName>bigfile</DisplayName>
     </Owner>
  </Contents>
</ListBucketResult>

다음은 bigfile 객체에서 첫 번째 메가바이트를 다운로드하는 요청입니다.

<GetObject xmlns="https://doc.s3.amazonaws.com/2006-03-01">
  <Bucket>bigbucket</Bucket>
  <Key>bigfile</Key>
  <GetMetadata>true</GetMetadata>
  <GetData>true</GetData>
  <InlineData>true</InlineData>
  <ByteRangeStart>0</ByteRangeStart>
  <ByteRangeEnd>1048576</ByteRangeEnd>
  <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
  <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
  <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</GetObject>

Amazon S3는 파일의 첫 번째 메가바이트와 파일의 Etag를 반환합니다.

<GetObjectResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
  <GetObjectResponse>
    <Status>
      <Code>200</Code>
      <Description>OK</Description>
    </Status>
    <Metadata>
      <Name>Content-Type</Name>
      <Value>text/plain</Value>
    </Metadata>
    <Metadata>
      <Name>family</Name>
      <Value>Muntz</Value>
    </Metadata>
    <Data>--first megabyte of bigfile--</Data>
    <LastModified>2006-01-01T12:00:00.000Z</LastModified>
    <ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
  </GetObjectResponse>
</GetObjectResponse>

이전 부분이 다운로드된 이후 파일이 변경되지 않았는지 확인하려면 IfMatch 요소를 지정합니다. IfMatch 요소가 필수는 아니지만 변경 가능성이 있는 콘텐츠에는 권장됩니다.

다음은 IfMatch 요청 헤더를 사용하여 파일의 나머지 부분을 가져오는 요청입니다.

<GetObject xmlns="https://doc.s3.amazonaws.com/2006-03-01">
  <Bucket>bigbucket</Bucket>
  <Key>bigfile</Key>
  <GetMetadata>true</GetMetadata>
  <GetData>true</GetData>
  <InlineData>true</InlineData>
  <ByteRangeStart>10485761</ByteRangeStart>
  <ByteRangeEnd>2023276</ByteRangeEnd>
  <IfMatch>"828ef3fdfa96f00ad9f27c383fc9ac7f"</IfMatch>
  <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
  <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
  <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</GetObject>

Amazon S3는 다음 응답과 함께 파일의 나머지 부분을 반환합니다.

<GetObjectResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
  <GetObjectResponse>
    <Status>
      <Code>200</Code>
      <Description>OK</Description>
    </Status>
    <Metadata>
      <Name>Content-Type</Name>
      <Value>text/plain</Value>
    </Metadata>
    <Metadata>
      <Name>family</Name>
      <Value>>Muntz</Value>
    </Metadata>
    <Data>--remainder of bigfile--</Data>
    <LastModified>2006-01-01T12:00:00.000Z</LastModified>
    <ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
  </GetObjectResponse>
</GetObjectResponse>

버전이 지정된 GetObject

다음 요청은 버킷에 있는 객체의 지정된 버전을 반환합니다.

<GetObject xmlns="https://doc.s3.amazonaws.com/2006-03-01">
<Bucket>quotes</Bucket>
<Key>Nelson</Key>
<GetMetadata>true</GetMetadata>
<GetData>true</GetData>
<InlineData>true</InlineData>
<AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
<Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
<Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</GetObject>

샘플 응답

<GetObjectResponse xmlns="https://s3.amazonaws.com/doc/2006-03-01">
<GetObjectResponse>
<Status>
<Code>200</Code>
<Description>OK</Description>
</Status>
<Metadata>
<Name>Content-Type</Name>
<Value>text/plain</Value>
</Metadata>
<Metadata>
<Name>family</Name>
<Value>Muntz</Value>
</Metadata>
<Data>aGEtaGE=</Data>
<LastModified>2006-01-01T12:00:00.000Z</LastModified>
<ETag>&quot;828ef3fdfa96f00ad9f27c383fc9ac7f&quot;</ETag>
</GetObjectResponse>
</GetObjectResponse>

REST GET 오류 복구

객체 GET이 실패하면 다운로드할 범위를 지정하여 파일의 나머지 부분을 가져올 수 있습니다. 이렇게 하려면 ListBucket을 사용하여 객체의 크기를 가져오고 파일의 나머지 부분에서 범위 GET을 수행해야 합니다. 자세한 내용은 GetObjectExtended(SOAP API) 섹션을 참조하세요.

관련 리소스

객체에 대한 작업(SOAP API)