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

Object Storage Service:GetBucket (ListObjects)

最終更新日:Oct 30, 2024

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

使用上の注意

  • GetBucket (ListObjects) 操作は、GetBucketV2 (ListObjectsV2) に更新されます。 アプリケーションを開発するときは、GetBucketV2 (ListObjectsV2) 操作を呼び出すことを推奨します。 下位互換性を提供するために、OSSは引き続きGetBucket (ListObjects) 操作をサポートします。 GetBucketV2 (ListObjectsV2) の詳細については、「ListObjectsV2 (GetBucketV2) 」をご参照ください。

  • オブジェクトのユーザーメタデータは、GetBucket (ListObjects) リクエストに対して返されません。

  • GetBucket (ListObjects) 操作は、バケットに対して実行されます。 バケットのストレージクラスに基づいて、PUTリクエストに対して課金されます。 GetBucket (ListObjects) 操作を呼び出すたびに、API呼び出し料金が課金されます。 詳細については、「API操作呼び出し料金」をご参照ください。

リクエスト構文

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

リクエストヘッダー

GetBucket (ListObjects) リクエストには、[権限付与][ホスト] などの共通リクエストヘッダーのみが含まれます。 詳細については、「共通リクエストヘッダー」をご参照ください。

リクエストパラメーター

パラメーター

タイプ

必須

説明

区切り文字

String

任意

/

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

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

マーカー

String

任意

test1.txt

ListObjects (GetBucket) 操作が開始されるオブジェクトの名前。 このパラメーターを指定すると、マーカーの後に名前がアルファベット順になっているオブジェクトが返されます。

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

条件付きクエリ中に指定されたマーカーがリストに存在しない場合でも、リストは、名前がmarkerパラメーターの値の後にアルファベット順にあるオブジェクトから開始されます。

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

max-keys

String

任意

200

返されるオブジェクトの最大数。 max-keysパラメーターの設定によりリスト操作を一度に完了できない場合、NextMarkerパラメーターが次のリスト操作のマーカーとして応答に含まれます。

有効な値: 1 ~ 1000

デフォルト値:100

プレフィックス

String

任意

楽しい

一覧表示するオブジェクトの名前のプレフィックス。

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

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

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 /が返されます。

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

encoding-type

String

任意

URL

レスポンス内のオブジェクト名のエンコードタイプ。

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

有効値: URL

重要

delimiter、marker、prefix、NextMarker、およびKeyの値はUTF-8エンコードされます。 delimiter、marker、prefix、NextMarker、またはKeyの値に、XML 1.0標準でサポートされていないコントロール文字が含まれている場合は、encoding-typeパラメーターを指定して、レスポンスの値をエンコードできます。

レスポンス要素

要素

タイプ

説明

ListBucketResult

Container

非該当

GetBucket (ListObjects) 操作に対する応答を格納するコンテナー。

子ノード: Name、Prefix、Marker、MaxKeys、Delimiter、IsTruncated、NextMarker、およびContents

親ノード:なし

名前

String

oss-example

バケットの名前です。

親ノード: ListBucketResult

プレフィックス

String

楽しい /

返されるバケットの名前に含まれるプレフィックス。

親ノード: ListBucketResultまたはCommonPrefixes

Marker

String

test1.txt

リスト操作が開始されるオブジェクトの名前。

親ノード: ListBucketResult

MaxKeys

String

100

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

親ノード: ListBucketResult

デリミタ

String

/

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

親ノード: ListBucketResult

EncodingType

String

url

レスポンス内のオブジェクト名のエンコードタイプ。 リクエストでencoding-typeパラメーターを指定すると、レスポンス内のDelimiter、Marker、Prefix、NextMarker、およびKeyのパラメーターがエンコードされます。

親ノード: ListBucketResult

IsTruncated

Enumerated string

false

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

有効な値:truefalse

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

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

親ノード: ListBucketResult

NextMarker

String

test100.txt

次のリスト操作が開始される位置。

親ノード: ListBucketResult

内容

Container

非該当

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

親ノード: ListBucketResult

キー

String

fun/test.jpg

オブジェクトのキー。The key of the object.

親ノード: ListBucketResult.Contents

TransitionTime

時間

2024-04-23T07:21:42.000Z

ライフサイクルルールに基づいて、オブジェクトのストレージクラスがコールドアーカイブまたはディープコールドアーカイブに変換された時刻。

説明
  • オブジェクトのストレージクラスが変換されてから180日を超えてオブジェクトが保存された場合、最小保存期間未満で保存されたコールドアーカイブまたはディープコールドアーカイブオブジェクトのストレージ使用量に対しては課金されません。 オブジェクトのストレージクラスが変換されてから180日以内にオブジェクトが保存された場合、最小保存期間未満で保存されたコールドアーカイブまたはディープコールドアーカイブオブジェクトのストレージ使用量に対して課金されます。

  • このヘッダーを使用して、ライフサイクルルールに基づいてオブジェクトのストレージクラスが低頻度アクセス (IA) またはアーカイブに変換された時刻を照会することはできません。 Last-Modifiedヘッダーの値に基づいて、オブジェクトが最小保存期間を超えて保存されているかどうかを判断できます。

親ノード: ListBucketResult.Contents

LastModified

時間

2012-02-24T08:42:32.000Z

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

説明
  • IAオブジェクトの最小保存期間 (30日) は、オブジェクトの最後に変更された時刻に基づいて計算されます。 Last-Modifiedヘッダーの値が現在の時刻より30日前の場合、最小保存期間未満で保存されたIAオブジェクトのストレージ使用量に対しては課金されません。

  • アーカイブオブジェクトの最小保存期間 (60日) は、オブジェクトの最終変更時刻に基づいて計算されます。 Last-Modifiedヘッダーの値が現在の時刻より60日前の場合、最小保存期間未満で保存されたアーカイブオブジェクトのストレージ使用量に対しては課金されません。

親ノード: ListBucketResult.Contents

ETag

String

5B3C1A2E053D763E1B002CC607C5A0FE1 ****

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

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

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

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

親ノード: ListBucketResult.Contents

タイプ

String

正常

オブジェクトのタイプです。 有効な値:

  • Normal: オブジェクトはシンプルアップロードを使用してアップロードされます。

  • マルチパート: オブジェクトはマルチパートアップロードを使用してアップロードされます。

  • Appendable: オブジェクトは追加アップロードを使用してアップロードされます。

サイズ

String

344606

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

親ノード: ListBucketResult.Contents

StorageClass

String

標準

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

親ノード: ListBucketResult.Contents

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要素は、復元されたオブジェクトを読み取ることができるまでの時間を示します。

所有者

Container

非該当

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

子ノード: DisplayNameとID

親ノード: コンテンツ

ID

String

0022012 ****

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

親ノード: ListBucketResult.Contents.Owner

DisplayName

String

user_example

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

親ノード: ListBucketResult.Contents.Owner

CommonPrefixes

Container

非該当

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

親ノード: ListBucketResult

x-oss-request-idContent-Typeなどの一般的なレスポンスヘッダーの詳細については、「一般的なレスポンスヘッダー」をご参照ください。

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

    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: 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>100</MaxKeys>
    <Delimiter></Delimiter>
    <IsTruncated>false</IsTruncated>
    <Contents>
          <Key>fun/movie/001.avi</Key>
          <TransitionTime>2024-04-23T07:21:42.000Z</TransitionTime>
          <LastModified>2012-02-24T08:43:07.000Z</LastModified>
          <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
          <Type>Normal</Type>
          <Size>344606</Size>
          <StorageClass>Standard</StorageClass>
          <Owner>
              <ID>0022012****</ID>
              <DisplayName>user-example</DisplayName>
          </Owner>
    </Contents>
    <Contents>
          <Key>fun/movie/007.avi</Key>
          <LastModified>2012-02-24T08:43:27.000Z</LastModified>
          <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
          <Type>Normal</Type>
          <Size>344606</Size>
          <StorageClass>Standard</StorageClass>
          <Owner>
              <ID>0022012****</ID>
              <DisplayName>user-example</DisplayName>
          </Owner>
    </Contents>
    <Contents>
          <Key>fun/test.jpg</Key>
          <LastModified>2012-02-24T08:42:32.000Z</LastModified>
          <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
          <Type>Normal</Type>
          <Size>344606</Size>
          <StorageClass>Standard</StorageClass>
          <Owner>
              <ID>0022012****</ID>
              <DisplayName>user-example</DisplayName>
          </Owner>
    </Contents>
    <Contents>
          <Key>oss.jpg</Key>
          <LastModified>2012-02-24T06:07:48.000Z</LastModified>
          <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
          <Type>Normal</Type>
          <Size>344606</Size>
          <StorageClass>Standard</StorageClass>
          <Owner>
              <ID>0022012****</ID>
              <DisplayName>user-example</DisplayName>
          </Owner>
    </Contents>
    </ListBucketResult>
  • prefixパラメーターが指定されているサンプルリクエスト

    GET /?prefix=fun 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>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>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
          <Type>Normal</Type>
          <Size>344606</Size>
          <StorageClass>Standard</StorageClass>
          <Owner>
              <ID>0022012****</ID>
              <DisplayName>user_example</DisplayName>
          </Owner>
    </Contents>
    <Contents>
          <Key>fun/movie/007.avi</Key>
          <LastModified>2012-02-24T08:43:27.000Z</LastModified>
          <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
          <Type>Normal</Type>
          <Size>344606</Size>
          <StorageClass>Standard</StorageClass>
          <Owner>
              <ID>0022012****</ID>
              <DisplayName>user_example</DisplayName>
          </Owner>
    </Contents>
    <Contents>
          <Key>fun/test.jpg</Key>
          <LastModified>2012-02-24T08:42:32.000Z</LastModified>
          <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
          <Type>Normal</Type>
          <Size>344606</Size>
          <StorageClass>Standard</StorageClass>
          <Owner>
              <ID>0022012****</ID>
              <DisplayName>user_example</DisplayName>
          </Owner>
    </Contents>
    </ListBucketResult>
  • プレフィックスと区切り文字パラメーターが指定されているサンプルリクエスト

    GET /?prefix=fun/&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>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>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag>
          <Type>Normal</Type>
          <Size>344606</Size>
          <StorageClass>Standard</StorageClass>
          <Owner>
              <ID>0022012****</ID>
              <DisplayName>user_example</DisplayName>
          </Owner>
    </Contents>
    <CommonPrefixes>
          <Prefix>fun/movie/</Prefix>
    </CommonPrefixes>
    </ListBucketResult>
  • markerパラメーターを指定したサンプルリクエスト

    この例では、max-keysパラメーターは2に設定されています。これは、返すオブジェクトの最大数が2であることを示します。

    GET /?max-keys=2&marker=test1.txt HTTP/1.1
    Host: examplebucket.oss-cn-shenzhen.aliyuncs.com
    Accept-Encoding: identity
    Accept: */*
    Connection: keep-alive
    User-Agent: aliyun-sdk-python/2.11.0(Darwin/18.2.0/x86_64;3.4.1)
    date: Tue, 26 May 2020 08:39:48 GMT
    authorization: OSS qn6q**************:77Dv****************

    正常に処理された場合のレスポンス例

    応答のNextMarkerパラメーターは、次のリスト操作のマーカーを示します。

    HTTP/1.1 200 OK
    Server: AliyunOSS
    Date: Tue, 26 May 2020 08:39:48 GMT
    Content-Type: application/xml
    Content-Length: 1032
    Connection: keep-alive
    x-oss-request-id: 5ECCD5D4881816373582xxx
    x-oss-server-time: 3
    
    <?xml version="1.0" encoding="UTF-8"?>
    <ListBucketResult>
      <Name>examplebucket</Name>
      <Prefix></Prefix>
      <Marker>test1.txt</Marker>
      <MaxKeys>2</MaxKeys>
      <Delimiter></Delimiter>
      <EncodingType>url</EncodingType>
      <IsTruncated>true</IsTruncated>
      <NextMarker>test100.txt</NextMarker>
      <Contents>
        <Key>test10.txt</Key>
        <LastModified>2020-05-26T07:50:18.000Z</LastModified>
        <ETag>"C4CA4238A0B923820DCC509A6F75****"</ETag>
        <Type>Normal</Type>
        <Size>1</Size>
        <StorageClass>Standard</StorageClass>
        <Owner>
          <ID>1305433xxx</ID>
          <DisplayName>1305433xxx</DisplayName>
        </Owner>
      </Contents>
      <Contents>
        <Key>test100.txt</Key>
        <LastModified>2020-05-26T07:50:20.000Z</LastModified>
        <ETag>"C4CA4238A0B923820DCC509A6F75****"</ETag>
        <Type>Normal</Type>
        <Size>1</Size>
        <StorageClass>Standard</StorageClass>
        <Owner>
          <ID>1305433xxx</ID>
          <DisplayName>1305433xxx</DisplayName>
        </Owner>
      </Contents>
    </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>

SDK

次のプログラミング言語のOSS SDKを使用して、GetBucket (ListObjects) 操作を呼び出すことができます。

エラーコード

エラーコード

HTTPステータスコード

説明

NoSuchBucket

404

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

AccessDenied

403

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

InvalidArgument

400

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

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