Perlゼミ

1. Perl
›
2. モジュール
›
3. here

Amazon::S3::Thin - 薄くて、軽量、低レベル操作ができるAmazon S3クライアント

Amazon::S3::Thinは薄くて、軽量、低レベル操作ができるAmazon S3クライアントです。以下は、Amazon::S3::Thin 0.29の日本語訳です。

概要

use Amazon::S3::Thin;
 
my $s3client = Amazon::S3::Thin->new({
      aws_access_key_id     => $aws_access_key_id,
      aws_secret_access_key => $aws_secret_access_key,
      aws_session_token     => $aws_session_token, # optional
      region                => $region, # e.g. 'ap-northeast-1'
    });
 
my $bucket = "mybucket";
my $key = "dir/file.txt";
my $response;
 
$response = $s3client->put_bucket($bucket);
 
$response = $s3client->put_object($bucket, $key, "hello world");
 
$response = $s3client->get_object($bucket, $key);
print $response->content; # => "hello world"
 
$response = $s3client->delete_object($bucket, $key);
 
$response = $s3client->list_objects(
                            $bucket,
                            {prefix => "foo", delimiter => "/"}
                           );

また、任意のユーザーエージェントを好きなように渡すことができます

my $s3client = Amazon::S3::Thin->new({
        ...
        ua => $any_LWP_copmatible_useragent,
    });

デフォルトでは、署名バージョン 4 が使用されます。署名バージョン 2 を使用するには、オプションを追加します。signature_version

my $s3client = Amazon::S3::Thin->new({
        ...
        signature_version     => 2,
    });

説明

Amazon::S3:::Thin は薄くて軽量で低レベルの Amazon S3 クライアントです。

リクエストを送信して応答を得るという目的だけで設計されています。

詳細には、次の機能を提供しています。

低レベル

HTTP::Responseオブジェクトを返して、内部で何が起こっているかを簡単に調べることができ、必要に応じてエラーを処理できます。

低依存

XML::*モジュールは必要ないので、インストールは簡単です。

低学習コスト

インターフェイスは、S3 公式 REST API に従うように設計されています。だから、学ぶことは簡単です。

以前に作られたモジュールとの比較

すでにAmazon::S3、Net::Amazon::S3のような便利なモジュールがあります。彼らはPerlプログラマにとってきれいに見える「Perlish」インターフェイスを提供しますが、低レベルの動作も隠しています。たとえば、「get_key」メソッドは、HTTP ステータス 404 を undef に変換し、HTTP 5xx ステータスを例外に変換します。

状況によっては、生の HTTP 通信を確認することが非常に重要です。だから私はこのモジュールを作ったのです。

コンストラクタ

new( \%params )

引数:オプションを含んだハッシュリファレンス.

戻り値:Amazon::S3::薄いオブジェクト

次の引数を受け取ることができます。

• aws_access_key_id (必須)- 資格情報のアクセス キー ID。
• aws_secret_access_key (必須)- 資格情報の秘密のアクセスキー。
• region - (必須)アクセスするバケットのリージョン(現在は署名バージョンが4の場合にのみ使用)
• secure- httpsを使用するかどうか。デフォルトは 0 (http) です。
• ua- ユーザー エージェント オブジェクトで、LWP::UserAgent と互換性があります。デフォルトはLWP::ユーザーエージェントのインスタンスです。
• signature_version- 使用する AWS 署名バージョン。サポートされる値は 2 と 4 です。デフォルトは 4 です。
• debug- デバッグオプション。デフォルトは 0 (偽) です。設定値 1 の場合、HTTP 要求と応答の内容は stderr に表示されます。
• virtual_host- 仮想ホスト型の要求形式を使用するかどうか。デフォルトは 0 (パススタイル) です。

アクセサ

次のアクセサが提供されます。これらを使用して、オブジェクトの属性を取得/設定できます。

secure

S3 に接続するときに https (1) または http (0) を使用するかどうか。

ua

ユーザー エージェントは、要求を実行し、応答を返すために内部で使用しました。この属性を設定する場合は、LWP::UserAgent(同じインターフェイスを提供する)と互換性のあるオブジェクトで設定してください。

debug

デバッグ オプション。

バケットに対する操作

put_bucket($bucket[,$headers])

引数:

1. バケット - バケットを持つ文字列

2. ヘッダー (オプション) - 余分なヘッダー情報を含むハッシュリファレンス

delete_bucket($bucket[$headers])

引数:

1. バケット - バケットを持つ文字列

2. ヘッダー (オプション) - 余分なヘッダー情報を含むハッシュリファレンス

オブジェクトに対する操作

get_object($bucket, $key[, $headers] )

引数:

1. バケット - バケットを持つ文字列

2. キー - キーを持つ文字列

3. ヘッダー (オプション) - 余分なヘッダー情報を含むハッシュリファレンス

戻り値:リクエストに応じたHTTP::Responseオブジェクト。返されたオブジェクトに対してcontent()メソッドを使用して、内容を読み取れます。

my $res = $s3->get_object( 'my.bucket', 'my/key.ext' );
 
if ($res->is_success) {
    my $content = $res->content;
}

GET オペレーションは、Amazon S3 からオブジェクトを取得します。

詳細については、GETに関するAmazonのドキュメントを参照してください。

head_object($bucket, $key)

引数:

1. バケット - バケットを持つ文字列

2. キー - キーを持つ文字列

戻り値:リクエストに応じたHTTP::Responseオブジェクト。返されたオブジェクトに対してheader()メソッドを使用して、メタデータを読み取れます。

my $res = $s3->head_object( 'my.bucket', 'my/key.ext' );
 
if ($res->is_success) {
    my $etag = $res->header('etag'); #=> `"fba9dede5f27731c9771645a39863328"`
}

HEAD オペレーションは、Amazon S3 からオブジェクトのメタデータを取得します。

詳細については、HEADに関するAmazonのドキュメントを参照してください。

delete_object($bucket, $key)

引数: バケット名を持つ文字列と、キー名を持つ文字列。

戻り値:リクエストに応じたHTTP::Responseオブジェクト。

DELETE 操作は、オブジェクトの null バージョン (存在する場合) を削除し、削除マーカーを挿入します。null バージョンがない場合、Amazon S3 はオブジェクトを削除しません。

応答オブジェクトを使用して、成功したかどうかを確認します。

詳細については、DELETEに関するAmazonのドキュメントを参照してください。

copy_object( $src_bucket, $src_key, $dst_bucket, $dst_key [, $headers] )

引数: ソース (バケット、キー) と宛先 (バケット、キー) を持つリスト、追加のヘッダー情報を含むハッシュリファレンス (オプション)。

戻り値:リクエストに応じたHTTP::Responseオブジェクト。

このメソッドは、Amazon の S3 API で説明されている PUT 操作のバリエーションです。すでに Amazon S3 に保存されているオブジェクトのコピーを作成します。この「PUT コピー」操作は、古いバケット/キーから GET を実行し、新しいバケット/キーに PUT を実行するのと同じです。

COPY 要求は 200 OK でエラー応答を返す場合がありますが、このメソッドはエラー応答を判別し、状況コードを 500 に書き換えます。

詳細については、COPYに関するAmazonのドキュメントを参照してください。

put_object($bucket, $key, $content[,$headers] )

引数:

1. バケット - 宛先バケットを含む文字列

2. キー - 宛先キーを持つ文字列

3. コンテンツ - アップロードするコンテンツを含む文字列

4. ヘッダー (オプション) - 余分なヘッダー情報を含むハッシュリファレンス

戻り値:リクエストに応じたHTTP::Responseオブジェクト。

PUT 操作は、バケットにオブジェクトを追加します。Amazon S3 は、部分オブジェクトを追加しません。成功レスポンスを受け取った場合、Amazon S3 はオブジェクト全体をバケットに追加します。

詳細については、PUTに関するAmazonのドキュメントを参照してください。

delete_multiple_objects($bucket, @keys)

引数: バケット名を持つ文字列と、削除するすべてのキーを含む配列。

戻り値:リクエストに応じたHTTP::Responseオブジェクト。

複数オブジェクトの削除操作では、単一の HTTP リクエストを使用して、バケットから複数のオブジェクト (最大 1000) を削除できます。削除するオブジェクトキーがわかっている場合、この操作は、個々の削除要求を 送信する代わりに、要求ごとのオーバーヘッドを削減します。delete_object()

詳細については、複数オブジェクトの削除に関するDELETEのAmazonのドキュメントを参照してください。

list_objects( $bucket [, \%options] )

引数: バケット名を持つ文字列、および以下のオプションを含むハッシュリファレンス(オプション)のいずれかを使用します。

• prefix (文字列)- 指定したプレフィックスで始まるキーのみを返します。ファイルシステム内のフォルダーを使用する場合と同じように、プレフィックスを使用してバケットを異なるグループのキーに分けることができます。
• delimiter (文字列)- キーの先頭 (または指定されている場合はプレフィックスの後) と区切り文字の最初の出現との間に同じ文字列を含むグループ キー。
• encoding-type (文字列)- "url" に設定すると、応答のキーがエンコードされます (XML パーサーが Unicode キーを動作できない場合に便利です)。
• marker (文字列)- オブジェクトをリストする際に開始するキーを指定します。Amazon S3 は、オブジェクトキーをアルファベット順に、マーカーの直後のキーから順に返します。
• max-keys (文字列)- 応答本文に返されるキーの最大数を設定します。デフォルトの 1000 キーより少ない数のキーを取得する場合は、これをリクエストに追加できます。

戻り値:リクエストに応じたHTTP::Responseオブジェクト。返されたオブジェクトに対してcontent()メソッドを使用して、内容を読み取れます。

このメソッドは、バケット内のオブジェクトの一部または全部 (最大 1000 個) を返します。応答に含まれるキーは少なくなる可能性がありますが、それ以上は含まれていないことに注意してください。検索条件を満たすキーが制限値 (1000 または max-key) を超えたために返されなかった場合、応答には .追加のキーを返す場合は、上記の「marker」を参照してください。

詳細については、AMAZONのRESTバケットGETのドキュメントを参照してください。

generate_presigned_post($bucket, $key [, $fields, $conditions, $expires_in ] )

引数:

1. バケット (文字列) - 送信先バケットを含む文字列

2. キー (文字列) - 宛先キーを持つ文字列

3. フィールド (配列リファレンス) - キー/値ペアの配列リファレンスを事前に記入したフォームフィールドに対して、上に構築します。

4. 条件 (配列リファレンス) - ポリシーに含める条件 (配列リファレンスまたはハッシュリファレンス) の配列リファレンス

5. expires_in (数) - 署名付き URL が期限切れになる前の現在の時刻からの秒数

戻り値: 「url」と「fields」という2 つの要素を持つハッシュリファレンスを返します。「url」は、ポストされたURLです。「fields」は、POSTをサブミットしたときに使用された、フォームのフィールドとそれぞれの値です。 は、投稿を送信するときに使用するフォームフィールドとそれぞれの値を記入した配列リファレンスです。(fieldsの順序に従う必要があります。)

このメソッドは、HTTP POST を使用して Amazon S3 にファイルをアップロードするための署名付き URL を生成します。boto3 からの元の実装は、S3Client.generate_presigned_post()を参照して移植されました。

注: このメソッドは、シグネチャ v4 のみがサポートされています。

これは、署名付き URL を生成し、ファイル「test.txt」をアップロードする例です。この場合、任意の値を持つオブジェクトメタデータ「x-amz-meta-foo」を設定することができ、アップロードサイズは1MBに制限されています。

my $presigned = $s3->generate_presigned_post('my.bucket', 'my/key.ext', [
    'x-amz-meta-foo' => 'bar',
], [
    ['starts-with' => '$x-amz-meta-foo', ''],
    ['content-length-range' => 1, 1024*1024],
], 24*60*60);
 
my $ua = LWP::UserAgent->new;
my $res = $ua->post(
    $presigned->{url},
    Content_Type => 'multipart/form-data',
    Content      => [
        @{$presigned->{fields}},
        file => ['test.txt'],
    ],
);

詳細については、POSTポリシーの作成に関するAmazonのドキュメントを参照してください。

Todo

多くの API はまだ実装されていません。

リポジトリ

https://github.com/DQNEO/Amazon-S3-Thin

ライセンス

著作権(C)DQNEO。

このライブラリはフリーソフトウェアです。Perl 自体と同じ用語で再配布したり、変更することができます。

著者

DQNEO

サンクス

ティモシー・アプネル・ブレノ・G・デ・オリベイラ

参考

Amazon::S3 https://github.com/tima/perl-amazon-s3

Net::Amazon::S3

アマゾン S3 API リファレンス : REST API

Amazon S3 API リファレンス : エラーコードのリスト