객체 나열하기

컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

버킷의 객체를 나열하려면 버킷으로 범위가 지정된 GET 요청을 수행합니다. 쿼리 문자열 매개변수를 사용하여 요청의 범위를 더 좁힐 수도 있습니다. 요청은 응답 본문의 XML 문서에 있는 객체 목록을 반환하며, 목록의 객체는 이름을 기준으로 사전순으로 정렬됩니다.

버킷에 있는 객체 목록을 가져오려면 버킷 READ 권한이 있어야 하며 버킷의 ACL 또는 CORS를 나열할 수 있는 버킷 FULL_CONTROL 권한이 있어야 합니다.

delimiter, marker, max-keys, prefix 쿼리 문자열 매개변수를 사용하여 GET 버킷 요청으로 반환되는 객체의 목록을 제한하고 구성할 수 있습니다.

XML API는 1,000개보다 긴 목록을 반환하지 않습니다.

쿼리 문자열 매개변수

매개변수 설명 필수
delimiter 디렉터리와 유사한 이름 지정 체계를 사용하는 객체 목록을 단순화하는 데 사용할 수 있는 문자 또는 여러 문자. prefix와 함께 사용할 수 있습니다. 없음
encoding-type url로 설정하면 객체 이름이 응답에서 URL 인코딩됩니다. 없음
generation-marker 객체 나열을 시작할 객체 생성입니다. 세대 아이콘을 사용하는 경우 마커도 사용해야 합니다. 없음
marker 객체 나열을 시작하려는 객체 이름입니다. 이름이 marker보다 더 크면 이름이 객체 목록에서 반환됩니다. 없음
max-keys 목록 객체 요청에 반환되는 객체의 최대 개수입니다. 없음
prefix 지정된 값으로 시작하는 이름의 색인만 GET 버킷 요청에 반환되는 객체의 수를 제한하는 데 사용할 수 있는 문자열입니다. delimiter와 함께 사용할 수 있습니다. 없음
versions 버전이 지정된 버킷에 지정된 경우 모든 객체 버전 목록이 반환됩니다. 생략하면 현재 버전만 나열됩니다. 없음

서명된 URL을 만들고 사용할 때 포함되는 매개변수에 대한 정보는 서명된 URL 쿼리 문자열 매개변수를 참조하세요.

요청 헤더

일반적인 요청 헤더를 참조하세요.

요청 본문 요소

이 요청은 요청 본문에 XML 문서를 포함하지 않습니다.

요청 구문

다음 구문은 매개변수를 사용하지 않거나 delimiter, generation-marker, marker, max-keys, prefix 중 하나 이상을 사용하는 GET 버킷 요청에 적용됩니다. , versions 쿼리 문자열 매개변수

GET /?prefix=a_prefix&marker=a_marker&max-keys=max_number_of_keys&delimiter=a_delimiter HTTP/1.1
Host: BUCKET_NAME.storage.googleapis.com
Date: DATE
Content-Length: 0
Authorization: AUTHENTICATION_STRING

응답 헤더

이 요청은 사용 중인 요청 헤더에 따라 다양한 응답 헤더를 반환할 수 있습니다.

응답 본문 요소

매개변수 없이 또는 delimiter, generation-marker, marker, max-keys, prefix 중 하나 이상을 사용하는 경우에만 다음 응답 본문 요소가 적용됩니다. ) 또는 versions 쿼리 문자열 매개변수를 사용하여 버킷의 객체를 나열합니다.

요소 설명
ListBucketResult 요청 중인 객체 정보의 컨테이너입니다.
Name 버킷 이름입니다.
CommonPrefixes prefix 및 delimiter 제약조건을 충족하는 프리픽스의 컨테이너입니다. 이 컨테이너는 요청에 delimiter를 지정하고 중복 항목이 생략된 경우에만 사용됩니다.
Delimiter 요청에 지정한 delimiter입니다.
MaxKeys 요청에 지정한 max-keys입니다.
Prefix 요청에 지정한 prefix입니다.
GenerationMarker 요청에 지정한 generation-marker입니다.
NextGenerationMarker 반환된 객체 목록이 완전하지 않고 versions 매개변수가 사용된 경우 NextGenerationMarker는 마지막으로 반환된 객체의 세대를 제공합니다. 목록이 이미 완료되었다면 NextGenerationMarker는 반환되지 않습니다.
Marker 요청에 지정한 marker입니다.
NextMarker NextMarker은 마지막으로 반환된 객체의 이름을 제공합니다. 이 결과 집합을 적용한 후에도 계속 버킷을 나열하려면 향후 GET Bucket 호출의 marker 쿼리 문자열 매개변수에 NextMarker 값을 제공할 수 있습니다. 버킷의 마지막 객체를 따르는 객체가 더 이상 없으면 NextMarker는 반환되지 않습니다.
IsTruncated 버킷의 모든 객체가 목록에 표시되는지 여부를 나타냅니다. max-keys가 버킷의 객체 수보다 작으면 이 요소는 True입니다.
Contents versions 쿼리 매개변수가 사용되지 않는 경우 객체 정보의 컨테이너입니다.
Version versions 쿼리 매개변수가 사용되는 경우 객체 정보 컨테이너입니다.
Key 객체 이름입니다.
Generation 객체의 세대입니다.
MetaGeneration 객체 메타데이터 생성
IsLatest versions 쿼리 매개변수가 지정되면 객체가 현재 활성 상태인 경우 true로 설정됩니다. 실시간 즉, 이 객체가 세대 없이 요청되면 이 객체가 반환됨을 의미합니다.
LastModified 객체 메타데이터가 마지막으로 수정된 날짜 및 시간입니다.
DeletedTime versions 쿼리 매개변수가 지정된 경우 현재 객체가 아닌 객체에 대한 객체 교체 또는 삭제 날짜 및 시간이 포함됩니다.
ETag 객체의 HTTP 1.1 항목 태그
Size 객체 크기(바이트).
KmsKeyName 객체를 암호화하는 데 사용되는 KMS 키의 이름입니다. 이 요소는 객체가 고객 관리 암호화 키로 암호화된 경우에만 존재합니다.

예시

다음 샘플은 travel-maps라는 버킷의 객체를 나열합니다.

요청

GET / HTTP/1.1
Host: travel-maps.storage.googleapis.com
Date: Wed, 17 Feb 2010 15:31:56 GMT
Content-Length: 0
Content-Type: text/plain
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg

응답

HTTP/1.1 200 OK
 Content-Length: 4061
 Content-Type: application/xml
 Date: Wed, 17 Feb 2010 23:31:57 GMT
 Expires: Wed, 17 Feb 2010 23:31:57 GMT

<?xml version='1.0' encoding='utf-8'?>
<ListBucketResult xmlns='http://doc.s3.amazonaws.com/2006-03-01'>
  <Name>travel-maps</Name>
  <Prefix></Prefix>
  <Marker></Marker>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>europe/france/cannes.pdf</Key>
    <Generation>1360887759327000</Generation>
    <MetaGeneration>1</MetaGeneration>
    <LastModified>2010-02-17T22:11:12.487Z</LastModified>
    <ETag>"53fc311c15eda0a031809982ccf92aac"</ETag>
    <Size>5061631</Size>
  </Contents>
  <Contents>
    <Key>europe/france/paris.pdf</Key>
    <Generation>1360887759329000</Generation>
    <MetaGeneration>1</MetaGeneration>
    <LastModified>2010-02-17T22:09:57.457Z</LastModified>
    <ETag>"53fc311c15eda0a031809982ccf92aac"</ETag>
    <Size>5061631</Size>
  </Contents>
</ListBucketResult>

다음 샘플은 travel-maps의 객체를 나열하지만 '문자'로 시작하고 'test' 다음에 오는 25개의 객체로 목록을 제한합니다.

요청

GET /?prefix=t&marker=test&max-keys=25 HTTP/1.1
Host: travel-maps.storage.googleapis.com
Date: Mon, 16 Feb 2010 22:58:38 GMT
Content-Length: 0
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg

응답

HTTP/1.1 200 OK
Date: Mon, 15 Feb 2010 12:30:40 GMT
Content-Length: 2705
Content-Type: application/xml

<?xml version='1.0' encoding='utf-8'?>
<ListBucketResult xmlns='http://doc.s3.amazonaws.com/2006-03-01'>
  <Name>travel-maps</Name>
  <Prefix>t</Prefix>
  <Marker>test</Marker>
  <MaxKeys>25</MaxKeys>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>test_a.jpg</Key>
    <Generation>1360887659329000</Generation>
    <MetaGeneration>1</MetaGeneration>
    <LastModified>2010-02-17T03:12:55.561Z</LastModified>
    <ETag>"2281880ef78388266ecd7d4c1b472a0e"</ETag>
    <Size>328</Size>
  </Contents>
  <Contents>
    <Key>test_b.jpg</Key>
    <Generation>1360887659323000</Generation>
    <MetaGeneration>1</MetaGeneration>
    <LastModified>2010-02-17T03:12:54.606Z</LastModified>
    <ETag>"2281880ef78388266ecd7d4c1b472a0e"</ETag>
    <Size>328</Size>
  </Contents>
  <Contents>
    <Key>test_c.jpg</Key>
    <LastModified>2010-02-17T03:12:53.734Z</LastModified>
    <ETag>"2281880ef78388266ecd7d4c1b472a0e"</ETag>
    <Size>328</Size>
  </Contents>
</ListBucketResult>

프리픽스 및 구분 기호 사용 예시

다음 예시에서는 prefix 및 delimiter를 사용하여 디렉터리와 유사한 스키마를 사용하여 이름이 지정된 객체의 목록을 반환합니다. prefix=europe/ 및 delimiter=/를 사용하면 europe/ '디렉터리'에 있는 객체만 반환됩니다. europe 디렉터리의 '하위 디렉터리'에 있는 객체는 나열되지 않고, 응답의 CommonPrefixes 요소에 이름 이름의 앞부분이 포함됩니다. 이 샘플에서는 다음 객체가 travel-maps이라는 버킷에 포함되어 있다고 가정합니다.

  • 아프리카/ghana.jpg
  • Aricica/egypt/caroi.jpg
  • europe/finland.jpg
  • europe/norway.jpg
  • europe/france/paris.jpg
  • europe/italy/rome.jpg
  • europe/sweden/stockholm.jpg
  • europe/sweden/stockholm/nordic_museum.jpg

샘플 요청은 Contents 요소에 다음 두 객체를 나열하는 XML 문서를 반환합니다.

  • europe/finland.jpg
  • europe/norway.jpg

다음 europe 하위 디렉터리는 CommonPrefixes 요소에 나열됩니다.

  • europe/france/
  • 유럽/이탈리아/
  • europe/sweden/

요청

GET /travel-maps?delimiter=/&prefix=europe/ HTTP/1.1
Host: storage.googleapis.com
Date: Mon, 16 Feb 2010 22:58:38 GMT
Content-Length: 0
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg

응답

HTTP/1.1 200 OK
Date: Mon, 15 Feb 2010 12:30:40 GMT
Content-Length: 1200
Content-Type: application/xml

<?xml version="1.0"?>
<ListBucketResult xmlns='http://doc.s3.amazonaws.com/2006-03-01'>
  <Name>mybucket</Name>
  <Prefix>europe/</Prefix>
  <Marker />
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>europe/finland.jpg</Key>
    <Generation>1360887659323000</Generation>
    <MetaGeneration>1</MetaGeneration>
    <LastModified>2010-02-17T03:12:55.561Z</LastModified>
    <ETag>"781e5e245d69b566979b86e28d23f2c7"</ETag>
    <Size>10</Size>
  </Contents>
  <Contents>
    <Key>europe/norway.jpg</Key>
    <Generation>1360887659323000</Generation>
    <MetaGeneration>1</MetaGeneration>
    <LastModified>2010-02-17T03:12:55.561Z</LastModified>
    <ETag>"781e5e245d69b566979b86e28d23f2c7"</ETag>
    <Size>10</Size>
  </Contents>
  <CommonPrefixes>
    <Prefix>europe/france/</Prefix>
  </CommonPrefixes>
  <CommonPrefixes>
    <Prefix>europe/italy/</Prefix>
  </CommonPrefixes>
  <CommonPrefixes>
    <Prefix>europe/sweden/</Prefix>
  </CommonPrefixes>
</ListBucketResult>