ListObjectsV2 (GetBucketV2) 操作は、バケット内のオブジェクトをリストします。
使用上の注意
バケット内のすべてのオブジェクトをリストするには、
oss:ListObjects権限が必要です。ListObjectsV2 (GetBucketV2) リクエストは、カスタムオブジェクトのメタデータを返しません。
ロギングまたはリアルタイムログクエリを有効にすると、この操作で生成されるアクセスログの operation フィールドの値は
GetBucketになります。ListObjectsV2 (GetBucketV2) 操作の呼び出しは、PUT リクエストとして課金されます。 詳細については、「PUT リクエスト」をご参照ください。
デフォルトでは、1 回の応答で最大 100 個のオブジェクトが返されます。 すべてのオブジェクトを取得するには、`NextContinuationToken` や `continuationToken` などのパラメーターを使用して、セグメント単位で取得する必要があります。
バケットでバージョン管理が有効になっている場合、上書きまたは誤った削除操作により、多くの削除マーカーと以前のバージョンが作成されます。 リストのパフォーマンス低下を防ぐために、ライフサイクルルールを設定して、削除マーカーと不要な以前のバージョンを定期的にクリーンアップします。
リクエスト構文
GET /?list-type=2 HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValueリクエストパラメーター
名前 | タイプ | 必須 | 例 | 説明 |
list-type | 数値 | はい | 2 | 値は 2 のみです。 |
delimiter | 文字列 | いいえ | / | オブジェクト名をグループ化するための文字。 指定されたプレフィックスを含み、デリミタが最初に現れる前にあるすべてのオブジェクト名は、要素 (CommonPrefixes) としてグループ化されます。 デフォルト値: なし |
start-after | 文字列 | いいえ | b | オブジェクトのリストが、`start-after` の値のアルファベット順で次に来るオブジェクトから返されるように指定します。 `start-after` はページネーションに使用されます。 パラメーターの長さは 1024 バイト未満である必要があります。 条件付きのクエリの場合、`start-after` の値がリストに存在しなくても、応答は `start-after` の値のアルファベット順で次に来るオブジェクトから開始されます。 デフォルト値: なし |
continuation-token | 文字列 | いいえ | test1.txt | リスト操作がこのトークンから開始されるように指定します。 このトークンは、ListObjectsV2 (GetBucketV2) 操作の応答の `NextContinuationToken` の値から取得できます。 |
max-keys | 文字列 | いいえ | 100 | 返すオブジェクトの最大数を指定します。 値: 1 から 1000 までの整数 デフォルト値: 100 説明
|
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/` が返されます。 説明
デフォルト値: なし |
encoding-type | 文字列 | いいえ | url | 応答をエンコードし、エンコーディングタイプを指定します。 デフォルト値: なし 有効な値: url 説明 `delimiter`、`start-after`、`prefix`、`NextContinuationToken`、および `Key` は UTF-8 文字を使用します。 これらのパラメーターに XML 1.0 でサポートされていない制御文字が含まれている場合、`encoding-type` を指定して、応答内の `delimiter`、`start-after`、`prefix`、`NextContinuationToken`、および `Key` 要素をエンコードできます。 |
fetch-owner | ブール値 | いいえ | 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
|
ID | 文字列 | 0022012**** | バケットオーナーのユーザー ID。 親ノード: ListBucketResult.Contents.Owner |
IsTruncated | 列挙文字列 | 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 操作が実行された時刻。 このフィールドは、Sealed 状態の Appendable Object にアクセスしたときに返されます。 親ノード: ListBucketResult.Contents |
ContinuationToken | 文字列 | test1.txt | リクエストで `ContinuationToken` パラメーターが指定されている場合、応答には `ContinuationToken` 要素が含まれます。 親ノード: ListBucketResult |
KeyCount | 数値 | 6 | このリクエストで返されたキーの数。 `Delimiter` が指定されている場合、`KeyCount` は `Key` 要素と `CommonPrefixes` 要素の数の合計です。 親ノード: ListBucketResult |
NextContinuationToken | 文字列 | CgJiYw-- | ListObjectsV2 (GetBucketV2) リクエストにさらに結果があることを示します。 次の結果セットを取得するには、`NextContinuationToken` を `ContinuationToken` として指定します。 親ノード: ListBucketResult |
RestoreInfo | 文字列 | ongoing-request="true" | オブジェクトの解凍状態。
親ノード: 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: 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> <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: 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>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>
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>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: 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>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>
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>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: 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></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>アーカイブまたはコールドアーカイブオブジェクトを含むバケットへのリクエスト
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 コマンドラインインターフェイス
ListObjectsV2 操作の ossutil コマンドの詳細については、「list-objects-v2 (get-bucket-v2)」をご参照ください。
エラーコード | HTTP ステータスコード | 説明 |
NoSuchBucket | 404 | 指定されたバケットは存在しません。 バケット名が有効かどうかを確認してください。 |
AccessDenied | 403 | バケットにアクセスするために必要な権限がありません。 バケットにアクセスできるのは、バケットのオーナーと |
InvalidArgument | 400 |
|