すべてのプロダクト
Search
ドキュメントセンター

Object Storage Service:GetBucketV2操作を呼び出してバケットを一覧表示する

最終更新日:Sep 23, 2024

バケット内のすべてのオブジェクトを一覧表示します。

使用上の注意

  • バケット内のすべてのオブジェクトを一覧表示するには、oss:ListObjects権限が必要です。

  • ListObjectsV2 (GetBucketV2) 操作は、オブジェクトのユーザーメタデータを返しません。

  • ListObjectsV2 (GetBucketV2) 操作を呼び出すバケットに対してloggingまたはリアルタイムログクエリが有効になっている場合、呼び出しのアクセスログの操作フィールドの値はGetBucketです。

  • ListObjectsV2 (GetBucketV2) 操作を呼び出すと、PUTリクエストのAPI操作呼び出し料金が請求されます。 詳細は、「PUTリクエスト」をご参照ください。

リクエスト構文

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

リクエストパラメーター

パラメーター

データ型

必須

説明

list-type

Numeric

課金されます

2

ListObjectsV2 (GetBucketV2) 操作のバージョン。 値を 2 に設定します。

区切り文字

String

課金されません

/

オブジェクトを名前でグループ化するために使用する文字。 リクエストで区切り文字パラメーターを指定した場合、レスポンスにはCommonPrefixesパラメーターが含まれます。 プレフィックスから次の区切り文字までの同じ文字列を名前に含むオブジェクトは、CommonPrefixesパラメーターで単一の結果要素としてグループ化されます。

デフォルトでは、このパラメータは空のままです。

start-after

String

課金されません

b

リスト操作の開始元となるオブジェクトの名前。 このパラメーターを指定すると、start-afterパラメーターの値のアルファベット順の後に名前が表示されるオブジェクトが返されます。

start-afterパラメーターは、返されたオブジェクトをページごとに一覧表示するために使用されます。 パラメーターの値は、長さが1,024バイト未満である必要があります。

指定されたstart-after値が条件付きクエリ中に存在しない場合でも、ListObjectsV2 (GetBucketV2) 操作は、名前がstart-after値の後のアルファベット順のオブジェクトから開始します。

デフォルトでは、このパラメータは空のままです。

continuation-token

String

課金されません

test1.txt

ListObjectsV2 (GetBucketV2) 操作の開始元となるトークン。 ListObjectsV2 (GetBucketV2) 操作への応答で、NextContinuationTokenパラメーターからトークンを取得できます。

max-keys

String

課金されません

100

返されるオブジェクトの最大数。

有効な値: 1 ~ 1000

デフォルト値:100

説明
  • オブジェクトの数がmax-keysパラメーターの値を超える場合、次のリスト操作の継続トークンとしてNextContinuationTokenパラメーターが含まれます。

  • 返されるオブジェクトの数は、max-keysの値よりも少ない場合があります。 この場合、すべてのオブジェクトがリストされていない場合は、次のリスト操作の継続トークンとしてNextContinuationToken応答パラメーターの値を使用する必要があります。

プレフィックス

String

課金されません

a

返されるオブジェクトの名前に含める必要があるプレフィックス。

prefixがリクエスト内のディレクトリ名に設定されている場合、ディレクトリ内のすべてのオブジェクトとサブディレクトリを含む、このプレフィックスを名前が含むオブジェクトが一覧表示されます。

prefixが指定され、delimiterがスラッシュ (/) に設定されている場合、ディレクトリ内のオブジェクトのみが一覧表示されます。 ディレクトリ内のサブディレクトリの名前は、CommonPrefixesパラメーターで返されます。 ただし、サブディレクトリ内のオブジェクトおよびディレクトリはリストされません。

たとえば、バケットにはfun/test.jpg、fun/movie/001.avi、fun/movie/007.aviのオブジェクトが含まれています。 prefixがfun /に設定されている場合、3つのオブジェクトが返されます。 prefixがfun /に設定され、delimiterがスラッシュ (/) に設定されている場合、fun/test.jpgとfun/movie /が返されます。

説明
  • プレフィックスの値は1,024バイト未満である必要があります。

  • prefixパラメーターの値は、スラッシュ (/) で始めることはできません。 prefixパラメーターを空のままにすると、バケット内のすべてのオブジェクトが一覧表示されます。

  • プレフィックスを指定した場合、返されるオブジェクトの名前にはプレフィックスが含まれます。

デフォルトでは、このパラメータは空のままです。

encoding-type

String

課金されません

url

レスポンス内のコンテンツのエンコードタイプ。

デフォルトでは、このパラメータは空のままです。

有効値: url

説明

デリミタ、start-after、プレフィックス、NextContinuationToken、およびKeyの値は、UTF-8でエンコードされます。 区切り文字、start-after、プレフィックス、NextContinuationToken、またはKey値に、XML 1.0標準でサポートされていない制御文字が含まれている場合は、encoding-typeを指定して、レスポンス内の値をエンコードできます。

fetch-owner

ブール値

課金されません

false

レスポンスにオブジェクト所有者に関する情報を含めるかどうかを指定します。

有効な値:truefalse

  • true: 応答にはオブジェクト所有者情報が含まれます。

  • false: レスポンスにオブジェクト所有者情報が含まれていません。

デフォルト値:false

レスポンスパラメーター

パラメーター

データ型

説明

内容

Container

非該当

返された各オブジェクトのメタデータを格納するコンテナー。

親ノード: ListBucketResult

CommonPrefixes

String

非該当

デリミタパラメーターがリクエストで指定されている場合、レスポンスにはCommonPrefixesパラメーターが含まれます。 プレフィックスから次の区切り文字までの同じ文字列を名前に含むオブジェクトは、CommonPrefixesパラメーターで単一の結果要素としてグループ化されます。

親ノード: ListBucketResult

子ノード: プレフィックス

デリミタ

String

/

オブジェクトを名前でグループ化するために使用される文字。 プレフィックスから次の区切り文字までの同じ文字列を名前に含むオブジェクトは、CommonPrefixesパラメーターで単一の結果要素としてグループ化されます。

親ノード: ListBucketResult

EncodingType

String

非該当

レスポンス内のコンテンツのエンコードタイプ。 リクエストでencoding-typeを指定した場合、Delimiter、StartAfter、Prefix、NextContinuationToken、およびKeyの値がレスポンスでエンコードされます。

親ノード: ListBucketResult

DisplayName

String

user_example

オブジェクト所有者の名前。

親ノード: ListBucketResult、Contents、およびOwner

ETag

String

5B3C1A2E053D763E1B002CC607C5A0FE1 ****

エンティティタグ (ETag) 。 オブジェクトが作成されると、オブジェクトのコンテンツを識別するためにETagが作成されます。

親ノード: ListBucketResult.Contents

  • PutObject操作を呼び出して作成されたオブジェクトの場合、オブジェクトのETag値はオブジェクトコンテンツのMD5ハッシュになります。

  • 別のメソッドを使用して作成されたオブジェクトの場合、ETag値はオブジェクトコンテンツのMD5ハッシュではなく、特定のルールに基づいて計算された一意の値です。

  • オブジェクトのETagを使用して、オブジェクトの内容が変更されているかどうかを確認できます。 データの整合性を検証するには、オブジェクトのETag値ではなく、オブジェクトのMD5ハッシュを使用することをお勧めします。

ID

String

0022012 ****

バケット所有者のID。

親ノード: ListBucketResult、Contents、およびOwner

IsTruncated

Enumerated string

false

返された結果が切り捨てられるかどうかを示します。

有効な値:truefalse

  • trueは、今回すべての結果が返されないことを示します。

  • falseは、すべての結果が今回返されることを示します。

親ノード: ListBucketResult

キー

String

fun/test.jpg

オブジェクト名

親ノード: ListBucketResult.Contents

LastModified

時間

2012-02-24T08:42:32.000Z

オブジェクトの最後に変更された時刻。

親ノード: ListBucketResult.Contents

ListBucketResult

Container

非該当

ListObjectsV2 (GetBucketV2) リクエストの結果を格納するコンテナー。

子ノード: Name、Prefix、StartAfter、MaxKeys、Delimiter、IsTruncated、NextContinuationToken、およびContents

親ノード: なし

StartAfter

String

test1.txt

リクエストでstart-afterパラメーターが指定されている場合、レスポンスにはStartAfterパラメーターが含まれます。

MaxKeys

String

100

レスポンスで返されるオブジェクトの最大数。

親ノード: ListBucketResult

名前

String

examplebucket

バケットの名前です。

親ノード: ListBucketResult

所有者

Container

非該当

バケット所有者に関する情報を格納するコンテナー。

子ノード: DisplayNameとID

親ノード: ListBucketResult.Contents

プレフィックス

String

楽しい /

返されるオブジェクト名に含まれるプレフィックス。

親ノード: ListBucketResult

データ型

String

正常

オブジェクトのタイプです。

有効な値: Normal、Multipart、Appendable、およびSymlink。

親ノード: ListBucketResult.Contents

サイズ

String

344606

返されるオブジェクトのサイズ。 単位:バイト

親ノード: ListBucketResult.Contents

StorageClass

String

標準

オブジェクトのストレージクラス。

親ノード: ListBucketResult.Contents

ContinuationToken

String

test1.txt

リクエストでcontinuation-tokenパラメーターが指定されている場合、レスポンスにはContinuationTokenパラメーターが含まれます。

親ノード: ListBucketResult

KeyCount

Numeric

6

このリクエストに対して返されるオブジェクト名の数。 区切り文字が指定されている場合、KeyCountはKeyとCommonPrefixesの値の合計です。

親ノード: ListBucketResult

NextContinuationToken

String

CgJiYw-

次のListObjectsV2 (GetBucketV2) 操作の開始元となるオブジェクトの名前。 NextContinuationTokenパラメーターの値は、後続の結果のクエリに使用されます。

親ノード: ListBucketResult

RestoreInfo

String

継続的-リクエスト="true"

オブジェクトの復元ステータス。

  • RestoreObjectリクエストが送信されなかった場合、またはリクエストの有効期限が切れた場合、このフィールドはレスポンスに含まれません。

  • RestoreObjectリクエストが送信されても復元が完了していない場合、RestoreInfoパラメーターの値はcendoing-request="true" です。

  • RestoreObjectリクエストが送信され、復元が完了した場合、RestoreInfoパラメーターの値は、cending-request="false", expiry-date="Thu, 24 Sep 2020 12:40:33 GMT" の形式になります。 有効期限フィールドは、復元されたオブジェクトを読み取ることができる時間を示します。

親ノード: ListBucketResult.Contents

  • 単純なListObjects (GetBucket) 操作のサンプルリクエスト

    GET /?list-type=2 HTTP/1.1
    Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
    Date: Fri, 24 Feb 2012 08:43:27 GMT
    Authorization: OSS qn6q**************:77Dv****************

    通常のレスポンス例

    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: Fri, 24 Feb 2012 08:43:27 GMT
    Authorization: OSS qn6q**************:77Dv****************

    通常のレスポンス例

    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>
  • プレフィックスおよび区切り文字パラメーターを指定したサンプルリクエスト

    GET /?list-type=2&prefix=a/&delimiter=/ HTTP/1.1
    Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
    Date: Fri, 24 Feb 2012 08:43:27 GMT
    Authorization: OSS qn6q**************:77Dv****************

    通常のレスポンス例

    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: Fri, 24 Feb 2012 08:43:27 GMT
    Authorization: OSS qn6q**************:77Dv****************

    通常のレスポンス例

    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.txtexampleobject2.txt、およびexampleobject3.txtのコールドアーカイブオブジェクトが含まれています。 3つのオブジェクトの状態は次のとおりです。

    • exampleobject1.txtを復元するRestoreObjectリクエストが送信されないか、オブジェクトを復元するために送信されたRestoreObjectリクエストが期限切れになります。

    • RestoreObjectリクエストがexampleobject2.txtを復元するために送信され、オブジェクトが復元されます。

    • RestoreObjectリクエストがexampleobject3.txtを復元するために送信され、オブジェクトが復元されます。

    リクエストの例

    GET / HTTP/1.1
    Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
    Date: Fri, 24 Feb 2012 08:43:27 GMT
    Authorization: OSS qn6q**************:77Dv****************

    通常のレスポンス例

    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>

エラーコード

HTTPステータスコード

説明

NoSuchBucket

404

要求されたバケットが存在しません。 要求されたバケットの名前が命名規則に準拠しているかどうかを確認します。

AccessDenied

403

バケットにアクセスする権限がありません。 バケットにアクセスできるのは、oss:ListObjects権限が付与されたバケット所有者とRAMユーザーだけです。

InvalidArgument

400

  • max-keysの値は0より小さいか、または1,000より大きい。

  • prefix、marker、またはdelimiterの値の長さが無効です。