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

リクエスト構文

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

リクエスト要素

GetBucket (ListObject) リクエストを開始する際、prefix、marker、delimiter、max-keys を使用して、ListObject 操作から部分的な結果が返されるように範囲を指定することができます。

要素 必須 説明
delimiter String いいえ オブジェクト名をグループ化するための文字を指定します。指定したプレフィックスで始まり、最初の delimiter で終わる名前を持つオブジェクトは、要素のグループ (CommonPrefixes) として機能します。

デフォルト値:なし

marker String いいえ アルファベット順で marker 後の最初のエントリから結果が返されるように設定します。

デフォルト値:なし

max-keys String いいえ 1 つのリクエストに対して返される最大オブジェクト数を制限します。 max-keys の値は、1000 以下にする必要があります。

デフォルト値:100

max-keys で設定された制限により、一度にリスト操作を完了できない場合、 次回のリスト操作のマーカーとなる <NextMarker> がレスポンスに含まれます。

prefix String いいえ 指定したプレフィックスで始まるオブジェクトキーのみが返されるように制限します。prefix を使用してクエリから返されるキーには、指定したプレフィックスが含まれている点に注意してください。

デフォルト値:なし

encoding-type String いいえ 返される結果をエンコードし、エンコードタイプを指定します。パラメーター delimiter、marker、prefix、NextMarker、key は、UTF-8 文字を使用しますが、XML 1.0 標準では、特定の制御文字 (0 から 10 までの ASCII 値を含む文字など) の解析をサポートしていません。 返される結果の一部の要素に XML 1.0 標準でサポートされていない文字が含まれる場合、encoding-type を指定すると、delimiter、marker、prefix、NextMarker、key などの要素をエンコードすることができます。

デフォルト値:なし

オプションの値:url

XML 1.0 では、特定の制御文字 (0 から 10 までの ASCII 値を含む文字など) の解析をサポートしていません。 返される結果の一部の要素に XML 1.0 標準でサポートされていない文字が含まれる場合、encoding-type の値を設定すると、delimiter、marker、prefix、NextMarker、key などの要素をエンコードすることができます。

レスポンス要素

要素 説明
Contents Container 返されるすべてのオブジェクトメタを保存するコンテナー。

親ノード:ListBucketResult

CommonPrefixes String リクエストに delimiter パラメーターを指定した場合、 OSS から返されるレスポンスに CommonPrefixes 要素が含まれます。 この 要素は、末尾が delimiter で、 共通のプレフィックスを持つオブジェクトのセットを示します。

親ノード:ListBucketResult

Delimiter String オブジェクト名をグループ化する文字。指定したプレフィックスで始まり、最初の delimiter で終わる名前を持つオブジェクトは、要素のグループ (CommonPrefixes) として機能します。

親ノード:ListBucketResult

EncodingType String 返される結果のエンコードタイプ。リクエストに encoding-type が指定されている場合、返される結果の delimiter、marker、prefix、NextMarker、key がエンコードされます。

親ノード:ListBucketResult

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

親ノード:ListBucketResult.Contents.Owner

ETag String ETag (エンティティタグ) は、オブジェクトの生成時に作成され、オブジェクトのコンテンツを示すために使用されます。

親ノード:ListBucketResult.Contents

PutObject リクエストで作成されたオブジェクトの場合、ETag の値はオブジェクトのコンテンツ内の MD5 の値です。 その他の方法で作成されたオブジェクトの場合、ETag の値はオブジェクトのコンテンツ内の UUID です。この ETag の値を使用して、オブジェクトのコンテンツが変更されているかどうかをチェックできます。 データの整合性を検証するため、ETag をオブジェクトコンテンツの MD5 値として使用することを推奨します。

ID String バケット所有者のユーザー ID。

親ノード: ListBucketResult.Contents.Owner

IsTruncated Enumerated string すべての結果が返されているかどうかを示します。
有効な値: truefalse
  • true は、リクエストに対して一部の結果が返されていません。
  • false は、リクエストに対してすべての結果が返されています。

親ノード:ListBucketResult

Key String オブジェクトのキー。

親ノード:ListBucketResult.Contents

Lastmodified Time オブジェクトの最終変更時刻。

親ノード:ListBucketResult.Contents

ListBucketResult Container GetBucket (ListObject) リクエストの結果を保存するコンテナー。

サブノード:Name、Prefix、Marker、MaxKeys、Delimiter、IsTruncated、Nextmarker、Contents

親ノード:なし

Marker String 現在の GetBucket (ListObject) 操作の開始位置を示します。

親ノード:ListBucketResult

MaxKeys String リクエストに対するレスポンスとして返される結果の最大数。

親ノード:ListBucketResult

Name String バケット名。

親ノード:ListBucketResult

Owner Container バケット所有者の情報を保存するコンテナー。

サブノード:DisplayName と ID

親ノード:ListBucketResult

Prefix String リクエストに対して返される結果のプレフィックス。

親ノード:ListBucketResult

Size String オブジェクトのバイト数。

親ノード:ListBucketResult.Contents

StorageClass String オブジェクトのストレージクラス。 標準ストレージクラスのみがサポートされます。

親ノード:ListBucketResult.Contents

詳細分析

  • GetBucket リクエストでは、オブジェクト内のカスタムメタは返されません。
  • アクセスするバケットが存在しない場合、 404 Not Found エラーがエラーコード NoSuchBucket と共に返されます。
  • バケットにアクセスする権限がない場合、403 Forbidden エラーがエラーコード AccessDenied と共に返されます。
  • 条件付きクエリでは、リストに marker が存在しない場合でも、結果はアルファベット順で marker の次の文字から表示されます。max-keys の値が 0 より小さいか 1000 より大きい場合、 400 Bad Request エラーがエラーコード InvalidArgument と共に返されます。
  • パラメーター Prefix、Marker、Delimiter の長さが要件を満たさない場合、400 Bad Request エラーがエラーコード InvalidArgument と共に返されます。
  • パラメーター Prefix と Marker は、ページ単位で結果を表示する場合に使用します。パラメーター長は、1024 バイト未満でなければなりません。
  • Prefix の値をディレクトリ名に設定すると、そのプレフィックスを持つすべてのオブジェクト、つまりディレクトリ内のすべてのオブジェクトとサブディレクトリをリストできます。

    Prefix を設定し、Delimiter を "/" に設定すると、ディレクトリ内のオブジェクトのみが返されます。 ディレクトリ内のサブディレクトリは、CommonPrefixs で返されます。 サブディレクトリ内のすべてのオブジェクトとディレクトリが表示されるわけではありません。

    たとえば、fun/test.jpg、fun/movie/001.avi、fun/movie/007.avi という 3 つのオブジェクトがバケットに保存されているとします。 Prefix が "fun/" に設定されている場合、3 つのオブジェクトがすべて返されます。 さらに delimiter が "/" に設定されている場合、“fun/test.jpg” と “fun/movie/“ が返されます。

単純なリクエスト例

GET / HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:BC+oQIXVR2/ZghT7cGa0ykboO4M=

レスポンス例

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906008B
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>oss-example</Name>
<Prefix></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>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</ETag>
        <Type>Normal</Type>
        <Size>344606</Size>
        <StorageClass>Standard</StorageClass>
        <Owner>
            <ID>00220120222</ID>
            <DisplayName>user-example</DisplayName>
        </Owner>
    </Contents>
    <Contents>
        <Key>fun/movie/007.avi</Key>
        <LastModified>2012-02-24T08:43:27.000Z</LastModified>
        <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</ETag>
        <Type>Normal</Type>
        <Size>344606</Size>
        <StorageClass>Standard</StorageClass>
        <Owner>
            <ID>00220120222</ID>
            <DisplayName>user-example</DisplayName>
        </Owner>
    </Contents>
<Contents>
        <Key>fun/test.jpg</Key>
        <LastModified>2012-02-24T08:42:32.000Z</LastModified>
        <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</ETag>
        <Type>Normal</Type>
        <Size>344606</Size>
        <StorageClass>Standard</StorageClass>
        <Owner>
            <ID>00220120222</ID>
            <DisplayName>user-example</DisplayName>
        </Owner>
    </Contents>
    <Contents>
        <Key>oss.jpg</Key>
        <LastModified>2012-02-24T06:07:48.000Z</LastModified>
        <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</ETag>
        <Type>Normal</Type>
        <Size>344606</Size>
        <StorageClass>Standard</StorageClass>
        <Owner>
            <ID>00220120222</ID>
            <DisplayName>user-example</DisplayName>
        </Owner>
    </Contents>
</ListBucketResult>

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

GET /? prefix=fun HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:BC+oQIXVR2/ZghT7cGa0ykboO4M=

レスポンス例

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906008B
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>oss-example</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>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</ETag>
        <Type>Normal</Type>
        <Size>344606</Size>
        <StorageClass>Standard</StorageClass>
        <Owner>
            <ID>00220120222</ID>
            <DisplayName>user_example</DisplayName>
        </Owner>
    </Contents>
    <Contents>
        <Key>fun/movie/007.avi</Key>
        <LastModified>2012-02-24T08:43:27.000Z</LastModified>
        <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</ETag>
        <Type>Normal</Type>
        <Size>344606</Size>
        <StorageClass>Standard</StorageClass>
        <Owner>
            <ID>00220120222</ID>
            <DisplayName>user_example</DisplayName>
        </Owner>
    </Contents>
    <Contents>
        <Key>fun/test.jpg</Key>
        <LastModified>2012-02-24T08:42:32.000Z</LastModified>
        <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</ETag>
        <Type>Normal</Type>
        <Size>344606</Size>
        <StorageClass>Standard</StorageClass>
        <Owner>
            <ID>00220120222</ID>
            <DisplayName>user_example</DisplayName>
        </Owner>
    </Contents>
</ListBucketResult>

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

GET /? prefix=fun/&delimiter=/ HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:DNrnx7xHk3sgysx7I8U9I9IY1vY=

レスポンス例

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906008B
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>oss-example</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>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</ETag>
        <Type>Normal</Type>
        <Size>344606</Size>
        <StorageClass>Standard</StorageClass>
        <Owner>
            <ID>00220120222</ID>
            <DisplayName>user_example</DisplayName>
        </Owner>
    </Contents>
   <CommonPrefixes>
        <Prefix>fun/movie/</Prefix>
   </CommonPrefixes>
</ListBucketResult>