src/ceph/doc/radosgw/s3/perl.rst

   1 .. _perl:
   2
   3 Perl S3 Examples
   4 ================
   5
   6 Creating a Connection
   7 ---------------------
   8
   9 This creates a connection so that you can interact with the server.
  10
  11 .. code-block:: perl
  12
  13         use Amazon::S3;
  14         my $access_key = 'put your access key here!';
  15         my $secret_key = 'put your secret key here!';
  16
  17         my $conn = Amazon::S3->new({
  18                 aws_access_key_id     => $access_key,
  19                 aws_secret_access_key => $secret_key,
  20                 host                  => 'objects.dreamhost.com',
  21                 secure                => 1,
  22                 retry                 => 1,
  23         });
  24
  25
  26 Listing Owned Buckets
  27 ---------------------
  28
  29 This gets a list of `Amazon::S3::Bucket`_ objects that you own.
  30 We'll also print out the bucket name and creation date of each bucket.
  31
  32 .. code-block:: perl
  33
  34         my @buckets = @{$conn->buckets->{buckets} || []};
  35         foreach my $bucket (@buckets) {
  36                 print $bucket->bucket . "\t" . $bucket->creation_date . "\n";
  37         }
  38
  39 The output will look something like this::
  40
  41    mahbuckat1   2011-04-21T18:05:39.000Z
  42    mahbuckat2   2011-04-21T18:05:48.000Z
  43    mahbuckat3   2011-04-21T18:07:18.000Z
  44
  45
  46 Creating a Bucket
  47 -----------------
  48
  49 This creates a new bucket called ``my-new-bucket``
  50
  51 .. code-block:: perl
  52
  53         my $bucket = $conn->add_bucket({ bucket => 'my-new-bucket' });
  54
  55
  56 Listing a Bucket's Content
  57 --------------------------
  58
  59 This gets a list of hashes with info about each object in the bucket.
  60 We'll also print out each object's name, the file size, and last
  61 modified date.
  62
  63 .. code-block:: perl
  64
  65         my @keys = @{$bucket->list_all->{keys} || []};
  66         foreach my $key (@keys) {
  67                 print "$key->{key}\t$key->{size}\t$key->{last_modified}\n";
  68         }
  69
  70 The output will look something like this::
  71
  72    myphoto1.jpg 251262  2011-08-08T21:35:48.000Z
  73    myphoto2.jpg 262518  2011-08-08T21:38:01.000Z
  74
  75
  76 Deleting a Bucket
  77 -----------------
  78
  79 .. note::
  80    The Bucket must be empty! Otherwise it won't work!
  81
  82 .. code-block:: perl
  83
  84         $conn->delete_bucket($bucket);
  85
  86
  87 Forced Delete for Non-empty Buckets
  88 -----------------------------------
  89
  90 .. attention::
  91
  92    not available in the `Amazon::S3`_ perl module
  93
  94
  95 Creating an Object
  96 ------------------
  97
  98 This creates a file ``hello.txt`` with the string ``"Hello World!"``
  99
 100 .. code-block:: perl
 101
 102         $bucket->add_key(
 103                 'hello.txt', 'Hello World!',
 104                 { content_type => 'text/plain' },
 105         );
 106
 107
 108 Change an Object's ACL
 109 ----------------------
 110
 111 This makes the object ``hello.txt`` to be publicly readable and
 112 ``secret_plans.txt`` to be private.
 113
 114 .. code-block:: perl
 115
 116         $bucket->set_acl({
 117                 key       => 'hello.txt',
 118                 acl_short => 'public-read',
 119         });
 120         $bucket->set_acl({
 121                 key       => 'secret_plans.txt',
 122                 acl_short => 'private',
 123         });
 124
 125
 126 Download an Object (to a file)
 127 ------------------------------
 128
 129 This downloads the object ``perl_poetry.pdf`` and saves it in
 130 ``/home/larry/documents/``
 131
 132 .. code-block:: perl
 133
 134         $bucket->get_key_filename('perl_poetry.pdf', undef,
 135                 '/home/larry/documents/perl_poetry.pdf');
 136
 137
 138 Delete an Object
 139 ----------------
 140
 141 This deletes the object ``goodbye.txt``
 142
 143 .. code-block:: perl
 144
 145         $bucket->delete_key('goodbye.txt');
 146
 147 Generate Object Download URLs (signed and unsigned)
 148 ---------------------------------------------------
 149 This generates an unsigned download URL for ``hello.txt``. This works
 150 because we made ``hello.txt`` public by setting the ACL above.
 151 Then this generates a signed download URL for ``secret_plans.txt`` that
 152 will work for 1 hour. Signed download URLs will work for the time
 153 period even if the object is private (when the time period is up, the
 154 URL will stop working).
 155
 156 .. note::
 157    The `Amazon::S3`_ module does not have a way to generate download
 158    URLs, so we are going to be using another module instead. Unfortunately,
 159    most modules for generating these URLs assume that you are using Amazon,
 160    so we have had to go with using a more obscure module, `Muck::FS::S3`_. This
 161    should be the same as Amazon's sample S3 perl module, but this sample
 162    module is not in CPAN. So, you can either use CPAN to install
 163    `Muck::FS::S3`_, or install Amazon's sample S3 module manually. If you go
 164    the manual route, you can remove ``Muck::FS::`` from the example below.
 165
 166 .. code-block:: perl
 167
 168         use Muck::FS::S3::QueryStringAuthGenerator;
 169         my $generator = Muck::FS::S3::QueryStringAuthGenerator->new(
 170                 $access_key,
 171                 $secret_key,
 172                 0, # 0 means use 'http'. set this to 1 for 'https'
 173                 'objects.dreamhost.com',
 174         );
 175
 176         my $hello_url = $generator->make_bare_url($bucket->bucket, 'hello.txt');
 177         print $hello_url . "\n";
 178
 179         $generator->expires_in(3600); # 1 hour = 3600 seconds
 180         my $plans_url = $generator->get($bucket->bucket, 'secret_plans.txt');
 181         print $plans_url . "\n";
 182
 183 The output will look something like this::
 184
 185    http://objects.dreamhost.com:80/my-bucket-name/hello.txt
 186    http://objects.dreamhost.com:80/my-bucket-name/secret_plans.txt?Signature=XXXXXXXXXXXXXXXXXXXXXXXXXXX&Expires=1316027075&AWSAccessKeyId=XXXXXXXXXXXXXXXXXXX
 187
 188
 189 .. _`Amazon::S3`: http://search.cpan.org/~tima/Amazon-S3-0.441/lib/Amazon/S3.pm
 190 .. _`Amazon::S3::Bucket`: http://search.cpan.org/~tima/Amazon-S3-0.441/lib/Amazon/S3/Bucket.pm
 191 .. _`Muck::FS::S3`: http://search.cpan.org/~mike/Muck-0.02/
 192