Amazon S3 GET Bucket のパラメータとレスポンスの関係

Amazon Simple Storage Service (Amazon S3) を使ってみようと試行中です。

まず単純なところで、その振る舞いを把握しようと WEB ブラウザと REST API の GET Bucket を使って、フォルダやファイルをリストアップしてみた。この GET Bucket ですが、Developer Guide を読んでも、どう振る舞うのかイメージできないことが多々ありましたので、補足を意図して残しておきます。

prefix パラメータは、指定した文字列の前方一致で、ファイル(フォルダ)をフィルタするものです。↓こんな感じです。このとき、先頭に foo を含むパスがリストアップされます。

http://s3.amazonaws.com/(bucket)?prefix=foo

特定のフォルダで絞り込むときなどに使えそうです。

marker パラメータは、多数のファイル(フォルダ)があるとき、そのリストをページングするためのものです。↓こんな感じです。このとき、foo.txt 以降のファイル(フォルダ)がリストアップされます。

http://s3.amazonaws.com/(bucket)?marker=foo.txt

marker パラメータの値には、リストの ListBucketResult/Contents/Key 要素の値を指定します。つまり、リストの最後の同要素を指定すればよいということです。

リストの並び順は、パスの辞書順のようです。リストが継続しているかどうかは、レスポンスの ListBucketResult/IsTruncated 要素で判断できます。

max-keys パラメータは、リストに含めるファイル(フォルダ)の上限件数です。↓こんな感じです。このとき、10件のファイル(フォルダ)がリストアップされます。

http://s3.amazonaws.com/(bucket)?max-keys=10

省略値は 100 件です。ただし、後述の delimiter パラメータを使って、フォルダをまとめたときの ListBucketResult/CommonPrefixes 要素もこの件数に含まれるため、delimiter パラメータと併用したときは、max-keys パラメータの件数と、実際のファイル(フォルダ)の件数が一致しないことがあります。

delimiter パラメータは、指定した文字列を区切りとして、パスをまとめ上げるものです(っていっても伝わりませんよね)。↓こんな感じです。このとき、ルートのファイルとフォルダ(フォルダの中身は含まない)がリストアップされます。

http://s3.amazonaws.com/(bucket)?delimiter=/

カレントフォルダのフォルダとファイルをリストアップするときに使えそうです。カレントフォルダは prefix パラメータを使って表現し、その prefix パラメータの値には、レスポンスの ListBucketResult/CommonPrefixes/Prefix 要素の値を指定します。よく考えたら、カレントフォルダは URI での表現もできますね。そして、これらを繰り返せば、フォルダツリーが得られることになります。

delimiter パラメータを使ったとき、レスポンス中のフォルダは ListBucketResult/Contents/Key = "(folder)_$folder$" として表現されます。_$folder$ の接尾辞でフォルダと判断するのでしょうかね。