ruby-box¶ ↑
Maintained by: Adrien Giboire
RubyBox
provides a simple, chainable, feature-rich client for Box’s 2.0 API.
Authorization¶ ↑
RubyBox
uses Box’s OAuth2 Implementaton, Here are the steps involved in authorizing a client:
1) Get the authorization url.
require 'ruby-box-updated' session = RubyBox::Session.new({ client_id: 'your-client-id', client_secret: 'your-client-secret' }) authorize_url = session.authorize_url('https://redirect-url-in-app-settings')
2) After redirecting to the authorize_url, exchange the code given for an access_token
@token = session.get_access_token('code-returned-to-redirect_url') p '@token.token' # the access token. p '@token.refresh_token' # token that can be exchanged for a new access_token once the access_token expires. # refreshing token. session = RubyBox::Session.new({ client_id: 'your-client-id', client_secret: 'your-client-secret', access_token: 'original-access-token' }) # you need to persist this somehow. the refresh token will change every time you use it @token = session.refresh_token('your-refresh-token') save_me_somehow(@token.refresh_token)
3) Create a client using a session initialized with the access_token.
require 'ruby-box-updated' session = RubyBox::Session.new({ client_id: 'your-client-id', client_secret: 'your-client-secret', access_token: 'access-token' }) client = RubyBox::Client.new(session)
Usage¶ ↑
Once you’ve created a client, you can start interacting with the Box API. What follows are some basic examples of RubyBox’s usage.
Warning¶ ↑
Please note that using a file/folder path is extremely inefficient, as it causes the gem to traverse the directory structure recursively querying each folder in turn. Prefer the _by_id
methods where possible for single-request access.
Items¶ ↑
File
s and Folder
s are subclasses of Item
. Folder
contents (i.e. files and folders inside that folder) are retrieved in a mini-format
when the Folder
instance is loaded.
There are two caveats to this:
Only some fields are available¶ ↑
a File
mini looks like this:
{ "type": "file", "id": "5000948880", "sequence_id": "3", "etag": "3", "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc", "name": "tigers.jpeg" }
a Folder
mini looks like this:
{ "type":"folder", "id":"301415432", "sequence_id":"0", "name":"my first sub-folder" }
Requests to fields other than the above (e.g. file.size
) will cause a one-off hit to the api, so take care when iterating over folder contents lest a single application method result in hundreds of api hits and take forever to complete.
This can be mitigated by passing a list of extra fields you want to fetch into the .items
method:
folder = client.folder_by_id(@folder_id) # retrieve size, created_at, and description for all items in this directory detailed_items = folder.items(@item_limit, @offset, ['size', 'created_at', 'description'])
Note: only the type
and id
fields are included in addition to whatever you specify using the above method, so you must be explicit.
Folders¶ ↑
-
Listing items in a folder:
files = client.folder('/image_folder').files # all files in a folder using a path. files = client.folder(@folder_id).files # all files in a folder using an id. folders = client.root_folder.folders # all folders in the root directory. files_and_folders = client.folder('files').items # all files and folders in /files
-
Creating a folder:
client.folder_by_id(@folder_id).create_subfolder('subfolder') # using an id. client.folder('image_folder').create_subfolder('subfolder') # using a path.
-
Setting the description on a folder:
folder = client.folder('image_folder') # using a path. folder.description = 'Description on Folder' folder.update
-
Listing the comments in a discussion surrounding a folder.
folder = client.folder('image_folder') # lookups by id are more efficient discussion = folder.discussions.first discussion.comments.each {|comment| p comment.message}
-
Creating a shared link for a folder.
folder = client.folder('image_folder').create_shared_link # lookups by id are more efficient p folder.shared_link.url # https://www.box.com/s/d6de3224958c1755412
-
Creating an email to upload files in a folder.
folder = client.folder('documents_folder').create_folder_upload_email # lookups by id are more efficient p folder.folder_upload_email.email # upload.adrien_.8kge3wck1h@u.box.com
Files¶ ↑
-
Fetching a file’s meta information.
file = client.file('/image_folder/an-image.jpg')# lookups by id are more efficient file = client.file(@file_id) p file.name p file.created_at
-
Uploading a file to a folder.
file = client.upload_file('./LICENSE.txt', '/license_folder') # lookups by id are more efficient file = client.upload_file_by_folder_id('./LICENSE.txt', @folder_id)
-
Downloading a file.
f = open('./LOCAL.txt', 'w+') f.write( client.file('/license_folder/LICENSE.txt').download ) f.close() # Or you can fetch by file.id, which is more efficient: f = open('./LOCAL.txt', 'w+') f.write( client.file_by_id(@file_id).download ) # lookups by id are more efficient f.close() # You can also grab the raw url with client.file_by_id(@file_id).download_url # Note that this URL is not persistent. Clients will need to follow the url immediately in order to # actually download the file
-
Deleting a file.
client.file_by_id(@file_id).delete # this client.file('/license_folder/LICENSE.txt').delete
-
Displaying comments on a file.
comments = client.file('/image_folder/an-image.jpg').comments # lookups by id are more efficient comments = client.file_by_id(@file_id).comments comments.each do |comment| p comment.message end
-
Creating a shared link for a file.
file = client.file('/image_folder/an-image.jpg').create_shared_link file = client.file_by_id(@file_id).create_shared_link # using an id p file.shared_link.url # https://www.box.com/s/d6de3224958c1755412
-
Copying a file to another folder.
file = client.file('/one_folder/cow_folder/an-image.jpg') folder = client.folder('image_folder') # lookups by id are more efficient file = client.file_by_id(@file_id) folder = client.folder_by_id(@folder_id) file.copy_to(folder)
-
Moving a file to another folder.
file = client.file('/one_folder/cow_folder/an-image.jpg') folder = client.folder('image_folder') # lookups by id are more efficient file = client.file_by_id(@file_id) folder = client.folder_by_id(@folder_id) file.move_to(folder)
-
Adding a comment to a file.
file = client.file('/image_folder/an-image.jpg') # path file = client.file_by_id(@file_id) # id comment = file.create_comment('Hello World!')
Search¶ ↑
You can use RubyBox’s search method to return files and folders that match a given query.
items = client.search('image') items.each do |item| p "type=#{item.type} name=#{item.name}" end
Events¶ ↑
You can use RubyBox’s event_response method to return an EventResponse that can be used to process any incoming events.
eresp = client.event_response eresp.chunk_size eresp.next_stream_position eresp.events.each do |ev| p "type=#{ev.event_id} type=#{ev.event_type} user=#{ev.created_by.name}" end
As-User¶ ↑
-
This must be manually enabled for your account by Box Staff. Contact api@box.com for access. [ More Info ] (developers.box.com/docs/#users-as-user)
session = RubyBox::Session.new({ client_id: 'your-client-id', client_secret: 'your-client-secret', access_token: 'original-access-token' , as_user: 'your-users-box-id' })
Users¶ ↑
Current User Info
me = client.me
Current User’s enterprise
me = client.me.enterprise
An array of Ruby:Box users in an enterprise (Supports Filtering, Limit and Offset)
users = client.users
-
Remember the API filters “name” and “login” by the start of the string. ie: to get “sean+awesome@gmail.com” an approriate filter term would be “sean”
users = client.users("sean" , 10 , 1)
Contributors¶ ↑
Contributing to ruby-box¶ ↑
RubyBox
does not yet support all of Box’s API Version 2.0 functionality, be liberal with your contributions.
-
Rename account.example to account.yml and fill in your Box credentials
-
Type bundle install
-
Type rake.. tests should pass
-
Add a failing test
-
Make it pass
-
Submit a pull request
Copyright¶ ↑
Copyright © 2012 Attachments.me. See LICENSE.txt for further details.