Object Storage Service ListObjectsV2 (GetBucketV2) API - Object Storage Service

ListObjectsV2 (GetBucketV2) 操作は、バケット内のオブジェクトに関する情報をリストします。

リクエスト構文

GET /?list-type=2 HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

注意事項

ListObjectsV2 (GetBucketV2) リクエストは、カスタムオブジェクトメタデータを返しません。デフォルトでは、1 回の応答で最大 100 個のオブジェクトが返されます。すべてのオブジェクトを取得するには、NextContinuationToken や continuationToken などのパラメーターを使用して、セグメント単位で取得する必要があります。

バケット内のすべてのオブジェクトをリストするには、oss:ListObjects 権限が必要です。
ロギングまたはリアルタイムログクエリを有効にすると、この操作で生成されるアクセスログの operation フィールドの値は GetBucket になります。
バケットでバージョン管理が有効になっている場合、上書きまたは誤った削除操作によって多くの削除マーカーと以前のバージョンが作成されます。ライフサイクルルールを設定して、削除マーカーと不要な以前のバージョンを定期的にクリーンアップし、リストパフォーマンスの低下を防ぐことを推奨します。
ListObjectsV2 (GetBucketV2) 操作の呼び出しは、PUT リクエストとして課金されます。詳細については、「PUT リクエスト」をご参照ください。

リクエストパラメーター

名前	タイプ	必須	例	説明
list-type	数値	はい	2	値は 2 に固定されています。
delimiter	文字列	いいえ	/	オブジェクト名をグループ化するための文字。指定されたプレフィックスを含み、デリミタが最初に現れる前にあるすべてのオブジェクト名は、1 つの要素 (CommonPrefixes) としてグループ化されます。デフォルト値：なし
start-after	文字列	いいえ	b	`start-after` の値のアルファベット順で次に来るオブジェクトからオブジェクトのリストを返すように指定します。このパラメーターはページネーションに使用されます。パラメーターの長さは 1024 バイト未満である必要があります。条件付きクエリの場合、`start-after` の値がリストに存在しなくても、応答は `start-after` の値のアルファベット順で次に来るオブジェクトから開始されます。デフォルト値：なし
continuation-token	文字列	いいえ	test1.txt	リスト操作を開始するトークンを指定します。このトークンは、以前の ListObjectsV2 (GetBucketV2) 操作の応答にある NextContinuationToken の値から取得できます。
max-keys	数値	いいえ	100	返すオブジェクトの最大数を指定します。値は 0 より大きく、1000 以下である必要があります。デフォルト値：100 `max-keys` の設定により、1 回の応答ですべてのオブジェクトをリストできない場合、応答には `NextContinuationToken` が含まれます。このトークンを次のリクエストの `continuation-token` として使用してください。返されるオブジェクトの数が、指定された `max-keys` の値に達することは保証されません。この場合、応答から `NextContinuationToken` を取得し、次のリクエストの `continuation-token` として使用してください。
prefix	文字列	いいえ	a	応答を、指定されたプレフィックスで始まるキーに限定します。 `prefix` をフォルダ名に設定すると、操作はそのフォルダ内のすべてのファイルとサブフォルダを再帰的にリストします。 `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/ フォルダが返されます。パラメーターの長さは 1024 バイト未満である必要があります。 `prefix` パラメーターはスラッシュ (/) で始めることはできません。 `prefix` パラメーターが空の場合、デフォルトでバケット内のすべてのオブジェクトがリストされます。 `prefix` を使用してクエリを実行する場合、返されるキーには引き続きプレフィックスが含まれます。デフォルト値：なし
encoding-type	文字列	いいえ	url	応答をエンコードし、エンコーディングタイプを指定します。デフォルト値：なし有効な値：url `delimiter`、`start-after`、`prefix`、`NextContinuationToken`、または `Key` に XML 1.0 でサポートされていない制御文字が含まれている場合、`encoding-type` パラメーターを指定して、応答でこれらの要素を URL エンコードできます。 `delimiter`、`start-after`、`prefix`、`NextContinuationToken`、および `Key` パラメーターは UTF-8 文字エンコーディングを使用します。
fetch-owner	ブール値	いいえ	false	応答にオーナー情報を含めるかどうかを指定します。有効な値：true、false true：応答にオーナー情報が含まれます。 false：応答にオーナー情報が含まれません。デフォルト値：false

応答パラメーター

名前	タイプ	例	説明
Contents	コンテナー	N/A	返された各オブジェクトのメタデータを格納するコンテナー。親ノード：ListBucketResult
CommonPrefixes	コンテナー	N/A	リクエストで Delimiter パラメーターが指定されている場合、応答には CommonPrefixes 要素が含まれます。この要素は、デリミタで終わり、共通のプレフィックスを共有するオブジェクト名のコレクションを示します。親ノード：ListBucketResult 子ノード：Prefix
Delimiter	文字列	/	オブジェクト名をグループ化するために使用される文字。指定されたプレフィックスを含み、デリミタが最初に現れる前にあるすべてのオブジェクト名は、CommonPrefixes 要素としてグループ化されます。親ノード：ListBucketResult
EncodingType	文字列	N/A	応答で使用されるエンコーディングタイプ。リクエストで `encoding-type` が指定されている場合、応答の `Delimiter`、`StartAfter`、`Prefix`、`NextContinuationToken`、および `Key` 要素はエンコードされます。親ノード：ListBucketResult
DisplayName	文字列	user_example	オブジェクト所有者の表示名。親ノード：ListBucketResult.Contents.Owner
ETag	文字列	5B3C1A2E053D763E1B002CC607C5A0FE1****	ETag はオブジェクトが生成されるときに作成され、オブジェクトのコンテンツを一意に識別します。親ノード：ListBucketResult.Contents PutObject リクエストによって作成されたオブジェクトの場合、ETag の値はそのコンテンツの MD5 ハッシュです。他の方法で作成されたオブジェクトの場合、ETag の値は特定の計算ルールに基づいて生成された一意の値ですが、そのコンテンツの MD5 ハッシュではありません。 ETag の値は、オブジェクトのコンテンツが変更されたかどうかを確認するために使用できます。データ整合性を確保するために、MD5 検証の基準として ETag の値を使用しないでください。
ID	文字列	0022012****	バケット所有者のユーザー ID。親ノード：ListBucketResult.Contents.Owner
IsTruncated	列挙文字列	false	返された結果が切り捨てられているかどうかを示します。戻り値：true、false true は、すべての結果が返されていないことを示します。 false は、すべての結果が返されていることを示します。親ノード：ListBucketResult
Key	文字列	fun/test.jpg	オブジェクトキーの名前。親ノード：ListBucketResult.Contents
LastModified	時間	2012-02-24T08:42:32.000Z	オブジェクトが最後に変更された時刻。親ノード：ListBucketResult.Contents
ListBucketResult	コンテナー	N/A	GetBucket リクエストの結果を格納するコンテナー。子ノード：Name、Prefix、StartAfter、MaxKeys、Delimiter、IsTruncated、NextContinuationToken、Contents 親ノード：なし
StartAfter	文字列	test1.txt	リクエストで StartAfter パラメーターが指定されている場合、応答には StartAfter 要素が含まれます。
MaxKeys	数値	100	応答で返される結果の最大数。親ノード：ListBucketResult
Name	文字列	examplebucket	バケットの名前。親ノード：ListBucketResult
Owner	コンテナー	N/A	バケット所有者の情報を格納するコンテナー。子ノード：DisplayName、ID 親ノード：ListBucketResult.Contents
Prefix	文字列	fun/	クエリ結果のプレフィックス。親ノード：ListBucketResult
Type	文字列	Normal	ファイルタイプ有効な値：Normal、Multipart、Appendable、および Symlink。親ノード：ListBucketResult.Contents
Size	数値	344606	オブジェクトのサイズ (バイト単位)。親ノード：ListBucketResult.Contents
StorageClass	文字列	Standard	オブジェクトのストレージクラス。親ノード：ListBucketResult.Contents
SealedTime	時間	2020-05-21T12:07:15.000Z	オブジェクトに対して Seal 操作が実行された時刻。このフィールドは、シール状態の追加可能オブジェクトにアクセスしたときに返されます。親ノード：ListBucketResult.Contents
ContinuationToken	文字列	test1.txt	リクエストで ContinuationToken パラメーターが指定されている場合、応答には ContinuationToken 要素が含まれます。親ノード：ListBucketResult
KeyCount	数値	6	このリクエストで返されるキーの数。 Delimiter パラメーターが指定されている場合、KeyCount は Key 要素と CommonPrefixes 要素の数の合計です。親ノード：ListBucketResult
NextContinuationToken	文字列	CgJiYw--	ListObjectsV2 (GetBucketV2) リクエストにさらに結果があることを示します。次の結果セットを取得するには、次のリクエストの ContinuationToken として NextContinuationToken の値を指定します。親ノード：ListBucketResult
RestoreInfo	文字列	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` フィールドは、解凍されたオブジェクトの有効期限を示します。親ノード：ListBucketResult.Contents

例

シンプルなリクエスト

リクエスト例

GET /?list-type=2 HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Thu, 17 Apr 2025 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: Thu, 17 Apr 2025 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>
    <MaxKeys>100</MaxKeys>
    <EncodingType>url</EncodingType>
    <IsTruncated>false</IsTruncated>
    <Contents>
        <Key>a</Key>
        <LastModified>2020-05-18T05:45:43.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>a/b</Key>
        <LastModified>2020-05-18T05:45:47.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>b</Key>
        <LastModified>2020-05-18T05:45:50.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>b/c</Key>
        <LastModified>2020-05-18T05:45:54.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>bc</Key>
        <LastModified>2020-05-18T05:45:59.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>c</Key>
        <LastModified>2020-05-18T05:45:57.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <KeyCount>6</KeyCount>
</ListBucketResult>

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

リクエスト例

GET /?list-type=2&prefix=a HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Thu, 17 Apr 2025 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: Thu, 17 Apr 2025 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>a</Prefix>
    <MaxKeys>100</MaxKeys>
    <EncodingType>url</EncodingType>
    <IsTruncated>false</IsTruncated>
    <Contents>
        <Key>a</Key>
        <LastModified>2020-05-18T05:45:43.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>a/b</Key>
        <LastModified>2020-05-18T05:45:47.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <KeyCount>2</KeyCount>
</ListBucketResult>

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

リクエスト例

GET /?list-type=2&prefix=a/&delimiter=/ HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Thu, 17 Apr 2025 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: Thu, 17 Apr 2025 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>a/</Prefix>
    <MaxKeys>100</MaxKeys>
    <Delimiter>/</Delimiter>
    <EncodingType>url</EncodingType>
    <IsTruncated>false</IsTruncated>
    <Contents>
        <Key>a/b</Key>
        <LastModified>2020-05-18T05:45:47.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <CommonPrefixes>
        <Prefix>a/b/</Prefix>
    </CommonPrefixes>
    <KeyCount>2</KeyCount>
</ListBucketResult>

start-after、max-keys、および fetch-owner パラメーターを含むリクエスト

リクエスト例

GET /?list-type=2&start-after=b&max-keys=3&fetch-owner=true HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Thu, 17 Apr 2025 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: Thu, 17 Apr 2025 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></Prefix>
    <StartAfter>b</StartAfter>
    <MaxKeys>3</MaxKeys>
    <EncodingType>url</EncodingType>
    <IsTruncated>true</IsTruncated>
    <NextContinuationToken>CgJiYw--</NextContinuationToken>
    <Contents>
        <Key>b/c</Key>
        <LastModified>2020-05-18T05:45:54.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
        <Owner>
            <ID>1686240967192623</ID>
            <DisplayName>1686240967192623</DisplayName>
        </Owner>
    </Contents>
    <Contents>
        <Key>ba</Key>
        <LastModified>2020-05-18T11:17:58.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
        <Owner>
            <ID>1686240967192623</ID>
            <DisplayName>1686240967192623</DisplayName>
        </Owner>
    </Contents>
    <Contents>
        <Key>bc</Key>
        <LastModified>2020-05-18T05:45:59.000Z</LastModified>
        <ETag>"35A27C2B9EAEEB6F48FD7FB5861D****"</ETag>
        <Size>25</Size>
        <StorageClass>STANDARD</StorageClass>
        <Owner>
            <ID>1686240967192623</ID>
            <DisplayName>1686240967192623</DisplayName>
        </Owner>
    </Contents>
    <KeyCount>3</KeyCount>
</ListBucketResult>

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

リクエスト例

GET /?list-type=2 HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Thu, 17 Apr 2025 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: Thu, 17 Apr 2025 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>
  <MaxKeys>100</MaxKeys>
  <EncodingType>url</EncodingType>
  <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>

以下にファイルの状態を説明します：

exampleobject1.txt の場合、RestoreObject リクエストが送信されていないか、期限切れになっています。
exampleobject2.txt の場合、RestoreObject リクエストは送信されましたが、解凍は完了していません。
exampleobject3.txt の場合、RestoreObject リクエストが送信され、解凍が完了しています。

エラーコード

エラーコード	HTTP ステータスコード	説明
NoSuchBucket	404	指定されたバケットが存在しません。リクエスト内のバケット名が命名規則に準拠しているか確認してください。
AccessDenied	403	バケットにアクセスする権限がありません。バケット所有者と `oss:ListObjects` 権限を付与されたユーザーのみがバケットにアクセスできます。
InvalidArgument	400	max-keys パラメーターの値が 0 未満または 1000 を超えています。 prefix、start-after、または delimiter パラメーターの長さが無効です。

統合方法

SDK
次の言語の SDK を使用して ListObjectsV2 操作を呼び出すことができます：
Java
Python V2
C
Go V2
Node.js
IOS
Android
Ruby
PHP V2
.NET
ossutil コマンドラインインターフェイス
ListObjectsV2 操作の ossutil コマンドについては、「list-objects-v2 (get-bucket-v2)」をご参照ください。