Atmos¶ ↑
This gem is a Ruby library for EMC's Atmos (www.emc.com/atmos) REST API.
Logging is done via the Log4r
package. The name of the logger
is the string atmos
, and the log level is set to
Log4r::FATAL
by default.
Getting started¶ ↑
You'll need this gem and a URL to your Atmos installation.
You'll also need your Atmos authentication credentials.
Basics¶ ↑
XML Parser¶ ↑
The very first thing is that you have to pick your XML parser. There are
two options: nokogiri
for performance or rexml
for only pure ruby requirements. Setting the parser does the require, so
make sure you have the gem you want to use installed. This gem doesn't
require either, since it doesn't know which you plan to use.
Atmos::Parser::parser = Atmos::Parser::NOKOGIRI Atmos::Parser::parser = Atmos::Parser::REXML
Datastore¶ ↑
The Atmos installation you will be connecting to
is your datastore. You can see more detailed information at
Atmos::Store
.
store = Atmos::Store.new(:url => "https://mgmt.atmosonline.com", :uid => <your identifier>, :secret => <your secret>)
From your store, you can create and retrieve objects. Note that objects are always retrieved without their data, so a progressive download can be done.
obj = store.get(id) newobj = store.create(options)
Now that you have a store, you can iterate through all listable tags, object ids by listable tag, and objects by listable tag. Remember that when an Atmos::Object is instantiated, it loads all ACLs and Metadata.
store.each_listable_tag { |tag| } store.each_object_id_by_tag(tag) do |id| end store.each_object_by_tag(tag) do |obj| end
Objects¶ ↑
See Atmos::Object
for more detailed info on the object API.
Creating Objects¶ ↑
At the very simplest, you can create an object with nothing. The mimetype
will default to binary/octet-stream
. The object will be
created with no data, no metadata, with permissions set for only the
creator to access.
obj = store.create()
You can also create an object with (any combination of) more information
up front. (See Atmos::Store.create
for more detailed info on
object creation options.)
obj = store.create( :user_acl => {'janet' => :full, 'xavier' => :read}, :group_acl => {'other' => :read}, :metadata => {'key' => 'value', 'another_key' => nil}, :listable_metadata => {'lkey' => 'lvalue', 'another_lkey' => nil}, :mimetype => "video/quicktime", :data => open("local/video_file.qt") )
Reading Objects¶ ↑
You can get the data for an object all at once, which means it all gets read into memory all at once:
@data = @obj.data
Or progressively download it by passing a block to read
:
@file = open('mydata', 'w') @obj.read do |chunk| @file.write chunk end
Object Metadata¶ ↑
An object has system and user metadata. User metadata can be modified,
system metadata cannot. User metadata is further divided into listable
and non-listable metadata. Listable metadata means the object is indexed
on the key value of the metadata key/value pair (also known as a
tag
), and can be retrieved via the tag.
Set or change user metadata, listable or non-listable, keys and values must be Strings:
@obj.metadata[newkey] = "newvalue"
(See Atmos::Metadata
for more detailed info.)
Object ACL¶ ↑
There are two ACLs on an object: user_acl
and
group_acl
. User and group names are ruby Strings, while the
values are one of the following symbols: :none
,
:read
, :write
,:full
. They are
accessed as Hashes on the object. All normal Hash functions will work.
When permissions are set to :none
the pair disappears from the
hash.
@obj.user_acl['user'] = :full @obj.group_acl['other'] = :none
(See Atmos::ACL
for more detailed info.)
Other Object Functionality¶ ↑
@obj.exists? @obj.delete