mirror of
https://github.com/ceph/ceph
synced 2024-12-23 03:44:23 +00:00
cbe85ec126
* and add the link to library homepage in the section titles Signed-off-by: Kefu Chai <kchai@redhat.com>
365 lines
8.5 KiB
ReStructuredText
365 lines
8.5 KiB
ReStructuredText
.. _ruby:
|
|
|
|
Ruby `AWS::SDK`_ Examples (aws-sdk gem ~>2)
|
|
===========================================
|
|
|
|
Settings
|
|
---------------------
|
|
|
|
You can setup the connection on global way:
|
|
|
|
.. code-block:: ruby
|
|
|
|
Aws.config.update(
|
|
endpoint: 'https://objects.dreamhost.com.',
|
|
access_key_id: 'my-access-key',
|
|
secret_access_key: 'my-secret-key',
|
|
force_path_style: true,
|
|
region: 'us-east-1'
|
|
)
|
|
|
|
|
|
and instantiate a client object:
|
|
|
|
.. code-block:: ruby
|
|
|
|
s3_client = Aws::S3::Client.new
|
|
|
|
Listing Owned Buckets
|
|
---------------------
|
|
|
|
This gets a list of buckets that you own.
|
|
This also prints out the bucket name and creation date of each bucket.
|
|
|
|
.. code-block:: ruby
|
|
|
|
s3_client.list_buckets.buckets.each do |bucket|
|
|
puts "#{bucket.name}\t#{bucket.creation_date}"
|
|
end
|
|
|
|
The output will look something like this::
|
|
|
|
mahbuckat1 2011-04-21T18:05:39.000Z
|
|
mahbuckat2 2011-04-21T18:05:48.000Z
|
|
mahbuckat3 2011-04-21T18:07:18.000Z
|
|
|
|
|
|
Creating a Bucket
|
|
-----------------
|
|
|
|
This creates a new bucket called ``my-new-bucket``
|
|
|
|
.. code-block:: ruby
|
|
|
|
s3_client.create_bucket(bucket: 'my-new-bucket')
|
|
|
|
If you want a private bucket:
|
|
|
|
`acl` option accepts: # private, public-read, public-read-write, authenticated-read
|
|
|
|
.. code-block:: ruby
|
|
|
|
s3_client.create_bucket(bucket: 'my-new-bucket', acl: 'private')
|
|
|
|
|
|
Listing a Bucket's Content
|
|
--------------------------
|
|
|
|
This gets a list of hashes with the contents of each object
|
|
This also prints out each object's name, the file size, and last
|
|
modified date.
|
|
|
|
.. code-block:: ruby
|
|
|
|
s3_client.get_objects(bucket: 'my-new-bucket').contents.each do |object|
|
|
puts "#{object.key}\t#{object.size}\t#{object.last-modified}"
|
|
end
|
|
|
|
The output will look something like this if the bucket has some files::
|
|
|
|
myphoto1.jpg 251262 2011-08-08T21:35:48.000Z
|
|
myphoto2.jpg 262518 2011-08-08T21:38:01.000Z
|
|
|
|
|
|
Deleting a Bucket
|
|
-----------------
|
|
.. note::
|
|
The Bucket must be empty! Otherwise it won't work!
|
|
|
|
.. code-block:: ruby
|
|
|
|
s3_client.delete_bucket(bucket: 'my-new-bucket')
|
|
|
|
|
|
Forced Delete for Non-empty Buckets
|
|
-----------------------------------
|
|
First, you need to clear the bucket:
|
|
|
|
.. code-block:: ruby
|
|
|
|
Aws::S3::Bucket.new('my-new-bucket', client: s3_client).clear!
|
|
|
|
after, you can destroy the bucket
|
|
|
|
.. code-block:: ruby
|
|
|
|
s3_client.delete_bucket(bucket: 'my-new-bucket')
|
|
|
|
|
|
Creating an Object
|
|
------------------
|
|
|
|
This creates a file ``hello.txt`` with the string ``"Hello World!"``
|
|
|
|
.. code-block:: ruby
|
|
|
|
s3_client.put_object(
|
|
key: 'hello.txt',
|
|
body: 'Hello World!',
|
|
bucket: 'my-new-bucket',
|
|
content_type: 'text/plain'
|
|
)
|
|
|
|
|
|
Change an Object's ACL
|
|
----------------------
|
|
|
|
This makes the object ``hello.txt`` to be publicly readable, and ``secret_plans.txt``
|
|
to be private.
|
|
|
|
.. code-block:: ruby
|
|
|
|
s3_client.put_object_acl(bucket: 'my-new-bucket', key: 'hello.txt', acl: 'public-read')
|
|
|
|
s3_client.put_object_acl(bucket: 'my-new-bucket', key: 'private.txt', acl: 'private')
|
|
|
|
|
|
Download an Object (to a file)
|
|
------------------------------
|
|
|
|
This downloads the object ``poetry.pdf`` and saves it in
|
|
``/home/larry/documents/``
|
|
|
|
.. code-block:: ruby
|
|
|
|
s3_client.get_object(bucket: 'my-new-bucket', key: 'poetry.pdf', response_target: '/home/larry/documents/poetry.pdf')
|
|
|
|
|
|
Delete an Object
|
|
----------------
|
|
|
|
This deletes the object ``goodbye.txt``
|
|
|
|
.. code-block:: ruby
|
|
|
|
s3_client.delete_object(key: 'goodbye.txt', bucket: 'my-new-bucket')
|
|
|
|
|
|
Generate Object Download URLs (signed and unsigned)
|
|
---------------------------------------------------
|
|
|
|
This generates an unsigned download URL for ``hello.txt``. This works
|
|
because we made ``hello.txt`` public by setting the ACL above.
|
|
This then generates a signed download URL for ``secret_plans.txt`` that
|
|
will work for 1 hour. Signed download URLs will work for the time
|
|
period even if the object is private (when the time period is up, the
|
|
URL will stop working).
|
|
|
|
.. code-block:: ruby
|
|
|
|
puts Aws::S3::Object.new(
|
|
key: 'hello.txt',
|
|
bucket_name: 'my-new-bucket',
|
|
client: s3_client
|
|
).public_url
|
|
|
|
puts Aws::S3::Object.new(
|
|
key: 'secret_plans.txt',
|
|
bucket_name: 'hermes_ceph_gem',
|
|
client: s3_client
|
|
).presigned_url(:get, expires_in: 60 * 60)
|
|
|
|
The output of this will look something like::
|
|
|
|
http://objects.dreamhost.com/my-bucket-name/hello.txt
|
|
http://objects.dreamhost.com/my-bucket-name/secret_plans.txt?Signature=XXXXXXXXXXXXXXXXXXXXXXXXXXX&Expires=1316027075&AWSAccessKeyId=XXXXXXXXXXXXXXXXXXX
|
|
|
|
.. _`AWS::SDK`: http://docs.aws.amazon.com/sdkforruby/api/Aws/S3/Client.html
|
|
|
|
|
|
|
|
Ruby `AWS::S3`_ Examples (aws-s3 gem)
|
|
=====================================
|
|
|
|
Creating a Connection
|
|
---------------------
|
|
|
|
This creates a connection so that you can interact with the server.
|
|
|
|
.. code-block:: ruby
|
|
|
|
AWS::S3::Base.establish_connection!(
|
|
:server => 'objects.dreamhost.com',
|
|
:use_ssl => true,
|
|
:access_key_id => 'my-access-key',
|
|
:secret_access_key => 'my-secret-key'
|
|
)
|
|
|
|
|
|
Listing Owned Buckets
|
|
---------------------
|
|
|
|
This gets a list of `AWS::S3::Bucket`_ objects that you own.
|
|
This also prints out the bucket name and creation date of each bucket.
|
|
|
|
.. code-block:: ruby
|
|
|
|
AWS::S3::Service.buckets.each do |bucket|
|
|
puts "#{bucket.name}\t#{bucket.creation_date}"
|
|
end
|
|
|
|
The output will look something like this::
|
|
|
|
mahbuckat1 2011-04-21T18:05:39.000Z
|
|
mahbuckat2 2011-04-21T18:05:48.000Z
|
|
mahbuckat3 2011-04-21T18:07:18.000Z
|
|
|
|
|
|
Creating a Bucket
|
|
-----------------
|
|
|
|
This creates a new bucket called ``my-new-bucket``
|
|
|
|
.. code-block:: ruby
|
|
|
|
AWS::S3::Bucket.create('my-new-bucket')
|
|
|
|
|
|
Listing a Bucket's Content
|
|
--------------------------
|
|
|
|
This gets a list of hashes with the contents of each object
|
|
This also prints out each object's name, the file size, and last
|
|
modified date.
|
|
|
|
.. code-block:: ruby
|
|
|
|
new_bucket = AWS::S3::Bucket.find('my-new-bucket')
|
|
new_bucket.each do |object|
|
|
puts "#{object.key}\t#{object.about['content-length']}\t#{object.about['last-modified']}"
|
|
end
|
|
|
|
The output will look something like this if the bucket has some files::
|
|
|
|
myphoto1.jpg 251262 2011-08-08T21:35:48.000Z
|
|
myphoto2.jpg 262518 2011-08-08T21:38:01.000Z
|
|
|
|
|
|
Deleting a Bucket
|
|
-----------------
|
|
.. note::
|
|
The Bucket must be empty! Otherwise it won't work!
|
|
|
|
.. code-block:: ruby
|
|
|
|
AWS::S3::Bucket.delete('my-new-bucket')
|
|
|
|
|
|
Forced Delete for Non-empty Buckets
|
|
-----------------------------------
|
|
|
|
.. code-block:: ruby
|
|
|
|
AWS::S3::Bucket.delete('my-new-bucket', :force => true)
|
|
|
|
|
|
Creating an Object
|
|
------------------
|
|
|
|
This creates a file ``hello.txt`` with the string ``"Hello World!"``
|
|
|
|
.. code-block:: ruby
|
|
|
|
AWS::S3::S3Object.store(
|
|
'hello.txt',
|
|
'Hello World!',
|
|
'my-new-bucket',
|
|
:content_type => 'text/plain'
|
|
)
|
|
|
|
|
|
Change an Object's ACL
|
|
----------------------
|
|
|
|
This makes the object ``hello.txt`` to be publicly readable, and ``secret_plans.txt``
|
|
to be private.
|
|
|
|
.. code-block:: ruby
|
|
|
|
policy = AWS::S3::S3Object.acl('hello.txt', 'my-new-bucket')
|
|
policy.grants = [ AWS::S3::ACL::Grant.grant(:public_read) ]
|
|
AWS::S3::S3Object.acl('hello.txt', 'my-new-bucket', policy)
|
|
|
|
policy = AWS::S3::S3Object.acl('secret_plans.txt', 'my-new-bucket')
|
|
policy.grants = []
|
|
AWS::S3::S3Object.acl('secret_plans.txt', 'my-new-bucket', policy)
|
|
|
|
|
|
Download an Object (to a file)
|
|
------------------------------
|
|
|
|
This downloads the object ``poetry.pdf`` and saves it in
|
|
``/home/larry/documents/``
|
|
|
|
.. code-block:: ruby
|
|
|
|
open('/home/larry/documents/poetry.pdf', 'w') do |file|
|
|
AWS::S3::S3Object.stream('poetry.pdf', 'my-new-bucket') do |chunk|
|
|
file.write(chunk)
|
|
end
|
|
end
|
|
|
|
|
|
Delete an Object
|
|
----------------
|
|
|
|
This deletes the object ``goodbye.txt``
|
|
|
|
.. code-block:: ruby
|
|
|
|
AWS::S3::S3Object.delete('goodbye.txt', 'my-new-bucket')
|
|
|
|
|
|
Generate Object Download URLs (signed and unsigned)
|
|
---------------------------------------------------
|
|
|
|
This generates an unsigned download URL for ``hello.txt``. This works
|
|
because we made ``hello.txt`` public by setting the ACL above.
|
|
This then generates a signed download URL for ``secret_plans.txt`` that
|
|
will work for 1 hour. Signed download URLs will work for the time
|
|
period even if the object is private (when the time period is up, the
|
|
URL will stop working).
|
|
|
|
.. code-block:: ruby
|
|
|
|
puts AWS::S3::S3Object.url_for(
|
|
'hello.txt',
|
|
'my-new-bucket',
|
|
:authenticated => false
|
|
)
|
|
|
|
puts AWS::S3::S3Object.url_for(
|
|
'secret_plans.txt',
|
|
'my-new-bucket',
|
|
:expires_in => 60 * 60
|
|
)
|
|
|
|
The output of this will look something like::
|
|
|
|
http://objects.dreamhost.com/my-bucket-name/hello.txt
|
|
http://objects.dreamhost.com/my-bucket-name/secret_plans.txt?Signature=XXXXXXXXXXXXXXXXXXXXXXXXXXX&Expires=1316027075&AWSAccessKeyId=XXXXXXXXXXXXXXXXXXX
|
|
|
|
.. _`AWS::S3`: http://amazon.rubyforge.org/
|
|
.. _`AWS::S3::Bucket`: http://amazon.rubyforge.org/doc/
|
|
|