Class: Dropbox::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/dropbox/client.rb

Overview

Client contains all the methods that map to the Dropbox API endpoints.

Instance Method Summary collapse

Constructor Details

#initialize(access_token) ⇒ Client

Returns a new instance of Client.

Parameters:

  • access_token (String) 


9
10
11
12
13
14
15
 
# File 'lib/dropbox/client.rb', line 9

def initialize(access_token)
  unless access_token =~ /^[a-z0-9_-]{64}$/i
    raise ClientError.invalid_access_token
  end

  @access_token = access_token
end

Instance Method Details

#append_upload_session(cursor, body, close = false) ⇒ Dropbox::UploadSessionCursor

Append more data to an upload session.

Parameters:

Returns:



260
261
262
263
264
265
 
# File 'lib/dropbox/client.rb', line 260

def append_upload_session(cursor, body, close=false)
  args = {cursor: cursor.to_h, close: close}
  resp = upload_request('/files/upload_session/append_v2', body, args)
  cursor.offset += body.length
  cursor
end

#check_save_url_job_status(async_job_id) ⇒ nil, ...

Check the status of a save_url job.

Parameters:

  • async_job_id (String)

Returns:

  • (nil) —

    if the job is still in progress.

  • (Dropbox::FileMetadata) —

    if the job is complete.

  • (String) —

    an error message, if the job failed.



209
210
211
212
 
# File 'lib/dropbox/client.rb', line 209

def check_save_url_job_status(async_job_id)
  resp = request('/files/save_url/check_job_status', async_job_id: async_job_id)
  parse_tagged_response(resp)
end

#continue_list_folder(cursor) ⇒ Array<Dropbox::Metadata>

Get the contents of a folder that are after a cursor.

Parameters:

  • cursor (String)

Returns:



138
139
140
141
 
# File 'lib/dropbox/client.rb', line 138

def continue_list_folder(cursor)
  resp = request('/files/list_folder/continue', cursor: cursor)
  resp['entries'].map { |e| parse_tagged_response(e) }
end

#copy(from_path, to_path) ⇒ Dropbox::Metadata

Copy a file or folder to a different location in the user’s Dropbox.

Parameters:

  • from_path (String)
  • to_path (String)

Returns:



30
31
32
33
 
# File 'lib/dropbox/client.rb', line 30

def copy(from_path, to_path)
  resp = request('/files/copy', from_path: from_path, to_path: to_path)
  parse_tagged_response(resp)
end

#create_folder(path) ⇒ Dropbox::FolderMetadata

Create a folder at a given path.

Parameters:

  • path (String)

Returns:



60
61
62
63
 
# File 'lib/dropbox/client.rb', line 60

def create_folder(path)
  resp = request('/files/create_folder', path: path)
  FolderMetadata.new(resp)
end

#delete(path) ⇒ Dropbox::Metadata

Delete the file or folder at a given path.

Parameters:

  • path (String)

Returns:



69
70
71
72
 
# File 'lib/dropbox/client.rb', line 69

def delete(path)
  resp = request('/files/delete', path: path)
  parse_tagged_response(resp)
end

#download(path) ⇒ Dropbox::FileMetadata, HTTP::Response::Body

Download a file from a user’s Dropbox.

Parameters:

  • path (String)

Returns:



79
80
81
82
 
# File 'lib/dropbox/client.rb', line 79

def download(path)
  resp, body = content_request('/files/download', path: path)
  return FileMetadata.new(resp), body
end

#finish_upload_session(cursor, path, body, options = {}) ⇒ Dropbox::FileMetadata

Finish an upload session and save the uploaded data to the given file path.

Parameters:

Options Hash (options):

  • :mode (String)
  • :autorename (Boolean)
  • :mute (Boolean)

Returns:



275
276
277
278
279
280
281
 
# File 'lib/dropbox/client.rb', line 275

def finish_upload_session(cursor, path, body, options={})
  options[:client_modified] = Time.now.utc.iso8601
  options[:path] = path
  args = {cursor: cursor.to_h, commit: options}
  resp = upload_request('/files/upload_session/finish', body, args)
  FileMetadata.new(resp)
end

#get_account(account_id) ⇒ Dropbox::BasicAccount

Get information about a user’s account.

Parameters:

  • account_id (String)

Returns:



287
288
289
290
 
# File 'lib/dropbox/client.rb', line 287

def ()
  resp = request('/users/get_account', account_id: )
  BasicAccount.new(resp)
end

#get_account_batch(account_ids) ⇒ Array<Dropbox::BasicAccount>

Get information about multiple user accounts.

Parameters:

  • account_ids (Array<String>)

Returns:



296
297
298
299
 
# File 'lib/dropbox/client.rb', line 296

def ()
  resp = request('/users/get_account_batch', account_ids: )
  resp.map { |a| BasicAccount.new(a) }
end

#get_copy_reference(path) ⇒ Dropbox::Metadata, String

Get a copy reference to a file or folder.

Parameters:

  • path (String)

Returns:



40
41
42
43
44
 
# File 'lib/dropbox/client.rb', line 40

def get_copy_reference(path)
  resp = request('/files/copy_reference/get', path: path)
  metadata = parse_tagged_response(resp['metadata'])
  return metadata, resp['copy_reference']
end

#get_current_account ⇒ Dropbox::FullAccount

Get information about the current user’s account.

Returns:



304
305
306
307
 
# File 'lib/dropbox/client.rb', line 304

def 
  resp = request('/users/get_current_account')
  FullAccount.new(resp)
end

#get_latest_list_folder_cursor(path) ⇒ String

Get a cursor for a folder’s current state.

Parameters:

  • path (String)

Returns:

  • (String) —

    cursor



147
148
149
150
 
# File 'lib/dropbox/client.rb', line 147

def get_latest_list_folder_cursor(path)
  resp = request('/files/list_folder/get_latest_cursor', path: path)
  resp['cursor']
end

#get_metadata(path) ⇒ Dropbox::Metadata

Get the metadata for a file or folder.

Parameters:

  • path (String)

Returns:



88
89
90
91
 
# File 'lib/dropbox/client.rb', line 88

def get_metadata(path)
  resp = request('/files/get_metadata', path: path)
  parse_tagged_response(resp)
end

#get_preview(path) ⇒ Dropbox::FileMetadata, HTTP::Response::Body

Get a preview for a file.

Parameters:

  • path (String)

Returns:



98
99
100
101
 
# File 'lib/dropbox/client.rb', line 98

def get_preview(path)
  resp, body = content_request('/files/get_preview', path: path)
  return FileMetadata.new(resp), body
end

#get_space_usage ⇒ Dropbox::SpaceUsage

Get the space usage information for the current user’s account.

Returns:



312
313
314
315
 
# File 'lib/dropbox/client.rb', line 312

def get_space_usage
  resp = request('/users/get_space_usage')
  SpaceUsage.new(resp)
end

#get_temporary_link(path) ⇒ Dropbox::FileMetadata, String

Get a temporary link to stream content of a file.

Parameters:

  • path (String)

Returns:



108
109
110
111
 
# File 'lib/dropbox/client.rb', line 108

def get_temporary_link(path)
  resp = request('/files/get_temporary_link', path: path)
  return FileMetadata.new(resp['metadata']), resp['link']
end

#get_thumbnail(path, format = 'jpeg', size = 'w64h64') ⇒ Dropbox::FileMetadata, HTTP::Response::Body

Get a thumbnail for an image.

Parameters:

  • path (String)
  • format (String) (defaults to: 'jpeg')
  • size (String) (defaults to: 'w64h64')

Returns:



120
121
122
123
 
# File 'lib/dropbox/client.rb', line 120

def get_thumbnail(path, format='jpeg', size='w64h64')
  resp, body = content_request('/files/get_thumbnail', path: path, format: format, size: size)
  return FileMetadata.new(resp), body
end

#list_folder(path) ⇒ Array<Dropbox::Metadata>

Get the contents of a folder.

Parameters:

  • path (String)

Returns:



129
130
131
132
 
# File 'lib/dropbox/client.rb', line 129

def list_folder(path)
  resp = request('/files/list_folder', path: path)
  resp['entries'].map { |e| parse_tagged_response(e) }
end

#list_revisions(path) ⇒ Array<Dropbox::FileMetadata>, Boolean

Get the revisions of a file.

Parameters:

  • path (String)

Returns:



157
158
159
160
161
 
# File 'lib/dropbox/client.rb', line 157

def list_revisions(path)
  resp = request('/files/list_revisions', path: path)
  entries = resp['entries'].map { |e| FileMetadata.new(e) }
  return entries, resp['is_deleted']
end

#move(from_path, to_path) ⇒ Dropbox::Metadata

Move a file or folder to a different location in the user’s Dropbox.

Parameters:

  • from_path (String)
  • to_path (String)

Returns:



168
169
170
171
 
# File 'lib/dropbox/client.rb', line 168

def move(from_path, to_path)
  resp = request('/files/move', from_path: from_path, to_path: to_path)
  parse_tagged_response(resp)
end

#permanently_delete(path) ⇒ void

This method returns an undefined value.

Permanently delete the file or folder at a given path.

Parameters:

  • path (String) 


177
178
179
180
 
# File 'lib/dropbox/client.rb', line 177

def permanently_delete(path)
  request('/files/permanently_delete', path: path)
  nil
end

#restore(path, rev) ⇒ Dropbox::FileMetadata

Restore a file to a specific revision.

Parameters:

  • path (String)
  • rev (String)

Returns:



187
188
189
190
 
# File 'lib/dropbox/client.rb', line 187

def restore(path, rev)
  resp = request('/files/restore', path: path, rev: rev)
  FileMetadata.new(resp)
end

#revoke_token ⇒ void

This method returns an undefined value.

Disable the access token used to authenticate the call.

Raises:



20
21
22
23
 
# File 'lib/dropbox/client.rb', line 20

def revoke_token
  r = HTTP.auth('Bearer ' + @access_token).post(API + '/auth/token/revoke')
  raise ApiError.new(r) if r.code != 200
end

#save_copy_reference(copy_reference, path) ⇒ Dropbox::Metadata

Save a copy reference to the user’s Dropbox.

Parameters:

  • copy_reference (String)
  • path (String)

Returns:



51
52
53
54
 
# File 'lib/dropbox/client.rb', line 51

def save_copy_reference(copy_reference, path)
  resp = request('/files/copy_reference/save', copy_reference: copy_reference, path: path)
  parse_tagged_response(resp['metadata'])
end

#save_url(path, url) ⇒ String, Dropbox::FileMetadata

Save a specified URL into a file in user’s Dropbox.

Parameters:

  • path (String)
  • url (String)

Returns:

  • (String) —

    the job id, if the processing is asynchronous.

  • (Dropbox::FileMetadata) —

    if the processing is synchronous.



198
199
200
201
 
# File 'lib/dropbox/client.rb', line 198

def save_url(path, url)
  resp = request('/files/save_url', path: path, url: url)
  parse_tagged_response(resp)
end

#search(path, query, start = 0, max_results = 100, mode = 'filename') ⇒ Array<Dropbox::Metadata>

Search for files and folders.

Parameters:

  • path (String)
  • query (String)
  • start (Integer) (defaults to: 0)
  • max_results (Integer) (defaults to: 100)
  • mode (String) (defaults to: 'filename')

Returns:



222
223
224
225
226
227
 
# File 'lib/dropbox/client.rb', line 222

def search(path, query, start=0, max_results=100, mode='filename')
  resp = request('/files/search', path: path, query: query, start: start,
    max_results: max_results, mode: mode)
  matches = resp['matches'].map { |m| parse_tagged_response(m['metadata']) }
  return matches
end

#start_upload_session(body, close = false) ⇒ Dropbox::UploadSessionCursor

Start an upload session to upload a file using multiple requests.

Parameters:

  • body (String, Enumerable)
  • close (Boolean) (defaults to: false)

Returns:



249
250
251
252
 
# File 'lib/dropbox/client.rb', line 249

def start_upload_session(body, close=false)
  resp = upload_request('/files/upload_session/start', body, close: close)
  UploadSessionCursor.new(resp['session_id'], body.length)
end

#upload(path, body, options = {}) ⇒ Dropbox::FileMetadata

Create a new file.

Parameters:

  • path (String)
  • body (String, Enumerable)
  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • :mode (String)
  • :autorename (Boolean)
  • :mute (Boolean)

Returns:



237
238
239
240
241
242
 
# File 'lib/dropbox/client.rb', line 237

def upload(path, body, options={})
  options[:client_modified] = Time.now.utc.iso8601
  options[:path] = path
  resp = upload_request('/files/upload', body, options.merge(path: path))
  FileMetadata.new(resp)
end