edit-icon download-icon

GetBucket (List Object)

最終更新日: Aug 01, 2018

GetBucket 操作を使用すると、バケット内のオブジェクトの情報をすべて表示できます。

リクエスト構文

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

リクエストパラメーター

GetBucket (ListObject) リクエストを開始するときに、prefix、marker、delimiter、max-keys の各パラメーターを使用して制限を指定すると、部分的な結果を取得することができます。

名前 必須かどうか 説明
delimiter string  いいえ オブジェクト名をグループ化するために使用する文字。指定したプレフィックスから最初の delimiter までの名前を持つオブジェクトはすべて要素のグループ (CommonPrefixes) として機能します。
デフォルト値: なし
marker string  いいえ アルファベット順で marker 後の最初のエントリから結果を返すように設定します。
デフォルト値: なし
max-keys string  いいえ 1 件のリクエストに対して返されるオブジェクトの最大数を制限します。指定されていない場合のデフォルト値は 100 です。max-keys の値は 1000 以下にする必要があります。
デフォルト値: 100
prefix string いいえ 返されるオブジェクトキーに指定に応じたプレフィックスが付与されるという制限を適用します。プレフィックスを使用するクエリから返されるキーにはそのプレフィックスも含まれることに注意してください。
デフォルト値: なし
encoding-type string  いいえ 返されるコンテンツのエンコーディングとエンコーディングのタイプを指定します。オブジェクトキーでは UTF-8 文字が使用されますが、XML 1.0 標準では、0 ~ 10 の ASCII 値を含む文字などの特定の制御文字の解析はサポートされていません。XML 1.0 標準でサポートされていない制御文字がオブジェクトキーに含まれている場合は、encoding-type を指定して返されるオブジェクトキーをエンコードできます。
デフォルト値: なし

応答の要素

名前 説明
Contents container 返されるすべてのオブジェクトのメタの保存に使用されるコンテナー。
親ノード: ListBucketResult
CommonPrefixes string リクエストに delimiter パラメーターを指定した場合、OSS から返される応答に CommonPrefixes 要素が含まれます。この要素は、末尾が delimiter で、共通のプレフィックスを持つ、オブジェクトのセットを示します。
親ノード: ListBucketResult
Delimiter string オブジェクト名をグループ化するために使用する文字。指定したプレフィックスから最初の delimiter までの名前を持つオブジェクトはすべて要素のグループ (CommonPrefixes) として機能します。
親ノード: ListBucketResult
encoding-type string 返される結果におけるエンコーディングのタイプを指定します。リクエストで encoding-type を指定した場合は、返される結果において Delimiter、Marker、Prefix、NextMarker、Key などの要素がエンコードされます。
親ノード: ListBucketResult
DisplayName string オブジェクトオーナーの名前。
親ノード: ListBucketResult.Contents.Owner
ETag string ETag (エンティティタグ) は、オブジェクトの生成時に作成され、オブジェクトのコンテンツを示すために使用されます。PutObject リクエストを使用して作成されたオブジェクトの場合、ETag の値はオブジェクトのコンテンツの MD5 値です。その他の方法で作成されたオブジェクトの場合、ETag の値はオブジェクトのコンテンツの UUID です。この ETag の値を使用して、オブジェクトのコンテンツが変更されているかどうかを確認できます。
親ノード: ListBucketResult.Contents
ID string バケットオーナーのユーザー ID。
親ノード: ListBucketResult.Contents.Owner
IsTruncated enumerated string すべての結果が返されたかどうかを示します。”true” の場合は、今回返されなかった結果があります。”false” の場合は、すべての結果が返されています。
有効な値: true と false
親ノード: ListBucketResult
Key string オブジェクトのキー。
親ノード: ListBucketResult.Contents
LastModified time オブジェクトが最後に変更された日時。
親ノード: ListBucketResult.Contents
ListBucketResult container GetBucket リクエストの結果の保存に使用されるコンテナー。
サブノード: Name、Prefix、Marker、MaxKeys、Delimiter、IsTruncated、Nextmarker、Contents
親ノード: なし
Marker string 現在の GetBucket (List Object) リクエストの開始位置を示します。
親ノード: ListBucketResult
MaxKeys string リクエストに応じて返される結果の最大数。
親ノード: ListBucketResult
Name string バケット名。
親ノード: ListBucketResult
Owner container バケットオーナーに関する情報の保存に使用されるコンテナー。
サブノード: DisplayName、ID
親ノード: ListBucketResult
Prefix string クエリの現在の結果の開始プレフィックス。
親ノード: ListBucketResult
Size string オブジェクトのバイト数。
親ノード: ListBucketResult.Contents
StorageClass string オブジェクトのストレージタイプ。現在利用できるのは “Standard” ,“IA”と“Archive” タイプです。 (Archiveタイプは現在同一リージョンでのみ利用可能です。)
親ノード: ListBucketResult.Contents

詳細分析

  • GetBucket リクエストでは、オブジェクトのユーザー定義メタは返されません。
  • アクセス先のバケットが存在しない場合や、標準の命名規則に従っていないために作成できない場合は、エラー 404 Not Found が返されます。エラーコードは NoSuchBucket です。
  • バケットにアクセスする権限がない場合は、エラー 403 Forbidden が返されます。エラーコードは AccessDenied です。
  • max-keys の設定のために結果を一度に表示できない場合は、返される結果に <NextMarker> が追加されます。NextMarker は、続きがあることを示すマーカーと見なすことができます。NextMarker の値も結果に含まれます。
  • 条件クエリでは、実際にはリストに marker が含まれていなくても、返される結果は、アルファベット順で marker の次に相当するエントリから表示されます。max-keys の値が 0 より小さいか 1000 より大きい場合は、エラー 400 Bad Request が返されます。エラーコードは InvalidArgument です。
  • prefix、marker、delimiter のいずれかのパラメーターが長さの要件を満たしていない場合は、400 Bad Request が返されます。エラーコードは InvalidArgument です。
  • パラメーターの prefix と marker を使用すると、ページ分割を実現できます。パラメーターの長さは 1024 バイト未満である必要があります。
  • フォルダー一覧の名前をプレフィックスとして設定すると、そのプレフィックスで始まるファイルが列挙されて、そのフォルダーのすべてのファイルとサブフォルダーが再帰的に返されます。さらに delimiter を “/“ に設定すると、返される値にはフォルダーのファイルのみが含まれ、サブフォルダーは CommonPrefixes セクションに返されます。サブフォルダー内のファイルとフォルダーは再帰的に表示されません。たとえば、バケットに次の 3 つのオブジェクトがあったとします。fun/test.jpg、fun/movie/001.avi、fun/movie/007.aviprefix を “fun/“ に設定すると、3 つのオブジェクトが返されます。さらに delimiter を “/“ に設定すると、ファイル “fun/test.jpg” とプレフィックス “fun/movie/“ が返されます。つまり、フォルダーロジックが実現されます。

シナリオ例

バケット “my_oss” に 4 つのオブジェクトがあり、それぞれ次のような名前が付けられています。

  • oss.jpg
  • fun/test.jpg
  • fun/movie/001.avi
  • fun/movie/007.avi

リクエストの例:

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

レスポンスの例:

  1. HTTP/1.1 200 OK
  2. x-oss-request-id: 534B371674E88A4D8906008B
  3. Date: Fri, 24 Feb 2012 08:43:27 GMT
  4. Content-Type: application/xml
  5. Content-Length: 1866
  6. Connection: keep-alive
  7. Server: AliyunOSS
  8. <?xml version="1.0" encoding="UTF-8"?>
  9. <ListBucketResult xmlns="http://doc.oss-cn-hangzhou.aliyuncs.com">
  10. <Name>oss-example</Name>
  11. <Prefix></Prefix>
  12. <Marker></Marker>
  13. <MaxKeys>100</MaxKeys>
  14. <Delimiter></Delimiter>
  15. <IsTruncated>false</IsTruncated>
  16. <Contents>
  17. <Key>fun/movie/001.avi</Key>
  18. <LastModified>2012-02-24T08:43:07.000Z</LastModified>
  19. <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</ETag>
  20. <Type>Normal</Type>
  21. <Size>344606</Size>
  22. <StorageClass>Standard</StorageClass>
  23. <Owner>
  24. <ID>00220120222</ID>
  25. <DisplayName>user-example</DisplayName>
  26. </Owner>
  27. </Contents>
  28. <Contents>
  29. <Key>fun/movie/007.avi</Key>
  30. <LastModified>2012-02-24T08:43:27.000Z</LastModified>
  31. <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</ETag>
  32. <Type>Normal</Type>
  33. <Size>344606</Size>
  34. <StorageClass>Standard</StorageClass>
  35. <Owner>
  36. <ID>00220120222</ID>
  37. <DisplayName>user-example</DisplayName>
  38. </Owner>
  39. </Contents>
  40. <Contents>
  41. <Key>fun/test.jpg</Key>
  42. <LastModified>2012-02-24T08:42:32.000Z</LastModified>
  43. <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</ETag>
  44. <Type>Normal</Type>
  45. <Size>344606</Size>
  46. <StorageClass>Standard</StorageClass>
  47. <Owner>
  48. <ID>00220120222</ID>
  49. <DisplayName>user-example</DisplayName>
  50. </Owner>
  51. </Contents>
  52. <Contents>
  53. <Key>oss.jpg</Key>
  54. <LastModified>2012-02-24T06:07:48.000Z</LastModified>
  55. <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</ETag>
  56. <Type>Normal</Type>
  57. <Size>344606</Size>
  58. <StorageClass>Standard</StorageClass>
  59. <Owner>
  60. <ID>00220120222</ID>
  61. <DisplayName>user-example</DisplayName>
  62. </Owner>
  63. </Contents>
  64. </ListBucketResult>

リクエストの例 (prefix を含む場合):

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

レスポンスの例:

  1. HTTP/1.1 200 OK
  2. x-oss-request-id: 534B371674E88A4D8906008B
  3. Date: Fri, 24 Feb 2012 08:43:27 GMT
  4. Content-Type: application/xml
  5. Content-Length: 1464
  6. Connection: keep-alive
  7. Server: AliyunOSS
  8. <?xml version="1.0" encoding="UTF-8"?>
  9. <ListBucketResult xmlns="http://doc.oss-cn-hangzhou.aliyuncs.com">
  10. <Name>oss-example</Name>
  11. <Prefix>fun</Prefix>
  12. <Marker></Marker>
  13. <MaxKeys>100</MaxKeys>
  14. <Delimiter></Delimiter>
  15. <IsTruncated>false</IsTruncated>
  16. <Contents>
  17. <Key>fun/movie/001.avi</Key>
  18. <LastModified>2012-02-24T08:43:07.000Z</LastModified>
  19. <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</ETag>
  20. <Type>Normal</Type>
  21. <Size>344606</Size>
  22. <StorageClass>Standard</StorageClass>
  23. <Owner>
  24. <ID>00220120222</ID>
  25. <DisplayName>user_example</DisplayName>
  26. </Owner>
  27. </Contents>
  28. <Contents>
  29. <Key>fun/movie/007.avi</Key>
  30. <LastModified>2012-02-24T08:43:27.000Z</LastModified>
  31. <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</ETag>
  32. <Type>Normal</Type>
  33. <Size>344606</Size>
  34. <StorageClass>Standard</StorageClass>
  35. <Owner>
  36. <ID>00220120222</ID>
  37. <DisplayName>user_example</DisplayName>
  38. </Owner>
  39. </Contents>
  40. <Contents>
  41. <Key>fun/test.jpg</Key>
  42. <LastModified>2012-02-24T08:42:32.000Z</LastModified>
  43. <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</ETag>
  44. <Type>Normal</Type>
  45. <Size>344606</Size>
  46. <StorageClass>Standard</StorageClass>
  47. <Owner>
  48. <ID>00220120222</ID>
  49. <DisplayName>user_example</DisplayName>
  50. </Owner>
  51. </Contents>
  52. </ListBucketResult>

リクエストの例 (prefix と delimiter を含む場合):

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

レスポンスの例:

  1. HTTP/1.1 200 OK
  2. x-oss-request-id: 534B371674E88A4D8906008B
  3. Date: Fri, 24 Feb 2012 08:43:27 GMT
  4. Content-Type: application/xml
  5. Content-Length: 712
  6. Connection: keep-alive
  7. Server: AliyunOSS
  8. <?xml version="1.0" encoding="UTF-8"?>
  9. <ListBucketResult xmlns="http://doc.oss-cn-hangzhou.aliyuncs.com">
  10. <Name>oss-example</Name>
  11. <Prefix>fun/</Prefix>
  12. <Marker></Marker>
  13. <MaxKeys>100</MaxKeys>
  14. <Delimiter>/</Delimiter>
  15. <IsTruncated>false</IsTruncated>
  16. <Contents>
  17. <Key>fun/test.jpg</Key>
  18. <LastModified>2012-02-24T08:42:32.000Z</LastModified>
  19. <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</ETag>
  20. <Type>Normal</Type>
  21. <Size>344606</Size>
  22. <StorageClass>Standard</StorageClass>
  23. <Owner>
  24. <ID>00220120222</ID>
  25. <DisplayName>user_example</DisplayName>
  26. </Owner>
  27. </Contents>
  28. <CommonPrefixes>
  29. <Prefix>fun/movie/</Prefix>
  30. </CommonPrefixes>
  31. </ListBucketResult>