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

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

使用上の注意

バケット内のすべてのオブジェクトを一覧表示するには、oss:ListObjects権限が必要です。
ListObjectsV2 (GetBucketV2) 操作は、オブジェクトのユーザーメタデータを返しません。
ListObjectsV2 (GetBucketV2) 操作を呼び出すバケットに対してloggingまたはリアルタイムログクエリが有効になっている場合、呼び出しのアクセスログの操作フィールドの値はGetBucketです。
ListObjectsV2 (GetBucketV2) 操作を呼び出すと、PUTリクエストのAPI操作呼び出し料金が請求されます。詳細は、「PUTリクエスト」をご参照ください。
デフォルトでは、リクエストごとに一覧表示できるオブジェクトの最大数は100です。すべてのオブジェクトを一覧表示する場合は、NextContinuationTokenパラメーターとcontinuationTokenパラメーターの設定が必要です。

リクエスト構文

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	Boolean	不可	false	レスポンスにオブジェクト所有者に関する情報を含めるかどうかを指定します。有効な値：true と false true: 応答にはオブジェクト所有者情報が含まれます。 false: レスポンスにオブジェクト所有者情報が含まれていません。デフォルト値：false

レスポンスパラメーター

パラメーター	タイプ	例	説明
内容	コンテナー	非該当	返された各オブジェクトのメタデータを格納するコンテナー。親ノード: 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	返された結果が切り捨てられるかどうかを示します。有効な値：true と false trueは、今回すべての結果が返されないことを示します。 falseは、すべての結果が今回返されることを示します。親ノード: ListBucketResult
キー	String	fun/test.jpg	オブジェクト名親ノード: ListBucketResult.Contents
LastModified	時間	2012-02-24T08:42:32.000Z	オブジェクトの最後に変更された時刻。親ノード: ListBucketResult.Contents
ListBucketResult	コンテナー	非該当	ListObjectsV2 (GetBucketV2) リクエストの結果を格納するコンテナー。子ノード: Name、Prefix、StartAfter、MaxKeys、Delimiter、IsTruncated、NextContinuationToken、およびContents 親ノード: なし
StartAfter	String	test1.txt	リクエストでstart-afterパラメーターが指定されている場合、レスポンスにはStartAfterパラメーターが含まれます。
MaxKeys	String	100	レスポンスで返されるオブジェクトの最大数。親ノード: ListBucketResult
名前	String	examplebucket	バケットの名前です。親ノード: ListBucketResult
所有者	コンテナー	非該当	バケット所有者に関する情報を格納するコンテナー。子ノード: 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要素の値は`cending-request="true"` になります。 RestoreObject要求が送信され、復元が完了した場合、RestoreInfo要素の値は、`cending-request="false", expiry-date="Thu, 2020 Sep 24 12:40:33 GMT"` 形式になります。`expiry-date`要素は、復元されたオブジェクトを読み取ることができるまでの時間を示します。親ノード: 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.txt、exampleobject2.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の値の長さが無効です。