GetBucket (ListObjects) API を使用したファイル情報のリスト - Object Storage Service

GetBucket (ListObjects) 操作を呼び出して、バケット内のすべてのオブジェクトに関する情報をリスト表示できます。この情報には、オブジェクト名、サイズ、最終更新日時が含まれます。

使用上の注意

GetBucket (ListObjects) 操作は GetBucketV2 (ListObjectsV2) に更新されました。アプリケーションを開発する際は、新しいバージョンの GetBucketV2 (ListObjectsV2) を使用することを推奨します。下位互換性のために、OSS は引き続き GetBucket (ListObjects) をサポートします。GetBucketV2 (ListObjectsV2) の詳細については、「ListObjectsV2 (GetBucketV2)」をご参照ください。
カスタムオブジェクトメタデータは、GetBucket (ListObjects) リクエストへの応答では返されません。
GetBucket (ListObjects) 操作はバケットレベルの操作です。この操作を呼び出すたびに、1 回の PUT リクエストに相当する料金が課金されます。料金はバケットのストレージクラスに基づきます。詳細については、「PUT API リクエスト」をご参照ください。
バケットでバージョン管理が有効になっている場合、オブジェクトを上書きまたは削除すると、多数の削除マーカーと以前のバージョンが作成されます。ライフサイクルルールを設定して、不要になった削除マーカーと以前のバージョンを定期的に削除することを推奨します。これにより、オブジェクトをリスト表示する際のパフォーマンスの低下を防ぐことができます。

リクエスト構文

GET / HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

リクエストヘッダー

この操作では、Authorization や Host などの共通リクエストヘッダーのみを使用します。詳細については、「共通リクエストヘッダー」をご参照ください。

リクエストパラメーター

名前	タイプ	必須	例	説明
delimiter	String	No	/	オブジェクト名をグループ化するための文字。プレフィックスからデリミタの最初の出現まで同じ文字列を含むすべてのオブジェクト名は、CommonPrefixes という名前の単一の要素としてグループ化されます。デフォルト値: なし。
marker	String	No	test1.txt	リスト操作を開始するオブジェクト。オブジェクトは、指定されたマーカーの後にアルファベット順で返されます。マーカーはページネーションに使用されます。このパラメーターの値は、長さが 1,024 バイト未満である必要があります。条件付きクエリの場合、指定されたマーカーが存在しなくても、リストはマーカーのアルファベット順で次のオブジェクトから開始されます。デフォルト値: なし。
max-keys	String	No	200	返すオブジェクトの最大数。この制限のためにリストが完了しない場合、応答には次のリクエストのマーカーとして使用する NextMarker 要素が含まれます。有効な値: 1～1000。デフォルト値: 100。
prefix	String	No	fun	リストするオブジェクトの名前に含める必要があるプレフィックス。プレフィックスは 1,024 バイト未満である必要があります。クエリにプレフィックスを使用すると、返されるキーにもプレフィックスが含まれます。 prefix をディレクトリ名に設定すると、そのディレクトリに再帰的に存在するすべてのオブジェクトとサブディレクトリがリストされます。プレフィックスに基づいて delimiter をスラッシュ (/) に設定すると、ディレクトリ内のオブジェクトのみがリストされます。ディレクトリ内のサブディレクトリの名前は CommonPrefixes で返されます。サブディレクトリに再帰的に存在するオブジェクトとディレクトリはリストされません。たとえば、バケットに fun/test.jpg、fun/movie/001.avi、fun/movie/007.avi の 3 つのオブジェクトが含まれているとします。prefix を fun/ に設定すると、3 つのオブジェクトが返されます。prefix を fun/ に、delimiter をスラッシュ (/) に設定すると、fun/test.jpg と fun/movie/ が返されます。デフォルト値: なし。
encoding-type	String	No	url	応答内のコンテンツのエンコーディングタイプ。デフォルト値: なし。有効な値: url 重要 delimiter、marker、prefix、NextMarker、および Key の値は UTF-8 でエンコードされます。delimiter、marker、prefix、NextMarker、または Key の値に XML 1.0 でサポートされていない制御文字が含まれている場合、encoding-type パラメーターを指定して、応答でこれらの値をエンコードできます。

応答要素

名前	タイプ	例	説明
ListBucketResult	Container	N/A	GetBucket リクエストの結果のコンテナー。子ノード: Name、Prefix、Marker、MaxKeys、Delimiter、IsTruncated、Nextmarker、Contents 親ノード: なし
Name	String	oss-example	バケット名。親ノード: ListBucketResult
Prefix	String	fun/	クエリ結果のプレフィックス。親ノード: ListBucketResult または CommonPrefixes
Marker	String	test1.txt	この GetBucket (ListObjects) 操作の開始位置。親ノード: ListBucketResult
MaxKeys	String	100	応答で返される結果の最大数。親ノード: ListBucketResult
Delimiter	String	/	オブジェクト名をグループ化するために使用される文字。プレフィックスから Delimiter 文字の最初の出現まで同じ文字列を含むすべてのオブジェクト名は、CommonPrefixes という名前の単一の要素としてグループ化されます。親ノード: ListBucketResult
EncodingType	String	url	返された結果に使用されるエンコーディングタイプ。リクエストで encoding-type パラメーターを指定した場合、応答の Delimiter、Marker、Prefix、NextMarker、および Key 要素がエンコードされます。親ノード: ListBucketResult
IsTruncated	Enumerated string	false	リクエストで返された結果が切り捨てられているかどうかを示します。有効な値: true および false true: すべての結果が返されるわけではありません。 false: すべての結果が返されます。親ノード: ListBucketResult
NextMarker	String	test100.txt	次のリストの開始位置。親ノード: ListBucketResult
Contents	Container	N/A	返された各オブジェクトのメタデータのコンテナー。親ノード: ListBucketResult
Key	String	fun/test.jpg	オブジェクトのキー。親ノード: ListBucketResult.Contents
TransitionTime	Time	2024-04-23T07:21:42.000Z	ライフサイクルルールに基づいて、オブジェクトがコールドアーカイブまたはディープコールドアーカイブストレージクラスに移行された時間。説明ストレージクラスが変換されてから 180 日を超えてコールドアーカイブまたはディープコールドアーカイブオブジェクトを削除した場合、早期削除料金は請求されません。変換から 180 日以内にオブジェクトを削除した場合、早期削除料金が請求されます。このヘッダーを使用して、ライフサイクルルールに基づいてオブジェクトのストレージクラスが低頻度アクセスまたはアーカイブに変換された時間をクエリすることはできません。オブジェクトが最小ストレージ期間を超えて保存されているかどうかは、`Last-Modified` 時間に基づいて判断できます。親ノード: ListBucketResult.Contents
SealedTime	Time	2020-05-21T12:07:15.000Z	オブジェクトに対してシール操作が実行された時間。説明このフィールドは、AppendObject 操作を使用して作成され、シールされた追加可能オブジェクトに対してのみ返されます。親ノード: ListBucketResult.Contents
LastModified	Time	2012-02-24T08:42:32.000Z	オブジェクトが最後に変更された日時。説明低頻度アクセス (IA) オブジェクトの最小ストレージ期間は 30 日で、オブジェクトの Last-Modified 時間から計算されます。最終変更から 30 日を超えて IA オブジェクトを削除した場合、早期削除料金は請求されません。アーカイブストレージオブジェクトの最小ストレージ期間は 60 日で、オブジェクトの Last-Modified 時間から計算されます。最終変更から 60 日を超えてアーカイブストレージオブジェクトを削除した場合、早期削除料金は請求されません。親ノード: ListBucketResult.Contents
ETag	String	5B3C1A2E053D763E1B002CC607C5A0FE1****	エンティティタグ (ETag)。ETag は、オブジェクトのコンテンツを識別するためにオブジェクトが作成されるときに作成されます。 PutObject リクエストによって作成されたオブジェクトの場合、ETag 値はオブジェクトコンテンツの MD5 ハッシュです。他のメソッドで作成されたオブジェクトの場合、ETag 値は特定のルールに基づいて計算された一意の値です。ETag 値はオブジェクトコンテンツの MD5 ハッシュではありません。 ETag 値は、オブジェクトのコンテンツが変更されたかどうかを確認するために使用できます。オブジェクトのデータ整合性を検証するために ETag 値を使用しないでください。親ノード: ListBucketResult.Contents
Type	String	Normal	オブジェクトのタイプ。有効な値: Normal: オブジェクトは単純なアップロードによって作成されます。 Multipart: オブジェクトはマルチパートアップロードによって作成されます。 Appendable: オブジェクトは追加アップロードによって作成されます。 Symlink: シンボリックリンクは PutSymlink 操作によって作成されます。
Size	String	344606	返されたオブジェクトのサイズ (バイト単位)。親ノード: ListBucketResult.Contents
StorageClass	String	Standard	オブジェクトのストレージクラス。親ノード: ListBucketResult.Contents
RestoreInfo	String	ongoing-request="true”	オブジェクトの解凍状態。 RestoreObject リクエストが送信されていないか、送信された RestoreObject リクエストが期限切れの場合、このフィールドは返されません。 RestoreObject リクエストが送信されたが、解凍操作が完了していない場合、RestoreInfo の値は `ongoing-request="true"` です。 RestoreObject リクエストが送信され、解凍操作が完了した場合、RestoreInfo の値は `ongoing-request="false", expiry-date="Thu, 24 Sep 2020 12:40:33 GMT"` です。`expiry-date` フィールドは、解凍されたオブジェクトの有効期限を示します。
Owner	Container	N/A	バケットのオーナーに関する情報のコンテナー。子ノード: DisplayName および ID 親ノード: ListBucketResult.Contents
ID	String	0022012****	バケットオーナーのユーザー ID。親ノード: ListBucketResult.Contents.Owner
DisplayName	String	user_example	オブジェクトオーナーの名前。親ノード: ListBucketResult.Contents.Owner
CommonPrefixes	Container	N/A	リクエストで Delimiter パラメーターを指定すると、応答に CommonPrefixes 要素が含まれます。この要素は、共通のプレフィックスを持ち、デリミタで終わるオブジェクト名のコレクションを示します。親ノード: ListBucketResult

x-oss-request-id や Content-Type などの他の共通レスポンスヘッダーの詳細については、「共通レスポンスヘッダー」をご参照ください。

例

単純なリクエスト

GET / HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

レスポンスの例

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Fri, 24 Feb 2012 08:43:27 GMT
Content-Type: application/xml
Content-Length: 1866
Connection: keep-alive
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”>
<Name>examplebucket</Name>
<Prefix></Prefix>
<Marker></Marker>
<MaxKeys>100</MaxKeys>
<Delimiter></Delimiter>
<IsTruncated>false</IsTruncated>
<Contents>
      <Key>fun/movie/001.avi</Key>
      <TransitionTime>2024-04-23T07:21:42.000Z</TransitionTime>
      <LastModified>2012-02-24T08:43:07.000Z</LastModified>
      <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
      <Type>Normal</Type>
      <Size>344606</Size>
      <StorageClass>Standard</StorageClass>
      <Owner>
          <ID>0022012****</ID>
          <DisplayName>user-example</DisplayName>
      </Owner>
</Contents>
<Contents>
      <Key>fun/movie/007.avi</Key>
      <LastModified>2012-02-24T08:43:27.000Z</LastModified>
      <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
      <Type>Normal</Type>
      <Size>344606</Size>
      <StorageClass>Standard</StorageClass>
      <Owner>
          <ID>0022012****</ID>
          <DisplayName>user-example</DisplayName>
      </Owner>
</Contents>
<Contents>
      <Key>fun/test.jpg</Key>
      <LastModified>2012-02-24T08:42:32.000Z</LastModified>
      <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
      <Type>Normal</Type>
      <Size>344606</Size>
      <StorageClass>Standard</StorageClass>
      <Owner>
          <ID>0022012****</ID>
          <DisplayName>user-example</DisplayName>
      </Owner>
</Contents>
<Contents>
      <Key>oss.jpg</Key>
      <LastModified>2012-02-24T06:07:48.000Z</LastModified>
      <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
      <Type>Normal</Type>
      <Size>344606</Size>
      <StorageClass>Standard</StorageClass>
      <Owner>
          <ID>0022012****</ID>
          <DisplayName>user-example</DisplayName>
      </Owner>
</Contents>
</ListBucketResult>

prefix パラメーターを含むリクエスト

GET /?prefix=fun HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

レスポンスの例

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Fri, 24 Feb 2012 08:43:27 GMT
Content-Type: application/xml
Content-Length: 1464
Connection: keep-alive
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”>
<Name>examplebucket</Name>
<Prefix>fun</Prefix>
<Marker></Marker>
<MaxKeys>100</MaxKeys>
<Delimiter></Delimiter>
<IsTruncated>false</IsTruncated>
<Contents>
      <Key>fun/movie/001.avi</Key>
      <LastModified>2012-02-24T08:43:07.000Z</LastModified>
      <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
      <Type>Normal</Type>
      <Size>344606</Size>
      <StorageClass>Standard</StorageClass>
      <Owner>
          <ID>0022012****</ID>
          <DisplayName>user_example</DisplayName>
      </Owner>
</Contents>
<Contents>
      <Key>fun/movie/007.avi</Key>
      <LastModified>2012-02-24T08:43:27.000Z</LastModified>
      <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
      <Type>Normal</Type>
      <Size>344606</Size>
      <StorageClass>Standard</StorageClass>
      <Owner>
          <ID>0022012****</ID>
          <DisplayName>user_example</DisplayName>
      </Owner>
</Contents>
<Contents>
      <Key>fun/test.jpg</Key>
      <LastModified>2012-02-24T08:42:32.000Z</LastModified>
      <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
      <Type>Normal</Type>
      <Size>344606</Size>
      <StorageClass>Standard</StorageClass>
      <Owner>
          <ID>0022012****</ID>
          <DisplayName>user_example</DisplayName>
      </Owner>
</Contents>
</ListBucketResult>

prefix および delimiter パラメーターを含むリクエスト

GET /?prefix=fun/&delimiter=/ HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

レスポンスの例

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Fri, 24 Feb 2012 08:43:27 GMT
Content-Type: application/xml
Content-Length: 712
Connection: keep-alive
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”>
<Name>examplebucket</Name>
<Prefix>fun/</Prefix>
<Marker></Marker>
<MaxKeys>100</MaxKeys>
<Delimiter>/</Delimiter>
<IsTruncated>false</IsTruncated>
<Contents>
      <Key>fun/test.jpg</Key>
      <LastModified>2012-02-24T08:42:32.000Z</LastModified>
      <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
      <Type>Normal</Type>
      <Size>344606</Size>
      <StorageClass>Standard</StorageClass>
      <Owner>
          <ID>0022012****</ID>
          <DisplayName>user_example</DisplayName>
      </Owner>
</Contents>
<CommonPrefixes>
      <Prefix>fun/movie/</Prefix>
</CommonPrefixes>
</ListBucketResult>

marker パラメーターを指定したページネーションリクエスト

この例では、max-keys は 2 に設定されており、最大 2 つのオブジェクトが返されることを示します。

GET /?max-keys=2&marker=test1.txt HTTP/1.1
Host: examplebucket.oss-cn-shenzhen.aliyuncs.com
Accept-Encoding: identity
Accept: */*
Connection: keep-alive
User-Agent: aliyun-sdk-python/2.11.0(Darwin/18.2.0/x86_64;3.4.1)
date: Tue, 26 May 2020 08:39:48 GMT
authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

レスポンスの例

応答の NextMarker 要素は、次のリクエストのマーカーとして使用できます。

HTTP/1.1 200 OK
Server: AliyunOSS
Date: Tue, 26 May 2020 08:39:48 GMT
Content-Type: application/xml
Content-Length: 1032
Connection: keep-alive
x-oss-request-id: 5ECCD5D4881816373582xxx
x-oss-server-time: 3

<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult>
  <Name>examplebucket</Name>
  <Prefix></Prefix>
  <Marker>test1.txt</Marker>
  <MaxKeys>2</MaxKeys>
  <Delimiter></Delimiter>
  <EncodingType>url</EncodingType>
  <IsTruncated>true</IsTruncated>
  <NextMarker>test100.txt</NextMarker>
  <Contents>
    <Key>test10.txt</Key>
    <LastModified>2020-05-26T07:50:18.000Z</LastModified>
    <ETag>"C4CA4238A0B923820DCC509A6F75****"</ETag>
    <Type>Normal</Type>
    <Size>1</Size>
    <StorageClass>Standard</StorageClass>
    <Owner>
      <ID>1305433xxx</ID>
      <DisplayName>1305433xxx</DisplayName>
    </Owner>
  </Contents>
  <Contents>
    <Key>test100.txt</Key>
    <LastModified>2020-05-26T07:50:20.000Z</LastModified>
    <ETag>"C4CA4238A0B923820DCC509A6F75****"</ETag>
    <Type>Normal</Type>
    <Size>1</Size>
    <StorageClass>Standard</StorageClass>
    <Owner>
      <ID>1305433xxx</ID>
      <DisplayName>1305433xxx</DisplayName>
    </Owner>
  </Contents>
</ListBucketResult>

アーカイブまたはコールドアーカイブオブジェクトを含むバケットへのリクエスト

examplebucket バケットに exampleobject1.txt、exampleobject2.txt、exampleobject3.txt オブジェクトが含まれていると仮定します。3 つのオブジェクトはすべてコールドアーカイブストレージクラスにあります。3 つのオブジェクトの状態は次のとおりです。

exampleobject1.txt の場合、RestoreObject リクエストが送信されていないか、送信された RestoreObject リクエストが期限切れです。
exampleobject2.txt の場合、RestoreObject リクエストが送信され、解凍操作が進行中です。
exampleobject3.txt の場合、RestoreObject リクエストが送信され、解凍操作が完了しています。

リクエストの例

GET / HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

レスポンスの例

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Date: Fri, 24 Feb 2012 08:43:27 GMT
Content-Type: application/xml
Content-Length: 1866
Connection: keep-alive
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”>
  <Name>examplebucket</Name>
  <Prefix></Prefix>
  <Marker></Marker>
  <MaxKeys></MaxKeys>
  <Delimiter></Delimiter>
  <IsTruncated>false</IsTruncated>
  <Contents>
        <Key>exampleobject1.txt</Key>
        <LastModified>2020-06-22T11:42:32.000Z</LastModified>
        <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
        <Type>Normal</Type>
        <Size>344606</Size>
        <StorageClass>ColdArchive</StorageClass>
        <Owner>
            <ID>0022012****</ID>
            <DisplayName>user-example</DisplayName>
        </Owner>
  </Contents>
  <Contents>
        <Key>exampleobject2.txt</Key>
        <LastModified>2020-06-22T11:42:32.000Z</LastModified>
        <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
        <Type>Normal</Type>
        <Size>344606</Size>
        <StorageClass>Standard</StorageClass>
        <RestoreInfo>ongoing-request="true"</RestoreInfo>
        <Owner>
            <ID>0022012****</ID>
            <DisplayName>user-example</DisplayName>
        </Owner>
  </Contents>
  <Contents>
        <Key>exampleobject3.txt</Key>
        <LastModified>2020-06-22T11:42:32.000Z</LastModified>
        <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
        <Type>Normal</Type>
        <Size>344606</Size>
        <StorageClass>Standard</StorageClass>
        <RestoreInfo>ongoing-request="false", expiry-date="Thu, 24 Sep 2020 12:40:33 GMT"</RestoreInfo>
        <Owner>
            <ID>0022012****</ID>
            <DisplayName>user-example</DisplayName>
        </Owner>
  </Contents>
</ListBucketResult>

SDK

次のプログラミング言語の SDK を使用して、この操作を呼び出すことができます:

ossutil コマンドラインツール

GetBucket 操作に対応する ossutil コマンドの詳細については、「list-objects (get-bucket)」をご参照ください。

エラーコード

エラーコード	HTTP ステータスコード	説明
NoSuchBucket	404	指定されたバケットが存在しません。バケット名が有効かどうかを確認してください。
AccessDenied	403	バケットにアクセスするために必要な権限がありません。バケットにアクセスできるのは、バケットのオーナーと `oss:ListObjects` 権限を付与されたユーザーのみです。
InvalidArgument	400	max-keys の値が 0 未満または 1,000 を超えています。 prefix、marker、または delimiter パラメーターの長さが無効です。