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

   1 .. _ruby:
   2
   3 Ruby `AWS::SDK`_ Examples (aws-sdk gem ~>2)
   4 ===========================================
   5
   6 Settings
   7 ---------------------
   8
   9 You can setup the connection on global way:
  10
  11 .. code-block:: ruby
  12
  13         Aws.config.update(
  14                 endpoint: 'https://objects.dreamhost.com.',
  15                 access_key_id: 'my-access-key',
  16                 secret_access_key: 'my-secret-key',
  17                 force_path_style: true,
  18                 region: 'us-east-1'
  19         )
  20
  21
  22 and instantiate a client object:
  23
  24 .. code-block:: ruby
  25
  26         s3_client = Aws::S3::Client.new
  27
  28 Listing Owned Buckets
  29 ---------------------
  30
  31 This gets a list of buckets that you own.
  32 This also prints out the bucket name and creation date of each bucket.
  33
  34 .. code-block:: ruby
  35
  36         s3_client.list_buckets.buckets.each do |bucket|
  37                 puts "#{bucket.name}\t#{bucket.creation_date}"
  38         end
  39
  40 The output will look something like this::
  41
  42    mahbuckat1   2011-04-21T18:05:39.000Z
  43    mahbuckat2   2011-04-21T18:05:48.000Z
  44    mahbuckat3   2011-04-21T18:07:18.000Z
  45
  46
  47 Creating a Bucket
  48 -----------------
  49
  50 This creates a new bucket called ``my-new-bucket``
  51
  52 .. code-block:: ruby
  53
  54         s3_client.create_bucket(bucket: 'my-new-bucket')
  55
  56 If you want a private bucket:
  57
  58 `acl` option accepts: # private, public-read, public-read-write, authenticated-read
  59
  60 .. code-block:: ruby
  61
  62         s3_client.create_bucket(bucket: 'my-new-bucket', acl: 'private')
  63
  64
  65 Listing a Bucket's Content
  66 --------------------------
  67
  68 This gets a list of hashes with the contents of each object
  69 This also prints out each object's name, the file size, and last
  70 modified date.
  71
  72 .. code-block:: ruby
  73
  74         s3_client.get_objects(bucket: 'my-new-bucket').contents.each do |object|
  75                 puts "#{object.key}\t#{object.size}\t#{object.last-modified}"
  76         end
  77
  78 The output will look something like this if the bucket has some files::
  79
  80    myphoto1.jpg 251262  2011-08-08T21:35:48.000Z
  81    myphoto2.jpg 262518  2011-08-08T21:38:01.000Z
  82
  83
  84 Deleting a Bucket
  85 -----------------
  86 .. note::
  87    The Bucket must be empty! Otherwise it won't work!
  88
  89 .. code-block:: ruby
  90
  91         s3_client.delete_bucket(bucket: 'my-new-bucket')
  92
  93
  94 Forced Delete for Non-empty Buckets
  95 -----------------------------------
  96 First, you need to clear the bucket:
  97
  98 .. code-block:: ruby
  99
 100         Aws::S3::Bucket.new('my-new-bucket', client: s3_client).clear!
 101
 102 after, you can destroy the bucket
 103
 104 .. code-block:: ruby
 105
 106         s3_client.delete_bucket(bucket: 'my-new-bucket')
 107
 108
 109 Creating an Object
 110 ------------------
 111
 112 This creates a file ``hello.txt`` with the string ``"Hello World!"``
 113
 114 .. code-block:: ruby
 115
 116         s3_client.put_object(
 117                 key: 'hello.txt',
 118                 body: 'Hello World!',
 119                 bucket: 'my-new-bucket',
 120                 content_type: 'text/plain'
 121         )
 122
 123
 124 Change an Object's ACL
 125 ----------------------
 126
 127 This makes the object ``hello.txt`` to be publicly readable, and ``secret_plans.txt``
 128 to be private.
 129
 130 .. code-block:: ruby
 131
 132         s3_client.put_object_acl(bucket: 'my-new-bucket', key: 'hello.txt', acl: 'public-read')
 133
 134         s3_client.put_object_acl(bucket: 'my-new-bucket', key: 'private.txt', acl: 'private')
 135
 136
 137 Download an Object (to a file)
 138 ------------------------------
 139
 140 This downloads the object ``poetry.pdf`` and saves it in
 141 ``/home/larry/documents/``
 142
 143 .. code-block:: ruby
 144
 145         s3_client.get_object(bucket: 'my-new-bucket', key: 'poetry.pdf', response_target: '/home/larry/documents/poetry.pdf')
 146
 147
 148 Delete an Object
 149 ----------------
 150
 151 This deletes the object ``goodbye.txt``
 152
 153 .. code-block:: ruby
 154
 155         s3_client.delete_object(key: 'goodbye.txt', bucket: 'my-new-bucket')
 156
 157
 158 Generate Object Download URLs (signed and unsigned)
 159 ---------------------------------------------------
 160
 161 This generates an unsigned download URL for ``hello.txt``. This works
 162 because we made ``hello.txt`` public by setting the ACL above.
 163 This then generates a signed download URL for ``secret_plans.txt`` that
 164 will work for 1 hour. Signed download URLs will work for the time
 165 period even if the object is private (when the time period is up, the
 166 URL will stop working).
 167
 168 .. code-block:: ruby
 169
 170         puts Aws::S3::Object.new(
 171                 key: 'hello.txt',
 172                 bucket_name: 'my-new-bucket',
 173                 client: s3_client
 174         ).public_url
 175
 176         puts Aws::S3::Object.new(
 177                 key: 'secret_plans.txt',
 178                 bucket_name: 'hermes_ceph_gem',
 179                 client: s3_client
 180         ).presigned_url(:get, expires_in: 60 * 60)
 181
 182 The output of this will look something like::
 183
 184    http://objects.dreamhost.com/my-bucket-name/hello.txt
 185    http://objects.dreamhost.com/my-bucket-name/secret_plans.txt?Signature=XXXXXXXXXXXXXXXXXXXXXXXXXXX&Expires=1316027075&AWSAccessKeyId=XXXXXXXXXXXXXXXXXXX
 186
 187 .. _`AWS::SDK`: http://docs.aws.amazon.com/sdkforruby/api/Aws/S3/Client.html
 188
 189
 190
 191 Ruby `AWS::S3`_ Examples (aws-s3 gem)
 192 =====================================
 193
 194 Creating a Connection
 195 ---------------------
 196
 197 This creates a connection so that you can interact with the server.
 198
 199 .. code-block:: ruby
 200
 201         AWS::S3::Base.establish_connection!(
 202                 :server            => 'objects.dreamhost.com',
 203                 :use_ssl           => true,
 204                 :access_key_id     => 'my-access-key',
 205                 :secret_access_key => 'my-secret-key'
 206         )
 207
 208
 209 Listing Owned Buckets
 210 ---------------------
 211
 212 This gets a list of `AWS::S3::Bucket`_ objects that you own.
 213 This also prints out the bucket name and creation date of each bucket.
 214
 215 .. code-block:: ruby
 216
 217         AWS::S3::Service.buckets.each do |bucket|
 218                 puts "#{bucket.name}\t#{bucket.creation_date}"
 219         end
 220
 221 The output will look something like this::
 222
 223    mahbuckat1   2011-04-21T18:05:39.000Z
 224    mahbuckat2   2011-04-21T18:05:48.000Z
 225    mahbuckat3   2011-04-21T18:07:18.000Z
 226
 227
 228 Creating a Bucket
 229 -----------------
 230
 231 This creates a new bucket called ``my-new-bucket``
 232
 233 .. code-block:: ruby
 234
 235         AWS::S3::Bucket.create('my-new-bucket')
 236
 237
 238 Listing a Bucket's Content
 239 --------------------------
 240
 241 This gets a list of hashes with the contents of each object
 242 This also prints out each object's name, the file size, and last
 243 modified date.
 244
 245 .. code-block:: ruby
 246
 247         new_bucket = AWS::S3::Bucket.find('my-new-bucket')
 248         new_bucket.each do |object|
 249                 puts "#{object.key}\t#{object.about['content-length']}\t#{object.about['last-modified']}"
 250         end
 251
 252 The output will look something like this if the bucket has some files::
 253
 254    myphoto1.jpg 251262  2011-08-08T21:35:48.000Z
 255    myphoto2.jpg 262518  2011-08-08T21:38:01.000Z
 256
 257
 258 Deleting a Bucket
 259 -----------------
 260 .. note::
 261    The Bucket must be empty! Otherwise it won't work!
 262
 263 .. code-block:: ruby
 264
 265         AWS::S3::Bucket.delete('my-new-bucket')
 266
 267
 268 Forced Delete for Non-empty Buckets
 269 -----------------------------------
 270
 271 .. code-block:: ruby
 272
 273         AWS::S3::Bucket.delete('my-new-bucket', :force => true)
 274
 275
 276 Creating an Object
 277 ------------------
 278
 279 This creates a file ``hello.txt`` with the string ``"Hello World!"``
 280
 281 .. code-block:: ruby
 282
 283         AWS::S3::S3Object.store(
 284                 'hello.txt',
 285                 'Hello World!',
 286                 'my-new-bucket',
 287                 :content_type => 'text/plain'
 288         )
 289
 290
 291 Change an Object's ACL
 292 ----------------------
 293
 294 This makes the object ``hello.txt`` to be publicly readable, and ``secret_plans.txt``
 295 to be private.
 296
 297 .. code-block:: ruby
 298
 299         policy = AWS::S3::S3Object.acl('hello.txt', 'my-new-bucket')
 300         policy.grants = [ AWS::S3::ACL::Grant.grant(:public_read) ]
 301         AWS::S3::S3Object.acl('hello.txt', 'my-new-bucket', policy)
 302
 303         policy = AWS::S3::S3Object.acl('secret_plans.txt', 'my-new-bucket')
 304         policy.grants = []
 305         AWS::S3::S3Object.acl('secret_plans.txt', 'my-new-bucket', policy)
 306
 307
 308 Download an Object (to a file)
 309 ------------------------------
 310
 311 This downloads the object ``poetry.pdf`` and saves it in
 312 ``/home/larry/documents/``
 313
 314 .. code-block:: ruby
 315
 316         open('/home/larry/documents/poetry.pdf', 'w') do |file|
 317                 AWS::S3::S3Object.stream('poetry.pdf', 'my-new-bucket') do |chunk|
 318                         file.write(chunk)
 319                 end
 320         end
 321
 322
 323 Delete an Object
 324 ----------------
 325
 326 This deletes the object ``goodbye.txt``
 327
 328 .. code-block:: ruby
 329
 330         AWS::S3::S3Object.delete('goodbye.txt', 'my-new-bucket')
 331
 332
 333 Generate Object Download URLs (signed and unsigned)
 334 ---------------------------------------------------
 335
 336 This generates an unsigned download URL for ``hello.txt``. This works
 337 because we made ``hello.txt`` public by setting the ACL above.
 338 This then generates a signed download URL for ``secret_plans.txt`` that
 339 will work for 1 hour. Signed download URLs will work for the time
 340 period even if the object is private (when the time period is up, the
 341 URL will stop working).
 342
 343 .. code-block:: ruby
 344
 345         puts AWS::S3::S3Object.url_for(
 346                 'hello.txt',
 347                 'my-new-bucket',
 348                 :authenticated => false
 349         )
 350
 351         puts AWS::S3::S3Object.url_for(
 352                 'secret_plans.txt',
 353                 'my-new-bucket',
 354                 :expires_in => 60 * 60
 355         )
 356
 357 The output of this will look something like::
 358
 359    http://objects.dreamhost.com/my-bucket-name/hello.txt
 360    http://objects.dreamhost.com/my-bucket-name/secret_plans.txt?Signature=XXXXXXXXXXXXXXXXXXXXXXXXXXX&Expires=1316027075&AWSAccessKeyId=XXXXXXXXXXXXXXXXXXX
 361
 362 .. _`AWS::S3`: http://amazon.rubyforge.org/
 363 .. _`AWS::S3::Bucket`: http://amazon.rubyforge.org/doc/
 364