Project

ruby-box

0.12
No commit activity in last 3 years
No release in over 3 years
There's a lot of open issues
ruby gem for box.com 2.0 api
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

Runtime

 Project Readme

ruby-box

Build Status: Build Status

Mainted by: Attachments.me

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'

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'

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

Files and Folders 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

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

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
  • Remeber 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 (c) 2012 Attachments.me. See LICENSE.txt for further details.